Agents

Agents are specialized AI workers that run independently to handle specific tasks. While the main chat is great for interactive work, agents let you delegate entire workflows — research, code implementation, testing, code review — and run them in the background.

Built-in Roles

What each role does

• Researcher — Explores codebases and searches the web. Can read files and search but cannot modify anything. Runs autonomously without checkpoints.
• Coder — Implements features, writes code, runs commands. Has full read/write/bash access. Checkpoints on write operations.
• Reviewer — Reviews code for quality, bugs, and security issues. Read-only access, cannot modify files.
• Planner — Creates implementation plans and architectural designs. Read-only. For new projects, prioritizes web research over local file reading. For existing codebases, reads local files first. Outputs are saved as plan files.
• DevOps — Handles infrastructure, CI/CD, deployment tasks. Read/write/bash access with checkpoints.
• Tester — Writes and runs tests. Read/write/bash/python access with checkpoints.
• Odyssey — Coordinates teams of agents. Uses a two-phase workflow: first plans using planner/researcher agents, then executes with coder/devops only after user approval. Cannot directly read or write files.

Automatic Agent Routing

The server classifies every message and may automatically assign an agent based on the task type:

You don't need to manually pick an agent for most tasks — the classifier handles it. When an agent is auto-assigned, you'll see it in the status bar.

Spawning Agents Manually

Use the /agent command or @ mention shorthand to explicitly choose a role:

/agent researcher explore the authentication system and document the flow
/agent coder add input validation to all form handlers in src/forms/
@planner design a caching layer for the API
@reviewer check src/auth/ for security vulnerabilities

The agent starts running immediately. You can continue chatting while it works.

Trust Levels

Trust levels determine how much autonomy an agent has:

• Autonomous — Runs without interruption. All tool calls execute immediately.
• Supervised — Pauses for approval before write operations, shell commands, and delegation. See Checkpoint Approval below.
• Readonly — Cannot use write tools at all. Limited to reading, searching, and web access.

In Auto operation mode, all checkpoints are auto-approved regardless of trust level.

Team Presets

Team presets run multiple agents in sequence, with each agent receiving the previous agent's output as context.

/team <preset> <target>

Examples

/team code-review src/auth/
/team refactor src/api/client.ts
/team investigate "why does login fail intermittently"
/team full-stack "add rate limiting to the API"

Plan and Execute

A common workflow: have the AI or a planner agent create a plan, then execute it.

1. Ask for a plan (either in chat or via an agent):

   @planner design a strategy for migrating the database layer to Prisma

2. Review the numbered steps the planner outputs. The plan is saved to .agents/plan/.

3. Execute the plan:

   /execute

   This spawns the odyssey agent, which reads the plan and delegates tasks to the appropriate agents.

4. Optionally add instructions:

   /execute skip the migration step, focus on the model definitions

Monitoring Agents

Status Bar

When agents are running, a status bar appears showing up to 5 agents with their role, elapsed time, and recent tool calls.

Commands

Keyboard Shortcuts

Checkpoint Approval

Agents with supervised trust pause before executing write operations or shell commands. When this happens, you'll see a checkpoint approval prompt.

Batch Mode (default)

• Y — Approve all pending checkpoints
• N — Deny all pending checkpoints
• Tab — Switch to individual review mode

Individual Mode

• Up/Down — Navigate between checkpoints
• Y/N — Approve or deny the current checkpoint
• A — Approve all remaining
• D — Deny all remaining
• Tab — Switch back to batch mode

On macOS, the dock icon bounces when a checkpoint needs your attention.

Denial Behavior

Denying a delegation checkpoint (spawn_agent or delegate) immediately stops the parent agent. This prevents agents like odyssey from retrying denied delegations.

Denying 3 or more checkpoints of any type also stops the agent. The agent will provide a summary of work completed so far.

Agent Memory

Agents learn from their work and persist memories across sessions. Each role maintains its own memory store.

/memory              ← List all roles with stored memories
/memory researcher   ← View the researcher's memories
/memory clear coder  ← Clear all stored memory for the coder role

Memories include learnings, preferences, facts, and patterns discovered during agent runs. They're automatically injected into future runs for the same role.

Memory is stored in ~/.coalcode/agents/memory/.

Agent History

Every completed agent run is saved with its objective, status, metrics, and summary.

/history             ← Show the last 15 agent runs
/history coder       ← Filter history by role

History is stored in ~/.coalcode/agents/history/.

Limits

Creating Custom Roles

You can define your own agent roles beyond the 7 built-ins. See Custom Roles.