Agent System

---
title: Agents
description: Understanding the multi-agent system
---

# Agent System

Cuttlefish uses specialized agents for different tasks, each optimized for its role through category-based model routing.

## Core Agents

### Orchestrator
Receives requests, creates task plans, and coordinates other agents.

- **Category**: `deep`
- **Model**: Claude Sonnet 4.6 (recommended)
- **Role**: Strategic planning and task decomposition

### Coder
Writes code, executes commands, and modifies files in the sandbox.

- **Category**: `deep`
- **Model**: Claude Sonnet 4.6 (recommended)
- **Role**: Implementation and execution

### Critic
Reviews code, runs tests, and approves or rejects changes.

- **Category**: `unspecified-high`
- **Model**: Configurable (Claude Sonnet 4.6 or Opus 4.6)
- **Role**: Quality assurance and validation

## Workflow

The system implements a **Planner → Coder → Critic** loop:

```
1. User sends request
   ↓
2. Orchestrator analyzes and creates plan
   ↓
3. Coder implements changes in sandbox
   ↓
4. Critic reviews code and runs tests
   ↓
5. If approved: commit and push
   If rejected: loop back to step 3
```

## Future Agents (v1.1+)

- **Planner**: Creates strategic implementation plans (`ultrabrain` category)
- **Explorer**: Searches codebases and finds patterns (`quick` category)
- **Librarian**: Finds documentation and retrieves external resources (`quick` category)
- **DevOps**: Handles builds, deployments, and infrastructure (`unspecified-high` category)

## Category-Based Model Routing

Each agent category maps to an optimal model:

```toml
[categories]
deep = "claude-sonnet-4-6"
quick = "claude-haiku-4-5"
ultrabrain = "claude-opus-4-6"
unspecified-high = "claude-sonnet-4-6"
```

This allows you to:
- Use fast models for quick tasks (save costs)
- Use powerful models for complex reasoning
- Optimize each agent independently
- Switch models without changing agent code

## Sandbox Isolation

Each agent runs in an isolated Docker container:

- **No cross-contamination**: Projects don't interfere with each other
- **Resource limits**: CPU, memory, and disk quotas per container
- **Network access**: Can install packages and clone repositories
- **Automatic cleanup**: Stale containers are removed automatically