Aider | CodeWorlds

Aider - complete guide to AI pair programming in terminal

What is Aider?

Aider is an open source CLI tool created by Paul Gauthier that enables pair programming with AI directly in the terminal. Unlike IDEs with built-in AI, Aider works independently of any editor, making it an ideal choice for developers who prefer Vim, Emacs, terminal, or simply enjoy working from the command line.

Aider stands out with its deep Git integration - every change made by AI is automatically committed with a sensible description, allowing easy tracking and reverting of changes. Aider can directly edit files in your repository, run tests, and fix bugs - all through natural conversation.

Aider works with the best AI models, including Claude (Anthropic) and GPT-4 (OpenAI), letting you choose the model best suited to your workflow.

Why Aider?

Key advantages of Aider

Terminal-native - Work with AI without leaving the terminal
Git integration - Automatic commits with sensible descriptions
Multi-model support - Claude, GPT-4, Ollama, local models
Repo-aware - Understands the entire project structure
Open source - MIT license, active development
Lightweight - No heavy IDE, minimal resource consumption
Editor-agnostic - Works with any editor

Aider vs other AI tools

Aspect	Aider	Claude Code	GitHub Copilot	Cursor
Interface	Terminal	Terminal	IDE plugin	IDE
Git integration	Automatic	Manual	None	Manual
Open source	Yes	No	No	No
Multi-model	Yes	Claude only	Copilot only	Yes
Price	Free + API	API cost	$10-19/mo	$20/mo
Offline	With local models	No	No	No

Installation

pip (standard)

Code

Bash

# Install with pip
pip install aider-chat

# Verify
aider --version

pipx (recommended - isolated environment)

Code

Bash

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

# Install aider
pipx install aider-chat

# Upgrade
pipx upgrade aider-chat

Homebrew (macOS)

Code

Bash

brew install aider

Docker

Code

Bash

# Run aider in a container
docker run -it --rm \
  -v $(pwd):/app \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  paulgauthier/aider

API key configuration

Code

Bash

# Claude (Anthropic) - recommended
export ANTHROPIC_API_KEY=sk-ant-...

# OpenAI GPT-4
export OPENAI_API_KEY=sk-...

# Azure OpenAI
export AZURE_API_KEY=...
export AZURE_API_BASE=https://your-resource.openai.azure.com
export AZURE_API_VERSION=2024-02-01

# Ollama (local models)
# No API key required - automatic detection

Add to ~/.bashrc or ~/.zshrc:

Code

Bash

# Aider configuration
export ANTHROPIC_API_KEY="sk-ant-your-key"
export AIDER_MODEL="claude-3-5-sonnet-20241022"
export AIDER_AUTO_COMMITS=true

Basic usage

Starting a session

Code

Bash

# Default model (GPT-4 Turbo)
aider

# With Claude Sonnet (recommended)
aider --model claude-3-5-sonnet-20241022

# With specific files in context
aider src/app.ts src/utils.ts

# Entire directory
aider src/

# With glob patterns
aider "src/**/*.ts"

Example session

Code

Bash

$ aider src/api/users.ts

Aider v0.50.0
Model: claude-3-5-sonnet-20241022 with diff edit format
Git repo: .git with 142 files
Repo-map: using 1024 tokens

Added src/api/users.ts to the chat.

> Add email validation to the createUser function

I'll add email validation to the createUser function using a regex pattern.

src/api/users.ts
<<<<<<< SEARCH
export async function createUser(data: CreateUserInput) {
  const user = await db.user.create({
    data: {
      email: data.email,
      name: data.name,
    },
  });
  return user;
}
=======
const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;

export async function createUser(data: CreateUserInput) {
  if (!EMAIL_REGEX.test(data.email)) {
    throw new Error('Invalid email format');
  }

  const user = await db.user.create({
    data: {
      email: data.email.toLowerCase().trim(),
      name: data.name,
    },
  });
  return user;
}
>>>>>>> REPLACE

Applied edit to src/api/users.ts
Commit 8f3a2b1 feat: add email validation to createUser

> Also add a check if the email is already taken

I'll add a check for existing email before creating the user.

src/api/users.ts
<<<<<<< SEARCH
export async function createUser(data: CreateUserInput) {
  if (!EMAIL_REGEX.test(data.email)) {
    throw new Error('Invalid email format');
  }

  const user = await db.user.create({
=======
export async function createUser(data: CreateUserInput) {
  if (!EMAIL_REGEX.test(data.email)) {
    throw new Error('Invalid email format');
  }

  const normalizedEmail = data.email.toLowerCase().trim();

  const existingUser = await db.user.findUnique({
    where: { email: normalizedEmail },
  });

  if (existingUser) {
    throw new Error('Email already exists');
  }

  const user = await db.user.create({
>>>>>>> REPLACE

Applied edit to src/api/users.ts
Commit 2d4f6a9 feat: check for duplicate email before creating user

Aider commands

File management

Code

Bash

/add <file>       # Add file to chat context
/drop <file>      # Remove file from context
/ls               # Show files in context
/clear            # Clear context (start fresh)

# Examples:
> /add src/components/Button.tsx
> /add src/hooks/*.ts
> /drop src/utils.ts

Git and history

Code

Bash

/diff             # Show uncommitted changes
/undo             # Undo last AI change (git reset)
/commit           # Commit current changes
/git <cmd>        # Run any git command

# Examples:
> /diff
> /undo
> /git status
> /git log --oneline -5

Running code

Code

Bash

/run <cmd>        # Run a shell command
/test             # Run tests (configurable)
/lint             # Run linter

# Examples:
> /run npm test
> /run python -m pytest tests/
> /test

Session control

Code

Bash

/help             # Show all commands
/quit             # End session
/voice            # Enable voice mode
/tokens           # Show token usage
/model <name>     # Change model during session
/settings         # Show current settings

# Examples:
> /model gpt-4-turbo
> /tokens
> /settings

Working with code

Code

Bash

/architect        # Architecture mode (planning)
/ask              # Ask a question without editing
/code             # Return to edit mode

# Examples:
> /architect What's the best way to organize this project?
> /ask What does this function do?

Edit modes

Diff mode (default)

Code

DIFF

# Aider shows changes in diff format
# Best for precise, small changes

src/utils.ts
<<<<<<< SEARCH
function formatDate(date: Date): string {
  return date.toISOString();
}
=======
function formatDate(date: Date, format: string = 'ISO'): string {
  switch (format) {
    case 'ISO':
      return date.toISOString();
    case 'locale':
      return date.toLocaleDateString();
    case 'relative':
      return formatRelative(date);
    default:
      return date.toISOString();
  }
}
>>>>>>> REPLACE

Whole file mode

Code

Bash

# For smaller files - AI rewrites the entire file
aider --edit-format whole

# Or set in .aider.conf.yml
edit-format: whole

Unified diff mode

Code

Bash

# Format similar to git diff
aider --edit-format udiff

# Example output:
--- src/app.ts
+++ src/app.ts
@@ -10,6 +10,10 @@
 function main() {
+  // Initialize logging
+  setupLogger();
+
   startServer();
 }

Ask mode (no editing)

Code

Bash

# Questions only, no file modifications
aider --ask

# In a session:
> /ask Explain how this algorithm works
> /ask What are the potential issues with this code?

Working with Git

Automatic commits

Code

Bash

# Enabled by default - every change = commit
# To disable:
aider --no-auto-commits

# Or commit manually:
> /commit "my message"

Sensible commit messages

Code

Bash

$ aider src/auth.ts

> Add JWT token refresh support

Applied edit to src/auth.ts
Commit a3f8d21 feat(auth): implement JWT token refresh mechanism

> Fix the bug with the expired token

Applied edit to src/auth.ts
Commit 7b2c4e9 fix(auth): handle expired token edge case

# Aider automatically generates sensible commit messages
# in conventional commits format

Reverting changes

Code

Bash

# Undo the last AI change
> /undo

Undoing: feat(auth): implement JWT token refresh mechanism
HEAD is now at previous commit

# Undo several changes
> /git reset --soft HEAD~3

Working with branches

Code

Bash

# Create a feature branch before working
git checkout -b feature/new-auth

# Work with aider
aider src/auth/

> Implement OAuth2 flow

# When done
git push -u origin feature/new-auth

Model selection

Claude (Anthropic) - recommended

Code

Bash

# Claude 3.5 Sonnet - best balance
aider --model claude-3-5-sonnet-20241022

# Claude 3 Opus - most advanced
aider --model claude-3-opus-20240229

# Claude 3 Haiku - fastest/cheapest
aider --model claude-3-haiku-20240307

OpenAI GPT

Code

Bash

# GPT-4 Turbo
aider --model gpt-4-turbo

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

# GPT-4o-mini - economical
aider --model gpt-4o-mini

Local models (Ollama)

Code

Bash

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Pull a model
ollama pull codellama:34b
ollama pull deepseek-coder:33b

# Use with aider
aider --model ollama/codellama:34b
aider --model ollama/deepseek-coder:33b

# For better results - larger context
aider --model ollama/codellama:34b --map-tokens 4096

Model comparison

Model	Code quality	Speed	Cost	Notes
claude-3-5-sonnet	⭐⭐⭐⭐⭐	Fast	$$	Best choice
claude-3-opus	⭐⭐⭐⭐⭐	Slow	$$$$	Complex tasks
gpt-4-turbo	⭐⭐⭐⭐	Fast	$$$	Good alternative
gpt-4o	⭐⭐⭐⭐	Very fast	$$	Faster GPT-4
ollama/codellama	⭐⭐⭐	Depends on GPU	Free	Offline, privacy
deepseek-coder	⭐⭐⭐⭐	Medium	$	Good quality/price ratio

Configuration

Configuration file

~/.aider.conf.yml

YAML

# ~/.aider.conf.yml (global)
# or .aider.conf.yml (project-level)

# Default model
model: claude-3-5-sonnet-20241022

# Automatic commits
auto-commits: true
dirty-commits: true

# Edit format
edit-format: diff

# Coloring
dark-mode: true
pretty: true

# Git
attribute-author: true
attribute-committer: false

# Context
map-tokens: 1024
max-chat-history-tokens: 4000

# Ignored files (in addition to .gitignore)
aiderignore:
  - "*.log"
  - "node_modules/"
  - "dist/"

# Automatic file adding
auto-add: true

# Voice (if you use it)
voice-language: en

Environment variables

~/.bashrc

Bash

# ~/.bashrc or ~/.zshrc

# API Keys
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."

# Default settings
export AIDER_MODEL="claude-3-5-sonnet-20241022"
export AIDER_AUTO_COMMITS="true"
export AIDER_DARK_MODE="true"
export AIDER_PRETTY="true"

# Editor for longer messages
export AIDER_EDITOR="vim"
export AIDER_EDITOR_MODEL="claude-3-5-sonnet-20241022"

.aiderignore

Code

GITIGNORE

# .aiderignore - files ignored by aider
# (in addition to .gitignore)

# Large binary files
*.bin
*.exe
*.dll

# Generated files
dist/
build/
*.min.js

# Files with secrets
.env*
*credentials*
*.pem
*.key

# Tests (if you don't want them edited)
__tests__/
*.test.ts
*.spec.ts

# Documentation
docs/
*.md

Advanced usage

Architect mode

Code

Bash

# Planning mode - AI proposes architecture without editing
aider --architect

> /architect How to organize the authentication system for this application?

Based on your codebase, I recommend:

1. **Structure**:
   - src/auth/
     - providers/ (OAuth, JWT, etc.)
     - middleware/
     - utils/
     - types.ts

2. **Flow**:
   - Login → Validate → Generate tokens → Store session
   - Middleware checks token on protected routes

3. **Security considerations**:
   - Use httpOnly cookies for refresh tokens
   - Implement rate limiting
   - Add CSRF protection

Should I implement this structure?

> Yes, implement it

# Aider switches to edit mode and implements the plan

Multi-file refactoring

Code

Bash

# Add multiple files to context
aider src/api/*.ts src/models/*.ts src/utils/*.ts

> Convert all API endpoints to async/await instead of .then()

I'll refactor the API endpoints to use async/await.

[Aider modifies multiple files simultaneously]

Applied edits to:
- src/api/users.ts
- src/api/posts.ts
- src/api/comments.ts

Commits:
- refactor(api): convert users endpoints to async/await
- refactor(api): convert posts endpoints to async/await
- refactor(api): convert comments endpoints to async/await

Testing and debugging

Code

Bash

# Run tests after each change
> /run npm test

# If tests fail
> Fix the failing tests

# Aider sees the test output and fixes the code
Applied edit to src/utils.ts
Commit fix: correct date formatting in utils

> /run npm test
All tests passed!

Voice mode

Code

Bash

# Enable voice mode
aider --voice

# Or in a session
> /voice

Listening... (say 'stop' to end)

[Speak into the microphone]
"Add a function for phone number validation"

I'll add a phone number validation function...

Watch mode

Code

Bash

# Automatically react to file changes
aider --watch

# Aider watches files and reacts to comments like:
// AI: add error handling here
// AIDER: refactor this function

Workflow integration

VS Code + Aider

.vscode/tasks.json

JSON

// .vscode/tasks.json
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Aider: Start Session",
      "type": "shell",
      "command": "aider --model claude-3-5-sonnet-20241022 ${file}",
      "presentation": {
        "reveal": "always",
        "panel": "new"
      }
    },
    {
      "label": "Aider: Ask About File",
      "type": "shell",
      "command": "aider --ask ${file}",
      "presentation": {
        "reveal": "always"
      }
    }
  ]
}

Neovim + Aider

Code

LUA

-- lua/plugins/aider.lua
return {
  "joshuavial/aider.nvim",
  config = function()
    require("aider").setup({
      auto_manage_context = true,
      default_bindings = true,
    })

    -- Keybindings
    vim.keymap.set("n", "<leader>ao", "<cmd>AiderOpen<cr>", { desc = "Open Aider" })
    vim.keymap.set("n", "<leader>as", "<cmd>AiderSend<cr>", { desc = "Send to Aider" })
    vim.keymap.set("v", "<leader>as", "<cmd>AiderSend<cr>", { desc = "Send selection to Aider" })
    vim.keymap.set("n", "<leader>ac", "<cmd>AiderComplete<cr>", { desc = "Complete with Aider" })
  end
}

tmux + Aider

~/.tmux.conf

Bash

# ~/.tmux.conf
# Open aider in a new pane

bind-key a split-window -h "aider"
bind-key A split-window -v -l 40% "aider --ask"

# Session script
#!/bin/bash
# dev-session.sh

tmux new-session -d -s dev -n code
tmux send-keys -t dev:code 'nvim .' Enter

tmux split-window -h -t dev:code
tmux send-keys -t dev:code 'aider' Enter

tmux select-pane -t dev:code.0
tmux attach -t dev

Git hooks with Aider

Code

Bash

#!/bin/bash
# .git/hooks/pre-commit

# Check for TODO/FIXME and suggest fixes
if git diff --cached | grep -E "(TODO|FIXME):" > /dev/null; then
    echo "Found TODO/FIXME comments in staged changes."
    echo "Consider running: aider --ask 'Review TODOs and suggest fixes'"
fi

# Run linter before commit
npm run lint || exit 1

Best practices

Effective prompts

Code

Bash

# ❌ Too vague
> Fix bugs

# ✅ Specific
> Fix the TypeError in processUser function on line 45 -
> the 'user' variable can be undefined

# ❌ No context
> Add validation

# ✅ With context
> Add input validation for the registration form:
> - email: valid format
> - password: min 8 characters, 1 digit, 1 uppercase letter
> - name: 2-50 characters, letters only

Session organization

Code

Bash

# 1. Start with a small context
aider src/api/users.ts

# 2. Add files as needed
> /add src/types/user.ts
> /add src/utils/validation.ts

# 3. Remove unnecessary ones
> /drop src/utils/validation.ts

# 4. Regularly check context
> /ls
> /tokens

Working with large projects

.aider.conf.yml

YAML

# .aider.conf.yml for large projects

# Increase repository map limit
map-tokens: 2048

# Automatically add related files
auto-add: true

# Ignore large/unnecessary files
aiderignore:
  - "node_modules/"
  - "dist/"
  - "*.min.js"
  - "package-lock.json"

Troubleshooting

High token consumption

Code

Bash

# Check usage
> /tokens

# Reduce context
> /drop <unnecessary-files>

# Use a smaller repository map
aider --map-tokens 512

# Or disable the map
aider --no-map

Model refuses to edit

Code

Bash

# 1. Check if the file is in context
> /ls

# 2. Explicitly add the file
> /add file-to-edit.ts

# 3. Check permissions
ls -la file-to-edit.ts

# 4. Make sure the file is not ignored
cat .aiderignore

Git issues

Code

Bash

# If aider doesn't commit
> /git status

# Check if the repo is initialized
git status

# Fix dirty state
git stash
# or
git add -A && git commit -m "WIP"

Slow responses

Code

Bash

# Use a faster model
aider --model gpt-4o-mini
aider --model claude-3-haiku-20240307

# Reduce context
> /clear
> /add only-needed-file.ts

# Check connection
curl -I https://api.anthropic.com

Cost comparison

Example coding session

Code

TEXT

Typical session: 1 hour, ~50 interactions

| Model | Input tokens | Output tokens | Cost |
|-------|-------------|---------------|-------|
| claude-3-5-sonnet | ~100k | ~50k | ~$0.90 |
| claude-3-opus | ~100k | ~50k | ~$4.50 |
| gpt-4-turbo | ~100k | ~50k | ~$2.00 |
| gpt-4o-mini | ~100k | ~50k | ~$0.15 |
| ollama/codellama | ~100k | ~50k | $0.00 |

Monthly costs (active developer)

Code

TEXT

40 hours/month of programming with AI:

claude-3-5-sonnet: ~$36/month
gpt-4-turbo: ~$80/month
gpt-4o-mini: ~$6/month
ollama: $0 (+ GPU cost)

FAQ

Is Aider safe for my code?

Yes. Aider does not send your code anywhere other than the chosen API (Anthropic/OpenAI). For maximum privacy, use local models through Ollama.

Can I use Aider offline?

Yes, with local models through Ollama. You need a GPU for reasonable performance.

How does Aider differ from Claude Code?

Aider: Open source, multi-model, deep Git integration
Claude Code: Closed source, Claude only, simpler to use

Does Aider overwrite my files without asking?

Aider shows proposed changes in diff format and waits for confirmation (or automatically applies them with --yes). You can always revert with /undo.

Which model should I choose?

Claude 3.5 Sonnet: Best overall choice
GPT-4o-mini: Budget option
Ollama: Maximum privacy, offline

Summary

Aider is a powerful tool for developers who prefer the terminal and command line. Thanks to its deep Git integration, support for multiple AI models, and open source approach, Aider offers flexibility and control that is lacking in IDE-based solutions.

Key advantages of Aider:

Terminal-native - Ideal for Vim/Emacs/CLI users
Git-first - Automatic commits, easy reverting
Multi-model - Claude, GPT-4, local models
Open source - Full transparency, MIT license
Economical - Pay only for API usage, no subscription

If you value a terminal workflow and want to maintain full control over your environment, Aider is an excellent choice for AI pair programming.