> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/yocxy2/claurst/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-agent orchestration

> How Claurst transforms into a coordinator that spawns and directs parallel worker agents to tackle complex tasks.

When you enable coordinator mode, Claurst stops acting as a single agent and becomes an orchestrator — it spawns multiple worker agents, dispatches tasks to them in parallel, synthesizes their findings, and verifies the results.

## Enabling coordinator mode

```bash theme={null}
export CLAUDE_CODE_COORDINATOR_MODE=1
```

With this variable set, Claurst activates the coordinator system prompt from the `cc-query` crate's `agent_tool.rs` and takes on the orchestrator role for the session.

## The four-phase workflow

Coordinator mode structures every complex task into four distinct phases:

| Phase          | Who                | Purpose                                                  |
| -------------- | ------------------ | -------------------------------------------------------- |
| Research       | Workers (parallel) | Investigate codebase, find files, understand the problem |
| Synthesis      | Coordinator        | Read findings, understand the problem, craft specs       |
| Implementation | Workers            | Make targeted changes per spec, commit                   |
| Verification   | Workers            | Test changes work                                        |

The coordinator never writes code itself during implementation — it delegates to workers and reads their output before issuing precise instructions.

## Parallelism principle

The coordinator system prompt makes this explicit:

> "Parallelism is your superpower. Workers are async. Launch independent workers concurrently whenever possible — don't serialize work that can run simultaneously."

Independent research tasks, parallel file investigations, and concurrent test runs should all be dispatched simultaneously rather than one at a time.

<Tip>
  Do NOT say "based on your findings" — read the actual findings and specify exactly what to do. The coordinator must absorb worker output and translate it into concrete, actionable instructions before delegating the next step.
</Tip>

## Worker communication

Workers communicate back to the coordinator using `<task-notification>` XML messages. These structured messages carry status updates, findings, and results that the coordinator reads and acts upon during the Synthesis phase.

```xml theme={null}
<task-notification>
  <status>completed</status>
  <findings>Found 3 usages of deprecated API in src/api/client.rs:42, src/lib.rs:17, src/main.rs:88</findings>
</task-notification>
```

## Shared scratchpad

The `tengu_scratch` feature gate enables a shared scratchpad directory for cross-worker durable knowledge sharing. Workers can write intermediate findings here so that later workers (or the coordinator itself) can read accumulated context without re-running expensive operations.

## Agent swarm mode

Beyond the four-phase workflow, Claurst supports an agent swarm mode (gated by the `tengu_amber_flint` feature) with two teammate models:

* **In-process teammates** — share the same process using `AsyncLocalStorage` for context isolation, with color assignments for visual distinction in the terminal.
* **Process-based teammates** — run as separate processes managed via tmux or iTerm2 panes, enabling full isolation with independent working directories and tool access.

Both models support team memory synchronization, allowing workers to share learned context across the session.

## Spawning sub-agents programmatically

The `AgentTool` (exposed as `"Task"` in the tool registry) lets the coordinator spawn sub-agents directly from a tool call:

```json theme={null}
{
  "description": "Investigate all usages of the deprecated Config::load() method",
  "prompt": "Search the entire codebase for calls to Config::load(). List every file and line number. Output your findings as a structured list.",
  "tools": ["Bash", "Glob", "Grep", "Read"],
  "max_turns": 5
}
```

The `AgentTool` creates a dedicated `AnthropicClient`, filters the tool list to the specified subset (always excluding `AgentTool` itself to prevent unbounded recursion), and runs an independent `run_query_loop`. The final assistant message is returned as the tool result.

## Background task management

For longer-running work, the coordinator uses the task management tools backed by the global `TASK_STORE` in `cc-tools`:

| Tool             | What it does                                                    |
| ---------------- | --------------------------------------------------------------- |
| `TaskCreateTool` | Creates a background task with a UUID, subject, and description |
| `TaskGetTool`    | Returns the current state of a task by ID                       |
| `TaskListTool`   | Lists all non-deleted tasks with optional status filter         |
| `TaskUpdateTool` | Updates task fields; setting `status=deleted` removes it        |

Tasks move through states: `Pending` → `InProgress` → `Completed` (or `Failed`). The coordinator polls task state to know when workers have finished before entering the Synthesis phase.

## Example: coordinator session

<Steps>
  <Step title="Enable coordinator mode">
    ```bash theme={null}
    export CLAUDE_CODE_COORDINATOR_MODE=1
    claude
    ```
  </Step>

  <Step title="Describe the high-level task">
    Give Claurst a complex, multi-file task. It will automatically enter coordinator mode and plan the worker dispatch strategy.
  </Step>

  <Step title="Research phase runs in parallel">
    The coordinator spawns multiple workers simultaneously via `AgentTool`, each investigating a different aspect of the codebase. Workers write findings to the shared scratchpad.
  </Step>

  <Step title="Coordinator synthesizes">
    After all research workers complete, the coordinator reads every finding and crafts precise implementation specs — specifying exact files, line numbers, and changes required.
  </Step>

  <Step title="Implementation workers execute">
    Workers receive deterministic specs and make targeted changes. Because the coordinator read the actual findings, there is no ambiguity in the instructions.
  </Step>

  <Step title="Verification workers confirm">
    A final wave of workers runs tests and checks to confirm all changes are correct before the coordinator reports completion.
  </Step>
</Steps>