# 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 | Role | Trust Level | Can Write Files | Can Spawn Children | Time Limit | | --------- | ----------- | ---------------- | ------------------- | ----------- | | **researcher** | autonomous | No | No | 5 min | | **coder** | supervised | Yes | No | 5 min | | **reviewer** | readonly | No | No | 3 min | | **planner** | readonly | No | No | 5 min | | **devops** | supervised | Yes | No | 5 min | | **tester** | supervised | Yes | No | 5 min | | **odyssey** | supervised | No (delegates) | Yes | 10 min | ### 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: | Classification | Agent | When | | --------------------- | ---------- | ---------------------------------------------------------------------- | | REASONING | **researcher** | Questions requiring research, analysis, or web searches | | BUILD / complex tasks | **odyssey** | Multi-step implementation or project-building tasks | | PLAN | **planner** | Architecture and design requests | | INVESTIGATE | **researcher** | Debugging and exploration tasks | | REVIEW | **reviewer** | Code review requests | 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](/content/docs/agents#checkpoint-approval/index.html) 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 | Pipeline | Use case | | --------------- | ---------------------------------- | ------------------------------------------------------------------ | | `code-review` | researcher → reviewer | Analyze code and get structured feedback | | `refactor` | planner → coder → reviewer | Design, implement, and validate a refactoring | | `investigate` | researcher → planner | Explore a problem and produce an action plan | | `full-stack` | planner → coder → tester → reviewer | Full feature implementation with testing | ### 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 | Command | Description | | --------------------- | -------------------------------------------------------- | | `/agents` | List all agents with status, tool count, and token usage | | `/agents kill ` | Cancel a specific agent by ID prefix | | `/agents kill all` | Cancel all running agents | | `/focus `| View detailed output for a specific agent | | `/focus main` | Return to the main chat view | ### Keyboard Shortcuts | Key | Action | | -------- | -------------------------------- | | **Ctrl+,** | Focus on the previous agent | | **Ctrl+.** | Focus on the next agent | ## 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 | Limit | Value | | ----------------------------------- | ---------------------------- | | Max concurrent agents | 3 (additional agents are queued by priority) | | Max agent tree depth | 3 levels (odyssey → child → grandchild) | | Token budget per agent | 128,000 tokens | | Default time limit | 5 minutes (odyssey: 10 minutes, reviewer: 3 minutes) | | Max tool iterations per agent | 50 | ## Creating Custom Roles You can define your own agent roles beyond the 7 built-ins. See [Custom Roles](/content/docs/custom-roles/index.html).