====== Aider ======

Aider is an open-source AI pair programming tool created by Paul Gauthier that runs entirely in the terminal. It connects to LLMs like Claude, GPT-4, and Gemini to edit code directly in a local git repository, automatically committing changes with descriptive messages. With over 42,000 GitHub stars and millions of installs, Aider has established itself as a leading terminal-based AI coding assistant through its deep git integration, repository-wide context awareness, and flexible multi-model support.

===== Core Architecture =====

Aider's architecture is built around three key components:

**Repository Map (Tree-sitter)**

Aider generates a structured map of the entire codebase using **Tree-sitter**, a language-agnostic parser generator. This repo map indexes files, functions, classes, methods, and their relationships across 100+ programming languages. Rather than naively concatenating file contents, the map provides the LLM with a compact representation of project structure, enabling:

  * Understanding of cross-file dependencies
  * Identification of relevant context without reading every file
  * Efficient handling of large repositories that exceed context windows

The repo map is generated by parsing all source files into syntax trees, extracting declarations, building a dependency graph, and ranking symbols by relevance using PageRank-like scoring.

**Edit Formats**

Aider supports multiple formats for applying LLM-generated changes:

  * **Whole-file**: Replaces entire files -- suitable for major rewrites or new files
  * **Diff**: Standard unified diff format for precise line-based modifications
  * **Udiff**: Aider's custom micro-diff format that minimizes token usage and reduces errors by making minimal, targeted edits

The edit format is selected based on the model's capabilities -- more capable models use diff/udiff, while others default to whole-file replacement.

**Architect/Editor Pattern**

The **Architect mode** introduces a two-model system that separates reasoning from editing:

  * **Architect LLM** (e.g., Claude Sonnet, o1-preview): Analyzes the problem, designs the solution, and produces a high-level plan without writing code
  * **Editor LLM** (e.g., GPT-4o, DeepSeek): Interprets the architect's plan and generates exact file edits in diff/udiff format

This separation achieves the highest benchmark scores (85% on Aider's code editing benchmark) by optimizing each model for its strength.

===== Git Integration =====

Git is fundamental to Aider's workflow, not an afterthought:

  * Every edit is **automatically committed** with an LLM-generated descriptive message
  * Changes are applied as atomic commits -- multi-file edits are grouped together
  * Users can review changes via ''/diff'' or standard ''git diff''
  * Reverting is trivial: ''git reset HEAD~1'' undoes the last AI change
  * Aider expects to run inside a git repository and will initialize one if needed

This makes AI-assisted changes fully traceable, reviewable, and reversible through familiar git workflows.

===== Multi-File Editing =====

Aider handles coordinated edits across multiple files through:

  * ''/add <files>'': Add files as editable context
  * ''/read-only <files>'': Add files as reference context (prevents accidental modification)
  * The Tree-sitter repo map identifies cross-file dependencies automatically
  * Multi-file diffs are generated in a single LLM response and applied atomically

===== Key Commands =====

<code python>
# Aider workflow examples (terminal commands)

# Start aider with Claude Sonnet in architect mode
# $ aider --sonnet --architect

# Start with GPT-4o
# $ aider --4o

# In-chat commands:
# /add src/auth.py src/models.py    - Add files for editing
# /read-only src/config.py          - Add as read-only context
# /ask "How does the auth flow work?" - Ask without making edits
# /architect                         - Toggle architect mode
# /diff                              - Review pending changes
# /run pytest tests/                 - Run tests after edits
# /undo                              - Undo last change (git reset)
# /tokens                            - Show token usage
# /model claude-3-5-sonnet           - Switch models mid-session

# Example session:
# $ cd /path/to/project
# $ aider --sonnet --architect
# > /add src/api.py src/models.py
# > Add pagination to the /users endpoint with limit and offset params
# (Aider edits both files and auto-commits)
# > /run pytest tests/test_api.py
# (Aider sees test results and can fix failures)
</code>

===== Supported Models =====

Aider works with virtually any LLM provider:

^ Provider ^ Models ^ Best For ^
| Anthropic | Claude 3.5 Sonnet, Claude 3 Opus | Architect + Editor |
| OpenAI | GPT-4o, o1-preview, o1-mini | Editor, general use |
| DeepSeek | DeepSeek Chat V3, DeepSeek R1 | Cost-effective editor |
| Google | Gemini Pro | Alternative provider |
| Local | Ollama, LM Studio, any OpenAI-compatible | Privacy, offline use |

Models are configured via API keys in environment variables (''ANTHROPIC_API_KEY'', ''OPENAI_API_KEY'', etc.) or command-line flags.

===== Benchmark Performance =====

On Aider's code editing benchmark (measuring accurate multi-file changes):

  * **Architect/Editor mode**: 85% accuracy (highest recorded)
  * Top combinations: o1-preview (Architect) + DeepSeek (Editor), o1-preview + Claude 3.5 Sonnet (Editor)
  * Single-model baselines trail due to weaker edit precision
  * The two-step process adds latency but significantly improves correctness

===== Comparison to Alternatives =====

^ Feature ^ Aider ^ Cursor ^ GitHub Copilot ^ Claude Code ^
| Interface | Terminal / chat | Full IDE (VS Code fork) | IDE plugin | Terminal / chat |
| Repo Awareness | Tree-sitter map (whole codebase) | Project-level context | Current file focus | Codebase search |
| File Edits | Multi-file diff/udiff + auto-commit | Inline suggestions | Inline autocomplete | Multi-file edits |
| Git Integration | Auto-commit with descriptive messages | Manual | Manual | Auto-commit |
| Model Flexibility | Any LLM (bring your own key) | Proprietary + OpenAI | OpenAI-focused | Claude only |
| Open Source | Yes (Apache 2.0) | No | No | No |
| Cost Model | Free tool + API costs only | Subscription | Subscription | Subscription / API |

===== Additional Features =====

**Linting and Testing Integration**
  * ''/run'' executes any shell command and feeds output back to the LLM
  * If tests fail after an edit, Aider can automatically attempt to fix the failures
  * Linter output is parsed and used to guide corrections

**Voice and Web Input**
  * Voice input via ''/voice'' for hands-free coding
  * URL scraping via ''/web'' to add documentation or issue context
  * Image input for visual context (UI mockups, diagrams)

===== Installation =====

<code python>
# Install via pipx (recommended)
# $ pipx install aider-chat

# Or via pip
# $ pip install aider-chat

# Or via Homebrew (macOS)
# $ brew install aider

# Quick start
# $ export ANTHROPIC_API_KEY=sk-ant-...
# $ cd /path/to/git/repo
# $ aider --sonnet
</code>

===== References =====

  * [[https://aider.chat|Aider Official Website]]
  * [[https://github.com/Aider-AI/aider|Aider GitHub Repository]]
  * [[https://aider.chat/docs/benchmarks.html|Aider Code Editing Benchmarks]]
  * [[https://aider.chat/docs/repomap.html|Repository Map Documentation]]

===== See Also =====

  * [[taskweaver|TaskWeaver]] - Code-first agent framework with a different approach to code generation
  * [[llm_as_judge|LLM-as-a-Judge]] - Evaluation methodology relevant to coding benchmarks
  * [[agentbench|AgentBench]] - Benchmark that includes coding-related agent tasks