Aider does not discover instruction files automatically. Load your conventions as read-only context with aider --read CONVENTIONS.md (or --read AGENTS.md), or make it permanent with read: AGENTS.md in .aider.conf.yml, which Aider looks for in your home directory, the git root and the current directory. Aider's docs do not describe MCP, a sandbox, hooks or skills. Its safety net is git: it commits each change so you can /undo. Use it with API keys for your model provider.
Aider at a glance
| Global instructions | ◐ Partialread: in ~/.aider.conf.yml |
|---|---|
| Project instructions | ◐ Partial Only files you pass with --read / /read or list under read: in .aider.conf.yml |
| Nested / subfolder | ✕ No No automatic discovery |
| AGENTS.md | ◐ Partial Not auto-loaded; read: AGENTS.md works like any conventions file |
| Skills (SKILL.md) | ? Not documented Not documented |
| MCP config | ? Not documented Not documented in Aider's docs |
| Permissions / allowlist | ◐ Partial Confirms suggested shell commands; --yes-always skips confirmations; auto-commits every edit |
| Sandbox | ? Not documented Not documented |
| Hooks | ◐ Partial--lint-cmd / --test-cmd run after edits (no general hook system documented) |
| Claude Pro/Max login | ? Not documented Not documented |
| ChatGPT Plus/Pro login | ? Not documented Not documented |
| API key / own plan | ✓ Yes API keys for Anthropic, OpenAI, Gemini, DeepSeek, OpenRouter, local models and more |
Exact file paths
| Path | Scope | What it does |
|---|---|---|
.aider.conf.yml | Home / git root / cwd | All CLI options as YAML |
CONVENTIONS.md or AGENTS.md | Project | Loaded only via read: / --read |
.aiderignore | Git root | Files Aider should ignore |
Using a shared AGENTS.md with Aider
Add read: [AGENTS.md] to .aider.conf.yml (or run aider --read AGENTS.md). See one AGENTS.md for every agent, or generate one with the AGENTS.md generator.
Copy-paste examples
Always load AGENTS.md
File: .aider.conf.yml
read: [AGENTS.md]
auto-commits: true
test-cmd: npm test
auto-test: true
Safe permissions preset
Safe Aider config
File: .aider.conf.yml
read: [AGENTS.md]
auto-commits: true # every edit is a git commit you can /undo
yes-always: false # keep confirming shell commands
test-cmd: npm test
auto-test: true
Aider has no permission rule engine or sandbox in its docs, so run it in a container or VM for risky repos and never pass --yes-always there.
Gotchas
- Nothing is loaded unless you ask: an AGENTS.md in the repo is ignored until you add
read:. - Files passed with
--readare read-only context and can be cached when prompt caching is on. --yes-alwaysauto-confirms everything, including suggested shell commands.
FAQ
Does Aider read AGENTS.md?
Where is the Aider config file?
Sources
Checked against these official pages on 2026-10-12. Cells marked "Not documented" mean we could not find the behaviour in these docs; it may still exist.