# Aider Integration

> **Last verified**: 2026-09-18 · 📄 Per official docs (upstream repository; see the status note below)

> **Upstream activity**: the last commit in Aider-AI/aider is dated 2026-05-22 with no releases since (checked via the GitHub API on 2026-09-18). Everything on this page still works; for an actively maintained alternative look at [Cline](/docs/ide/cline) or [Kilo Code](/docs/ide/kilo-code).

## At a glance

| Item | Details |
|---|---|
| Models you can use | Claude ✅ (`anthropic/` prefix on the Anthropic endpoint) · GPT ✅ · Chinese models ✅ (OpenAI-compatible endpoint) · Gemini ❌ (no Gemini route documented here) |
| Protocol & Base URL | Anthropic: `https://api.qcode.cc/api` · OpenAI: `https://api.qcode.cc/openai/v1` |
| Relevant env vars | `ANTHROPIC_API_BASE` and `OPENAI_API_BASE` point to the two legs respectively |
| Where to configure | CLI flags or `~/.aider.conf.yml` |
| Official docs | [aider.chat](https://aider.chat) |

[Aider](https://github.com/paul-gauthier/aider) is a popular open-source AI pair programmer (39K+ GitHub stars) that runs in your terminal and supports 100+ languages. It routes models through LiteLLM, so it speaks **both the Anthropic and the OpenAI protocol**.

## 🔴 Read this first: Claude requires the Anthropic endpoint

QCode's OpenAI-compatible endpoint **does not accept Claude models**. Pointing `OPENAI_API_BASE` at QCode and then using an `openai/claude-…` model name returns `model_not_available_on_endpoint`.

| Model you want | Aider model prefix | Env var | Value |
|---|---|---|---|
| Claude | `anthropic/` | `ANTHROPIC_API_BASE` | `https://api.qcode.cc/api` |
| GPT / the four Chinese families | `openai/` | `OPENAI_API_BASE` | `https://api.qcode.cc/openai/v1` |

See [Endpoints & API Paths](/docs/getting-started/endpoints-and-api-paths).

## Why Aider

- **Fully open source**: you only pay for API usage
- **Architect mode**: one model plans, another edits — better output quality
- **Deep Git integration**: every AI edit becomes a git commit
- **Repository Map**: tree-sitter based indexing of the whole codebase
- **Both protocols**: Claude over Anthropic, GPT / Chinese models over OpenAI

## Install

```bash
# pipx recommended (isolated install)
pipx install aider-chat

# or pip
pip install aider-chat
```

## Configure Claude (Anthropic endpoint)

```bash
export ANTHROPIC_API_BASE="https://api.qcode.cc/api"
export ANTHROPIC_API_KEY="cr_your_qcode_key"

aider --model anthropic/claude-sonnet-5
```

LiteLLM appends `/v1/messages` to this base automatically, so **stop at `/api`** with no trailing slash.

> **The variable name varies by version**: LiteLLM has historically used both `ANTHROPIC_API_BASE` and `ANTHROPIC_BASE_URL`. If one has no effect, try the other, or pass `--anthropic-api-key` on the command line. Defer to the [Aider docs](https://aider.chat/).

Persist it (append to `~/.zshrc` or `~/.bashrc`):

```bash
echo 'export ANTHROPIC_API_BASE="https://api.qcode.cc/api"' >> ~/.zshrc
echo 'export ANTHROPIC_API_KEY="cr_your_qcode_key"' >> ~/.zshrc
source ~/.zshrc
```

## Configure GPT and Chinese models (OpenAI-compatible endpoint)

```bash
export OPENAI_API_BASE="https://api.qcode.cc/openai/v1"
export OPENAI_API_KEY="cr_your_qcode_key"

aider --model openai/gpt-5.5
```

The four Chinese families (`glm-5.2` / `kimi-k3` / `deepseek-v4-pro` / `qwen3.7-max` …) work on both legs; ids are in [Chinese Models](/docs/usage/cn-models).

## Usage

```bash
cd /path/to/your/project

# Everyday driver
aider --model anthropic/claude-sonnet-5

# Flagship
aider --model anthropic/claude-opus-5
```

### Architect mode (recommended)

One model plans, another applies the edits:

```bash
# Opus plans + Sonnet edits (recommended)
aider --architect --model anthropic/claude-opus-5 --editor-model anthropic/claude-sonnet-5

# Sonnet plans + Haiku edits (cheaper)
aider --architect --model anthropic/claude-sonnet-5 --editor-model anthropic/claude-haiku-4-5
```

> Both models must sit on the **same protocol leg**. Mixing them (e.g. `anthropic/` planner with an `openai/claude-…` editor) fails on the editor side.

### Common commands

Inside an Aider session:

| Command | What it does |
|---------|--------------|
| `/add file.py` | Add a file to the chat context |
| `/drop file.py` | Remove a file |
| `/run pytest` | Run a command and send the output to the AI |
| `/diff` | Show all changes |
| `/undo` | Undo the last AI edit |
| `/commit` | Commit current changes |
| `/help` | Show help |

## Alternative endpoints

The four access domains are functionally identical and differ only in network routing. One key works on all of them:

| Node | Anthropic (Claude) | OpenAI (GPT / Chinese) |
|------|--------------------|------------------------|
| Global | `https://api.qcode.cc/api` | `https://api.qcode.cc/openai/v1` |
| Asia (best from mainland China) | `https://asia.qcode.cc/api` | `https://asia.qcode.cc/openai/v1` |
| US | `https://us.qcode.cc/api` | `https://us.qcode.cc/openai/v1` |
| Europe | `https://eu.qcode.cc/api` | `https://eu.qcode.cc/openai/v1` |

## Available models

| Model | Name in Aider | Notes |
|-------|---------------|-------|
| Claude Sonnet 5 | `anthropic/claude-sonnet-5` | Recommended, best value |
| Claude Opus 5 | `anthropic/claude-opus-5` | Most capable |
| Claude Haiku 4.5 | `anthropic/claude-haiku-4-5` | Cheap and fast |
| GPT 5.5 | `openai/gpt-5.5` | OpenAI flagship |
| GLM 5.2 | `openai/glm-5.2` | Chinese, low unit price |

> 4.x models such as `claude-sonnet-4-6` and `claude-opus-4-8` are still sold (same `anthropic/` prefix). The live list is on [qcode.cc/models](https://qcode.cc/models).

## Aider vs Claude Code CLI

| Dimension | Aider | Claude Code CLI |
|-----------|-------|-----------------|
| Open source | Fully open | Closed |
| Git integration | Auto-commit per edit | Manual /commit |
| Architect mode | Two-model plan + edit | Single model |
| Tooling | File edit + shell | Richer (LSP, search, browser) |
| Context handling | Repository Map indexing | 200K–1M token window |
| Quota | Shares your QCode.cc plan | Shares your QCode.cc plan |

**A good pairing**: Aider for quick edits and Architect-mode planning, Claude Code CLI for deep project analysis and automation.

## Troubleshooting

### `model_not_available_on_endpoint`

You sent a Claude model to the OpenAI leg. Check two things: the model prefix should be `anthropic/`, not `openai/`; and the base should be `ANTHROPIC_API_BASE=https://api.qcode.cc/api`.

### "Model not found"

Aider needs the prefix to know which provider to use:

```bash
# correct
aider --model anthropic/claude-sonnet-5

# wrong (missing prefix)
aider --model claude-sonnet-5
```

### Requests time out

Try another node, or raise the timeout:

```bash
aider --model anthropic/claude-sonnet-5 --timeout 120
```

## Next

- [Endpoints & API Paths](/docs/getting-started/endpoints-and-api-paths) — protocol × model-family table
- [Cline Integration](/docs/ide/cline) — a GUI alternative inside VS Code
- [CLI Tips](/docs/usage/cli-tips) — advanced Claude Code usage
- [Aider docs](https://aider.chat/)