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

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.

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.

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.

<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:

{
  "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

1. Enable coordinator mode

   export CLAUDE_CODE_COORDINATOR_MODE=1
   claude
   
2. Describe the high-level task

   Give Claurst a complex, multi-file task. It will automatically enter coordinator mode and plan the worker dispatch strategy.

3. 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.

4. 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.

5. 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.

6. Verification workers confirm

   A final wave of workers runs tests and checks to confirm all changes are correct before the coordinator reports completion.