Aider is an AI pair programming tool that runs in your terminal. It connects to LLMs (OpenAI, Claude, Gemini, local models) and makes changes directly to your codebase, committing each edit to git automatically. It builds a repository map to understand your project structure, enabling intelligent multi-file edits.
GitHub: https://github.com/Aider-AI/aider
Docs: https://aider.chat
Website: https://aider.chat
Installation
# Install via pip
pip install aider-chat
# Install via pipx (isolated, recommended)
pipx install aider-chat
# Install via Homebrew (macOS/Linux)
brew install aider
# Verify install
aider --version
# Quick upgrade
pip install --upgrade aider-chat
Configuration
API Keys
# Set API keys in environment
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GEMINI_API_KEY="AIza..."
export DEEPSEEK_API_KEY="sk-..."
# Or pass directly
aider --openai-api-key sk-... --model gpt-4o
# For Ollama (local)
aider --model ollama/llama3.2 --ollama-host http://localhost:11434
Configuration File (.aider.conf.yml)
# .aider.conf.yml (project root or ~/.aider.conf.yml for global)
model: claude-opus-4-5
editor-model: claude-haiku-4-5 # Cheaper model for actual edits
weak-model: gpt-4o-mini # Used for commit messages, etc.
# Git settings
auto-commits: true
dirty-commits: true # Allow commits in dirty repos
commit-prompt: |
Write a concise conventional commit message.
# Display settings
dark-mode: true
pretty: true
stream: true
# Repository
map-tokens: 2048 # Tokens for repo map
map-refresh: auto
# Lint / test
auto-lint: true
lint-cmd:
python: "ruff check --fix {files}"
javascript: "eslint --fix {files}"
auto-test: false
test-cmd: "pytest --tb=short"
Conventions File (.aider.conventions.md)
# .aider.conventions.md
## Code Style
- Use Python 3.11+ type hints everywhere
- Follow PEP 8 with 100-char line length
- Prefer dataclasses over plain dicts for structured data
- Use `pathlib.Path` instead of `os.path`
## Testing
- Write pytest tests for all new functions
- Use `pytest.mark.asyncio` for async tests
- Test file naming: `test_<module>.py`
## Git
- Use conventional commits: feat, fix, docs, refactor, test, chore
- Keep commits atomic (one logical change)
## Architecture
- REST API built with FastAPI
- Database: PostgreSQL via SQLAlchemy 2.0 (async)
- All database access via repository pattern
Core API / Commands
Chat Modes
| Mode | Command | Description |
|---|
| Code | /code <prompt> or default | Make code changes (creates git commits) |
| Ask | /ask <question> | Ask questions without making changes |
| Architect | /architect <prompt> | Plan changes with a capable model, implement with cheaper model |
| Shell | /shell <command> | Run shell commands within aider session |
In-Session Commands
| Command | Description |
|---|
/add <file> | Add file to the chat context |
/drop <file> | Remove file from chat context |
/ls | List files currently in chat |
/git <args> | Run git command from within aider |
/commit | Manually commit current changes |
/undo | Undo last git commit made by aider |
/diff | Show diff of last commit |
/run <cmd> | Run shell command and share output with AI |
/test | Run configured test command |
/lint | Run configured lint command |
/clear | Clear chat history |
/reset | Drop all files and clear history |
/model <model> | Switch model mid-session |
/tokens | Show token usage stats |
/voice | Start voice input |
/paste | Paste clipboard content into chat |
/editor | Open system editor for long prompts |
/exit | Exit aider |
/help | Show all commands |
Model Selection
| Model | Flag | Best For |
|---|
gpt-4o | --model gpt-4o | Fast, cost-effective general coding |
o1 | --model o1 | Complex reasoning, algorithms |
claude-opus-4-5 | --model claude-opus-4-5 | Best quality, complex edits |
claude-sonnet-4-6 | --model claude-sonnet-4-6 | Balance of quality and speed |
gemini/gemini-2.5-pro | --model gemini/gemini-2.5-pro | Long context, competitive |
deepseek/deepseek-chat | --model deepseek/deepseek-chat | Cost-effective alternative |
ollama/llama3.2 | --model ollama/llama3.2 | Local, private |
ollama/deepseek-coder-v2 | --model ollama/deepseek-coder-v2 | Local code model |
Advanced Usage
Starting Aider
# Start with specific files
aider src/main.py src/utils.py
# Start with a model
aider --model claude-opus-4-5
# Start in a specific directory
aider --git /path/to/project
# No auto-commits (manual control)
aider --no-auto-commits
# Read-only files (aider can see but not edit)
aider --read docs/architecture.md
# Watch mode (monitor file changes)
aider --watch-files
# Non-interactive (pipe a message)
echo "Add docstrings to all functions in utils.py" | aider --yes src/utils.py
# Message via flag (great for scripting)
aider --message "Fix the bug in the login function" src/auth.py
Architect Mode (Two-Model Approach)
# Architect mode: powerful model plans, cheaper model implements
aider --architect \
--model claude-opus-4-5 \
--editor-model claude-haiku-4-5
# Or set in config:
# architect: true
# model: claude-opus-4-5
# editor-model: claude-haiku-4-5
# Inside aider session:
> /architect Refactor the database layer to use the repository pattern
Repository Map
# Aider generates a map of your entire repo for context
# Control map token budget
aider --map-tokens 4096 # More context for large repos
# Disable map (saves tokens for small projects)
aider --no-map
# Refresh map more/less frequently
aider --map-refresh always # always, auto, files, manual
# Show the repo map
aider --show-repo-map
Linting and Testing Integration
# Enable auto-lint
aider --auto-lint --lint-cmd "ruff check --fix {files}"
# Enable auto-test
aider --auto-test --test-cmd "pytest tests/"
# Combined: aider will lint after each edit, run tests, and fix failures
aider --auto-lint --auto-test \
--lint-cmd "ruff check --fix {files}" \
--test-cmd "pytest tests/ -x"
# Inside session, manually trigger:
> /lint
> /test
> Fix any failing tests
Git Integration
# Aider auto-commits each change with AI-generated commit messages
# Undo last aider commit:
> /undo
# Or via git:
git reset --soft HEAD~1
# Commit without making changes:
> /commit
# See recent aider commits:
git log --oneline --author="aider"
# Work on a feature branch:
git checkout -b feature/new-api
aider --model gpt-4o src/api.py
# Install voice dependencies
pip install "aider-chat[voice]"
# Start with voice enabled
aider --voice
# Toggle voice in session:
> /voice
# Speak your prompt, then press Enter to send
Non-Interactive / Scripted Usage
#!/bin/bash
# Automated code generation script
# Generate a new module
aider --yes --message "Create a FastAPI router for user authentication with JWT" \
--model gpt-4o \
src/routers/auth.py
# Add tests for it
aider --yes --message "Write pytest tests for the auth router" \
--model gpt-4o \
src/routers/auth.py tests/test_auth.py
# Fix lint issues
aider --yes --message "Fix all ruff linting errors" \
--auto-lint \
--lint-cmd "ruff check --fix {files}" \
src/routers/auth.py
Multi-File Editing
# In aider session:
> /add src/models/user.py src/routers/user.py tests/test_user.py
# Now ask for cross-file changes:
> Add email verification to the user registration flow.
Update the model, add the router endpoint, and write the test.
# Aider edits all 3 files and commits coherently
Common Workflows
New Feature Development
# 1. Start on feature branch
git checkout -b feature/payment-integration
# 2. Open aider with relevant files
aider src/payments/ tests/test_payments.py
# 3. Describe the feature
# > Implement Stripe payment processing with webhook support.
# Create a PaymentService class, handle successful payments and failures.
# 4. Review and test
# > /test
# > /lint
# 5. Iterate
# > The webhook handler needs to verify Stripe signatures before processing.
Bug Fix Workflow
# Add failing test + broken code
aider tests/test_auth.py src/auth.py
# Describe the bug
# > The login endpoint returns 500 when the email has uppercase letters.
# Fix it and update the test to cover this case.
# Verify fix
# > /test
# Commit
# > /commit
Code Review Preparation
# Ask mode — no changes, just analysis
aider --message "Review this file for security issues" \
--no-auto-commits \
src/auth.py
# Use /ask inside session
# > /ask What are the potential security vulnerabilities in this authentication code?
Refactoring
# Load all files involved in the refactor
> /add src/database/ src/repositories/ src/services/
> Refactor all direct database calls in the services layer to
go through repository classes. Keep the existing tests passing.
Tips and Best Practices
| Topic | Recommendation |
|---|
| Model choice | Use Claude Opus or GPT-4o for complex refactors; cheaper models for single-function edits |
| Architect mode | Use --architect for large features; it separates planning from implementation |
| Conventions file | Add .aider.conventions.md to your repo — it dramatically improves output quality |
| File scope | Add only relevant files to chat; avoid adding entire codebase (costs tokens) |
| Repo map | Let aider’s repo map do the heavy lifting for finding related files automatically |
| Auto-lint | Enable --auto-lint to catch syntax errors before committing |
| Undo | /undo is your safety net — use freely, it just reverts the last commit |
| Read-only | Use --read for documentation/spec files aider should reference but not edit |
| Streaming | Keep --stream on (default) to see output as it generates |
| Git commits | Each aider edit produces an atomic, AI-described commit — great for review |
| Voice | Voice input is useful for long prompt dictation without typing |
| Non-interactive | Use --message + --yes for CI/CD automation pipelines |
| Context window | Large files + large repo map = high token usage; use --map-tokens 1024 for smaller models |
