NAME
.aider.conf.yml — instruction file for Aider
SYNOPSIS
~/.aider.conf.yml
./.aider.conf.yml
METADATA
DESCRIPTION
.aider.conf.yml is the configuration file for Aider, an open-source AI pair programming CLI tool. Unlike most other AI tool configs that focus on coding instructions, Aider's YAML config primarily controls the tool's behavior: which AI model to use, how to interact with git, and what verification commands to run after changes.
Aider uses a two-file system for configuration. The YAML config (.aider.conf.yml) handles tool settings — model selection, git behavior, lint/test commands, and flags. Coding conventions and instructions go in a separate .aider.conventions.md file (plain Markdown, similar to CLAUDE.md). This separation of concerns is unique among AI coding tools.
The YAML keys mirror aider's CLI flags: --auto-commits becomes auto-commits in YAML, --model becomes model, etc. This makes it easy to move between CLI flags and persistent configuration. Both global (~/.aider.conf.yml) and project-level (./.aider.conf.yml) configs are supported, with project settings overriding global ones.
One of aider's standout features is its automatic lint-and-test loop: when lint-cmd and test-cmd are configured, aider runs them after every code change and automatically attempts to fix any failures. This makes the config file an important part of the quality assurance workflow.
Lower numbers load first. Higher-priority files override lower ones.
STRUCTURE
ANNOTATED EXAMPLE
1##############################################
2# .aider.conf.yml — Project-level config
3##############################################
4
5# Model selection
6model: claude-sonnet-4-20250514
7editor-model: claude-sonnet-4-20250514
8weak-model: claude-haiku-4-20250414
9
10# Git behavior
11auto-commits: true
12dirty-commits: false
13attribute-author: true
14attribute-committer: true
15
16# Automatic verification after changes
17auto-lint: true
18auto-test: true
19lint-cmd: "npm run lint"
20test-cmd: "npm test"
21
22# Shell integration
23suggest-shell-commands: true
24
25# Read-only context files (always included)
26read:
27 - docs/architecture.md
28 - docs/api-guide.md
29
30# Output
31stream: true
32pretty: true
33dark-mode: true
SPECIAL DIRECTIVES
read: [file paths]Specifies files that should be added as read-only context to every aider session. Useful for referencing documentation, style guides, or architecture docs without allowing edits.
conventions: stringA .aider.conventions.md file (separate from .aider.conf.yml) can contain coding conventions in Markdown. When present, aider includes it as read-only context. This is aider's equivalent of CLAUDE.md for free-form instructions.
COMMON MISTAKES
The filename must be exactly .aider.conf.yml — not .aider.yml, not aider.conf.yml. Aider silently ignores incorrectly named config files.
The project-level config is committed to git. API keys should go in the global config file (~/.aider.conf.yml) or as environment variables (OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.).
Aider's YAML config uses kebab-case keys that mirror the CLI flag names. --auto-commits becomes auto-commits: true in YAML.
The YAML config controls aider's behavior (model, git settings, lint/test commands). For coding conventions and style rules (the equivalent of CLAUDE.md), create a separate .aider.conventions.md file.
When set, aider automatically runs lint and test commands after making changes and will attempt to fix any failures. This is one of aider's most powerful features and should always be configured.