Aider: Practical Setup Guide for Open-Source AI Pair Programming

Aider
1

Aider is the open-source terminal AI coding tool that consistently ranks at the top of coding benchmarks. It’s model-agnostic, git-native, and costs only what you spend on API calls — no subscription. This guide takes you from installation to a productive workflow.

Installation

# Recommended: pipx (isolated environment)
pipx install aider-chat

# Alternative: pip
pip install aider-chat

# Verify
aider --version

Aider requires Python 3.9+ and git installed in your path.

Setting Up API Keys

Aider works with virtually any LLM. Set up the one(s) you want:

# Anthropic (Claude)
export ANTHROPIC_API_KEY=sk-ant-xxxxx

# OpenAI (GPT-4o)
export OPENAI_API_KEY=sk-xxxxx

# Google (Gemini)
export GEMINI_API_KEY=xxxxx

# For local models via Ollama
# No API key needed — Aider connects to localhost:11434

Add these to your .bashrc, .zshrc, or shell config so they persist.

Your First Session

cd your-project
aider

Aider starts, indexes your repository, and builds a map of your codebase. You’ll see a prompt where you can type commands or natural language instructions.

Add files to the conversation:

/add src/routes/users.ts src/services/userService.ts

Only added files can be edited by Aider. Other files in the repo are visible for reference (through the repo map) but won’t be modified.

Describe what you want:

Add email validation to the user registration endpoint. 
Use Zod for validation and return a 400 error with a clear 
message if the email format is invalid or the domain doesn't 
have MX records.

Aider edits the files, shows you the diff, and creates a git commit with a descriptive message. Every change is a commit — your git history stays clean.

Choosing the Right Model

Aider’s model flexibility is one of its biggest strengths. Launch with a specific model:

# Claude Sonnet (best all-around for most tasks)
aider --model claude-sonnet-4-20250514

# Claude Opus (heavy reasoning, complex refactoring)
aider --model claude-opus-4-20250514

# GPT-4o (fast, good for simpler tasks)
aider --model gpt-4o

# DeepSeek (strong coding model, lower cost)
aider --model deepseek/deepseek-coder

# Local model via Ollama
aider --model ollama/codellama:34b

Cost-effective strategy: Use Claude Sonnet as your default. Switch to Opus only for complex architectural work. Use local models for simple refactors and exploratory work where quality can be lower but you don’t want API costs.

Configuration File

Create .aider.conf.yml in your project root for persistent settings:

# Default model
model: claude-sonnet-4-20250514

# Auto-commit changes (default: true)
auto-commits: true

# Show diffs in the chat
show-diffs: true

# Encoding for your files
encoding: utf-8

# Files to always include
read:
  - README.md
  - ARCHITECTURE.md

# Dark mode for the terminal UI
dark-mode: true

# Git commit message style
attribute-author: false
attribute-committer: false

Essential Commands

Commands start with / in the Aider prompt:

/add file.ts          — add file to editable context
/drop file.ts         — remove file from context
/read-only file.ts    — add as reference only (not editable)
/ls                   — list files in context
/tokens               — show token usage and costs
/undo                 — undo the last change (git reset)
/diff                 — show current uncommitted changes
/test npm test        — run tests and fix failures
/lint npm run lint    — run linter and fix issues
/run <command>        — run any shell command
/clear                — clear conversation history
/model <name>         — switch model mid-session
/help                 — list all commands

The Git Workflow That Makes Aider Special

Every edit Aider makes creates a git commit. This means:

# See what Aider did
git log --oneline -10

# Don't like the last change? Undo instantly
/undo

# Want to review all AI-generated changes?
git log --author="aider" --oneline

# Cherry-pick specific changes
git cherry-pick <commit-hash>

# Squash multiple Aider commits before pushing
git rebase -i HEAD~5

This git-native approach means you’re never stuck with bad AI output. Rollback is always one command away.

Advanced Workflows

Test-Driven Development with Aider

/test npm test

Here are the failing tests. Fix the implementation in 
src/services/orderService.ts to make all tests pass. 
Don't modify the test files.

Aider reads the test failures, understands what’s expected, and fixes the implementation. If tests still fail, it iterates automatically.

Multi-File Refactoring

/add src/api/*.ts src/services/*.ts src/types/*.ts

Refactor all API routes to use a consistent error handling pattern:
1. Wrap each handler in a tryCatch utility
2. Use typed AppError class for known errors  
3. Log unexpected errors to console.error with request ID
4. Return { error: string, code: string, requestId: string }

Apply this to all route files. Keep the business logic unchanged.

Aider processes each file systematically, applying the same pattern consistently.

Using Web Context

/web https://supabase.com/docs/reference/javascript/auth-signup

Implement user registration using this Supabase auth approach. 
Follow the official documentation pattern.

Aider scrapes the page and uses it as context. This is useful for implementing features based on current documentation rather than training data.

Voice Coding

aider --voice

Aider supports voice input. Describe your changes by speaking instead of typing. Useful for complex instructions where typing is slower than talking.

Cost Management

Since you pay per API call, monitoring costs matters:

/tokens

Shows current session token usage and estimated cost. Strategies to keep costs down:

  • Add only relevant files — don’t /add your entire project
  • Use the repo map — Aider references other files automatically without adding them to editable context
  • Switch to cheaper models for simple tasks
  • Use /clear to reset context when switching tasks
  • Use local models (Ollama) for exploratory work and simple edits

A typical day of active Aider use with Claude Sonnet might cost $2-5 in API fees. Much less than a monthly Cursor subscription if you’re cost-conscious.

Making Aider Work for Teams

For team use:

  1. Commit .aider.conf.yml to the repo so everyone uses the same settings
  2. Add ARCHITECTURE.md with high-level system documentation that Aider can reference
  3. Set up a convention for Aider commit messages so they’re identifiable in git history
  4. Use /test and /lint commands to ensure AI changes meet your quality standards before pushing

What model and workflow combinations work best for you? Share your Aider setup. :backhand_index_pointing_down: