Aider Terminal Setup Guide: Install and Configure AI Pair Programming in Your CLI

Overview

Aider is a command-line AI coding assistant that edits files directly in your local repository. Unlike IDE-based tools, it operates entirely within the terminal — you describe what you want in natural language, and Aider proposes and applies code changes across multiple files.

It works with any LLM that exposes a chat API: OpenAI, Anthropic, Google, or local models via Ollama. Because it integrates with git, every change Aider makes is automatically committed with a descriptive message, giving you a clean undo path.

This guide covers installation on macOS, Linux, and Windows, API key configuration, first-run usage, and practical tips for getting productive fast.

Prerequisites

Before installing Aider, make sure you have these in place:

• Python 3.9+ — Aider is a Python package. Run python --version to check.
• Git — Aider creates commits automatically. It expects to run inside a git repository.
• An API key — from at least one LLM provider (OpenAI, Anthropic, Google, etc.). Local models via Ollama work too, but are slower for complex edits.
• A terminal emulator — any standard terminal works. On Windows, use PowerShell or Windows Terminal rather than the legacy Command Prompt for best results.

Step 1: Install Aider

The recommended installation method is pipx, which installs Aider in an isolated Python environment and avoids dependency conflicts with your other projects.

macOS / Linux:

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

# Install Aider
pipx install aider-chat

# Verify
aider --version

Windows (PowerShell):

# Install pipx
python -m pip install pipx
python -m pipx ensurepath

# Restart your terminal, then:
pipx install aider-chat

# Verify
aider --version

Alternative — plain pip:

pip install aider-chat

This works but risks dependency collisions in shared Python environments. Prefer pipx for a clean setup.

Step 2: Configure Your API Key

Aider needs an API key to communicate with an LLM. The simplest approach is setting an environment variable.

For Anthropic (Claude):

export ANTHROPIC_API_KEY=sk-ant-your-key-here

For OpenAI:

export OPENAI_API_KEY=sk-your-key-here

For Google Gemini:

export GEMINI_API_KEY=your-key-here

To persist the key across terminal sessions, add the export line to your shell profile:

# For bash
echo 'export ANTHROPIC_API_KEY=sk-ant-your-key-here' >> ~/.bashrc

# For zsh (default on macOS)
echo 'export ANTHROPIC_API_KEY=sk-ant-your-key-here' >> ~/.zshrc

Alternatively, create a .env file in your project root:

ANTHROPIC_API_KEY=sk-ant-your-key-here

Aider reads .env automatically. Add .env to your .gitignore to keep your key out of version control.

Step 3: Run Aider in a Project

Navigate to any git repository and launch Aider:

cd /path/to/your/project
aider

That’s it. Aider scans the repo, and you get an interactive prompt where you type natural language instructions. It decides which files to edit, shows you a diff, and commits the changes.

Specifying files explicitly:

aider src/app.py src/utils.py

This limits Aider’s context to just those files, which reduces token usage and keeps the model focused.

Choosing a model:

# Use Claude Sonnet
aider --model sonnet

# Use GPT-4o
aider --model gpt-4o

# Use a specific Anthropic model
aider --model claude-sonnet-4-20250514

$ aider --model sonnet
Aider v0.7x.x
Model: claude-sonnet-4-20250514 with diff edit format
Git repo: .git with 47 files
Repo-map: using 1024 tokens
> Add a health check endpoint to app.py
Applied edit to src/app.py
✓ Commit abcd123: feat: add /health endpoint

Step 4: Essential Commands Inside Aider

Once you’re in the Aider prompt, these commands give you control over the session:

The /undo command is particularly useful. Because Aider auto-commits each change, undoing is always one command away.

Step 5: Create a Configuration File

For project-specific defaults, create a .aider.conf.yml file in your repository root:

# .aider.conf.yml
model: sonnet
auto-commits: true
dark-mode: true
gitignore: true

You can also set user-wide defaults at ~/.aider.conf.yml. Project-level config overrides user-level config.

Common configuration options:

# Model and provider
model: sonnet
# Edit format: diff, whole, udiff
edit-format: diff
# Disable auto-commits if you prefer manual control
auto-commits: false
# Enable pretty, colored output
pretty: true
stream: true
# Map repository structure (helps the model navigate large codebases)
map-tokens: 1024

Step 6: Use Aider With Local Models (Optional)

If you want to avoid API costs entirely, Aider works with local models via Ollama or any OpenAI-compatible endpoint.

# Install Ollama (macOS/Linux)
curl -fsSL https://ollama.com/install.sh | sh

# Pull a coding model
ollama pull deepseek-coder-v2

# Run Aider with the local model
aider --model ollama/deepseek-coder-v2

Local models are slower and less accurate than cloud models for complex multi-file edits, but they work offline and cost nothing beyond electricity. Good for prototyping and simple edits.

Tips and Best Practices

1. Keep context small. Only /add the files Aider actually needs to edit. Dumping your entire codebase into context wastes tokens and confuses the model.

2. Write specific prompts. “Fix the bug” is vague. “The /users endpoint returns 500 when the email field is missing — add validation and return a 422″ gives Aider something concrete to work with.

3. Use /undo freely. Aider commits every change. If a result is wrong, /undo it and rephrase your request. This is faster than trying to manually revert partial edits.

4. Pair it with git branches. Start a feature branch before an Aider session. If the session goes sideways, you can reset the entire branch without affecting main.

5. Check your token usage. Run /tokens periodically. Large repositories with many files in context can burn through API credits fast, especially with Opus-class models.