src/coordinator/, src/tasks/
How it works
The coordinator spawns sub-agents viaAgentTool, organizes them into teams, and routes messages between agents and back to the primary session. Each agent runs its own Query Engine instance with access to the full tool set.
The coordinator is gated behind the
COORDINATOR_MODE feature flag. Proactive scheduling behavior is separately controlled by the PROACTIVE flag.Core tools
AgentTool
Spawns a sub-agent to work on a specific task. The sub-agent runs with its own context and reports results back to the coordinator.
TeamCreateTool
Creates a named team of agents for coordinated parallel work.
TeamDeleteTool
Dissolves a team and cleans up its associated agents and resources.
SendMessageTool
Sends a message to a specific agent or team, enabling inter-agent communication.
SleepTool
Pauses an agent for a specified duration — useful in polling loops or when waiting for external events.
Task types
The task system (src/tasks/) underpins multi-agent execution. Each task type maps to a different execution environment:
| Task type | Location | Purpose |
|---|---|---|
LocalShellTask | LocalShellTask/ | Background shell command execution |
LocalAgentTask | LocalAgentTask/ | Sub-agent running locally in a separate process |
RemoteAgentTask | RemoteAgentTask/ | Agent running on a remote machine |
InProcessTeammateTask | InProcessTeammateTask/ | Parallel teammate agent running in the same process |
DreamTask | DreamTask/ | Background ideation or planning process |
LocalMainSessionTask | LocalMainSessionTask.ts | The main session itself represented as a task |
Task management tools
| Tool | Purpose |
|---|---|
TaskCreateTool | Create a new background task |
TaskUpdateTool | Update task status or metadata |
TaskGetTool | Retrieve details of a specific task |
TaskListTool | List all active and completed tasks |
TaskOutputTool | Get the output produced by a task |
TaskStopTool | Stop a running task |
Coordinator mode
coordinatorMode.ts manages the coordinator lifecycle. When COORDINATOR_MODE is enabled, the primary session acts as an orchestrator rather than a direct executor — it delegates work to sub-agents and synthesizes their results.
Task decomposition
The coordinator analyzes the user’s request and breaks it into parallel subtasks.
Progress monitoring
Active tasks are tracked via
TaskListTool and TaskGetTool. The coordinator polls or awaits completion signals.Proactive mode
When thePROACTIVE flag is enabled, the coordinator can initiate work without an explicit user prompt — for example, picking up scheduled tasks, reacting to file system changes, or acting on remote agent messages.
Remote agents
RemoteAgentTask and the scheduleRemoteAgents skill allow tasks to be dispatched to agents running on remote machines. This is useful for distributing work across a fleet or for running tasks in isolated environments.