How to Set Up Aider: A Practical Guide

TL;DR

• Install Aider with pip install aider-chat and set up an LLM API key (OpenAI/Anthropic/Ollama).
• Add files to context with /add <file> or /add --all for full repo awareness.
• Use /diff for precise edits, /whole for full-file rewrites, and /architect for multi-file refactors.
• Git integration auto-commits changes with descriptive messages.
• Configure .aider.conf.yml to save model settings and default behaviors.

1. Installation and Model Setup

Install Aider

# macOS/Linux (Python 3.9+ required)
python -m pip install --upgrade aider-chat

# Windows (PowerShell)
python -m pip install --upgrade aider-chat

# Verify installation
aider --version
# Expected output: aider 0.36.0

Gotcha: If you get a command not found error, ensure ~/.local/bin is in your PATH:

export PATH=$PATH:~/.local/bin  # Add to ~/.bashrc or ~/.zshrc

Set Up an LLM

Aider supports OpenAI, Anthropic, Mistral, and local models via Ollama. Choose one:

Option 1: OpenAI (GPT-4o)

1. Get an OpenAI API key.
2. Set the key as an environment variable:

   export OPENAI_API_KEY="your-key-here"
   

   Copy
3. Start Aider:

   aider
   

   Copy

Option 2: Anthropic (Claude 3.5 Sonnet)

1. Get an Anthropic API key.
2. Set the key and model:

   export ANTHROPIC_API_KEY="your-key-here"
   aider --model claude-3-5-sonnet-20240620
   

   Copy

Option 3: Local Models (Ollama)

1. Install Ollama and pull a model:

   ollama pull llama3
   

   Copy
2. Start Aider with the local model:

   aider --model ollama/llama3
   

   Copy

Expected Output:

Aider v0.36.0
Model: claude-3-5-sonnet-20240620 with diff edit format
Git repo: .git with 12 files
Repo-map: using 1.2MB of 2.0MB
Use /help to see in-chat commands.

2. Adding Files to Context

Aider needs to "see" your code to edit it. Use these commands in the chat:

Example Workflow:

# Start Aider in your project directory
cd ~/projects/my-app
aider

# Add key files to context
/add src/utils.py
/add tests/test_utils.py

Gotcha: Large repos (10K+ files) may slow down Aider. Use /add selectively for files relevant to your task.

3. Edit Modes

Aider offers three edit modes. Choose based on precision needs:

1. /diff (Default)

• Shows a diff of proposed changes before applying.
• Best for small, precise edits.

Example:

User: /diff
Aider: Describe the change you want...
User: Refactor the `validate_input` function to use early returns.

Expected Output:

- def validate_input(data):
-     if not data:
-         return False
-     if len(data) > 100:
-         return False
-     return True
+ def validate_input(data):
+     if not data:
+         return False
+     if len(data) > 100:
+         return False
+     return True

Type y to apply the changes.

2. /whole

• Rewrites the entire file.
• Use for major refactors or when /diff is too restrictive.

Example:

User: /whole src/utils.py
Aider: What changes do you want to make to this file?
User: Rewrite the file to use type hints and add docstrings.

3. /architect

• Multi-file refactors with high-level guidance.
• Best for cross-file changes (e.g., "Move the auth logic to a new module").

Example:

User: /architect
Aider: What architectural change do you want to make?
User: Split the monolithic `handlers.py` into separate files per route.

4. Git Integration and Auto-Commits

Aider auto-commits changes with descriptive messages. Configure this in .aider.conf.yml:

# .aider.conf.yml
git:
  auto_commits: true
  commit_message: "aider: {message}"  # Customize commit message format

Commands:

Gotcha: Auto-commits may clutter your history. Use /commit for manual control or squash later:

git rebase -i HEAD~5  # Squash aider commits

5. Using Local Models via Ollama

For privacy or cost savings, use local models:

1. Install Ollama and pull a model:

   ollama pull codellama:7b
   

   Copy
2. Start Aider with the local model:

   aider --model ollama/codellama:7b
   

   Copy
3. (Optional) Configure defaults in .aider.conf.yml:

   model: ollama/codellama:7b
   

   Copy

Performance Tip: Use smaller models (e.g., codellama:7b) for faster responses, but expect less accuracy than GPT-4o.

6. Multi-File Editing Workflows

Aider shines for cross-file changes. Example:

Task: Add Logging to a Module

1. Add relevant files to context:

   /add src/app.py
   /add src/utils/logger.py
   

   Copy
2. Describe the change:

   Add debug logging to all functions in `app.py`. Use the logger from `utils/logger.py`.
   

   Copy
3. Aider will:
   • Import the logger in app.py.
   • Add logger.debug() calls to each function.
   • Update logger.py if needed (e.g., add a debug method).

Gotcha: Multi-file edits may fail if the LLM loses context. Break large tasks into smaller steps.

7. Configuration and .aider.conf.yml

Save settings in .aider.conf.yml to avoid repeating flags:

# .aider.conf.yml
model: claude-3-5-sonnet-20240620
dark_mode: true
git:
  auto_commits: true
  commit_message: "aider: {message}"
cache:
  enabled: true  # Cache LLM responses for similar prompts

Key Settings:

Pro Tip: Use aider --dump-config to generate a starter config file.

Alternatives at a Glance

What's Next?

1. Try a small refactor: Use /diff to edit a single function in your codebase.
2. Set up auto-commits: Configure .aider.conf.yml to auto-commit with your preferred message format.
3. Explore local models: Install Ollama and test codellama:7b for cost-free coding assistance.

For teams adopting Aider, Hyperion <a href="/services/coaching-vs-consulting">consulting</a> offers AI tools consulting to integrate it into your CI/CD pipelines and security workflows—aligning with the AI Security Posture Framework™ for PROTECT (access controls) and COMPLY (audit logging) phases.