# How to use Aider: a step-by-step guide URL: https://agentvera.dev/en/blog/how-to-use-aider/ · Published: 2026-10-27 How to use Aider: install it, add API keys, pick a model, add files to the chat, use ask, code and architect modes, undo commits, and set up .aider.conf.yml. **In short:** - Install Aider with aider-install, the one-line script, uv or pipx, then run aider --model sonnet --api-key anthropic= inside a git repo. - Add only the files the change needs with /add, keep reference files read-only, and switch between /ask, /code and /architect depending on the task. - Aider commits every edit to git, so /undo reverts its last commit; .aider.conf.yml, --lint-cmd, --test-cmd and a CONVENTIONS.md file set your defaults. To use Aider, install it with `aider-install` or the one-line script, `cd` into a git repository, start it with `aider --model sonnet --api-key anthropic=` (or another provider), add the files you want changed with `/add`, and describe the change in plain English. Aider edits the files and commits each change to git, so `/undo` takes it back. That’s the whole loop. This guide covers the parts that make Aider pleasant to use: API keys and models, which files to add, the ask, code and architect modes, edit formats, git behavior, `.aider.conf.yml`, lint and test integration and a conventions file. Every command and flag here comes from the official Aider documentation at aider.chat as of October 2026. ## What Aider is Aider is an AI pair programmer for the terminal. It is a [coding agent](/en/glossary/coding-agent/ "What is a coding agent") that works with almost any LLM: Claude, GPT, Gemini, DeepSeek or a local model. Two things set it apart from most CLI agents. First, it is built around git: every edit becomes a commit. Second, it is explicit about context: you decide which files are in the chat, and a repository map gives the model a summary of the rest. If you’re weighing it against other terminal agents, [how to use opencode](/en/blog/how-to-use-opencode/ "How to use opencode") and [how to use GitHub Copilot CLI](/en/blog/how-to-use-copilot-cli/ "How to use GitHub Copilot CLI") follow the same step-by-step format. ## Step 1: install Aider The Aider docs list several install routes. Pick one. | Method | Command | | --- | --- | | aider-install (recommended) | `python -m pip install aider-install` then `aider-install` | | One-liner, macOS and Linux | `curl -LsSf https://aider.chat/install.sh \| sh` | | One-liner, Windows | `powershell -ExecutionPolicy ByPass -c "irm https://aider.chat/install.ps1 \| iex"` | | uv | `uv tool install --force --python python3.12 --with pip aider-chat@latest` | | pipx | `pipx install aider-chat` | `aider-install` sets up Aider in its own Python environment, so it doesn’t clash with your project’s packages. If you install with plain `pip`, do it inside a virtual environment. When the `aider` command isn’t found after a pip install, `python -m aider` runs the same thing. ## Step 2: API keys and models Aider talks to model providers with your own keys. The fastest start is to pass the model and key on the command line: ```bash cd /to/your/project # Anthropic aider --model sonnet --api-key anthropic= # OpenAI aider --model o3-mini --api-key openai= # DeepSeek aider --model deepseek --api-key deepseek= ``` Typing a key every time gets old. Aider also reads the usual environment variables (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `DEEPSEEK_API_KEY` and so on) and a `.env` file in your project. `--api-key provider=` works for any provider: `--api-key gemini=xxx` sets `GEMINI_API_KEY`. Short names like `sonnet` are built-in aliases. As of October 2026 the docs map `sonnet`, `opus` and `haiku` to current Claude models, `gemini` and `flash` to Gemini models, `deepseek` and `r1` to DeepSeek chat and reasoner, and `4o` to GPT-4o. You can define your own: ```bash aider --alias "fast:gpt-4o-mini" --model fast ``` Inside a session, `/model ` switches the main model, `/models ` lists available models, and `/reasoning-effort` sets the effort for models that support it. Aider also uses a cheaper “weak model” for commit messages and chat summaries; `--weak-model` changes it. Want to run on your own hardware? The [local LLM coding agent guide](/en/blog/local-llm-coding-agent/ "Local LLM coding agent") covers that setup. ## Step 3: add files to the chat Aider only edits files that are in the chat. You can name them when you start: ```bash aider src/api/users.py tests/test_users.py ``` or add them later: ```text /add src/api/users.py tests/test_users.py ``` The Aider docs are clear on one point: **add only the files that need to be edited for the task.** Every file you add costs tokens, and too many files can overwhelm the model. Aider builds a repository map of the whole repo, so the model already knows where related functions and classes live without you adding them. If you add nothing, Aider tries to work out which files need editing. The commands that manage context: - `/add ` adds files Aider may edit. - `/read-only ` adds reference files it can read but not change (docs, an example module). - `/drop ` removes files to free context; `/drop` alone clears them all. - `/ls` lists files in the chat and in the repo. - `/tokens` shows how many tokens the current context uses. - `/map` prints the repository map, and `/map-refresh` rebuilds it. Then describe the change: ```text Add pagination to the list_users endpoint: accept page and page_size query parameters, default to 20 per page, and update the tests. ``` ## Step 4: ask, code and architect modes Aider has chat modes, and choosing the right one is most of the skill. | Mode | What it does | Prompt | | --- | --- | --- | | code | The default. Aider edits files to make the change. | `>` | | ask | Discusses the code and answers questions. Never edits. | `ask>` | | architect | One model proposes the change, an editor model writes the edits. | `architect>` | | help | Answers questions about Aider itself. | `help>` | `/ask`, `/code` and `/architect` followed by a message apply to that one message. Typed alone, they switch the mode until you change it again; `/chat-mode ` does the same. `--chat-mode ` picks the mode at launch, and `--architect` is a shortcut. The workflow the docs recommend is to alternate. Ask first, refine the plan, then let it code: ```text /ask How should I add rate limiting to the login route without touching the other endpoints? Don't change anything yet. ``` When the plan looks right, type `/ok`. It is shorthand for “/code Ok, please go ahead and make those changes.” **Architect mode** splits the work between two models. The main model describes how to solve the problem, and an editor model, set with `--editor-model`, turns that into file edits. Aider picks a sensible editor model for each main model if you don’t. This often helps with reasoning models that are good at planning but less reliable at producing exact edits. The trade-off: architect mode sends two requests per change, so it is slower and costs more. ## Step 5: edit formats An edit format is how the model tells Aider what to change. You rarely need to touch it, because Aider picks the best format for each model, but it helps to know what you’re seeing: | Format | How edits are sent | | --- | --- | | whole | The model returns the full updated file. Simple, but expensive for big files. | | diff | Search/replace blocks: the old lines and their replacement. | | diff-fenced | Like diff, with the file path inside the code fence. Mainly for Gemini models. | | udiff | A simplified unified diff. | | editor-diff, editor-whole | Streamlined versions used by the editor model in architect mode. | Override with `--edit-format `, and set the editor model’s format with `--editor-edit-format`. If a model keeps producing edits that fail to apply, switching it to `whole` is a reasonable test for small files. ## Step 6: git, auto-commits and /undo Aider works best inside a git repo. By default: - Every edit Aider makes is committed with a descriptive message, written by the weak model in the Conventional Commits style. - If you had uncommitted changes in files before Aider edits them, it commits those first, so your work and its work stay in separate commits. - “(aider)” is added to the git author and committer name on its commits. That makes the safety net simple: - `/diff` shows the changes since your last message. - `/undo` reverts the last commit if Aider made it. - `/commit` commits outside edits you made yourself. - `/git ` runs any git command without leaving the chat. You can turn parts of this off: `--no-auto-commits` leaves edits uncommitted for you to review, `--no-dirty-commits` skips the pre-edit commit, and `--no-git` disables git entirely (the docs advise against it). Aider commits with `--no-verify` by default, so your pre-commit hooks don’t run; add `--git-commit-verify` if you want them to. If you’d rather keep Aider’s changes away from your main checkout, run it in a separate [git worktree](/en/blog/git-worktree-parallel-agents/ "Git worktrees for parallel agents"). ## Step 7: configure .aider.conf.yml Flags you use every time belong in a YAML file. Aider loads `.aider.conf.yml` from your home directory, then the git repo root, then the current directory; later files win. `--config ` loads only that file. ```yaml # .aider.conf.yml model: sonnet weak-model: haiku auto-commits: true dirty-commits: true lint-cmd: "python: ruff check --fix" test-cmd: pytest -q auto-test: false read: [CONVENTIONS.md] ``` Keys in the file match the long flag names without the dashes. API keys can go here too (`anthropic-api-key:`, `openai-api-key:`, or an `api-key:` list such as `- gemini=xxx`), but keep that file out of git if you do. By default Aider adds `.aider*` to `.gitignore` so its history files don’t end up in commits. ## Step 8: lint and test integration Aider lints the files it edits right after each change, using built-in linters for most popular languages. If the linter reports problems, Aider tries to fix them. You can bring your own linter: ```bash aider --lint-cmd "python: ruff check --fix" --lint-cmd "javascript: npx eslint --fix" ``` The command has to print errors and exit with a non-zero code when it finds problems. `--no-auto-lint` turns linting off. Tests work the same way, but they are off by default. Set a command with `--test-cmd` and turn on `--auto-test`, and Aider runs the tests after each change and tries to fix failures (any non-zero exit code). In the chat: - `/lint` lints and fixes the files in the chat, or all dirty files if none are added. - `/test ` runs a command and, if it fails, adds the output to the chat. - `/run ` (or `!`) runs a shell command and lets you share its output. ## Step 9: a conventions file Aider has no built-in project instruction file that it loads by itself. The documented approach is a plain Markdown file you load read-only: ```markdown # CONVENTIONS.md - Prefer httpx over requests for making http requests. - Use types everywhere possible. - Every new endpoint needs a test in tests/api/. ``` ```bash aider --read CONVENTIONS.md ``` or `/read-only CONVENTIONS.md` during a session, or `read: CONVENTIONS.md` in `.aider.conf.yml` so it loads every time. Read-only files are cached when prompt caching is on, so the cost stays low. If you already keep an `AGENTS.md` for other agents, you can load that instead; [CLAUDE.md and AGENTS.md](/en/blog/claude-md-agents-md/ "CLAUDE.md and AGENTS.md") has tips on writing rules agents actually follow. ## Two more features worth knowing **Scripting.** `--message` (or `-m`) sends one instruction, applies the edits and exits, which makes Aider easy to loop over files: ```bash for FILE in *.py ; do aider --message "add descriptive docstrings to all the functions" $FILE done ``` Add `--yes-always` to accept confirmations automatically, and `--message-file` to read the instruction from a file. **Watch mode.** Start Aider with `--watch-files` and keep working in your editor. Write a comment ending in `AI!` and Aider makes the change; end it with `AI?` and Aider answers the question. It works with `#`, `//` and `--` comments. ## Common pitfalls - **Adding the whole repo.** More files mean higher cost and worse edits. Add what changes, use `/read-only` for references, and trust the repo map. - **Forgetting the dirty-commit behavior.** Aider commits your pending edits before touching a file. If that surprises you, commit or stash first, or use `--no-dirty-commits`. - **Expecting hooks to run.** Commits skip pre-commit hooks unless you pass `--git-commit-verify`. - **Architect mode for everything.** It doubles the requests. Use it for tricky changes; plain code mode is fine for small edits. - **Keys in a committed config.** If `.aider.conf.yml` holds API keys, keep it in your home directory or out of git. - **Long chats.** Old messages cost tokens on every request. `/clear` wipes the chat history and `/reset` also drops the files. ## Running Aider in AgentVera AgentVera is a desktop app for macOS, Windows and Linux that runs CLI agents side by side in real terminals, using your own installs and keys. Aider is one of the agents it supports; the [Aider in AgentVera](/en/agents/aider/ "Aider in AgentVera") page lists the details: - **Your keys, your config.** Aider reads provider keys from environment variables or `.aider.conf.yml`, as usual. A model you pick in AgentVera is passed with `--model`, and low, medium or high effort with `--reasoning-effort`. - **Separate history per agent.** Each Aider agent keeps its own chat history file under `~/.aider/agentvera/` and continues it with `--restore-chat-history` when the app reopens, so several Aider agents never mix their histories. - **Roles as a read-only file.** Aider doesn’t allow extending its system prompt, so the agent’s role is passed with `--read`, the same mechanism as a conventions file. - **Panes next to other agents.** Run Aider in the [workspace](/en/features/workspace/ "Workspace") grid next to Claude Code or Codex, and start agents in their own worktrees from the [Git panel](/en/features/git-and-github/ "Git and GitHub"). - **Review and flows.** Aider agents get [automatic code review](/en/features/code-review/ "Code review") when a turn ends, and they work in flows (Pro and Team), broadcasts and scheduled tasks. One limit to know: the MCP servers you set up in AgentVera aren’t passed to Aider. The grid, worktrees and code review are on the free plan. [Download AgentVera](/en/download/ "Download AgentVera") to try it. ## Wrapping up Install Aider, `cd` into a git repo, start it with a model and key, and add only the files the change needs. Use `/ask` to plan and `/ok` or `/code` to apply, try `/architect` for harder problems, and lean on `/diff` and `/undo` because every edit is a commit. Put your defaults in `.aider.conf.yml`, your rules in `CONVENTIONS.md`, and let `--lint-cmd` and `--test-cmd` catch mistakes before you do. If you also use GitHub’s agent, [how to use GitHub Copilot CLI](/en/blog/how-to-use-copilot-cli/ "How to use GitHub Copilot CLI") is the same guide for that tool. ## Frequently asked questions **Is Aider free?** Aider itself costs nothing to install. You pay the model provider for the tokens you use with your own API key, or nothing at all if you point Aider at a local model. The cost depends on the model and on how many files you add to the chat. **Which model should I use with Aider?** Any model Aider supports works. The docs use sonnet, deepseek and o3-mini in the quick start, and aliases such as opus, gemini and flash also exist. Stronger models follow edit formats more reliably; you can pair a strong architect model with a cheaper editor model. **How do I undo a change Aider made?** Type /undo. Aider commits each edit to git with a descriptive message, and /undo reverts the last commit if Aider made it. /diff shows what changed since the last message, and plain git commands work too because every change is a normal commit. **Does Aider work without git?** Yes, with --no-git, but you lose auto-commits, /undo and /diff. The Aider docs recommend keeping git on. If you don’t want a commit after each edit, use --no-auto-commits and commit yourself. **How do I make Aider follow my coding style?** Write the rules in a short CONVENTIONS.md and load it with aider --read CONVENTIONS.md, or add read: CONVENTIONS.md to .aider.conf.yml so it loads every time. The file is read-only, so Aider uses it as guidance and never edits it. --- **About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/