Aider Configuration Guide

A comprehensive reference for configuring Aider, the AI pair programming assistant. This guide covers all configuration options available through `.aider.conf.yml` files.

Overview

Aider can be configured using YAML configuration files placed in:

Configuration Sections

1. Model Selection

Choose which AI model powers your coding sessions:

```yaml

Main chat model

model: claude-3-5-sonnet-20241022

Weaker model for commit messages and summaries

weak-model: claude-3-5-haiku-20241022

Model for editor tasks

editor-model: gpt-4o-mini

Edit format (architecture depends on model)

edit-format: diff

architect: false

```

**Key considerations:**

2. API Keys and Settings

Configure authentication for AI providers:

```yaml

Direct API keys (OpenAI and Anthropic only)

openai-api-key: sk-...

anthropic-api-key: sk-ant-...

Custom API endpoints

openai-api-base: https://api.custom-provider.com/v1

Environment variables (for other providers)

set-env:

- PROVIDER_API_KEY=xxx

- OPENAI_API_TYPE=azure

Provider-specific keys

api-key:

- deepseek=sk-...

- groq=gsk-...

```

**Security note:** Store sensitive keys in `.env` files, not YAML config.

3. Advanced Model Settings

Fine-tune model behavior:

```yaml

Model metadata and settings

model-settings-file: .aider.model.settings.yml

model-metadata-file: .aider.model.metadata.json

Model aliases for shortcuts

alias:

- gpt4=gpt-4-0613

- sonnet=claude-3-5-sonnet-20241022

Reasoning parameters (for supported models)

reasoning-effort: high

thinking-tokens: 10000

API behavior

verify-ssl: true

timeout: 120

show-model-warnings: true

Chat history limits

max-chat-history-tokens: 8000

```

4. Caching Configuration

Enable prompt caching to reduce costs and latency:

```yaml

Enable caching (can significantly reduce API costs)

cache-prompts: true

Keep cache warm with periodic pings

cache-keepalive-pings: 12

```

**Cost optimization:** Caching can reduce costs by 50-90% for repetitive prompts.

5. Repository Map Settings

Control how Aider understands your codebase:

```yaml

Token budget for repo map

map-tokens: 2048

Refresh frequency

Options: auto, always, files, manual

map-refresh: auto

Multiplier when no files specified

map-multiplier-no-files: 2

```

**Performance tip:** Lower `map-tokens` for faster responses, higher for better context.

6. History and Logging

Manage conversation history and logs:

```yaml

History file locations

input-history-file: .aider.input.history

chat-history-file: .aider.chat.history.md

llm-history-file: .aider.llm.history

Restore previous conversations

restore-chat-history: false

```

7. Output Customization

Personalize the terminal experience:

```yaml

Theme settings

dark-mode: true

pretty: true

stream: true

Custom colors

user-input-color: "#00cc00"

assistant-output-color: "#0088ff"

tool-error-color: "#FF2222"

tool-warning-color: "#FFA500"

Code syntax theme

code-theme: monokai

Completion menu colors

completion-menu-color: "#ffffff"

completion-menu-bg-color: "#1e1e1e"

Show diffs when committing

show-diffs: true

```

8. Git Integration

Configure version control behavior:

```yaml

Enable git features

git: true

gitignore: true

add-gitignore-files: false

aiderignore: .aiderignore

Auto-commit settings

auto-commits: true

dirty-commits: true

git-commit-verify: false

Attribution options

attribute-author: true

attribute-committer: true

attribute-commit-message-author: false

attribute-co-authored-by: true

Custom commit prompts

commit-prompt: "Write a concise commit message"

commit-language: en

Repository scope

subtree-only: false

```

**Best practice:** Enable `auto-commits` to track all AI changes.

9. Code Quality Tools

Integrate linting and testing:

```yaml

Linting configuration

auto-lint: true

lint-cmd:

- "python: ruff check --fix"

- "javascript: eslint --fix"

- "typescript: eslint --fix"

Testing configuration

auto-test: false

test-cmd: pytest tests/

Flags for specific actions

lint: false

test: false

```

**Workflow tip:** Enable `auto-test` for critical codebases.

10. File Management

Specify files for editing:

```yaml

Files to edit

file:

- src/main.py

- src/utils.py

Read-only reference files

read:

- docs/api.md

- requirements.txt

Ignore patterns

aiderignore: .aiderignore

```

11. Voice Settings

Configure voice input (requires `aider[voice]`):

```yaml

voice-format: wav

voice-language: en

voice-input-device: "Default Microphone"

```

12. Advanced Options

Additional configuration options:

```yaml

Editor and input

vim: false

fancy-input: true

multiline: false

editor: vim

Notifications

notifications: false

notifications-command: "osascript -e 'display notification \"Ready\"'"

URL handling

detect-urls: true

Analytics

analytics: false

analytics-disable: true

Updates

check-update: true

show-release-notes: true

Encoding and line endings

encoding: utf-8

line-endings: platform

Shell commands

suggest-shell-commands: true

Environment file

env-file: .env

```

Common Configuration Patterns

Minimal Setup (Free Tier)

```yaml

model: gpt-3.5-turbo

weak-model: gpt-3.5-turbo

map-tokens: 1024

cache-prompts: false

auto-commits: true

dark-mode: true

```

Professional Setup (Optimized for Quality)

```yaml

model: claude-3-5-sonnet-20241022

weak-model: claude-3-5-haiku-20241022

editor-model: gpt-4o-mini

cache-prompts: true

cache-keepalive-pings: 12

map-tokens: 4096

auto-lint: true

auto-test: false

show-diffs: true

attribute-co-authored-by: true

```

Team Setup (Consistency)

```yaml

model: gpt-4o

map-tokens: 2048

edit-format: diff

auto-lint: true

lint-cmd:

- "python: ruff check --fix"

- "javascript: eslint --fix"

git-commit-verify: true

attribute-commit-message-author: true

commit-language: en

```

Implementation Steps

When using this guide to configure Aider:

1. **Create configuration file** in repository root or home directory

2. **Start with model selection** based on budget and quality needs

3. **Configure API authentication** using secure methods

4. **Enable caching** to reduce costs

5. **Set up git integration** for automatic version control

6. **Add linting/testing** for code quality

7. **Customize output** for your terminal theme

8. **Test configuration** with a simple coding task

Important Notes

Troubleshooting

Common issues: