How to Use Aider for AI Pair Programming? Complete Terminal Guide 2026

TL;DR

Aider is an open-source, terminal-based AI pair programming tool that edits code directly in your local Git repository. You chat with it in natural language, it understands your entire codebase via repo-map, makes multi-file edits, and creates atomic Git commits for every change. It works with Claude Sonnet, GPT-5, DeepSeek V4, and local models via Ollama — you're not locked into any vendor. This guide covers installation, multi-model setup, core workflow, architect/editor mode, and best practices that will make you productive in under 30 minutes.

Prerequisites

Before you start, make sure you have:

• Python 3.10+ installed on your system (python3 --version)
• Git installed and configured (git --version)
• pipx for isolated Python tool installation (pip install pipx && pipx ensurepath)
• An API key from at least one LLM provider (OpenAI, Anthropic, DeepSeek, or a local model via Ollama)
• A Git repository to work in — Aider works best inside an existing repo (it auto-commits, so clean Git state is important)

Step 1: Install Aider

The recommended way to install Aider is via pipx, which keeps it in an isolated environment so it won't conflict with your other Python projects.

# Install pipx if you don't have it
python3 -m pip install --user pipx
python3 -m pipx ensurepath

# Install Aider
pipx install aider-chat

After installation, verify it works:

aider --version

# Expected output: aider v0.80.x (or similar)

Alternative install methods:

• pip (not recommended): pip install aider-chat — may conflict with other packages
• Docker: docker pull paulgauthier/aider — good for CI/CD or if you don't want Python on your machine
• One-click install script: Available at aider.chat/docs/install.html for macOS/Linux

Step 2: Set Up API Keys

Aider needs an API key to talk to an LLM. You can use any supported provider. Here are the most common ones:

Option A: Anthropic Claude (Recommended for Best Results)

Claude Sonnet 4 consistently produces the best code quality with Aider.

# macOS/Linux
export ANTHROPIC_API_KEY="sk-ant-..."

# Add to your shell profile for persistence
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.zshrc

Then launch with:

aider --model sonnet

Option B: OpenAI (GPT-5)

export OPENAI_API_KEY="sk-..."

aider --model openai/gpt-5

# Or for a cheaper option:
aider --model openai/gpt-5-mini

Option C: DeepSeek V4 (Cheapest, Open-Source)

export DEEPSEEK_API_KEY="sk-..."

aider --model deepseek/deepseek-chat

Option D: Local Models via Ollama (Free, Private)

# Install Ollama and pull a model
ollama pull qwen3:32b

# Launch Aider with a local model
aider --model ollama/qwen3:32b

Pro tip: You can set a default model in ~/.aider.conf.yml so you don't have to pass --model every time.

Step 3: Your First Aider Session

Navigate to a Git project and launch Aider:

cd ~/projects/my-app
aider

Aider will start in chat mode. You'll see something like:

Aider v0.80.0
Model: claude-sonnet-4-20250514
Git repo: .git with 24 files
Repo-map: using 1024 tokens, auto-refresh
────────────────────────────────────────────────
>

Core Commands

Aider has a few essential slash-commands that you'll use constantly:

Real Example: Add Dark Mode to a React App

Let's walk through a real workflow. Suppose you have a React app and want to add dark mode support:

> /add src/App.tsx src/index.css src/components/ThemeToggle.tsx
Added 3 files to the chat session.

> Add a dark mode toggle using React context. Create a ThemeContext,
  a ThemeProvider that wraps the app, and a ThemeToggle button component.
  Use Tailwind CSS dark: classes. Store the preference in localStorage.

Aider will:

1. Read the files you added
2. Plan the changes using its repo-map understanding
3. Create/Edit the files
4. Run any necessary install commands (e.g., npm install)
5. Auto-commit each logical change with a descriptive message

You'll see output like:

Added src/contexts/ThemeContext.tsx
Edited src/App.tsx
Edited src/index.css
Created src/components/ThemeToggle.tsx

Committing: feat: add dark mode with ThemeContext and localStorage persistence

Step 4: Understand the Repo-Map

One of Aider's killer features is the repo-map — an automatic, high-level index of your codebase that helps the LLM understand your project structure.

The repo-map uses Tree-sitter to parse your code and extract:

• All function and class signatures
• Type definitions
• Import/export relationships
• File structure and hierarchy

This means you don't need to add every file manually. Aider already knows what functions exist, what they're called, and how they relate. When you say "update the authenticate function to support OAuth," Aider searches the repo-map, finds the function, and edits it — even if you never explicitly added that file.

You can see how many tokens the repo-map is using:

aider --map-tokens 2048   # Increase repo-map context (default: 1024)
aider --no-map-tokens      # Disable repo-map (not recommended)

Step 5: Architect/Editor Mode (Advanced)

For complex, multi-file changes, Aider offers Architect/Editor mode — a two-model workflow where:

1. Architect model (reasoning-focused, e.g., Claude Opus or o3) analyzes the problem and produces a detailed plan
2. Editor model (code-generation-focused, e.g., Claude Sonnet or DeepSeek V4) executes the plan

This separation of "thinking" and "doing" dramatically improves results for complex refactors. The architect handles the hard reasoning once, and the editor focuses purely on implementation.

# Use o3 as architect, Sonnet as editor
aider --architect --model openai/o3 --editor-model sonnet

# Use DeepSeek R1 as architect, DeepSeek V4 as editor
aider --architect --model deepseek/deepseek-reasoner --editor-model deepseek/deepseek-chat

When to use Architect mode:

• Large refactors spanning 5+ files
• Database schema migrations
• API redesigns (REST to GraphQL)
• Adding a new architectural layer (auth, caching, event system)

When to skip it (use normal /code):

• Single-file bug fixes
• Adding a simple feature (one component, one route)
• Updating documentation
• Small formatting/style changes

Step 6: Git Integration Deep Dive

Aider's Git integration is not an afterthought — it's core to how the tool works. Every change Aider makes is automatically committed with descriptive messages.

Automatic Git Workflow

1. When you start Aider, it checks for uncommitted changes
2. If there are pre-existing changes, Aider commits them first (so its edits are isolated)
3. Every /code request that results in file changes triggers an atomic commit
4. Commit messages describe what changed and why

Safety Features

# Aider automatically creates a gitignore entry for itself

# to avoid committing its own cache files

# Undo the last Aider commit
> /undo

# See what changed
> /diff

# Explicit commit (rarely needed — usually auto)
> /commit

Working with Branches

# Create a feature branch before big changes
git checkout -b feature/add-auth

# Launch Aider in that branch
aider

# Aider's commits stay on this branch

# You can review, squash, or rebase later

Best practice: Always work on a feature branch when using Aider for non-trivial changes. This gives you a clean rollback path and makes PR review easier.

Step 7: Multi-File Editing & Context Management

Aider can edit multiple files in a single request — but you need to manage context wisely.

Adding Files

# Add specific files
> /add src/auth.ts src/db.ts src/api/routes.ts

# Add all files in a directory
> /add src/components/*.tsx

# Use read-only files (Aider sees them but won't edit)
> /read docs/API_SPEC.md

Context Limits

Every LLM has a context window limit. Aider shows you how much context you're using:

If you're approaching the limit:

• Use /drop <file> to remove files from context
• Use /clear to reset the conversation (repo-map stays)
• Add only the files Aider actually needs to see — not your entire project

In-Chat File Creation

You can ask Aider to create new files without adding them first:

Aider will create the file, add it to the chat, and commit it.

Step 8: Configuration & Customization

The .aider.conf.yml File

Create ~/.aider.conf.yml for persistent settings:

# ~/.aider.conf.yml
model: sonnet
dark-mode: true
map-tokens: 2048
auto-commits: true
git: true
chat-language: English

Per-Project `.aider.conf.yml

Place a .aider.conf.yml in your project root for project-specific settings that override global config:

# ./my-project/.aider.conf.yml
model: openai/gpt-5
read: [docs/STYLE_GUIDE.md, docs/ARCHITECTURE.md]
auto-test: true
test-cmd: npm test

Useful Config Options

Step 9: Cost Management

Aider gives you visibility into what you're spending on API calls.

Tracking Usage

After each session, Aider shows a summary:

Total cost: $0.42
Total tokens: 85,000 prompt + 12,000 completion
Session duration: 12 minutes

Cost-Saving Tips

1. Use DeepSeek for straightforward edits — DeepSeek V4 costs a fraction of Claude/GPT and handles most coding tasks well
2. Use /clear liberally — every message in the chat history adds to the prompt tokens
3. Be specific in your prompts — vague prompts lead to back-and-forth corrections, multiplying costs
4. Set a budget in your config:

# .aider.conf.yml
max-chat-history-tokens: 8000  # Limit accumulated context

Model Cost Comparison (June 2026, approximate)

Step 10: Advanced Workflows

Lint-Fix Cycle

# Set up auto-linting
aider --lint-cmd "eslint --fix src/" --auto-lint

# Aider will run the linter after each change and fix issues automatically

Test-Driven Development with Aider

# Write a failing test first, then ask Aider to make it pass
> /add tests/test_auth.py

> The test `test_login_returns_jwt` is failing. Implement the login
  endpoint in `src/auth.py` to make it pass. Use JWT with HS256.

PR Review Workflow

# Clone the PR branch
git fetch origin pull/42/head:pr-42
git checkout pr-42

# Ask Aider to review
aider --message "Review this PR. Check for security issues, missing error handling, and suggest improvements. Output a structured review."

Multi-Repo Coordination

# Use /read to bring in files from outside the repo
> /read ../shared-library/src/types.ts
> /read ../api-docs/openapi.yaml

# Now Aider can use types and API specs from sibling projects

Troubleshooting

API key not found

Make sure you exported the correct environment variable:

• OpenAI: OPENAI_API_KEY
• Anthropic: ANTHROPIC_API_KEY
• DeepSeek: DEEPSEEK_API_KEY

Run echo $ANTHROPIC_API_KEY to verify. If it returns nothing, re-export it.

Git repository not found

Aider requires a Git repo. Initialize one with:

git init
git add .
git commit -m "Initial commit"

Aider made changes I don't like

# Undo the last Aider commit
> /undo

# Or revert manually
git log --oneline  # Find the Aider commit
git revert <commit-hash>

Context window full" / slow responses

• Use /drop to remove files you no longer need
• Use /clear to start a fresh conversation (repo-map stays)
• Reduce map-tokens if your repo is very large
• Add only the specific files Aider needs, not your entire project

pipx: command not found

python3 -m pip install --user pipx
python3 -m pipx ensurepath

# Restart your terminal or run:
source ~/.zshrc  # or ~/.bashrc

Related Tutorials

• Claude Code vs Aider: Which CLI AI Coding Agent Wins in 2026?
• OpenAI Codex CLI Tutorial: Terminal-First AI Coding Agent
• How to Set Up Cursor Rules for AI Coding: Complete .mdc Guide
• n8n AI Agent Tutorial: Build Your First Automated Workflow