---
title: Run Aider on a Repo
description: "Pair program with Aider in an isolated sandbox with full git integration."
---

# Run Aider on a Repo

[Aider](https://aider.chat) is an AI pair programming tool that works directly in your terminal with deep git integration. This recipe sets up Aider in an isolated Caged sandbox.

## Prerequisites

- Caged CLI installed (`brew install caged-dev/tap/caged` or `curl -fsSL https://get.caged.dev | sh`)
- Caged account with API key (`caged login`)
- An `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` stored in your Caged secrets

## Quick Start Examples

### Basic: Sandbox with Aider

```bash
# Create sandbox with Aider pre-installed
caged up --template python-312 --agents aider

# Connect to the sandbox
caged connect cage_xxxxx

# Inside the sandbox, Aider is ready
caged> aider
```

### Clone a Repo + Aider

```bash
# Clone your repo and install Aider
caged up \
  --template python-312 \
  --repo https://github.com/your-org/your-project \
  --agents aider \
  --env "OPENAI_API_KEY=$OPENAI_API_KEY"

# Connect and start pair programming
caged connect cage_xxxxx
caged> aider --message "Add tests for the user module"
```

### Full Example with All Options

```bash
caged up \
  --template python-312 \
  --cpus 2 \
  --memory 1024 \
  --repo https://github.com/your-org/your-project \
  --budget 5 \
  --agents aider \
  --env "OPENAI_API_KEY=$OPENAI_API_KEY"
```

<Tip>
The `--agents aider` flag automatically installs `aider-chat` via pip — no manual setup needed.
</Tip>

## Config File (Recommended for Teams)

Create `.caged.yaml` in your repo root:

```yaml
# .caged.yaml
template: python-312
resources:
  cpu: 2
  memory: 1024
  disk: 10
timeout: 3600
budget: 5.00

agents:
  - aider

secrets:
  - OPENAI_API_KEY      # or ANTHROPIC_API_KEY for Claude

network_mode: allowlist
allowed_hosts:
  - api.openai.com
  - api.anthropic.com
  - github.com
  - pypi.org
```

Then run:

```bash
caged up
caged connect cage-xxxxx

# Inside the sandbox
aider
```

## Option 3: Use Aider with Claude

Aider works great with Claude models too:

```bash
caged run \
  --template python-312 \
  --agents aider \
  --env "ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY"
```

Inside the sandbox:

```bash
# Use Claude Sonnet (default for Anthropic)
aider --model claude-3-5-sonnet-20241022

# Or Claude Opus for complex tasks
aider --model claude-3-opus-20240229
```

## Aider Configuration

Create `.aider.conf.yml` in your project for persistent settings:

```yaml
# .aider.conf.yml
model: claude-3-5-sonnet-20241022
auto-commits: true
dark-mode: true
show-diffs: true
```

## Monitoring Progress

```bash
# Watch Aider's git commits in real-time
caged logs cage-xxxxx --follow

# Check cost
caged status cage-xxxxx
```

## Tips

<Tip>
**Auto-commits**: Aider commits each change with descriptive messages. Review the git log to see exactly what it changed.
</Tip>

<Tip>
**Add files to context**: Use `/add filename.py` in Aider to include specific files in the conversation context.
</Tip>

<Tip>
**Undo mistakes**: Aider's `/undo` command reverts the last change. Or use `caged snapshot restore` to go back further.
</Tip>