Aider User Guide

Aider is AI pair programming in your terminal. It connects a large language model (LLM) directly to your local git repository so you can describe changes in plain English — or by voice — and have those changes written into your files, automatically committed to git, linted, and tested. Aider reads and edits your existing codebase, builds a map of your whole project so the model understands code it can't see, and works with virtually any cloud or local LLM.

This guide covers everything you need to install Aider, connect it to a model, and use every feature productively. Architecture, the complete configuration reference, deployment, and internals live in the companion Admin Guide.

Table of Contents

1. Quick Start
2. Installation
3. Connecting to a Model
4. Your First Session
5. Everyday Usage: Adding Files & Asking for Changes
6. In-Chat Commands Reference
7. Chat Modes: code, ask, architect, context, help
8. Git Integration
9. Working in Your IDE (Watch Mode)
10. Voice-to-Code
11. Images and Web Pages
12. Copy/Paste with a Web Chat
13. The Browser GUI
14. Linting and Testing
15. Scripting and One-Shot Runs
16. Managing Context, History, and Cost
17. Configuration Files
18. How It Works: Concepts
19. Troubleshooting
20. FAQ
21. Command-Line Flag Reference

1. Quick Start

# 1. Install aider
python -m pip install aider-install
aider-install

# 2. Change into your project (ideally a git repo)
cd /to/your/project

# 3. Start aider with a model and an API key
aider --model sonnet --api-key anthropic=sk-ant-...

Once Aider starts, you are in an interactive chat. Add a file and ask for a change:

> /add src/app.py
> Add a --verbose flag that prints debug logging

Aider edits src/app.py, shows you the diff, and commits the change to git with a descriptive message. That is the whole loop: add files → describe what you want → review the diff → repeat.

Tip

You don't always need to /add files first. If you mention a filename in your request, Aider will offer to add it. And Aider's repo map lets the model reason about files that aren't in the chat at all.

2. Installation

Aider is published to PyPI as the package aider-chat and installs a single command named aider. It requires Python 3.10–3.14.

Recommended: the aider-install bootstrapper

The simplest, most reliable method uses Aider's installer, which sets up an isolated Python environment via uv so Aider's dependencies never conflict with your projects:

python -m pip install aider-install
aider-install

Installing aider-chat...
aider installed. Run `aider --help` to get started.

Alternative install methods

pipx (isolated)

pipx install aider-chat

uv (manual)

uv tool install --force --python python3.12 --with pip aider-chat@latest

pip (into current env)

python -m pip install aider-chat

Warning

Installing with plain pip into an environment that already has other packages can cause dependency conflicts (Aider pins litellm, pydantic, openai, and many others). Prefer aider-install, pipx, or uv tool install so Aider lives in its own environment.

Optional features (extras)

Some capabilities require optional dependency groups. Install them with the bracket syntax:

Verify the installation

aider --version

aider 0.x.y

Note

On first launch for a new version, Aider loads some heavy imports synchronously (this is normal and only happens once per version), then offers to show release notes.

3. Connecting to a Model

Aider talks to LLMs through LiteLLM, so it can reach almost any provider — OpenAI, Anthropic, Google Gemini, DeepSeek, xAI, OpenRouter, Azure, AWS Bedrock, and local models via Ollama or any OpenAI-compatible endpoint.

Choosing a model

Specify a model with --model. The default model is gpt-4o if you don't choose one. Aider works best with frontier coding models such as Claude Sonnet/Opus, DeepSeek R1 & V3, and OpenAI's o-series and GPT-4o.

Aider ships convenient aliases so you can type a short name instead of the full model ID:

You can define your own aliases with --alias:

aider --alias "fast:gemini/gemini-flash-latest" --alias "smart:claude-opus-4-7"

Providing API keys

There are several equivalent ways to supply credentials. Pick whichever fits your workflow:

Per-provider flag

aider --model sonnet --api-key anthropic=sk-ant-...
aider --model 4o --api-key openai=sk-...
aider --model deepseek --api-key deepseek=...

--api-key provider=key sets the PROVIDER_API_KEY environment variable for you.

Dedicated flags

aider --openai-api-key sk-... --model gpt-4o
aider --anthropic-api-key sk-ant-... --model sonnet

Environment variables

export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
export DEEPSEEK_API_KEY=...
export GEMINI_API_KEY=...
export OPENROUTER_API_KEY=...
aider --model sonnet

.env file

Create a .env in your project (Aider loads it automatically):

ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...

Tip

Use --set-env NAME=value to set any environment variable LiteLLM understands, e.g. --set-env OPENAI_API_BASE=https://my-proxy/v1 to point at a local or proxy endpoint.

Custom API base / proxies / local models

# Point OpenAI-compatible calls at a local server (e.g. Ollama, LM Studio, LiteLLM proxy)
aider --model openai/my-local-model --openai-api-base http://localhost:11434/v1 --api-key openai=dummy

Listing available models

aider --list-models gpt        # list known models matching "gpt"

Models which match "gpt":
- gpt-4o
- gpt-4o-mini
- gpt-4-turbo
...

Note

If you start Aider with no model and no keys, it will offer to connect to OpenRouter via a browser OAuth flow so you can get going without manually managing keys.

Weak and editor models

Aider can use up to three model "roles":

• Main model (--model) — does the heavy reasoning and code generation.
• Weak model (--weak-model) — a cheaper model used for commit messages and summarizing chat history. Defaults to a sensible companion of your main model.
• Editor model (--editor-model) — used in architect mode to apply the edits proposed by the main model.

aider --model opus --weak-model haiku

4. Your First Session

Run aider inside a git repository:

cd my-project
aider --model sonnet

Aider v0.x.y
Main model: claude-sonnet-4-6 with diff edit format
Weak model: claude-haiku-4-5
Git repo: .git with 248 files
Repo-map: using 1024 tokens
Use /help <question> for help, run "aider --help" to see cmd line args
>

The > prompt is where you type. You can either:

• Type a request in natural language → Aider treats it as a coding instruction.
• Type a /command → run a built-in command (see §6).
• Type !command → run a shell command and optionally feed its output to the chat.

A typical first exchange:

> /add hello.py
Added hello.py to the chat

> make hello.py print the current date and time

hello.py
<<<<<<< SEARCH
print("Hello, world!")
=======
from datetime import datetime
print(f"Hello, world! It is {datetime.now()}")
>>>>>>> REPLACE

Applied edit to hello.py
Commit a1b2c3d feat: print current date and time in hello.py

Aider edited the file, showed the change, and committed it to git automatically. Type /diff to review, or /undo to roll the commit back.

Tip

Press Ctrl-C to interrupt the model mid-response. Press it again (or use /exit) to quit. Your chat history is saved between sessions.

5. Everyday Usage: Adding Files & Asking for Changes

Add files you want edited

> /add src/models.py src/views.py

/add puts files into the chat as editable. The model sees their full contents and may modify them. Tab-completion and glob patterns (/add src/*.py) are supported.

Add reference files (read-only)

> /read-only docs/spec.md

/read-only adds files the model should consult but never edit — specs, API docs, examples. You can also pass a whole directory and Aider adds every file under it as read-only.

Drop files to save context

> /drop src/views.py

Removing files you're no longer working on frees up the model's context window (and reduces cost).

See what's in the chat

> /ls

Lists all files Aider knows about and marks which are in the chat.

Let Aider find files for you

You don't have to add everything manually. If you mention a filename in a request, Aider offers to add it. Better yet, Aider's repo map gives the model a high-level view of your entire codebase, so it can suggest the right files and reason about code that isn't in the chat.

Run shell commands inline

> !ls -la
> /run pytest -x

/run (or the ! prefix) executes a shell command. On a non-zero exit, Aider offers to add the output to the chat so the model can help fix the problem.

6. In-Chat Commands Reference

Type these at the > prompt. All commands start with /. Tab-completion is available for commands and their arguments.

Files & context

Models & modes

Git

Build, test, lint, web

Input, output & clipboard

Session management

Tip

Type /help how do I use a local model? to ask a free-form question about Aider itself. The answer is generated from Aider's own documentation (requires the [help] extra).

7. Chat Modes: code, ask, architect, context, help

Aider has several chat modes that change how it responds. Switch persistently with /chat-mode <mode> or one of the shortcut commands, or send a single message in a mode by giving the command an argument (e.g. /ask what does this function do?).

> /ask Why is the login flow failing for SSO users?
... (model explains, no files changed)

> /architect Refactor the payment module to support multiple currencies
... (architect proposes a plan; editor model applies the edits)

Note

Architect mode is also available at launch with --architect. By default it auto-accepts the architect's proposed edits; disable that with --no-auto-accept-architect.

8. Git Integration

Aider is built around git. Every change it makes is committed, so you always have a clean, reversible history.

Automatic commits

By default Aider commits each set of edits with a generated commit message. Control this behavior:

Reviewing and undoing

> /diff          # show what changed since your last message
> /undo          # revert aider's last commit
> /commit        # commit changes you made outside the chat
> /git log --oneline -5   # run any git command

Important

/undo only undoes commits that Aider made. It won't touch your own commits, which keeps your work safe.

Commit attribution

Aider can mark which changes it authored. These are configurable:

Scoping which files Aider sees

• --subtree-only — only consider files in the current subtree of the repo.
• .aiderignore — a .gitignore-style file (default .aiderignore in the git root) listing paths Aider must never read or edit. Override the location with --aiderignore.

Tip

Aider automatically adds .aider* and .env to your .gitignore so your chat history and secrets aren't committed. Skip this with --no-gitignore.

9. Working in Your IDE (Watch Mode)

You don't have to leave your editor. With watch mode, Aider monitors your source files and reacts to special AI comments you type directly in code.

Start Aider in watch mode in a terminal alongside your editor:

aider --watch-files

Then, in any file in your editor, add a comment containing ai:

def parse(data):
    # split on commas and strip whitespace ai!
    pass

Aider recognizes AI comments in many languages using #, //, --, or ; comment syntax (case-insensitive). The suffix controls what happens:

# refactor this into a list comprehension ai!
result = []
for x in items:
    result.append(x * 2)

Save the file and Aider picks up the comment, makes the change, and commits it — all without you switching windows.

Tip

Combine --watch-files with --subtree-only to limit watching to the directory you're working in.

10. Voice-to-Code

Speak your requests instead of typing them. In a session, run:

> /voice

Aider records from your microphone, transcribes the audio with a speech-to-text model, and submits the transcription as your message.

Requirements and configuration

• Voice transcription uses OpenAI Whisper, so an OPENAI_API_KEY must be set.
• Audio capture requires the system PortAudio library (installed automatically with Aider's audio dependencies on most platforms).
• webm and mp3 recording formats require ffmpeg to be installed; wav (the default) does not.

Note

If Aider reports "No audio input device detected," check your OS sound settings and that your terminal has microphone permission.

11. Images and Web Pages

You can give the model visual and reference context.

Add an image

> /paste            # paste an image from your clipboard (e.g. a screenshot or mockup)
> /add design.png   # or add an image file directly

Image support requires a multimodal model (e.g. GPT-4o, Claude, Gemini). Screenshots, diagrams, and UI mockups all work well as context.

Add a web page

> /web https://example.com/api-docs

Aider fetches the page, converts it to clean markdown, and adds it to the chat — handy for pulling in API documentation or reference material.

• By default, JavaScript-heavy pages are rendered with Playwright (install the [playwright] extra). Simpler pages use a fast HTTP fetch.
• Use --no-detect-urls to stop Aider from offering to scrape URLs it sees in your messages, or --disable-playwright to never use/install Playwright.

12. Copy/Paste with a Web Chat

If you'd rather use an LLM through its web chat interface (for example to use a subscription you already pay for), Aider streamlines the copy/paste loop.

Manual copy/paste

> /copy-context     # copies your code + repo context as markdown
# paste into the web chat, get a response, then:
> /paste            # paste the model's reply back into aider to apply edits
> /copy             # copy aider's last message to share elsewhere

Automatic copy/paste mode

aider --copy-paste

This watches your clipboard and automatically shuttles context and edits between Aider and your browser chat. You can also apply a block of edits you've copied with:

aider --apply-clipboard-edits

13. The Browser GUI

Prefer a graphical interface? Aider ships a browser-based UI built with Streamlit.

pip install aider-chat[browser]
aider --gui          # or: aider --browser

CONTROL-C to exit...
You can now view your Streamlit app in your browser.
Local URL: http://localhost:8501

The GUI provides chat, file management, diffs, and settings in your web browser.

Note

The browser GUI must be run inside a git repository. If Streamlit isn't installed, Aider prompts you to install the [browser] extra.

14. Linting and Testing

Aider can automatically check and fix its own work.

Linting

After each change, Aider can lint the edited files and fix any problems it introduced.

# Use the built-in linter (flake8 for Python, tree-sitter syntax checks for many languages)
aider --auto-lint

# Or specify your own per-language lint commands
aider --lint-cmd "python: flake8 --select=E9,F" --lint-cmd "javascript: eslint --fix"

• --auto-lint (on by default) runs the linter after each edit.
• --no-auto-lint disables it.
• /lint lints in-chat files (or all dirty files) on demand.
• aider --lint lints and fixes files, then exits.

Testing

aider --test-cmd "pytest" --auto-test

• --test-cmd sets the command Aider runs to test your code.
• --auto-test runs it automatically after each change; on failure, Aider tries to fix the problem.
• /test <cmd> runs tests on demand and feeds failures into the chat.
• aider --test runs tests once, fixes problems, then exits.

Tip

Pair --auto-test with --auto-lint to create a tight feedback loop: Aider edits → lints → tests → fixes, with you reviewing the diffs.

15. Scripting and One-Shot Runs

Aider can run non-interactively, which makes it scriptable in CI, hooks, and automation.

# Non-interactive single change
aider --model sonnet --message "Add type hints to utils.py" utils.py --yes-always

# Batch a set of instructions from a file
aider --load setup-commands.txt

Tip

--yes-always answers "yes" to every confirmation prompt — essential for unattended/CI runs. Use it carefully, since it allows Aider to proceed without asking.

You can also import Aider's Coder programmatically in Python for deeper scripting; see the Admin Guide for the architecture.

16. Managing Context, History, and Cost

LLMs have a finite context window, and tokens cost money. Aider gives you tools to manage both.

Inspect and trim context

> /tokens     # show how many tokens the current chat is using
> /drop big_file.py   # remove files you no longer need
> /clear      # clear chat history but keep files
> /reset      # drop all files AND clear history

Automatic history summarization

When the conversation grows past a limit, Aider summarizes older messages (using the weak model) to keep things within budget. Tune it with --max-chat-history-tokens.

Save and restore sessions

> /save my-session.txt   # write out the commands to recreate this session's file set
> /load my-session.txt   # restore it later

Use --restore-chat-history to reload previous chat messages when starting.

Prompt caching

For providers that support it, prompt caching can dramatically reduce cost and latency on repeated context.

aider --cache-prompts --cache-keepalive-pings 6

• --cache-prompts enables caching of the prompt prefix.
• --cache-keepalive-pings N sends N pings at 5-minute intervals to keep the cache warm.

Warning

Cost estimates may be inaccurate when streaming and caching are used together — Aider warns you when both are active.

Reasoning controls

For models that support extended thinking:

aider --model r1 --reasoning-effort high
aider --model opus --thinking-tokens 16k

Or change them mid-session with /reasoning-effort and /think-tokens.

17. Configuration Files

Anything you can pass on the command line, you can also set persistently in a config file or environment. Aider reads settings from several sources, with command-line flags taking the highest precedence, then .env, then the YAML config file.

.aider.conf.yml

A YAML file with one key per option (the flag name without the leading --). Aider searches for it in your current directory, then the git repo root, then your home directory. Override the location with --config <file> / -c.

# .aider.conf.yml
model: sonnet
weak-model: haiku
auto-commits: true
auto-lint: true
test-cmd: pytest
dark-mode: true

Caution

Use yes-always: (not yes:) as the key name in the config file. Aider detects the common yes: mistake and tells you to fix it.

.env

A standard environment file for secrets and provider settings. Aider searches the same locations and also loads ~/.aider/oauth-keys.env if present.

ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...

Specify a custom one with --env-file <file>.

Other dotfiles Aider uses

Note

Every boolean option has a --no- form, e.g. --no-auto-commits, --no-stream, --no-pretty. In YAML, set the key to false.

For the complete, exhaustive list of every setting and its default, see the Admin Guide → Configuration Reference.

18. How It Works: Concepts

A short conceptual tour so the rest of the tool makes sense. (For full internals, see the Admin Guide.)

The repo map

Aider builds a compact map of your whole repository using tree-sitter to extract the most important symbols (functions, classes, signatures) and a ranking algorithm to decide what's most relevant to your current request. This lets the model understand and reference code that isn't loaded into the chat, which is what makes Aider effective on large projects.

• --map-tokens N — roughly how many tokens to spend on the map (0 disables it).
• --map-refresh auto|always|files|manual — how often the map is rebuilt.
• /map and /map-refresh — view or refresh the map on demand.

Edit formats

Aider asks the model to express code changes in a structured edit format, then parses and applies them to your files. The right format depends on the model. Common ones:

You usually don't set this — Aider picks a sensible default per model. Override with --edit-format if needed.

Model roles

As described in §3, Aider can use a main, weak, and editor model so each job runs on the most cost-effective model.

19. Troubleshooting

Format: error → cause → solution.

Error: Can't initialize prompt toolkit / no fancy input

Cause: Your terminal doesn't support the rich input UI, or you're piping input. Solution: Run with --no-fancy-input, or --no-pretty for plain output.

Error: Terminal does not support pretty output (UnicodeDecodeError)

Cause: The terminal encoding can't render Aider's styled output. Solution: Aider automatically falls back to plain output. To force it, start with --no-pretty. On Windows, ensure your console uses UTF-8 (--encoding utf-8 is the default).

Error: Aider only works with git repos with version number 1 or 2

Cause: Your git index uses an unsupported format version. Solution: Convert it: git update-index --index-version=2, or run with --no-git.

Error: Windows PATH installation issues (the aider command isn't found)

Cause: The install directory wasn't added to your PATH (reported in issue #3123). Solution: Use the aider-install bootstrapper, then restart your terminal. If still missing, add the printed install directory to your PATH manually, or run via python -m aider.

Error: Unpaired ``` in SEARCH/REPLACE block or Expected DIVIDER

Cause: The model produced a malformed edit block (a diff-format parsing failure). Solution: This is usually transient — Aider asks the model to retry. If it persists with a particular model, switch edit formats with --edit-format whole, which is more robust for weaker models.

Error: Please set the OPENAI_API_KEY environment variable. (during /voice)

Cause: Voice transcription needs an OpenAI key. Solution: export OPENAI_API_KEY=sk-... before using /voice.

Error: No audio input device detected

Cause: No microphone is available or accessible. Solution: Check OS sound settings and terminal mic permissions; specify a device with --voice-input-device "<name>".

Error: GITHUB_COPILOT_TOKEN environment variable not found

Cause: Using a GitHub Copilot model without the required token. Solution: Set GITHUB_COPILOT_TOKEN in your environment.

Error: model warnings about unknown context window / costs

Cause: The model isn't in Aider's metadata database. Solution: Provide a .aider.model.metadata.json with the context size and costs, or pass --no-show-model-warnings to proceed anyway.

The commit message used the wrong model

Cause: Commit messages are generated by the weak model, which is independent of --model (see issue #5213). Solution: Set --weak-model explicitly, or --commit-prompt to control message generation.

Reporting a bug

> /report

This opens a pre-filled GitHub issue with your environment details (no code or keys). You can also run aider --just-check-update to see if you're behind.

20. FAQ

Q: Do I have to use git? Aider works best with git and uses it for auto-commit and undo, but you can run without it using --no-git.

Q: Which model should I use? Aider works best with top coding models — Claude Sonnet/Opus, DeepSeek R1/V3, OpenAI o-series and GPT-4o. Use the aliases (sonnet, opus, r1, 4o) for convenience. You can also use local models.

Q: Can I use a local LLM? Yes. Point --openai-api-base (or --set-env OPENAI_API_BASE=...) at any OpenAI-compatible server such as Ollama or LM Studio.

Q: How does Aider know about files I haven't added? Through the repo map — a tree-sitter-derived summary of your whole project that the model can reference. Add files with /add only when you want them edited in full detail.

Q: Does Aider send my code anywhere besides my model provider? Your code only goes to the LLM provider you configure. Optional, anonymous usage analytics never include your code, chat messages, keys, or personal info, and can be disabled with --analytics-disable.

Q: How do I stop auto-commits? --no-auto-commits. You can still commit on demand with /commit.

Q: How do I undo a change Aider made? /undo reverts Aider's last commit. /diff shows you what changed first.

Q: Can I run Aider in my editor instead of a terminal? Yes — use --watch-files and write # ... ai! comments in your code (see §9).

Q: How do I use a model Aider doesn't recognize? Add it to .aider.model.settings.yml and/or .aider.model.metadata.json, or pass settings via flags.

Q: How do I reduce cost? Use a cheaper model, set a --weak-model, enable --cache-prompts, drop unused files with /drop, and keep the repo map small with --map-tokens.

Q: Can I script Aider in CI? Yes. Use --message/--message-file for one-shot runs and --yes-always to skip prompts.

Q: How do I upgrade Aider? aider --upgrade (upgrades from PyPI), or reinstall with aider-install. Use --install-main-branch for the latest development version.

Q: How do I get shell tab-completion? aider --shell-completions bash (or zsh, fish) prints a completion script you can source.

Q: Does Aider support languages other than Python? Yes — 100+ languages via tree-sitter, including JavaScript, Rust, Go, Ruby, C/C++, PHP, and many more.

Q: What's the difference between /ask and /code? /ask answers questions without editing files; /code (the default mode) makes changes.

Q: What does architect mode do? It splits the work: a strong model plans the change in prose, and a separate editor model turns the plan into precise file edits — often improving results on complex tasks.

21. Command-Line Flag Reference

The most commonly used flags. Every boolean flag has a --no- counterpart. Run aider --help for the complete, always-current list.

Models & API

Files, git & repo map

Lint, test & run

Interface & input

Voice

Caching, history & config

Updates & maintenance