Skip to main content

Aider

What is this about?

This is a practical developer guide to Aider, the open-source terminal pair-programming tool from Aider-AI/aider. It is aimed at developers who want to understand how Aider works, how to install and configure it, and where it fits compared with other coding agents.

Checked against primary sources

This guide is based on Aider's official documentation and official GitHub repository, reviewed on June 24, 2026.

1. What Aider is​

Aider is an AI pair-programming CLI that works inside your terminal and edits files in your local repository. Its core model is:

  • you run aider in a git repository
  • you add only the files relevant to the task
  • you ask for changes in chat
  • Aider edits files, shows diffs, and commits its changes to git

The official project positions it as "AI pair programming in your terminal."

What makes Aider stand out is not only that it can talk to many LLMs, but that it is very opinionated about three things:

  • git-first safety
  • working from the terminal
  • tight control over file context

2. Why developers use it​

From the official docs and repo, Aider's strongest traits are:

CapabilityWhy it matters
Works with many LLMsYou are not locked into one provider.
Git integrationEvery AI change is easy to review, diff, undo, and branch.
Repository mapAider sends a compact map of the wider codebase to the model.
File-scoped editingYou choose which files are editable in the session.
Lint/test integrationIt can run linters and tests after edits and try to fix failures.
Terminal-first workflowGood fit for developers who already live in shell, tmux, neovim, or remote environments.
YAML configurationEasy to standardize team defaults in .aider.conf.yml.

This makes Aider especially attractive for:

  • existing repositories with git discipline
  • developers who prefer the terminal over a full agent IDE
  • model-agnostic workflows
  • cost-conscious setups where you want to swap providers freely

3. Installation and first run​

The official docs recommend aider-install as the quickest path, because it installs Aider into its own Python environment and can also provision Python 3.12 if needed.

Fastest install​

python -m pip install aider-install
aider-install

Alternative install methods​

The official docs also document:

  • uv
  • pipx
  • pip
  • platform-specific one-liners for macOS, Linux, and Windows

Minimal first session​

cd /path/to/your/project
aider app.py

Or with an explicit model:

# DeepSeek
aider --model deepseek --api-key deepseek=<key>

# Anthropic Sonnet
aider --model sonnet --api-key anthropic=<key>

# OpenAI
aider --model o3-mini --api-key openai=<key>

At the aider > prompt, ask for the change you want and review the diffs before continuing.

4. Core workflow​

The official usage guide is built around one key idea: only add the files you really need.

Launch with specific files​

aider src/api/users.py src/tests/test_users.py

Those files are added to the chat session and can be edited directly.

Add or remove files during the session​

Use in-chat commands:

  • /add to add files
  • /drop to remove files
  • /read-only to include reference files without allowing edits

Why this matters​

Aider explicitly warns that adding too many files can:

  • overwhelm the model
  • increase token cost
  • make edits less precise

That is one of Aider's strongest habits and also one of its best practices.

5. The repository map​

One of Aider's most important features is the repo map.

Instead of sending the full repository into context, Aider builds a compact map of the codebase that includes:

  • important files
  • key classes and functions
  • signatures and symbol definitions
  • dependency relationships across files

The official docs describe this as a way to help the model understand the rest of the codebase, even when you only add a small number of files directly.

Why the repo map matters​

It gives Aider two big advantages:

  1. The model can see enough structure to infer where related code probably lives.
  2. The model can ask for more specific files only when they are actually needed.

Token budget​

The repo map is controlled by settings such as:

  • --map-tokens
  • --map-refresh

By default, Aider tries to stay within a modest token budget and expands only when necessary.

6. Git-first behavior​

Aider works best when your code lives in a git repository.

According to the official docs, Aider:

  • offers to create a git repo if one does not exist
  • auto-commits its own edits
  • handles dirty files carefully before editing
  • supports undo through git history

Especially useful commands​

  • /diff shows changes since the last message
  • /undo reverts the last Aider change
  • /commit commits pending changes
  • /git runs raw git commands outside chat context

Why this is a real advantage​

This makes Aider feel more controlled than many "black box" agents:

  • edits are inspectable
  • history stays understandable
  • reverting mistakes is cheap

For teams that care about reviewability and branch hygiene, this is one of Aider's strongest differentiators.

7. Working with models​

Aider is explicitly model-agnostic.

The official LLM guide says it can connect to most major providers and also to local models. As of the reviewed docs, it highlights these as especially strong fits:

  • Gemini 2.5 Pro
  • DeepSeek R1 and V3
  • Claude 3.7 Sonnet
  • OpenAI o3, o4-mini, and GPT-4.1

It also supports:

  • OpenRouter
  • Ollama
  • OpenAI-compatible APIs
  • local model servers

Practical implication​

Aider is a good fit if you want:

  • one workflow across multiple providers
  • to compare models on the same coding task
  • to use local or cheaper APIs without changing your whole tool

Practical warning​

The official docs also warn that weaker models may not return edits in a form Aider can reliably apply. In other words:

  • just because a model can answer questions
  • does not mean it is strong enough for structured code editing

That is why Aider publishes and references its own leaderboards.

8. In-chat commands that matter most​

Aider has a large command surface, but a few commands matter for daily work much more than the rest:

CommandUse it for
/addAdd files to the editable context
/dropRemove files and free context
/askAsk questions without editing
/codeSwitch back into editing mode
/architectUse architect/editor mode with separate models
/modelSwitch the main model
/weak-modelSwitch the weaker helper model
/mapPrint the current repo map
/lintRun linting on chat files or dirty files
/testRun a test command and feed failures back
/runRun shell commands and optionally share output
/undoRevert the last Aider commit

Good mental model​

Think of Aider as a chat-driven coding loop with four recurring actions:

  1. add the right files
  2. ask for the change
  3. inspect the diff
  4. lint/test/undo as needed

9. Linting and testing​

Aider can automatically lint and test code after it edits files.

Linting​

The official docs say Aider includes built-in linters for many popular languages. You can also set your own lint command:

aider --lint-cmd "eslint"

Or configure per-language linters with --lint.

Testing​

You can run tests manually:

/test pytest -q

Or configure Aider to run them automatically after edits:

  • --test-cmd
  • --auto-test

Why this matters​

This is one of the features that makes Aider feel more like a developer workflow tool and less like a plain chat wrapper.

10. Configuration with .aider.conf.yml​

Aider supports a YAML config file named .aider.conf.yml.

The docs say Aider looks for config in:

  • your home directory
  • the repo root
  • the current directory

Later-loaded files take precedence.

Useful settings for developers​

These are among the most practical options from the official config reference:

  • model
  • weak-model
  • editor-model
  • api-key
  • map-tokens
  • auto-commits
  • auto-lint
  • test-cmd
  • auto-test
  • read
  • vim
  • chat-language
  • notifications

Example​

model: sonnet
api-key:
  - anthropic=YOUR_KEY
read:
  - CONVENTIONS.md
  - ARCHITECTURE.md
auto-commits: true
auto-lint: true
test-cmd: pytest -q
auto-test: true
map-tokens: 2048

This is where Aider becomes team-friendly: you can encode conventions, test commands, and workflow defaults in the repo.

11. Best practices​

Based on the official docs, these are the highest-signal habits:

1. Add only the files needed for the task​

This is probably the single most important Aider habit. It keeps context clean and edits more precise.

2. Let git do the safety work​

Lean into Aider's commit-based workflow:

  • inspect diffs often
  • use /undo aggressively
  • keep tasks small enough that single commits stay understandable

3. Give it project conventions up front​

Use read: in .aider.conf.yml or add read-only files like:

  • CONTRIBUTING.md
  • CONVENTIONS.md
  • architecture notes
  • coding standards

4. Wire in lint and tests early​

If Aider is going to edit code regularly, connect it to real validation instead of relying only on chat confidence.

5. Use stronger models for edits, cheaper ones for support when appropriate​

Aider separates main and helper roles, so there is room to tune cost and quality.

6. Use /ask and /architect deliberately​

Not every step should be direct editing. Sometimes planning before changing code gives better results and smaller diffs.

12. Where Aider is strongest​

Aider is a particularly strong fit when you want:

  • a terminal-first coding agent
  • explicit git history and undoability
  • freedom to choose different LLM providers
  • a tool that works well in existing codebases
  • a workflow that stays close to normal developer habits

It is especially good for:

  • bug fixes
  • focused refactors
  • test-assisted edits
  • remote server or SSH workflows
  • cost-sensitive experimentation across models

13. Where Aider is weaker​

Aider is not the ideal default for every team.

It may be less compelling if you want:​

  • a polished graphical IDE-native experience first
  • deep editor UI features like inline widgets and rich panels
  • a cloud agent that opens PRs asynchronously without local setup
  • a strongly guided product workflow instead of a flexible shell tool

In those cases, tools like:

  • Cursor
  • GitHub Copilot Agent Mode
  • Claude Code in IDE mode
  • cloud coding agents

may feel more immediately ergonomic.

14. Aider vs. other coding agents​

Aider vs. Claude Code​

  • Claude Code is more tightly integrated with Anthropic's agent stack and model capabilities.
  • Aider is more provider-flexible and more explicitly git-centric.

Aider vs. Codex CLI​

  • Codex CLI fits best if you want to stay inside OpenAI's ecosystem.
  • Aider fits better if you want to switch models and providers freely.

Aider vs. Cursor or Copilot​

  • Cursor/Copilot are more editor-native.
  • Aider is better for developers who prefer terminal workflows and transparent git operations.

Recommendation​

Aider is one of the most mature open-source terminal coding agents available today. It is not the fanciest option, but it is a very practical one.

Choose Aider if you want:

  • terminal-first pair programming
  • strong git ergonomics
  • repo-aware code editing
  • model/provider flexibility
  • lint/test loops in the same workflow

If your team is comfortable in the shell and values explicit control over automation, Aider is a very strong option.

Sources​