Install

# With uv (see /tutorials/uv-fast-python-toolchain.html)
uv tool install aider-chat
aider --version

# Or with pipx
pipx install aider-chat

# Or as a one-shot via uvx (no install)
uvx aider-chat --version

aider is a Python package; the underlying LLM is whatever provider's API you point it at. Storage on disk is negligible (~20 MB) plus per-repo cache files.

Pick a model

aider configures the model via env vars (or --model on the command line):

# OpenAI
export OPENAI_API_KEY=sk-...
aider --model gpt-5

# Anthropic
export ANTHROPIC_API_KEY=sk-ant-...
aider --model anthropic/claude-opus-4-7

# OpenRouter (one API key, many providers)
export OPENROUTER_API_KEY=sk-or-...
aider --model openrouter/anthropic/claude-opus-4-7

# Local Ollama (see /tutorials/ollama-self-host-llms-linux.html)
export OLLAMA_API_BASE=http://localhost:11434
aider --model ollama/qwen3:32b

The model matters. State-of-the-art frontier models do the heavy lifting well; smaller local models are useful for free, private, offline work but struggle with multi-file refactors. The aider docs publish a leaderboard ranking models on a real coding benchmark — check it before committing to a model.

The first session

cd ~/code/my-project
aider

aider checks for a Git repo (offers to initialize one if missing), reads .gitignore, builds a tree-sitter map of the codebase, and drops into a prompt:

> Add a CLI flag --verbose that increases logging level to DEBUG

aider proposes a diff, asks for confirmation, applies it, runs your configured test command, and commits with a message derived from the change. The next prompt starts with the result of that step still in context.

Adding files to the chat

By default aider sees the repository map but not the contents of files. To work on a specific file:

> /add src/cli.py src/main.py
> Refactor cli.py to use argparse subcommands instead of a single flat command

/add brings the full file into context. /drop removes it. The smaller the file set, the more headroom for the model to think about each one.

The /commands

  • /add <path>, /drop <path>, /ls — manage which files are in context
  • /run <cmd> — run a shell command and feed its output back to the model
  • /test — run the configured test command (set via --test-cmd "pytest" or in .aider.conf.yml)
  • /diff — show the diff since the last accepted change
  • /undo — git reset --hard HEAD~1 the last aider commit (only safe because every change is its own commit)
  • /clear — reset the conversation but keep file state
  • /architect — switch to "architect mode" (a planning step with a stronger model, then a separate "editor" model applies the changes)
  • /help — list everything

Per-project configuration

Drop .aider.conf.yml in the repo root:

model: anthropic/claude-opus-4-7
weak-model: anthropic/claude-haiku-4-5-20251001

test-cmd: pytest -x -q
auto-test: true            # run tests after every change
auto-commits: true         # commit after every accepted change
attribute-author: false    # don't change git author on AI commits
attribute-committer: true  # do mark committer as aider

read-only:                 # files visible to the model but not editable
  - ARCHITECTURE.md
  - docs/api.md

The weak-model is the cheaper model used for routine work (commit messages, summarization, file listing). The main model handles the actual reasoning.

The repo map

aider builds a structural map of every file in the repo using tree-sitter, then sends a compressed version to the model on each request: function signatures, type definitions, imports — not function bodies. The model uses it to decide which files to /add on its own when relevant. Repo maps are why aider scales to large codebases that don't fit in any context window; the model only sees full contents of the files it has reason to look at.

Editing rules: where it shines, where it doesn't

Good fits:

  • Boilerplate (new model + migration + admin + tests for a known framework)
  • Refactors with a clear shape (rename across files, extract method, move types)
  • Test scaffolding from existing code
  • Diff-style code review (point at a file, ask "what's wrong with this")
  • Documentation generation from code

Bad fits without close supervision:

  • Subtle algorithmic bugs — the model may "fix" the symptom and leave the cause
  • Security-sensitive code paths — review every change byte-by-byte
  • Performance-critical code where the wrong abstraction would be costly

Local LLM workflow

For sensitive code, offline work, or just to avoid API costs, point aider at a local Ollama (see that tutorial):

ollama pull qwen3:32b
ollama pull qwen2.5-coder:32b

export OLLAMA_API_BASE=http://localhost:11434
aider --model ollama/qwen2.5-coder:32b \
      --weak-model ollama/qwen2.5:7b

Quality is lower than frontier API models on hard tasks but acceptable for routine edits, especially with a 32B+ coder-tuned model on a GPU. Latency is bounded by your local hardware, not by API rate limits.

Cost discipline

API-billed models can rack up costs quickly on a large codebase. aider exposes per-prompt token usage on every request (input + output, with cost in USD); summing over a session is helpful for budget. For one-off batch tasks, --no-stream + a fixed token cap (--max-input-tokens, --max-output-tokens) avoids runaway requests. For interactive use, switching between a "thinking" frontier model and a cheaper "editor" model via /architect keeps cost down on the routine steps.