Aider is a CLI coding agent that edits your actual files and commits the changes to git. Not a chat window. Not a suggestion sidebar. It reads your codebase, takes an instruction, and writes the code — then commits it with a sensible message. That’s the pitch, and it mostly delivers. (For a full capability assessment before committing to the setup, read the Aider review.)

This guide gets you from zero to productive in under 30 minutes: installation, model configuration, codebase setup, and the workflow patterns that actually save time.

Prerequisites

Before installing Aider, you need:

• Python 3.10 or higher — check with python --version or python3 --version
• git — Aider’s commit integration requires it; initialize a repo before running Aider
• A model endpoint — either an API key (OpenAI, Anthropic, Gemini) or a local Ollama instance

Aider itself is lightweight. The model is the resource requirement. GPT-4o and Claude Sonnet run in the cloud — no local GPU needed. For local models via Ollama, expect 8GB+ RAM for a 7B model (GGUF Q4), 16GB+ for a 13B model.

Installation

Install via pip. A virtual environment is recommended but not strictly required:

pip install aider-chat

Verify:

aider --version

If you’re on a system with both Python 2 and 3, use pip3. On Linux, you may need ~/.local/bin in your PATH — add export PATH="$HOME/.local/bin:$PATH" to your shell profile if aider isn’t found after install.

To update later:

pip install --upgrade aider-chat

Check the Aider GitHub releases page for what changed in each version. The project ships fast — sometimes weekly.

License: Apache 2.0. Free to use, fork, and modify.

Connecting to a model

Aider’s usefulness scales directly with the model you point it at. Here are the three most common configurations.

Option A: OpenAI (GPT-4o)

export OPENAI_API_KEY=sk-...
aider --model gpt-4o

GPT-4o is the default if OPENAI_API_KEY is set and no --model flag is given. It’s capable and fast for code tasks. The cost is real on large codebases with many back-and-forth turns — keep an eye on token usage via aider --show-token-count.

Option B: Anthropic Claude

export ANTHROPIC_API_KEY=sk-ant-...
aider --model claude-3-5-sonnet-20241022

Claude Sonnet is consistently the strongest performer for multi-file refactors and architecture-level changes in the benchmarks that Aider’s maintainer publishes at aider.chat/docs/leaderboards/. If you’re doing anything beyond isolated functions, Claude tends to fewer edit conflicts.

For recent Claude 4.x models, check the leaderboards page — Aider tracks new models quickly.

Option C: Local Ollama (offline, no API cost)

If you have Ollama running, Aider can talk to it via the OpenAI-compatible API:

aider --model ollama/qwen2.5-coder:7b

Make sure Ollama is running first (ollama serve or the desktop app). Replace qwen2.5-coder:7b with whatever model you’ve pulled. For coding tasks, code-specialized models (Qwen2.5-Coder, DeepSeek-Coder, CodeLlama) outperform general-purpose models of the same size.

Realistic expectations with local models: a 7B model will handle single-file changes and simple refactors well. Multi-file architectural work is hit-or-miss. A 32B+ model narrows that gap but needs 24GB+ VRAM. If you need that performance without a local GPU investment, RunPod lets you run large models on rented A100s per-hour — useful for batch refactor sessions.

See Ollama vs LM Studio vs llama.cpp 2026 for a comparison of local runner options.

Persistent configuration with .aider.conf.yml

Instead of passing flags every session, create .aider.conf.yml at your project root:

model: claude-3-5-sonnet-20241022
auto-commits: true
gitignore: true
lint-cmd: ruff check {file}
test-cmd: pytest --tb=short
dark-mode: true

Key settings explained:

• auto-commits — when true, Aider commits after each successful edit. Set false if you want to review diffs before committing.
• gitignore: true — respects .gitignore when deciding which files to read; almost always what you want.
• lint-cmd / test-cmd — Aider runs these after edits and feeds failures back to the model automatically. This is the “architect” feedback loop that makes multi-step fixes work.
• dark-mode — cosmetic, but the diff rendering is much easier to read in dark terminals.

The config file is per-project and safe to commit. Don’t commit your API keys — use environment variables or a .env file in .gitignore.

Excluding files with .aiderignore

By default, Aider will include files you explicitly add to context (see below) plus anything it detects as relevant. To exclude directories it should never read:

# .aiderignore
node_modules/
.next/
dist/
*.lock
coverage/

The format mirrors .gitignore. Aider reads both .gitignore and .aiderignore.

Running Aider: the three modes

Start Aider in your project root:

aider

This opens an interactive prompt. From here, you have three interaction modes:

/code (default)

The main mode. You describe what you want, Aider edits the relevant files and commits.

> Refactor the auth middleware to use JWT instead of sessions. The current implementation is in src/middleware/auth.js.

Aider reads the file, writes the changes, shows you the diff, and commits with a generated message like refactor: migrate auth middleware to JWT.

/ask

Ask questions without making edits. Useful for orientation before touching code.

> /ask What does the payment flow look like? Where does the Stripe webhook handler live?

No file modifications, no commits. Pure Q&A against your codebase.

/architect

Two-model mode: a “planner” model proposes a high-level design, an “editor” model executes it. Useful for larger changes where you want reasoning separated from execution.

aider --architect --model claude-opus-4-7 --editor-model claude-3-5-sonnet-20241022

The architect model is more expensive (it thinks in longer chains) but produces fewer edit conflicts across large diffs. For single-file work, the overhead isn’t worth it.

Adding files to context

Aider won’t read your entire codebase blindly — you control what’s in context. Add files at startup:

aider src/api/routes.py src/models/user.py

Or from inside the session:

> /add src/services/email.py

Remove files:

> /drop src/models/user.py

View what’s currently in context:

> /ls

The repo map feature gives Aider a compressed view of your entire codebase (function signatures, class names, imports) even for files not explicitly added. This is what lets it write correct imports and call existing functions without you specifying every dependency. It works well on codebases up to ~100k tokens of total code; beyond that it degrades.

Workflow patterns that actually save time

Pattern 1: Test-driven fixes. Set test-cmd in your config, then run Aider with a failing test:

> Fix the failing test in tests/test_auth.py. The error is a 401 on requests that should be authenticated.

Aider runs the test, reads the failure output, edits the code, runs the test again, and repeats until it passes or gives up (usually 3 attempts).

Pattern 2: Scoped refactors. Add only the files in scope, state the change precisely:

> /add src/utils/date.py tests/test_date.py
> Replace the manual date parsing with Python's dateutil library. Update the tests accordingly.

Giving Aider a narrow context produces cleaner diffs than letting it roam freely.

Pattern 3: Commit rollback. Every Aider edit is a git commit. If a change breaks something:

git revert HEAD

No special Aider undo command needed — it’s just git.

Pattern 4: Voice of the reviewer. Use /ask before /code on anything non-trivial:

> /ask What are the implications of changing the session store from Redis to in-memory for the test environment?

Then make the change with /code. This surfaces gotchas before they’re baked into a commit.

Comparison: Aider vs alternatives

	Aider	Continue.dev	Cline	GitHub Copilot
Interface	CLI	IDE sidebar	IDE agent panel	IDE inline
File edits	Yes (git-committed)	Yes (inline)	Yes	Yes (inline)
Multi-file	Strong	Moderate	Strong	Weak
Local model support	Yes (Ollama)	Yes (Ollama)	Yes (Ollama)	No
Autonomous mode	Limited	No	Yes	No
Best for	Terminal users, batch refactors	Daily inline completion	Autonomous feature builds	Quick completions

For a deeper comparison, see Continue.dev vs Cline vs Aider 2026.

When NOT to use Aider

You work primarily in an IDE. Aider’s CLI workflow doesn’t integrate with editor keybindings, inline suggestions, or debuggers. If your brain lives in VS Code or JetBrains, Continue.dev or Cline fit better. See Continue.dev + Ollama Setup Guide for that path.

Your codebase is massive and poorly modularized. Aider’s repo map degrades past ~100k tokens of code. A monolith with 500k lines of tightly coupled code will confuse it on multi-file changes. You can work around this by being very deliberate about which files you add to context, but it’s friction.

You need autonomous, multi-step feature builds. Aider handles 3-10 step chains well. For “build me an entire feature from scratch across 20 files” style tasks, Cline’s autonomous agent loop (with Claude Sonnet) is more reliable.

You’re on a slow API connection or want hard cost control. Cloud models bill per token and Aider can consume a lot in an active session. Local Ollama avoids this entirely — see Ollama Review 2026 if you haven’t set it up yet.

You don’t use git. Aider’s workflow is built around commits. Without git, auto-commits don’t work and you lose the rollback safety net. You can run it with --no-auto-commits, but you’re giving up one of its core value props.

The bottom line

Aider earns its reputation for one thing: it actually makes commits. Not suggestions, not diff previews waiting for your approval — it writes the code and commits it. That reliability comes from git being the undo mechanism, which is clever and practical.

Start with a cloud model (Claude Sonnet for quality, GPT-4o for speed), configure .aider.conf.yml with your lint and test commands, and try it on a real failing test. That’s the fastest path to understanding what it can and can’t do for your specific codebase.

If you’re combining it with local models, the Ollama + Open WebUI on Linux setup guide has the foundation steps.