Aider Configuration Template

A comprehensive configuration template for Aider, the AI pair programming tool. This template covers all available options for customizing your Aider workflow, from model selection and API settings to git integration and output styling.

What This Configuration Does

This is a complete `.aider.conf.yml` configuration file that documents every available Aider setting. It serves as both a reference and a starting point for customizing Aider's behavior to match your development workflow.

Key configuration areas:

Instructions

Follow these steps to set up and customize your Aider configuration:

1. Create Configuration File

Create `.aider.conf.yml` in one of these locations (Aider searches in order):

2. Start With Essential Settings

Begin by uncommenting and configuring these critical options:

**Model Selection:**

```yaml

Specify your preferred model

model: anthropic/claude-3-7-sonnet-20250219

Optional: Use a faster/cheaper model for commits and summaries

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

```

**API Keys** (alternative: use `.env` file):

```yaml

Store keys in config (OpenAI and Anthropic only)

anthropic-api-key: your-api-key-here

OR use environment variables via .env file (recommended for security)

```

3. Configure Git Behavior

**Commit Settings:**

```yaml

Disable auto-commits if you prefer manual control

auto-commits: false

Show diffs before committing

show-diffs: true

Customize commit attribution

attribute-commit-message-author: true

```

**Git Integration:**

```yaml

Enable git integration (default: true)

git: true

Automatically add .aider* files to .gitignore

gitignore: true

Skip pre-commit hooks if needed

git-commit-verify: true

```

4. Customize Output Styling

**Theme Selection:**

```yaml

For dark terminals

dark-mode: true

code-theme: gruvbox-dark

OR for light terminals

light-mode: true

code-theme: solarized-light

```

**Color Customization:**

```yaml

Customize individual colors (use hex codes)

user-input-color: "#00cc00"

assistant-output-color: "#0088ff"

tool-error-color: "#FF2222"

```

5. Enable Code Quality Automation

**Linting:**

```yaml

Enable automatic linting after changes

auto-lint: true

Specify lint commands per language

lint-cmd:

- "python: ruff check --fix"

- "javascript: eslint --fix"

- "typescript: eslint --fix"

```

**Testing:**

```yaml

Specify test command

test-cmd: pytest

Enable automatic testing after changes

auto-test: true

```

6. Configure Repository Map

```yaml

Tokens allocated for repository context map

map-tokens: 1024

Control map refresh behavior

map-refresh: auto # Options: auto, always, files, manual

```

7. Advanced Settings

**Caching** (reduce API costs):

```yaml

cache-prompts: true

cache-keepalive-pings: 3 # Keep cache warm

```

**Chat History:**

```yaml

Restore previous conversation on startup

restore-chat-history: true

Custom history file location

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

```

**Editor Integration:**

```yaml

Specify external editor for /editor command

editor: code # or vim, emacs, etc.

Use VI mode in terminal

vim: true

```

8. Security Best Practices

**IMPORTANT**: Never commit API keys to version control.

**Recommended approach:**

1. Store keys in `.env` file (git-ignored)

2. Reference in config:

```yaml

env-file: .env

```

3. In `.env`:

```

ANTHROPIC_API_KEY=your-key-here

OPENAI_API_KEY=your-key-here

```

9. Verify Configuration

Test your configuration:

```bash

Check which config file is loaded

aider --config

Validate settings without starting chat

aider --exit

Show all active settings

aider --verbose --exit

```

10. Common Configuration Patterns

**Minimal Setup** (quick start):

```yaml

model: anthropic/claude-3-7-sonnet-20250219

dark-mode: true

auto-commits: false

```

**Quality-Focused** (with automation):

```yaml

model: anthropic/claude-3-7-sonnet-20250219

auto-lint: true

auto-test: true

show-diffs: true

lint-cmd:

- "python: ruff check --fix"

```

**Performance-Optimized** (with caching):

```yaml

model: anthropic/claude-3-7-sonnet-20250219

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

cache-prompts: true

map-tokens: 2048

```

Important Notes

Configuration Validation

After setting up your config, verify it works:

```bash

Test model connection

aider --model anthropic/claude-3-7-sonnet-20250219 --message "test" --yes-always

Check git integration

aider --show-repo-map

Verify linting setup

aider --lint

```

Troubleshooting

**Config not loading:**

**API errors:**

**Git issues:**

Reference

Full documentation: https://aider.chat/docs/config/options.html

Common model identifiers: