# Aider Deep Dive

## What Is It?

**Aider** is an AI pair programming tool that runs in your terminal. With **39.4k+ stars**, it's one of the most popular open-source coding assistants, known for its excellent Git integration, repository understanding, and multi-model support.

**Repository:** [Aider-AI/aider](https://github.com/Aider-AI/aider)

---

## The Problem It Solves

AI coding assistants often:
- Lack understanding of full repository context
- Don't integrate with version control
- Require switching between tools
- Can't work with local models

Aider provides:
- **Repository-aware editing** via tree-sitter AST analysis
- **Automatic Git commits** for every change
- **Multi-model support** (Claude, GPT, DeepSeek, local)
- **Terminal-first** workflow

---

## Key Statistics

| Metric | Value |
|--------|-------|
| **Stars** | 39,400 |
| **Forks** | 3,800 |
| **Contributors** | 164-218 |
| **Weekly Tokens** | 15 billion |
| **PyPI Downloads** | 4.1 million |
| **License** | Apache 2.0 |

---

## Core Features

### Repository Map

Aider's secret weapon - it creates a graph-based map of your entire codebase using tree-sitter:

- Parses Abstract Syntax Trees (AST) for 100+ languages
- Identifies important code through graph analysis
- Fits context efficiently within token budget
- Dynamically adapts to conversation

### Automatic Git Integration

Every change is automatically committed:

```bash
# Aider commits with descriptive messages
git log --oneline
# a1b2c3d (aider) Add authentication middleware
# d4e5f6a (aider) Fix login validation bug
```

Features:
- Atomic commits per change
- Conventional Commits format
- Easy reversion if needed
- Author attribution with "(aider)"

### Multi-Model Support

| Provider | Models |
|----------|--------|
| **Anthropic** | Claude 3.5/3.7 Sonnet, Opus 4 |
| **OpenAI** | GPT-4o, o1, o3-mini, GPT-5 |
| **DeepSeek** | R1, Chat V3 |
| **Google** | Gemini 2.5 Pro |
| **Local** | Ollama, any OpenAI-compatible |

---

## Installation

```bash
# pip
pip install aider-chat

# pipx (recommended)
pipx install aider-chat

# Homebrew
brew install aider
```

### Quick Start

```bash
# Set API key
export ANTHROPIC_API_KEY=sk-ant-...

# Start in your repo
cd your-project
aider

# Or specify model
aider --model claude-3.5-sonnet
```

---

## Basic Usage

### Add Files to Context

```bash
aider main.py utils.py
# or in chat:
/add src/*.py
```

### Make Changes

```
> Add error handling to the login function

I'll add try-except blocks and proper error messages...
[Shows diff]
[Auto-commits changes]
```

### Commands

| Command | Action |
|---------|--------|
| `/add file` | Add file to context |
| `/drop file` | Remove from context |
| `/diff` | Show all changes |
| `/undo` | Undo last change |
| `/run cmd` | Run shell command |
| `/voice` | Voice input mode |

---

## Architect Mode

Two-phase approach for complex changes:

1. **Architect** (reasoning model): Describes solution
2. **Editor** (coding model): Generates precise edits

```bash
# Enable architect mode
aider --architect

# Or specify models
aider --model o1-preview --editor-model gpt-4o
```

**Results:** o1-preview + DeepSeek Editor achieves 85% on benchmarks.

---

## Benchmark Performance

### SWE-Bench Lite

| System | Score |
|--------|-------|
| **Aider** | 26.3% (SOTA) |
| Amazon Q Developer | 20.3% |

### SWE-Bench Main

| System | Score |
|--------|-------|
| **Aider** | 18.9% (SOTA) |
| Amazon Q Developer | 13.8% |

### How Aider Achieves This

1. Repository map via tree-sitter
2. Graph-based context selection
3. Iterative approach until tests pass
4. No RAG, vector search, or complex agents

---

## Configuration

### Config File

Create `.aider.conf.yml` in your repo:

```yaml
# Model settings
model: claude-3.5-sonnet
editor-model: gpt-4o

# Git options
auto-commits: true
dirty-commits: true

# Context
map-tokens: 1000

# Testing
test-cmd: pytest
lint-cmd: ruff check

# Read conventions
read:
  - CONVENTIONS.md
  - ARCHITECTURE.md
```

### API Keys

```bash
# Environment variables
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...

# Or via config
aider --api-key anthropic=sk-ant-...
```

---

## Voice Coding

```bash
# Enable voice mode
aider

# In chat, use:
/voice
# Speak your request
# Press Enter to send
```

Requirements:
- macOS: `brew install portaudio`
- Linux: `sudo apt-get install libportaudio2`

---

## Comparison to Alternatives

### Aider vs Claude Code

| Aspect | Aider | Claude Code |
|--------|-------|-------------|
| **Interface** | Terminal | Terminal (agentic) |
| **Context** | Token budget | 200k consistent |
| **Git** | Excellent | Good |
| **Autonomy** | Limited | High |
| **Cost** | API-based | ~$8/90 min |
| **Open Source** | Yes | No |

### Aider vs Cursor

| Aspect | Aider | Cursor |
|--------|-------|--------|
| **Interface** | Terminal | IDE (VS Code) |
| **Cost** | Variable | $20/month |
| **Large Projects** | Excellent | Good |
| **Open Source** | Yes | No |

### When to Choose Aider

- Terminal-heavy workflow
- Git-centric development
- Large codebases
- Cost sensitivity
- Need for open-source

---

## Cost & Pricing

**Aider itself:** FREE (open-source)

### API Costs

| Model | Cost Range |
|-------|------------|
| Claude 3.5 Sonnet | $0.003-0.015/1K tokens |
| GPT-4o | $0.005-0.015/1K tokens |
| DeepSeek | Significantly cheaper |
| Ollama | Free (local) |

### Typical Monthly Cost

- Light usage: $5-15
- Moderate: $15-50
- Heavy: $50-200

### Cost Optimization

```bash
# Enable prompt caching (Claude, DeepSeek)
aider --cache-prompts

# Use cheaper models for simple tasks
aider --model gpt-4o-mini
```

---

## Advanced Features

### Browser UI (Experimental)

```bash
aider --browser
# Opens at localhost:5000
```

### MCP Integration

Aider can work with Model Context Protocol:

```bash
# As MCP server for Claude Code
aider-mcp-server
```

### Conventions Files

```yaml
# In .aider.conf.yml
read:
  - CONVENTIONS.md  # Coding standards
  - ARCHITECTURE.md # System design
```

Aider will follow your documented conventions.

---

## Best Practices

### Start Small

```bash
# Add specific files, not entire repo
aider src/auth.py src/utils.py
```

### Use Git Branches

```bash
# Work on feature branch
git checkout -b feature/new-login
aider
```

### Review Diffs

```bash
# Always check before accepting
/diff
```

### Iterate

```bash
# First attempt may not be perfect
> Fix the remaining test failures
```

### Read Conventions

```yaml
# Teach Aider your standards
read:
  - docs/CODING_STANDARDS.md
```

---

## Troubleshooting

### Common Issues

| Issue | Solution |
|-------|----------|
| Context too large | Use `/drop` to remove files |
| Wrong model | Check `--model` flag |
| Git errors | Ensure clean working tree |
| API errors | Verify API key |

### Debug Mode

```bash
aider --verbose
```

---

## Resources

- **Repository:** https://github.com/Aider-AI/aider
- **Website:** https://aider.chat
- **Documentation:** https://aider.chat/docs
- **Discord:** Active community

---

*Aider is the gold standard for terminal-based AI pair programming. If you value Git integration, repository understanding, and model flexibility, Aider delivers all three with a proven track record.*
