Aider: AI pair programming in your terminal

The Problem

Every AI coding tool on the market makes the same implicit bet: that developers want a GUI. Cursor has its editor fork. Copilot has its VS Code extension. Continue.dev has its sidebar. They all assume you want the AI inside your IDE, rendering diffs in a split pane, managing context through a visual interface.

But what if you don’t use VS Code? What if you live in Vim, Emacs, Helix, or Zed? What if you’re SSH’d into a headless server with no display server at all? What if your workflow is built around tmux panes, git worktrees, and a terminal that hasn’t seen a mouse click in years?

The terminal-native developer faces a stark choice: adopt an IDE you don’t want, or forgo AI assistance entirely. And even IDE users hit a wall when the task spans multiple files, requires deep codebase understanding, or needs clean git history with atomic commits.

Dimension	IDE-Based AI (Cursor, Copilot)	Terminal-Native AI (Aider)
Editor requirement	VS Code fork or extension	Any editor (Vim, Emacs, Helix, Zed, VS Code, JetBrains)
Remote/SSH support	Limited (port forwarding, remote extensions)	Native (runs in any terminal)
Git integration	Manual commits, no auto-commit	Automatic atomic commits per change
Codebase awareness	Open tabs + embeddings	Tree-sitter AST + PageRank repo map
Multi-LLM support	Provider-specific	100+ models via LiteLLM
Air-gap / compliance	Cloud-dependent	Works with local Ollama models
Cost model	Subscription ($10-20/mo)	BYOK (pay per token, ~$0.20-5/day)
Audit trail	Activity log (proprietary)	Full git history with AI-authored commits

Why this matters: The IDE-based AI tools are excellent for inline autocomplete and single-file edits. But they break down on multi-file refactors, remote development, and any workflow that doesn’t fit the IDE’s mental model. Aider solves a different problem: it treats the AI as a pair programmer who works in your git repo, not as a plugin in your editor. This is not a competing approach — it is a complementary one that covers the gaps IDE tools leave open.

The Investigation

Paul Gauthier, Aider’s creator, spent two years systematically investigating why AI coding tools fail on real-world codebases. The answer is not model quality — it is context quality.

Finding 1: Token budgets are the wrong lever.

Every AI coding tool faces the same constraint: the LLM’s context window. The naive solution is to throw more tokens at the problem — dump the entire codebase into the prompt. But context windows are finite (128K-200K tokens on most models), and filling them with irrelevant code actively hurts performance. The model spends its reasoning budget on noise.

Aider’s investigation found that a compressed, ranked map of the codebase outperforms raw file dumps by 20-30% on code editing tasks. The key insight: the model doesn’t need to see every line of every file. It needs to see the right 1,000 tokens — the class signatures, function declarations, and import relationships that define the code’s structure.

What this means: More context is not better context. Aider’s repo map system uses tree-sitter AST parsing to extract only structural metadata (class names, function signatures, type definitions), then ranks files by importance using PageRank on a dependency graph. The result is a 1,000-token map that captures the codebase’s architecture without drowning the model in implementation details.

Finding 2: Edit format determines success more than model choice.

Aider’s benchmark harness runs 225 coding exercises across C++, Go, Java, JavaScript, Python, and Rust (based on Exercism problems). The results reveal a surprising pattern: the same model achieves wildly different pass rates depending on how it’s asked to produce edits.

Edit Format	GPT-4o Pass Rate	Claude 3.5 Sonnet Pass Rate
Whole file rewrite	62%	68%
Search/replace blocks	71%	75%
Unified diff	65%	72%
Architect (plan + edit)	75%	81%

The architect mode — where one model plans and another (or the same model) implements — consistently outperforms single-pass editing by 10-15 percentage points. The reason is straightforward: planning and editing require different cognitive modes. A model that’s trying to reason about the problem while simultaneously formatting a correct diff is doing two things at once, and both suffer.

What this means: If you’re using an AI coding tool and getting mediocre results, the problem is likely not the model — it’s the edit format. Aider’s architect mode separates concerns: the architect reasons freely (no edit format constraints), then the editor translates that plan into precise file changes. This two-pass approach costs twice the tokens but delivers 10-15% better results on every benchmarked model.

Finding 3: Automatic git commits are not a convenience feature — they are a safety mechanism.

Aider auto-commits every change with a descriptive message. This seems like a minor UX nicety. In practice, it is the single most important architectural decision in the tool.

Without auto-commits, every AI edit is a gamble. If the edit is wrong, you need to manually undo it — and if you’ve made other changes since, you’re in merge-conflict territory. With auto-commits, every edit is an atomic, reversible unit. git reset HEAD~1 undoes the last AI change. git log --oneline shows the full edit history. git bisect works across AI and human commits alike.

Aider’s SWE Bench Lite result (26.3%, state-of-the-art at time of publication) relied heavily on this: the agent could try a fix, commit it, run the tests, and if they failed, reset and try again — all without manual intervention.

What this means: Auto-commits transform AI coding from a “hope it works” workflow into a “try, verify, revert if needed” workflow. This is the difference between a toy and a production tool. If your AI coding tool doesn’t auto-commit, you are one bad edit away from losing work.

The Solution

Aider is a ~15,000-line Python application (Apache 2.0 license, 46,000+ GitHub stars, 6.8M+ pip installs) that runs entirely in your terminal. It connects to 100+ LLM providers, builds a structural map of your codebase, and edits files through your local git repository.

┌──────────────────────────────────────────────────────────────────┐
│                        Aider Architecture                         │
│                                                                   │
│  ┌──────────────┐    ┌──────────────────┐    ┌───────────────┐   │
│  │  Terminal     │    │   Coder Class    │    │   LLM Layer   │   │
│  │  (IO System)  │───▶│  (Orchestrator)  │───▶│  (LiteLLM)    │   │
│  │               │    │                  │    │               │   │
│  │  • Read input │    │  • File mgmt     │    │  • OpenAI     │   │
│  │  • Render     │    │  • Message hist  │    │  • Anthropic  │   │
│  │    output     │    │  • Git ops       │    │  • DeepSeek   │   │
│  │  • Tab        │    │  • Cost tracking │    │  • Ollama     │   │
│  │    complete   │    │  • Edit dispatch │    │  • OpenRouter │   │
│  └──────┬───────┘    └──────┬───────────┘    └──────┬────────┘   │
│         │                   │                        │            │
│         │         ┌─────────┴──────────┐             │            │
│         │         │   RepoMap Engine   │             │            │
│         │         │  (tree-sitter +    │             │            │
│         │         │   PageRank)        │             │            │
│         │         └────────────────────┘             │            │
│         │                                            │            │
│  ┌──────┴────────────────────────────────────────────┴────────┐  │
│  │                    Edit Strategies                          │  │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │  │
│  │  │ EditBlock    │  │ WholeFile    │  │ ArchitectCoder   │  │  │
│  │  │ (surgical    │  │ (full file   │  │ (plan + edit,    │  │  │
│  │  │  line edits) │  │  rewrites)   │  │  2-model flow)   │  │  │
│  │  └──────────────┘  └──────────────┘  └──────────────────┘  │  │
│  └────────────────────────────────────────────────────────────┘  │
│                                                                   │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │              Git Integration (GitRepo)                     │  │
│  │  Auto-commit → git add → git commit → descriptive message │  │
│  └────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────┘

Here’s what each piece does:

• Terminal IO System: Reads your natural language input, renders model responses with syntax-highlighted diffs, and provides tab completion for file paths, commands, and symbols from your codebase.
• Coder Class: The central orchestrator. It manages which files are in the chat context, maintains conversation history, coordinates with the git repo and repo map, and dispatches edits to the appropriate strategy. The Coder.create() factory method instantiates the right subclass based on the edit format.
• LLM Layer (LiteLLM): Abstracts across 100+ model providers. You configure a main model (for reasoning and planning) and optionally an editor model (for implementing edits). Supports reasoning tokens, streaming, and cost tracking.
• RepoMap Engine: Uses tree-sitter to parse source files into ASTs, extracts symbol definitions and references, builds a dependency graph, and runs PageRank to rank files by importance. The top-ranked symbols are compressed into a ~1,000-token map that fits in every prompt.
• Edit Strategies: Three core strategies — EditBlock (surgical line replacements), WholeFile (full file rewrites), and ArchitectCoder (two-model plan-then-edit). Each strategy formats the LLM’s response differently and applies changes to the filesystem.
• Git Integration: After every successful edit, Aider runs git add, git commit with an AI-generated message, and attributes the commit to the AI assistant. Every change is atomic and reversible.

Setup

# Install via pip
pip install aider-chat

# Or via brew (macOS)
brew install aider

# Set your API key
export ANTHROPIC_API_KEY=sk-ant-...
# or
export OPENAI_API_KEY=sk-...

# Launch in your project directory
cd /path/to/your/project
aider

# Launch with specific model
aider --model claude-sonnet-4-20250514

# Launch with architect mode (two-model workflow)
aider --model claude-sonnet-4-20250514 --architect

# Launch with local model via Ollama
aider --model ollama/deepseek-coder-v2 --ollama

Production-Grade Configuration

# .aider.conf.yml — place in project root or ~/
model: claude-sonnet-4-20250514
editor-model: claude-sonnet-4-20250514
architect: true
auto-commits: true
auto-lint: true
auto-test: true
map-tokens: 1024
git: true
gitignore: true
lint-command: "ruff check --fix {filename}"
test-command: "pytest -x {filename}"

Code Walkthrough: The Core Loop

The heart of Aider is the Coder class in aider/coders/base_coder.py. Here is the simplified request-processing flow:

# Simplified from aider/coders/base_coder.py
class Coder:
    def run(self, message: str) -> str:
        """Process a user message and return the response."""
        # 1. Build the repo map (compressed codebase context)
        repo_map = self.repo_map.get_repo_map(
            self.abs_fnames,          # files in chat context
            self.get_chat_files(),     # files mentioned in conversation
            self.get_relevant_snippets()  # identifiers from chat
        )

        # 2. Assemble the full prompt
        prompt = self.format_prompt(
            message=message,
            repo_map=repo_map,
            chat_history=self.cur_messages[-10:],  # last 10 turns
            read_only_files=self.abs_read_only_fnames,
        )

        # 3. Send to LLM via LiteLLM
        response = self.send_completion(prompt)

        # 4. Parse the response for edit blocks
        edits = self.parse_edits(response)

        # 5. Apply edits to filesystem
        for edit in edits:
            self.apply_edit(edit)

        # 6. Lint and fix
        if self.auto_lint:
            self.lint_and_fix()

        # 7. Run tests
        if self.auto_test:
            self.run_tests()

        # 8. Git commit
        if self.auto_commits:
            commit_msg = self.generate_commit_message(edits)
            self.repo.commit(commit_msg)

        return response

The repo map generation is the most architecturally interesting piece:

# Simplified from aider/repomap.py
class RepoMap:
    def __init__(self, root: Path, token_limit: int = 1024):
        self.root = root
        self.token_limit = token_limit
        self.graph = nx.Graph()  # dependency graph
        self.parser = tree_sitter_parser()

    def get_repo_map(self, chat_files, mentioned_files, mentioned_idents):
        """Build a compressed map of the codebase."""
        # 1. Parse all source files with tree-sitter
        for file in self.root.rglob("*.py"):
            ast = self.parser.parse(file.read_text())
            symbols = self.extract_symbols(ast)
            refs = self.extract_references(ast)

            # 2. Build dependency graph
            for ref in refs:
                target = self.resolve_reference(ref, symbols)
                if target:
                    self.graph.add_edge(file, target.file)

        # 3. Run PageRank
        ranks = nx.pagerank(self.graph)

        # 4. Personalize: boost chat files and mentioned symbols
        for f in chat_files:
            ranks[f] *= 2.0
        for ident in mentioned_idents:
            for file in self.files_containing(ident):
                ranks[file] *= 1.5

        # 5. Binary search: fit top-ranked symbols into token budget
        ranked_files = sorted(ranks, key=ranks.get, reverse=True)
        return self.compress_to_token_limit(ranked_files, self.token_limit)

How to Use Effectively

Step 1: Add only the files that need editing

# Start Aider in your project
cd ~/projects/myapp
aider

# Add files to the chat context
/add src/auth/login.py
/add src/auth/session.py

# Now describe the change
"Add rate limiting to the login endpoint. Use a sliding window of 5 attempts per minute per IP address."

Aider only edits files you explicitly add with /add. Adding too many files “just in case” is the #1 cause of bad edits — irrelevant code distracts the model. The repo map already provides structural awareness of the rest of the codebase.

Step 2: Use architect mode for multi-file changes

# Switch to architect mode
/architect

# Describe a complex change
"Refactor the payment processing pipeline to support Stripe and PayPal. Extract a common PaymentGateway interface, implement both providers, and update the checkout controller."

# Aider's architect model will propose a plan first.
# Review the plan, then approve it.
# The editor model implements the plan as file edits.

The architect mode is the single highest-impact pattern in Aider. It separates planning from implementation, which reduces errors by 10-15% on every benchmarked model. Use it by default for any change that touches more than one file.

Step 3: Review diffs before accepting

# After each edit, Aider shows the diff
# Read it carefully before continuing

# If the edit is wrong, undo it
/git reset HEAD~1 --hard

# Or use git directly
git log --oneline
git show HEAD
git reset HEAD~1

Production pitfall: A bad edit buried under three later commits requires interactive rebase to untangle. Review every commit as it happens. The 30 seconds of diff review saves 30 minutes of debugging.

Step 4: Use /ask for questions, /code for edits

# Ask about the codebase without making changes
/ask "What's the authentication flow? Walk me through the middleware chain."

# The model answers without editing any files.
# When you're ready to make changes, switch to code mode:
/code "Add a JWT refresh token endpoint to the auth router."

Aider has three chat modes: /code (edit files), /ask (questions only), and /architect (plan then edit). Using the right mode for each interaction keeps the model focused and reduces context pollution.

Step 5: Create conventions files for consistent output

# Create a CONVENTIONS.md in your project root
cat > CONVENTIONS.md << 'EOF'
# Coding Conventions

## Python
- Use type hints on all function signatures
- Prefer Pydantic models over raw dicts
- Use async/await for all I/O operations
- Logging: use structlog, not print
- Error handling: raise custom exceptions, not bare Exception

## Testing
- Write pytest tests for all new functions
- Use fixtures, not setup methods
- Mock external services, not internal functions
EOF

# Aider reads CONVENTIONS.md automatically and includes it in every prompt

Production pitfall: Without conventions, Aider will use whatever style the training data suggests — which may not match your project’s standards. A CONVENTIONS.md file is the cheapest way to enforce consistent output. It costs zero tokens to maintain and saves hours of cleanup.

Use Cases

1. Rapid Prototyping

When you’d use this: You have an idea for a new feature and want a working prototype in hours, not days.

Why Aider fits: Aider’s terminal-native workflow means you can iterate fast — describe a change, see the diff, test it, repeat. No context switching between editor and terminal. Real-world examples include an alt-text generator built in 4 hours ($4 in API costs) and a federated trip-sharing platform where 87% of 3,513 lines were written by Aider in 3 days ($8 in API costs).

2. Multi-File Refactoring

When you’d use this: You need to extract a shared interface, rename a module, or restructure a subsystem across 5-10 files.

Why Aider fits: The repo map gives the model structural awareness of the entire codebase. Architect mode plans the refactor before touching files. Auto-commits make every step reversible. This is the use case where IDE-based tools (which only see open tabs) consistently fail.

3. Learning a New Language or Framework

When you’d use this: You’re writing Rust for the first time, or migrating from Express to Fastify.

Why Aider fits: You describe what you want in natural language, and Aider writes idiomatic code in the target language. The repo map shows the model your project’s existing patterns, so new code matches your conventions. Real-world examples include a Cardano blockchain parser written in Rust and a Kotlin-based federated app — both built by developers learning the language as they went.

4. Remote/SSH Development

When you’d use this: You’re developing on a headless server, a cloud VM, or a Raspberry Pi.

Why Aider fits: Aider runs in any terminal. No display server, no IDE, no browser needed. SSH into your server, run aider, and start coding. This is the use case that no IDE-based tool handles well.

5. Compliance and Air-Gapped Development

When you’d use this: Your organization requires all code to stay on-premises, or you’re working with classified data.

Why Aider fits: Aider works with local models via Ollama. No data leaves your machine. The entire tool is Apache 2.0 licensed — fully auditable, forkable, and air-gappable. You pay for electricity, not API tokens.

Cheat Sheet

Aspect	Detail
Repository	github.com/Aider-AI/aider
License	Apache 2.0
Language	Python (~15,000 lines)
GPU Requirements	None (API-based); optional for local models via Ollama
Setup Time	2 minutes (pip install + API key)
Key Features	Auto-commit, repo map (tree-sitter + PageRank), architect mode, 100+ LLM providers, voice-to-code, lint/test auto-fix
Common Gotchas	Forgetting /add before editing; adding too many files; one big prompt instead of atomic steps; not reviewing diffs; skipping /clear when context drifts
Best Models	Claude Sonnet 4, GPT-4o, DeepSeek V4-Flash, Claude Opus 4
Cost (Light)	$0.20-0.40/day (Sonnet, 1-2 sessions)
Cost (Heavy)	$5.00+/day (Sonnet, 20+ sessions)
Cost (Local)	$0 (electricity only, via Ollama)
Missing Features	No MCP support, no browser tool, no tab autocomplete, no native IDE UI

Vibe Coding Projects

Project 1: CLI Todo App with Natural Language Parsing

What it does: A command-line todo application that accepts natural language input like “add buy groceries due tomorrow high priority” and parses it into structured tasks with due dates, priorities, and tags. Stores tasks in SQLite, supports filtering and search.

What you’ll learn: How to use Aider for rapid prototyping from scratch. How to iterate on a CLI interface, add a database layer, and implement NLP parsing — all through natural language prompts. You’ll see how Aider handles the full stack from main.py to schema design.

Effort: 2-3 hours. ~$1-2 in API costs.

Project 2: FastAPI Blog Engine with Admin Dashboard

What it does: A full-featured blog engine with FastAPI backend, Jinja2 templates, SQLAlchemy ORM, markdown rendering, user authentication, and an admin dashboard for managing posts. Deployable with a single docker-compose up.

What you’ll learn: Multi-file project structure with Aider. How to use architect mode for planning the data model and API routes before writing code. How to use /add strategically to keep the model focused on the right files. How to use CONVENTIONS.md to enforce project-wide patterns.

Effort: 4-6 hours. ~$5-8 in API costs.

Project 3: Rust CLI Tool for File Deduplication

What it does: A high-performance file deduplication tool written in Rust. Scans directories, computes SHA-256 hashes, identifies duplicates, and offers interactive or automatic cleanup. Uses rayon for parallel processing and clap for CLI argument parsing.

What you’ll learn: How to use Aider to write code in a language you may not know well. How the repo map helps the model understand Rust’s module system and ownership model. How to use /test to run cargo test after every change and let Aider fix compilation errors automatically.

Effort: 3-5 hours. ~$3-5 in API costs.

Problems Solved Efficiently

Problem Type	Why Aider Fits	When to Look Elsewhere
Single-file feature additions	Fast iteration, auto-commit, surgical edits	Use Copilot/Cursor for inline autocomplete
Multi-file refactoring	Repo map + architect mode for structural awareness	Use Cursor for visual diff review
Greenfield prototyping	Rapid iteration, no setup overhead	Use Lovable/v0 for UI-first prototypes
Remote/SSH development	Runs in any terminal, no GUI needed	No alternative exists for this use case
Learning new languages	Model writes idiomatic code, you review	Use Copilot for inline suggestions in familiar languages
Compliance/air-gap	Local models via Ollama, Apache 2.0 license	Use Cursor Enterprise for managed compliance
Large codebase navigation	Repo map finds relevant files without manual search	Use Sourcegraph for code search and discovery
Automated git workflows	Auto-commit, commit messages, full audit trail	Use GitHub Actions for CI/CD automation

Architectural Tradeoffs

What we gained:

• Editor agnosticism. Aider works with Vim, Emacs, Helix, Zed, VS Code, JetBrains, or any editor that can write to a filesystem. You never outgrow it by switching editors.
• Git-native safety. Every edit is an atomic commit. Undo is git reset HEAD~1. Bisect works across AI and human changes. This is the strongest safety guarantee of any AI coding tool.
• Codebase awareness without token waste. The repo map compresses structural knowledge into ~1,000 tokens. IDE-based tools either dump entire files (token waste) or rely on embeddings (context drift).
• Multi-LLM flexibility. No vendor lock-in. Switch between Claude, GPT, DeepSeek, or local models with a single flag. Use the best model for each task.
• Cost transparency. You pay per token, not per seat. Light usage costs $6-12/month. Heavy usage costs $150+/month. Local models cost nothing.

What we sacrificed:

• No tab autocomplete. Aider is a chat interface, not an inline suggestion engine. You type, it responds. For developers who want continuous inline suggestions, Copilot or Cursor are better choices.
• No MCP support. Aider cannot connect to external tools, databases, or APIs through the Model Context Protocol. Cursor and Cline have this; Aider does not.
• No browser interaction. Aider cannot open a browser, click buttons, or scrape dynamic pages. Cline and Webwright can.
• Steeper learning curve. The terminal interface, slash commands, and /add//drop workflow take a few days to internalize. Cursor works out of the box.
• No visual diff review. Aider shows diffs as terminal output. Cursor shows them in a split pane with syntax highlighting and inline accept/reject buttons.
• Context drift in long sessions. The conversation history grows, and the model starts to forget earlier context. IDE tools have the same problem, but Aider’s terminal interface makes it harder to notice until the model starts producing irrelevant output.

The real lesson: Aider and IDE-based tools are complements, not competitors. Use Aider for multi-file refactoring, remote development, and git-native workflows. Use Copilot or Cursor for inline autocomplete and visual diff review. The developers who get the most out of AI coding tools run both — and switch between them based on the task.

Course-Style Deep Dive

How the Repo Map Works Under the Hood

The repo map is Aider’s most architecturally distinctive feature. Here is how it works, step by step:

1. AST Parsing. Aider uses tree-sitter to parse every source file in your git repository into an abstract syntax tree. Tree-sitter is a incremental parser that handles 100+ languages and produces a concrete syntax tree with precise node positions.

2. Symbol Extraction. From each AST, Aider extracts:

   • Definitions: class declarations, function/method signatures, type aliases, import statements, variable declarations at module scope
   • References: function calls, class instantiations, attribute accesses, import usages

3. Dependency Graph Construction. Each file becomes a node in a graph. An edge exists from file A to file B if A defines a symbol that B references. The graph is directed and weighted — more references = stronger edge.

4. PageRank Ranking. Aider runs Google’s PageRank algorithm on the dependency graph. Files that are referenced by many other files (utility modules, base classes, shared types) get higher ranks. Files that reference many other files (controllers, orchestrators) also get a boost.

5. Personalization. The base PageRank is personalized based on:

   • Files currently in the chat context (2x weight boost)
   • Files mentioned in the conversation (1.5x weight boost)
   • Identifiers mentioned in the user’s message (1.5x weight boost for files containing those identifiers)

6. Token Budget Compression. Aider uses binary search to find the optimal amount of structural context that fits within the token limit (default 1,024 tokens). It starts with the highest-ranked symbols and adds lower-ranked ones until the token budget is exhausted.

Advanced Pattern 1: Two-Model Architect Workflow

# Use a reasoning model for planning, a fast model for editing
aider --model o1-preview --editor-model claude-sonnet-4-20250514 --architect

# Or use the same model for both roles
aider --model claude-sonnet-4-20250514 --architect

The architect mode creates two Coder instances internally. The first (architect) receives your request and produces a natural-language plan. The second (editor) receives the plan and produces file edits. The two instances share the same repo map and file context, but use different model configurations.

# Conceptual flow of ArchitectCoder
class ArchitectCoder(AskCoder):
    def run(self, message):
        # Phase 1: Architect reasons about the problem
        plan = self.architect_model.send(message + self.repo_map)

        # Phase 2: Editor implements the plan
        editor_coder = Coder.create(
            self.editor_model,
            edit_format="editor-diff",
            repo=self.repo,
            fnames=self.abs_fnames,
        )
        result = editor_coder.run(with_message=plan)

        # Sync git state and costs back
        self.sync_commits(editor_coder)
        self.sync_costs(editor_coder)
        return result

Advanced Pattern 2: Custom Edit Formats

Aider’s edit strategies are pluggable. You can create a custom edit format by subclassing EditCoder and implementing get_edits():

# Conceptual: custom edit format
class MyCustomCoder(EditCoder):
    edit_format = "my-custom-format"

    def get_edits(self, response):
        """Parse the LLM response into Edit objects."""
        edits = []
        for block in self.parse_blocks(response):
            if block.type == "replace":
                edits.append(Edit(
                    path=block.path,
                    old_lines=block.old.splitlines(),
                    new_lines=block.new.splitlines(),
                ))
        return edits

Production Considerations

Rate limiting. Aider makes one LLM call per user message. If you’re running automated scripts or batch processing, you may hit API rate limits. Configure retry logic in your LiteLLM settings:

# ~/.aider.conf.yml
litellm:
  retry: 3
  retry_delay: 5  # seconds
  max_retry_delay: 60

Error handling. Aider’s lint-and-fix loop can enter an infinite cycle if the linter and the model disagree on formatting. Set a maximum fix iteration:

# ~/.aider.conf.yml
max-fix-iterations: 3

Cost monitoring. Aider tracks token usage and cost per session. Use the /tokens command to see current usage. Set a budget cap:

# ~/.aider.conf.yml
max-cost: 5.00  # USD, per session

Context window management. Long sessions accumulate conversation history. Use /clear to reset the history when the model starts producing irrelevant output. For very long tasks, restart Aider entirely rather than continuing a stale session.

The Results

Metric	Before Aider	After Aider	Improvement
Multi-file refactor time	2-4 hours (manual)	15-30 minutes (Aider)	4-8x faster
SWE Bench Lite score	20.3% (Amazon Q)	26.3% (Aider + GPT-4o)	+6 pts SOTA
Exercism pass rate (GPT-4o)	53% (single pass)	75% (architect mode)	+22 pts
Exercism pass rate (Claude 3.5)	60% (single pass)	81% (architect mode)	+21 pts
Files correctly identified	—	70.3% (repo map)	Baseline for comparison
Cost per refactor (Sonnet)	—	$0.20-0.40	Pay-per-use
Learning curve	—	2-3 days	Steeper than Cursor

What this means for you: Aider is not a replacement for your editor — it is a replacement for the manual, multi-file, context-switching work that your editor cannot help with. The 4-8x speedup on refactoring tasks is real and reproducible. The key is using the right workflow: architect mode for planning, atomic prompts for execution, and auto-commits for safety.

What to Watch Out For

1. Start with one file. When you’re new to Aider, add exactly one file to the chat context and make one change. Get comfortable with the diff output, the commit flow, and the undo mechanism before attempting multi-file changes.

2. Use /architect by default. For any change that touches more than one file, or any change you’re not 100% sure about, use architect mode. The 30 seconds of plan review saves 30 minutes of fixing wrong directions.

3. Review every commit. After each Aider edit, run git show HEAD or look at the diff Aider prints. If something looks wrong, undo immediately with git reset HEAD~1 --hard. Do not stack changes on top of unverified edits.

4. Keep sessions short. Aider’s context window fills up with conversation history. After 10-15 exchanges, the model starts to forget earlier context. Use /clear to reset the history, or restart Aider entirely for a fresh session.

5. Don’t let Aider choose libraries. Aider will pick trendy but unstable libraries, or libraries with APIs that don’t match your project’s patterns. Tell Aider explicitly which libraries to use: “Use httpx for HTTP requests, not requests or aiohttp.”

6. Use /run and /test to share errors. When a test fails or a command errors, paste the output into Aider. It can see the error and fix it. Without the error output, Aider is guessing at what went wrong.

7. Create a CONVENTIONS.md. This single file is the highest-leverage configuration you can make. It costs nothing to maintain and ensures every AI edit follows your project’s patterns.

Lesson 1: “The first 2-3 days with Aider feel like fighting the tool. The disciplines compound over weeks. Most users bounce before reaching the productivity zone.” — Aider community, r/ClaudeAI

Lesson 2: “Model choice matters less than prompt quality. A clear atomic prompt works on most capable models. A vague prompt fails on all of them.” — Aider creator, Paul Gauthier

Lesson 3: “I traded short-term productivity for deeper understanding. Aider wrote 87% of the code, but I had to understand every line to review it. The code was written in 3 days. The understanding took weeks.” — WueRide author, Stefan Siegl

Advice for Getting Started

1. Install Aider in a non-critical project first. A toy project, a personal tool, or a side project. Make mistakes there.
2. Run aider --model claude-sonnet-4-20250514 --architect as your default. This gives you the best model with the best workflow.
3. Add CONVENTIONS.md to your project before your first real edit. It costs 2 minutes and prevents hours of cleanup.
4. Use /add to add exactly the files you want changed. Never add files “just in case.”
5. After every edit, read the diff. If it looks wrong, undo it. If it looks right, move to the next atomic change.
6. When you get stuck, use /clear to reset the conversation history. A fresh context is better than a polluted one.
7. Run Aider alongside your existing editor. Use your editor for inline editing and autocomplete. Use Aider for multi-file refactoring and complex changes. They complement each other.

---

Next in the Open-Source AI Tools Mastery series: Continue.dev