Aider Guide

Aider is an open-source terminal coding agent that pairs tightly with git — every change the agent makes becomes a commit. It's model-agnostic (Claude, GPT, Gemini, DeepSeek, Ollama, 15+ providers), Apache 2.0, and actively maintained.

Setup

# Recommended — clean, isolated install
python -m pip install aider-install
aider-install

# Or with uv
uv tool install --force --python python3.12 aider-chat@latest

export ANTHROPIC_API_KEY=sk-ant-...
# or OPENAI_API_KEY, GEMINI_API_KEY, etc.

cd your-project
aider src/lib/date.ts src/lib/date.test.ts

How it works

• On launch, Aider scans your repo and builds a lightweight "repo map" (filenames, class/function signatures) that goes into the system prompt.
• You describe a change (/add auth.py then "handle expired tokens by redirecting to login").
• Aider edits the relevant files, runs your tests if configured, and commits automatically on success.
• Every agent action is a git commit — fully reversible with git reset.

Key features

• Git-native — every edit is a commit with a meaningful message. Easy to review, easy to revert.
• Model-agnostic — bring any of 15+ provider keys; route cheap tasks to Haiku or DeepSeek, reasoning to Sonnet / Opus.
• Repo map — Aider gives the model a compressed codebase outline so it can navigate large repos without reading every file.
• Test integration — configure test-cmd in .aider.conf.yml; Aider runs tests after edits and iterates on failures.
• Voice-to-code — speak a change, Aider implements it.
• Browser chat mode — local web UI as an alternative to the terminal.
• Prompt caching — supported for Anthropic models; lowers cost on long sessions.

Config

Aider reads .aider.conf.yml in the project root (or ~/.aider.conf.yml for user-level). Example:

# .aider.conf.yml
model: sonnet
editor-model: haiku # cheap model for small edits
auto-commits: true
test-cmd: pnpm test:run
lint-cmd: pnpm lint

Environment variables are read from .env by default.

Aider edits both files, runs the tests, commits if green, and reports the commit hash.

Gotchas

• Auto-commits can surprise you — if you want to review before commit, run with --no-auto-commits.
• /add vs implicit context — only files you /add are "in the chat"; the repo map shows names but not contents. Forgetting to /add leads to the agent working blind.
• Model switching — --model sonnet mid-session changes model. Good for routing, but mind cost.
• Test-cmd failure handling — if your test command is flaky, Aider will iterate forever trying to make it pass.

Best for

• Developers who live in git and want every change reviewable as a commit
• Teams that want model flexibility (multi-provider, local models via Ollama)
• Open-source contributors — Aider is Apache 2.0

Further reading

• Official docs: aider.chat/docs
• Tool Comparison Matrix — how Aider compares to Claude Code, Cursor, others