Complete Aider Tutorial: AI Pair Programming in Your Terminal

Aider is an open-source tool that lets you pair program with Large Language Models (LLMs) directly from your terminal. With Aider, you can edit code in your Git repository through natural language conversations, without needing to copy-paste code into a web interface. The tool supports various AI models including GPT-4o, Claude, Gemini, and local models through Ollama.

Why Aider?

In the increasingly crowded AI coding assistant ecosystem, Aider stands out for several reasons:

Installation

Using pip

pip install aider-chat

Using pipx (Recommended)

pipx installs Aider in an isolated environment so it doesn't conflict with your other Python packages:

pipx install aider-chat

Using Homebrew (macOS)

brew install aider

Verify Installation

aider --version

Configuring API Keys

Aider needs an API key from the LLM provider you want to use. Here's how to configure them:

OpenAI

export OPENAIAPIKEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx

Anthropic (Claude)

export ANTHROPICAPIKEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxx

Google Gemini

export GEMINIAPIKEY=xxxxxxxxxxxxxxxxxxxxxxxx

Using a .env File

You can also store API keys in a .env file at the root of your project:

# .env
OPENAIAPIKEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
ANTHROPICAPIKEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxx

Aider will automatically read the .env file when launched.

Basic Usage

Starting an Aider Session

Navigate to your Git repository and run:

cd /path/to/your/project
aider

By default, Aider will use the best available model based on your configured API keys.

Specifying a Model

# Using Claude Sonnet
aider --model claude-sonnet-4-6

Using GPT-4o
aider --model gpt-4o

Using a local model via Ollama
aider --model ollama/deepseek-coder-v2

Adding Files to the Conversation

When starting Aider, you can specify files to edit directly:

aider src/main.py src/utils.py tests/testmain.py

/add src/models.py

$ aider app.py

Add a GET /health endpoint that returns status "ok" and the current timestamp

app.py
<<<<<<< SEARCH
from flask import Flask

app = Flask(name)
=======
from flask import Flask, jsonify
from datetime import datetime

app = Flask(name)

@app.route('/health')
def healthcheck():
    return jsonify({
        'status': 'ok',
        'timestamp': datetime.utcnow().isoformat()
    })
>>>>>> REPLACE

Commit: feat: add health check endpoint with status and timestamp

Aider shows the proposed changes and creates a commit immediately if you approve.

In-Chat Commands

Aider provides many commands you can use within a chat session:

File Management

/add        # Add a file to the conversation (editable)
/read       # Add a file as read-only (for context)
/drop       # Remove a file from the conversation
/ls               # Show currently active files

Git Control

/commit           # Commit pending changes
/undo             # Undo the last commit made by Aider
/diff             # Show the diff from the last change
/git     # Run a git command directly

Navigation

/clear            # Clear chat history
/run     # Run a shell command and show output
/test    # Run tests and ask Aider to fix failures

Advanced Usage

Multi-File Editing

One of Aider's greatest strengths is its ability to edit multiple files simultaneously. This is particularly useful for refactoring:

aider src/models/user.py src/routes/auth.py src/services/userservice.py tests/testauth.py

> Refactor user authentication: move password validation logic from the route 
to userservice.py, add password hashing using bcrypt, and update the tests

# Aider will analyze the entire repository for context
aider --map-tokens 2048 src/main.py

aider --architect --model claude-sonnet-4-6 --editor-model claude-haiku-4-5-20251001

# Make sure Ollama is installed and the model is downloaded
ollama pull deepseek-coder-v2

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

aider --lint-cmd "ruff check --fix" --auto-lint \
      --test-cmd "pytest tests/" --auto-test

model: claude-sonnet-4-6
auto-commits: true
auto-lint: true
lint-cmd: "ruff check --fix"
auto-test: false
test-cmd: "pytest tests/ -x"
map-tokens: 2048

# Add the problematic file and the test file
aider src/parser.py tests/testparser.py

There's a bug in the parsecsv function: when there are empty columns at

the end of a row, the function drops them. Empty columns should be preserved
as empty strings. Fix this bug and add a test case for this scenario.

aider src/api/ src/models/ src/services/

Add pagination to the GET /api/users endpoint. Use cursor-based pagination
with "cursor" and "limit" parameters. Default limit 20, maximum 100.
Response should include "nextcursor" and "hasmore".

# Add files as read-only for context
aider --read src/legacymodule.py src/newmodule.py


Review src/newmodule.py and compare it with legacymodule.py. Make sure

all edge cases from the legacy module are handled in the new module.

aider src/api/routes.py README.md

Create API documentation in README.md based on all endpoints in routes.py.
Include example requests and responses for each endpoint.

/add src/targetfile.py
/read src/referencefile.py

# Less effective
Fix the login function

More effective
In the login() function at line 45, add rate limiting: maximum 5 attempts
per IP address within 15 minutes. Use Redis to store the counter.
Return HTTP 429 if the limit is reached.

/undo
Try a different approach: use a @ratelimit(max=5, window=900) decorator
instead of inline logic

4. Use /run to Verify

After Aider makes changes, verify the results:

/run python -m pytest tests/testauth.py -v
/run python src/main.py --dry-run

aider --commit-prompt "Use conventional commit format (feat:, fix:, refactor:, etc). Write in English."

/read src/config.py        # Context only
/read src/constants.py     # Context only
/add src/main.py           # File to be edited

aider --edit-format diff

docker run -it --rm \
  -v $(pwd):/app \
  -e OPENAIAPIKEY=$OPENAIAPI_KEY \
  paulgauthier/aider \
  --model gpt-4o

Troubleshooting

Model Not Responding Well

If the model produces poor output, try:

Git Conflicts

If conflicts occur when Aider creates commits:

/git stash
/clear
Start a new conversation with clearer context

Token Limits

If the conversation gets too long:

/clear           # Reset chat history
/tokens          # Check current token usage
/drop      # Remove unnecessary files

Conclusion

Aider is a powerful tool for AI-assisted coding directly from the terminal. Its key advantages are native Git integration, multi-file editing capabilities, and support for various AI models. Key takeaways:

• Always start with a small, specific scope
• Use /read to provide context without adding token costs
• Use /undo liberally to iterate
• Configure .aider.conf.yml for consistency across your team
• Consider architect mode for large-scale refactoring

With the right approach, Aider can be a significant productivity multiplier in your development workflow. It's not a developer replacement, but a partner that accelerates iteration and reduces boilerplate work.