# 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](#1-quick-start)
2. [Installation](#2-installation)
3. [Connecting to a Model](#3-connecting-to-a-model)
4. [Your First Session](#4-your-first-session)
5. [Everyday Usage: Adding Files & Asking for Changes](#5-everyday-usage-adding-files--asking-for-changes)
6. [In-Chat Commands Reference](#6-in-chat-commands-reference)
7. [Chat Modes: code, ask, architect, context, help](#7-chat-modes-code-ask-architect-context-help)
8. [Git Integration](#8-git-integration)
9. [Working in Your IDE (Watch Mode)](#9-working-in-your-ide-watch-mode)
10. [Voice-to-Code](#10-voice-to-code)
11. [Images and Web Pages](#11-images-and-web-pages)
12. [Copy/Paste with a Web Chat](#12-copypaste-with-a-web-chat)
13. [The Browser GUI](#13-the-browser-gui)
14. [Linting and Testing](#14-linting-and-testing)
15. [Scripting and One-Shot Runs](#15-scripting-and-one-shot-runs)
16. [Managing Context, History, and Cost](#16-managing-context-history-and-cost)
17. [Configuration Files](#17-configuration-files)
18. [How It Works: Concepts](#18-how-it-works-concepts)
19. [Troubleshooting](#19-troubleshooting)
20. [FAQ](#20-faq)
21. [Command-Line Flag Reference](#21-command-line-flag-reference)

---

## 1. Quick Start

```bash
# 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:

```text
> /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`](https://github.com/astral-sh/uv) so Aider's dependencies never conflict with your projects:

```bash
python -m pip install aider-install
aider-install
```

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

### Alternative install methods

=== "pipx (isolated)"

    ```bash
    pipx install aider-chat
    ```

=== "uv (manual)"

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

=== "pip (into current env)"

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

| Extra | Command | Enables |
|-------|---------|---------|
| `browser` | `pip install aider-chat[browser]` | The browser GUI (`--gui`), powered by Streamlit |
| `help` | `pip install aider-chat[help]` | The in-chat `/help` knowledge base |
| `playwright` | `pip install aider-chat[playwright]` | Rendering JavaScript-heavy pages for `/web` |
| `dev` | `pip install aider-chat[dev]` | Test and lint tooling for contributors |

### Verify the installation

```bash
aider --version
```

```text
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](https://docs.litellm.ai/), 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:

| Alias | Resolves to |
|-------|-------------|
| `sonnet` | `claude-sonnet-4-6` |
| `opus` | `claude-opus-4-7` |
| `haiku` | `claude-haiku-4-5` |
| `4o` | `gpt-4o` |
| `deepseek` | `deepseek/deepseek-chat` |
| `r1` | `deepseek/deepseek-reasoner` |
| `flash` | `gemini/gemini-flash-latest` |
| `flash-lite` | `gemini/gemini-2.5-flash-lite` |
| `gemini` | `gemini/gemini-3-pro-preview` |
| `gemini-2.5-pro` | `gemini/gemini-2.5-pro` |
| `grok3` | `xai/grok-3-beta` |

You can define your own aliases with `--alias`:

```bash
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"

    ```bash
    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"

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

=== "Environment variables"

    ```bash
    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):

    ```bash
    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

```bash
# 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

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

```text
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.

```bash
aider --model opus --weak-model haiku
```

---

## 4. Your First Session

Run `aider` inside a git repository:

```bash
cd my-project
aider --model sonnet
```

```text
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](#6-in-chat-commands-reference)).
- **Type `!command`** → run a shell command and optionally feed its output to the chat.

A typical first exchange:

```text
> /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

```text
> /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)

```text
> /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

```text
> /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

```text
> /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

```text
> !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

| Command | Description |
|---------|-------------|
| `/add` | Add files to the chat so aider can edit them or review them in detail |
| `/drop` | Remove files from the chat session to free up context space |
| `/read-only` | Add files for reference only, or turn added files into read-only |
| `/ls` | List all known files and indicate which are included in the chat session |
| `/tokens` | Report on the number of tokens used by the current chat context |
| `/clear` | Clear the chat history |
| `/reset` | Drop all files and clear the chat history |
| `/map` | Print out the current repository map |
| `/map-refresh` | Force a refresh of the repository map |

### Models & modes

| Command | Description |
|---------|-------------|
| `/model` | Switch the main model to a new LLM |
| `/editor-model` | Switch the editor model to a new LLM |
| `/weak-model` | Switch the weak model to a new LLM |
| `/models` | Search the list of available models |
| `/chat-mode` | Switch to a new chat mode |
| `/ask` | Ask questions about the code base without editing any files |
| `/code` | Ask for changes to your code |
| `/architect` | Enter architect/editor mode using 2 different models |
| `/context` | Enter context mode to see surrounding code context |
| `/ok` | Alias for `/code Ok, please go ahead and make those changes.` |
| `/reasoning-effort` | Set the reasoning effort level (number or low/medium/high) |
| `/think-tokens` | Set the thinking token budget, e.g. `8096`, `8k`, `10.5k`, `0.5M`, or `0` to disable |

### Git

| Command | Description |
|---------|-------------|
| `/commit` | Commit edits made to the repo outside the chat (commit message optional) |
| `/diff` | Display the diff of changes since the last message |
| `/undo` | Undo the last git commit if it was done by aider |
| `/git` | Run a git command (output excluded from chat) |

### Build, test, lint, web

| Command | Description |
|---------|-------------|
| `/run` | Run a shell command and optionally add the output to the chat (alias: `!`) |
| `/test` | Run a shell command and add the output to the chat on non-zero exit code |
| `/lint` | Lint and fix in-chat files, or all dirty files if none are in chat |
| `/web` | Scrape a webpage, convert to markdown, and send it in a message |

### Input, output & clipboard

| Command | Description |
|---------|-------------|
| `/voice` | Record and transcribe voice input |
| `/paste` | Paste image/text from the clipboard into the chat (optionally name the image) |
| `/copy` | Copy the last assistant message to the clipboard |
| `/copy-context` | Copy the current chat context as markdown, suitable to paste into a web UI |
| `/editor` (alias `/edit`) | Open an external editor to write a prompt |
| `/multiline-mode` | Toggle multiline mode (swaps behavior of Enter and Meta+Enter) |

### Session management

| Command | Description |
|---------|-------------|
| `/save` | Save commands to a file that can reconstruct the current chat session's files |
| `/load` | Load and execute commands from a file |
| `/settings` | Print out the current settings |
| `/help` | Ask questions about aider |
| `/report` | Report a problem by opening a GitHub issue |
| `/exit`, `/quit` | Exit the application |

> [!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?`).

| Mode | What it does |
|------|--------------|
| **code** (default) | Makes changes to your files using the model's edit format. |
| **ask** | Answers questions about your code *without* editing any files. Great for exploring before committing to a change. |
| **architect** | Uses **two** models: a strong "architect" model proposes the solution in prose, then a separate **editor model** turns that into precise file edits. Often produces higher-quality results on hard problems. |
| **context** | Identifies and shows the surrounding code context relevant to your request. |
| **help** | Answers questions about using Aider itself, drawing on Aider's documentation. |

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

| Flag | Effect |
|------|--------|
| `--no-auto-commits` | Don't auto-commit LLM changes (you commit manually). |
| `--no-dirty-commits` | Don't commit when the repo is already dirty before Aider runs. |
| `--commit` | Commit all pending changes with a generated message, then exit. |
| `--commit-prompt "..."` | Use a custom prompt for generating commit messages. |
| `--no-git` | Run without using git at all. |

### Reviewing and undoing

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

| Flag | Effect |
|------|--------|
| `--attribute-co-authored-by` | Add a `Co-authored-by: aider (model)` trailer (default: on). |
| `--no-attribute-author` / `--no-attribute-committer` | Don't modify the git author/committer name. |
| `--attribute-commit-message-author` | Prefix commit messages with `aider: ` when aider authored the change. |
| `--attribute-commit-message-committer` | Prefix *all* commit messages with `aider: `. |

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

```bash
aider --watch-files
```

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

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

| Comment ends with | Meaning |
|-------------------|---------|
| `ai!` | **Do it now** — Aider implements the requested change immediately. |
| `ai?` | **Answer my question** — Aider responds without necessarily editing. |
| `ai` (no `!`/`?`) | Marks a request; Aider acts when it sees a triggering `ai!`/`ai?`. |

```python
# 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:

```text
> /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.

| Flag | Default | Purpose |
|------|---------|---------|
| `--voice-format` | `wav` | Recording format (`wav`, `webm`, `mp3`). |
| `--voice-language` | `en` | Transcription language (ISO 639-1 code). |
| `--voice-input-device` | (system default) | Name of the microphone device to use. |

> [!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

```text
> /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

```text
> /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

```text
> /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

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

```bash
aider --apply-clipboard-edits
```

---

## 13. The Browser GUI

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

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

```text
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.

```bash
# 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

```bash
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.

| Flag | Behavior |
|------|----------|
| `--message "..."` / `-m` | Send one message, process the reply, then exit. |
| `--message-file <f>` / `-f` | Read the message from a file, process it, then exit. |
| `--apply <f>` | Apply edits from a file instead of running a chat. |
| `--lint` | Lint and fix, then exit. |
| `--test` | Run tests (requires `--test-cmd`), fix problems, then exit. |
| `--commit` | Commit pending changes with a generated message, then exit. |
| `--exit` | Do all startup work, then exit before accepting input (useful for warming caches/debugging). |
| `--load <f>` | Run `/commands` from a file at launch. |

```bash
# 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

```text
> /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

```text
> /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.

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

```bash
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`.

```yaml
# .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.

```bash
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
```

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

### Other dotfiles Aider uses

| File | Purpose |
|------|---------|
| `.aider.conf.yml` | Main configuration (YAML). |
| `.env` | API keys and environment variables. |
| `.aiderignore` | Paths Aider must never read or edit. |
| `.aider.model.settings.yml` | Settings for models Aider doesn't know about. |
| `.aider.model.metadata.json` | Context-window sizes and costs for unknown models. |
| `.aider.input.history` | Your input history (auto-managed). |
| `.aider.chat.history.md` | Markdown transcript of the chat (auto-managed). |
| `.aider.llm.history` | Optional raw LLM conversation log (`--llm-history-file`). |

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

| Format | Description |
|--------|-------------|
| `diff` | SEARCH/REPLACE blocks (the default for most strong models). |
| `whole` | The model returns whole files. |
| `udiff` / `udiff-simple` | Unified-diff style edits. |
| `diff-fenced` | SEARCH/REPLACE inside a fenced block (used by some Gemini models). |
| `patch` | A structured patch format. |
| `architect` | Prose plan from the main model, applied by the editor model. |

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](#3-connecting-to-a-model), 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](https://github.com/Aider-AI/aider/issues/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](https://github.com/Aider-AI/aider/issues/5213)).
**Solution:** Set `--weak-model` explicitly, or `--commit-prompt` to control message generation.

### Reporting a bug

```text
> /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](#9-working-in-your-ide-watch-mode)).

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

| Flag | Default | Description |
|------|---------|-------------|
| `--model` | `gpt-4o` | Main model for the chat. |
| `--weak-model` | (auto) | Model for commit messages and history summarization. |
| `--editor-model` | (auto) | Model used to apply edits in architect mode. |
| `--edit-format` / `--chat-mode` | (per model) | Edit format the LLM should use. |
| `--architect` | off | Use architect edit format for the main chat. |
| `--api-key` | — | `provider=key`, sets `PROVIDER_API_KEY` (repeatable). |
| `--openai-api-key`, `--anthropic-api-key` | — | Provider keys. |
| `--openai-api-base` | — | Custom API base URL (proxies, local models). |
| `--set-env` | — | Set an arbitrary environment variable (repeatable). |
| `--alias` | — | Define `alias:model-name` (repeatable). |
| `--list-models` / `--models` | — | List known models matching a name. |
| `--reasoning-effort` | (unset) | Reasoning effort API parameter. |
| `--thinking-tokens` | (unset) | Thinking token budget (`0` to disable). |
| `--timeout` | (none) | API call timeout in seconds. |
| `--no-verify-ssl` | verify on | Disable SSL certificate verification. |

### Files, git & repo map

| Flag | Default | Description |
|------|---------|-------------|
| `--file` | — | File to edit (repeatable); positional files also accepted. |
| `--read` | — | Read-only reference file or directory (repeatable). |
| `--no-git` | git on | Don't look for or use a git repo. |
| `--no-auto-commits` | commits on | Don't auto-commit LLM changes. |
| `--no-dirty-commits` | on | Don't commit a dirty repo before editing. |
| `--commit` | — | Commit pending changes, then exit. |
| `--commit-prompt` | — | Custom commit-message prompt. |
| `--subtree-only` | off | Only consider files in the current subtree. |
| `--aiderignore` | `.aiderignore` | Path to the aider ignore file. |
| `--map-tokens` | (per model) | Token budget for the repo map (`0` disables). |
| `--map-refresh` | `auto` | `auto`, `always`, `files`, or `manual`. |
| `--map-multiplier-no-files` | `2` | Map token multiplier when no files are specified. |
| `--watch-files` | off | Watch files for `ai` comments (IDE mode). |

### Lint, test & run

| Flag | Default | Description |
|------|---------|-------------|
| `--lint-cmd` | — | Per-language lint command, e.g. `"python: flake8 ..."` (repeatable). |
| `--no-auto-lint` | lint on | Disable auto-lint after changes. |
| `--test-cmd` | — | Command to run tests. |
| `--auto-test` | off | Run tests automatically after changes. |
| `--lint` / `--test` / `--commit` | — | One-shot lint / test / commit, then exit. |

### Interface & input

| Flag | Default | Description |
|------|---------|-------------|
| `--gui` / `--browser` | off | Run the Streamlit browser GUI. |
| `--message` / `-m` | — | One-shot message, then exit. |
| `--message-file` / `-f` | — | Read message from a file, then exit. |
| `--copy-paste` | off | Auto copy/paste between aider and a web chat. |
| `--apply-clipboard-edits` | — | Apply clipboard edits using the editor format. |
| `--vim` | off | VI editing mode in the terminal. |
| `--dark-mode` / `--light-mode` | — | Color scheme for your terminal background. |
| `--no-pretty` | pretty on | Disable colorized output. |
| `--no-stream` | stream on | Disable streaming responses. |
| `--multiline` | off | Multiline input mode (Meta-Enter to submit). |
| `--no-fancy-input` | on | Disable history/completion input UI. |
| `--code-theme` | `default` | Markdown code highlighting theme. |
| `--encoding` | `utf-8` | Input/output encoding. |
| `--yes-always` | — | Answer yes to every confirmation (for automation). |
| `-v` / `--verbose` | off | Verbose output. |

### Voice

| Flag | Default | Description |
|------|---------|-------------|
| `--voice-format` | `wav` | `wav`, `webm`, or `mp3`. |
| `--voice-language` | `en` | Transcription language (ISO 639-1). |
| `--voice-input-device` | (default) | Microphone device name. |

### Caching, history & config

| Flag | Default | Description |
|------|---------|-------------|
| `--cache-prompts` | off | Enable prompt caching. |
| `--cache-keepalive-pings` | `0` | Pings at 5-min intervals to keep cache warm. |
| `--max-chat-history-tokens` | (per model) | Soft token limit before summarization. |
| `--restore-chat-history` | off | Restore previous chat messages on start. |
| `--config` / `-c` | (search) | Config file path. |
| `--env-file` | `.env` | `.env` file path. |
| `--model-settings-file` | `.aider.model.settings.yml` | Settings for unknown models. |
| `--model-metadata-file` | `.aider.model.metadata.json` | Context/costs for unknown models. |

### Updates & maintenance

| Flag | Description |
|------|-------------|
| `--upgrade` / `--update` | Upgrade aider to the latest PyPI release. |
| `--install-main-branch` | Install the latest version from the main branch. |
| `--just-check-update` | Check for updates and report via exit code. |
| `--no-check-update` | Don't check for new versions on launch. |
| `--analytics-disable` | Permanently disable anonymous analytics. |
| `--shell-completions` | Print a shell completion script (`bash`/`zsh`/`fish`). |
| `--version` | Show version and exit. |

---

_Generated June 2026 from Aider-AI/aider at 5dc9490. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._