Aider Cheatsheet - Terminal AI Pair Programming
Aider is the open-source Apache 2.0 terminal AI pair programmer for developers who want a model to edit local files and auto git-commit, with 100+ model support and no vendor lock-in. Its signature is an automatic commit per change, forming a safe loop with --test-cmd/--lint-cmd where a bad edit is one /undo away. This sheet covers file context, chat-mode switching, and architect mode.
Typical Use Case
For developers who want controlled edits inside a real local repository, especially teams that value being able to undo. Aider differs most in its git integration: every change is committed automatically, and with --test-cmd and --lint-cmd that becomes an edit, test, commit loop, so a broken line is one /undo away from reverted. Four lines are covered: model and reasoning configuration, including the two-model split with --architect, a cheaper --weak-model for trivial subtasks, and --map-tokens to control repository map cost; file and context management through /add, /drop and /read-only; the four chat modes; and /save with /load to turn a session into a reproducible script.
Install & Start 5
pip install aider-chataideraider src/main.py tests/test_main.pyaider --model claude-sonnet-4-6export ANTHROPIC_API_KEY="sk-ant-..."Model & Reasoning 7
aider --model ollama/codellamaaider --architect --model claude-opus --editor-model claude-sonnetaider --weak-model gpt-4o-miniaider --reasoning-effort highaider /think-tokens 4096/model/modelsFiles & Context 9
/add src/auth/*.py/drop tests/auth/test_login.py/read-only docs/api-spec.md/ls/reset/clearaider --map-tokens 2048aider --show-repo-map/map-refreshChat Modes 5
/code/ask/architect/chat-mode/contextGit & Run 10
/git status/commit "Implement JWT auth"/undo/diff/run pytest tests//test/lintaider --auto-commitsaider --lint-cmd "ruff check"aider --test-cmd "pytest"Session & Tools 11
/voice/web https://docs.site/paste/copy/copy-context/save /path/script.md/load /path/script.md/settings/report/help/exitAdvanced 6
aider --message "/ask where is this bug"aider --edit-format wholeaider --cache-prompts/multiline-mode/vim/editorParameter matrix
| Parameter | Effect | Example |
|---|---|---|
--model <m> | Specify the main model | aider --model claude-sonnet-4-6 |
--editor-model <m> | Specify the editor model, used together with --architect | aider --architect --model claude-opus --editor-model claude-sonnet |
--weak-model <m> | Specify a cheap weak model for sub-tasks | aider --weak-model gpt-4o-mini |
--architect | Architect mode: the planning model produces the plan, the editor model produces the diff | aider --architect |
--reasoning-effort <lvl> | Set reasoning effort (when the model supports it) | aider --reasoning-effort high |
/think-tokens <n> | Set the thinking token budget per turn | /think-tokens 4096 |
--map-tokens <n> | Set the repo map token budget | aider --map-tokens 2048 |
--show-repo-map | Print the current repo map and exit | aider --show-repo-map |
--auto-commits | Auto git-commit on every change | aider --auto-commits |
--test-cmd <cmd> | Run the test command automatically after a change | aider --test-cmd "pytest" |
--lint-cmd <cmd> | Run lint automatically after a change | aider --lint-cmd "ruff check" |
--edit-format whole | Whole-file editing, suited to small files | aider --edit-format whole |
--message / -m <s> | Send a single non-interactive message | aider --message "/ask where is this bug" |
--cache-prompts | Enable prompt caching to cut cost and speed up | aider --cache-prompts |
/add / /drop | Add files to the session / remove them to save context | /add src/auth/*.py |
/read-only <f> | Read-only reference; editing forbidden | /read-only docs/api-spec.md |
/ask / /code / /architect | Ask / edit code / two-model mode | /ask where is this bug |
/run <cmd> and /test / /lint | Run a shell command and feed its output back into the session | /run pytest tests/ |
/commit / /undo / /diff | Commit dirty changes / undo the last commit / view the latest diff | /undo |
/save / /load <file> | Save the session as a reproducible script / load and run from a script | /save /path/script.md |
Common pitfalls
SymptomSessions get slower and more expensive, and the model starts editing unrelated files.
CauseToo many files pile up in the session, and the repo map plus file contents together eat up the context budget.
FixKeep only 3-5 relevant files per task and /drop them when done; if needed use --map-tokens to shrink the repo map budget.
SymptomAider edits files it should not, or rewrites read-only docs.
CauseThe file was added to the editable set with /add; read-only files should use /read-only rather than /add.
FixSwitch reference material from /add to /read-only, and use /ls to check which files are actually editable in the current session.
SymptomQuality on complex refactors is unstable, and the plan goes off track halfway.
CauseA single model handles both design and editing, so it easily loses the overall intent in the details.
FixUse /architect to switch to two models: the planning model produces the plan, and the editing model only lands the diff.
SymptomTests break after a change, but you do not know which change introduced it.
CauseTests are not wired into the loop, separating change from verification.
FixStart with --test-cmd "pytest" --lint-cmd "ruff check" so they run automatically before every commit.
SymptomAfter one big change you want to revert it all, but undo will not do it.
Cause/undo only undoes the most recent git commit made by Aider; earlier changes need manual handling.
FixFor important tasks, start on a dedicated branch or keep --auto-commits on, then locate the commit with git log and revert as needed.
SymptomAsking in Chinese gets a generic English answer, or one that does not match the actual project structure.
CauseThe repo map token budget is too small, so the model does not get enough structural information.
FixFirst run aider --show-repo-map to see whether the map covers the relevant directories, then raise --map-tokens.
SymptomWhen reporting a problem you cannot explain the config clearly, and you pasted the key along with it.
Cause/report pre-fills diagnostic info, so sending the content directly risks a leak.
FixBefore submitting, print the effective config with /settings for a self-check, and if needed delete the secret lines from the /copy-context output by hand before sending.
Troubleshooting
1Confirm which files are actually included in the session
/lsThe output should contain only the files the current task needs; remove any extra ones with /drop.
2Check whether the repo map covers the target directory
aider --show-repo-mapIt prints and exits, used to confirm the token budget is sufficient; if not, raise --map-tokens.
3Ask before acting, without making changes
/ask where is this bugAsk mode does not change files, good for locating a problem before deciding how to fix it.
4View the full diff of the most recent change
/diffConfirm the scope of the change matches expectations; on anything abnormal, immediately /undo back to the previous commit.
5Feed test output back into the session as evidence
/run pytest tests/The command output is fed to the model, which is faster and more complete than copy-pasting errors by hand.
6Print the effective config and check the model settings
/settingsFocus on checking whether the main model, editor model, test/lint commands and auto-commit toggle match expectations.
Command Examples
Ask read-only first, then decide whether to let it edit
/read-only docs/api-spec.md
/add src/main.py
/ask what are the possible causes of this endpoint returning 500/ask discusses without touching files. Keeping the spec read-only and the code in context lets it reason about the failure first, which is the safest way in: confirm the direction, then switch to /code.
Verify right after the edit, revert the whole batch if it fails
/code
/run pytest tests/
/diff
/undoEach Aider edit lands as a git commit and /undo rolls back the commits it made itself. When tests fail, read /diff to see which files moved, then /undo the whole batch — far cleaner than undoing file by file.
Plan with the architect, let the editor model implement
/architect
split rate limiting into middleware and config layers; give the plan first, do not change code
/codeLarge refactors drift when the main model goes straight to code. /architect produces the structure first, you review it, then /code implements — mistakes caught at the plan stage are the cheapest to undo.
Drop test files as context grows, keep production code
/add src/auth/*.py
/drop tests/auth/test_login.py
/lsContext is finite and test files often eat a large share while contributing little to the patch. /drop only removes them from context (the files are untouched), and /ls confirms what is actually loaded so the model never "assumes" it has seen a file.
One-shot question without entering the interactive UI
aider --message "/ask where is this bug"Useful in scripts and CI for a one-off "explain this code" pass. Feed files in with /add first; -m handles the single message then exits instead of sitting at the terminal waiting for input.
Common Pitfalls
- Starting Aider with a dirty worktree lets generated commits swallow your half-finished changes. Check /git status first, or work on a clean branch.
- --auto-commits commits after every edit; on a protected CI branch those commits fail halfway, leaving half-applied history that is painful to untangle. Leave it off at first.
- export ANTHROPIC_API_KEY="sk-..." stays in your shell history on disk forever. Use read -s or a .env plus environment management instead.
- Adding a .env or any file containing tokens via /add pushes that content into the model context and on to the remote API. /read-only prevents edits but still sends the text.
- /undo only rolls back commits Aider itself created. Hand-made commits you made outside the session are untouched, so using it at the wrong moment loses your own work.
- Closing the terminal without /exit leaves the session without a clean finish: uncommitted edits remain. Open /diff next time before deciding to commit or revert.
- Text fetched by /web enters the context and can be treated as instructions (prompt injection). Do not /web untrusted URLs into a session where code will be edited.
Tips
- Auto git-commit per change is Aider's killer feature: pair it with
--test-cmdand--lint-cmd, and a bad edit is one/undoaway. - For complex refactors use
/architectdual models: a planner proposes, an editor emits diffs — higher quality than single-model end-to-end and usually cheaper. - Add only relevant files (3-5 per task), then
/dropwhen done; smaller chats are faster, cheaper, and edit more precisely. - Use
/askfirst to let Aider plan before editing — figuring it out upfront avoids detours on complex tasks.
FAQ
When should I use /ask versus /code?
/ask discusses without touching files — ideal for explaining code or evaluating approaches — while /code edits files and is the default mode. In an unfamiliar repository, ask first and switch to code once the direction is agreed; this avoids sweeping edits before you have confirmed the plan. If a change goes wrong, /undo reverts the last git commit Aider made.
Why do I need to /add a file before it can be edited?
Aider only edits files you explicitly add to the session — /add src/auth/*.py makes it editable, while /read-only docs/api-spec.md brings it in as reference only and forbids modification. This is deliberate, so it never touches files you had not planned to change. Use /drop to remove files you no longer need and keep the context small.
What problem does --architect mode solve?
It splits the work across two models: a planning model produces the design first, then an editing model implements it. Compared with a single model editing directly, you get a reviewable plan before large changes land, which cuts wasted effort when the direction was wrong. The cost is roughly double in tokens and time, so reserve it for cross-module refactors and use the default mode for small edits.
How does Aider interact with git?
Aider is built around git: it commits automatically after each change and you can always /undo the last one. To verify, use /run pytest tests/ so it runs the command and feeds the output back into the conversation — faster than pasting errors by hand. Use /diff to review the most recent change before deciding to keep it.
How do I run Aider with a local model?
Prefix the model name with ollama/, for example aider --model ollama/codellama, with ollama serve already running. Architect mode works with local models too: --architect sets the planning model and --editor-model the editing one, and both can be local — though planning quality on complex tasks will drop.
Official References
Each command links to its official documentation below, so you can verify the latest usage and read deeper.
Maintained by LaoHand
Publicly updated on Aug 5, 2026, continuously proofread against official docs.
Contact Us
Wrong command or description? Send us corrections, business inquiries or product feedback by email.
Contact Us