# Aider Integration

AVELIN API is fully compatible with [Aider](https://aider.chat) — an AI pair programming tool that runs in your terminal. Aider lets you edit code in your local git repository through natural language, with automatic commits, multi-file editing, and repo-map awareness powered by AVELIN's frontier models.

> **Why AVELIN + Aider?** Aider's repo-map and multi-file editing shine with 1M-token context windows. AVELIN delivers the best coding models with 90% prompt caching discounts, automatic failover, and ~100 tps throughput — all through a single OpenAI-compatible endpoint.

---

## Quick Setup

### Step 1: Get your AVELIN API key

Sign up at [avelin.ai](https://avelin.ai) and generate an API key. It will look like `sk-ave...xxxx`.

### Step 2: Install Aider

```bash
# Option A: pip
pip install aider-chat

# Option B: dedicated installer (recommended for isolated environments)
aider-install

# Option C: Homebrew (macOS)
brew install aider
```

### Step 3: Configure Aider

Aider supports OpenAI-compatible endpoints out of the box. You can configure it via environment variables, a config file, or CLI flags.

#### Option A: Environment Variables

```bash
export OPENAI_API_BASE=https://api.avelin.ai/v1
export OPENAI_API_KEY=sk-ave...xxxx
```

Add these to your `~/.bashrc` or `~/.zshrc` for persistence.

#### Option B: Config File

Create or edit `~/.aider.conf.yml`:

```yaml
openai-api-base: https://api.avelin.ai/v1
openai-api-key: sk-ave...xxxx
model: openai/avelin-coding-pro
```

#### Option C: CLI Flags

```bash
aider --model openai/avelin-coding-pro \
      --openai-api-base https://api.avelin.ai/v1 \
      --openai-api-key sk-ave...xxxx
```

### Step 4: Select Your Model

Start Aider with your chosen model:

```bash
# Using the config file (model already set)
aider

# Or specify on the command line
aider --model openai/avelin-coding-pro

# Add files to work with
aider src/main.py src/utils.py
```

---

## Recommended Models

### Primary Recommendation: `avelin-coding-pro`

For pair programming in the terminal:

| Feature | avelin-coding-pro | Why it matters for Aider |
|---|---|---|
| **Context window** | **1M tokens** | Aider's repo-map plus full file contents fit without truncation |
| **Max output** | **65K tokens** | Large multi-file diffs and comprehensive refactors |
| **Throughput** | **~100 tokens/sec** | 2× faster than standard tiers — tighter edit loops |
| **Reasoning** | Deep step-by-step thinking | Understands cross-file dependencies and side effects |
| **Tool calling** | First-class support | Reliable structured edit format for Aider's diff/whole modes |

### Alternative Models

| Model | When to use |
|---|---|
| `avelin-coding-fast` | Lighter coding tasks, quick questions — saves cost on simple edits |
| `avelin-coding-ultra` | System design, architecture reviews, large-scale refactors (use as architect model) |
| `avelin-fast` | Quick lookups, simple fixes — lowest cost, fastest response |

---

## Why AVELIN for Aider?

### 1. **Cost Optimization**

Aider sends your repo-map and file contents with every request. AVELIN minimizes the cost:

- **Prompt caching**: ~80% cost reduction on repeated system prompts and repo-maps
- **Competitive pricing**: Lower per-token costs than direct provider APIs
- **Pay-per-token**: No subscription lock-in — pay only for what you use

### 2. **Model Diversity**

Access multiple frontier coding models through one API. Use Aider's architect/edit model split:

```bash
aider --architect \
      --model openai/avelin-coding-ultra \
      --editor-model openai/avelin-coding-pro
```

This lets the architect model plan changes while the editor model writes the code.

### 3. **Reliability**

- **Automatic failover**: If one provider is slow or down, AVELIN switches to another
- **Retry logic**: Transient errors are handled automatically
- **99.9% uptime**: Enterprise-grade infrastructure — no interrupted editing sessions

### 4. **1M Context Windows**

Aider's repo-map gives the model a structural overview of your entire codebase. With 1M-token context windows, even large monorepos fit comfortably — no need to aggressively exclude files from the map.

---

## Example Workflows

### Multi-File Editing

```bash
# Start aider with the files you want to work on
$ aider src/auth.py src/models.py src/routes.py

> Add JWT authentication with refresh tokens. Update the User model
  to store refresh token hashes, and add login/refresh/logout endpoints.

Aider: I'll make these changes across all three files:

1. src/models.py — Add refresh_token_hash field to User model
2. src/auth.py — Add JWT generation, refresh token creation, and verification
3. src/routes.py — Add /auth/login, /auth/refresh, /auth/logout endpoints

[Applies edits to all three files]
[Commits: "Add JWT authentication with refresh tokens"]
```

### Refactoring Workflow

```bash
$ aider --map-tokens 4096

> /add src/**/*.py

> Refactor all database access to use the repository pattern.
  Create a BaseRepository class and migrate existing queries.

Aider: I'll analyze the codebase and implement the repository pattern...

[Creates src/repositories/base.py]
[Creates src/repositories/user_repo.py]
[Updates src/services/user_service.py]
[Commits: "Refactor database access to repository pattern"]
```

### Bug Fixing

```bash
$ aider src/api/endpoints.py tests/test_endpoints.py

> The /users endpoint returns a 500 error when the page parameter
  is negative. Fix the bug and add a test for edge cases.

Aider: Let me look at the endpoint code...

I see the issue — there's no validation on the `page` parameter before
it's used in the SQL OFFSET clause. I'll add validation and a test.

[Fixes src/api/endpoints.py — adds parameter validation]
[Updates tests/test_endpoints.py — adds edge case tests]
[Commits: "Fix 500 error on negative page parameter"]
```

---

## Advanced Configuration

### Full `.aider.conf.yml`

```yaml
# API Configuration
openai-api-base: https://api.avelin.ai/v1
openai-api-key: sk-ave...xxxx

# Model Selection
model: openai/avelin-coding-pro

# Editor Model (for architect mode)
editor-model: openai/avelin-coding-pro

# Weak/Fast model (for simple tasks like commit messages)
weak-model: openai/avelin-fast

# Context and Map Settings
map-tokens: 4096
map-multiplier-no-files: 2

# Edit Format
edit-format: diff

# Git Settings
auto-commits: true
dirty-commits: true
attribute-author: true
attribute-committer: true

# Output
dark-mode: true
pretty: true
```

### Architect Mode

Use a stronger model for planning and a faster model for editing:

```bash
aider --architect \
      --model openai/avelin-coding-ultra \
      --editor-model openai/avelin-coding-pro \
      --weak-model openai/avelin-fast
```

### Map Type Settings for Large Repos

Aider's repo-map is essential for understanding large codebases. Tune it for your project:

```yaml
# Increase map tokens for large repos
map-tokens: 8192

# Use tree-sitter for better code parsing
map-tokens-mult: 2

# Exclude generated/vendor files
read: .aiderignore
```

Create a `.aiderignore` file (gitignore syntax) to exclude noise:

```
node_modules/
dist/
*.min.js
vendor/
__pycache__/
*.pyc
```

### Model-Specific Flags

```bash
# Higher max output for large refactors
aider --model openai/avelin-coding-pro --max-chat-history-tokens 65536

# Streaming for real-time output
aider --stream

# No streaming (if terminal has issues)
aider --no-stream
```

---

## Troubleshooting

| Issue | Solution |
|---|---|
| **"Model not found"** | Ensure the model name is prefixed with `openai/` (e.g., `openai/avelin-coding-pro`) |
| **"API key invalid"** | Verify your AVELIN API key starts with `sk-ave` and `OPENAI_API_BASE` is set to `https://api.avelin.ai/v1` |
| **Slow responses** | Try `avelin-fast` for simpler tasks, or check your network connection |
| **Edit format errors** | Switch edit format: `--edit-format whole` or `--edit-format diff` |
| **Repo-map too large** | Reduce `--map-tokens` or add exclusions to `.aiderignore` |
| **Context overflow** | Start a new chat (`/clear`) or use `/drop` to remove files you no longer need |
| **Streaming garbled output** | Use `--no-stream` flag or try a different terminal emulator |
| **Architect mode not working** | Ensure both `--model` and `--editor-model` are set with `openai/` prefix |

---

## Related

- [API Quickstart](../../api/quickstart.md) — First API call in 5 minutes
- [Claude Code Guide](claude-code.md) — Anthropic's CLI coding tool
- [Hermes Agent Guide](../hermes.md) — Terminal-based agentic coding tool
- [Cursor Guide](cursor.md) — AI-first code editor
- [Cline Guide](cline.md) — Autonomous VS Code agent
- [Model Catalog](../../models/README.md) — Full model comparison
- [Aider Docs](https://aider.chat/docs) — Official Aider documentation