How to use Aider: a step-by-step guide

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=<key> (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 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 and 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.

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:

cd /to/your/project

# Anthropic
aider --model sonnet --api-key anthropic=<key>

# OpenAI
aider --model o3-mini --api-key openai=<key>

# DeepSeek
aider --model deepseek --api-key deepseek=<key>

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=<key> 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:

aider --alias "fast:gpt-4o-mini" --model fast

Inside a session, /model <name> switches the main model, /models <search> 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 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:

aider src/api/users.py tests/test_users.py

or add them later:

/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 <files> adds files Aider may edit.
• /read-only <files> adds reference files it can read but not change (docs, an example module).
• /drop <files> 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:

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.

/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 <mode> does the same. --chat-mode <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:

/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:

Override with --edit-format <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 <command> 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.

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 <file> loads only that file.

# .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:

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 <command> runs a command and, if it fails, adds the output to the chat.
• /run <command> (or !<command>) 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:

# CONVENTIONS.md
- Prefer httpx over requests for making http requests.
- Use types everywhere possible.
- Every new endpoint needs a test in tests/api/.

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 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:

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 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 grid next to Claude Code or Codex, and start agents in their own worktrees from the Git panel.
• Review and flows. Aider agents get automatic 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 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 is the same guide for that tool.