> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whim.run/llms.txt
> Use this file to discover all available pages before exploring further.
# Orchestrator Mode
> Coordinate multiple AI agents to tackle complex tasks in parallel.
Orchestrator mode transforms a task from a single worker into a **coordinator** that plans, decomposes, and delegates work across multiple child tasks. Instead of implementing code directly, the orchestrator uses the [Whim MCP tools](/whim-agent/mcp-tools) to create subtasks that each handle a piece of the work in parallel.
## Simple vs orchestrator mode
| | Simple mode | Orchestrator mode |
| ------------------ | ------------------------------------- | --------------------------------------------------- |
| **Agent behavior** | Reads, writes, and runs code directly | Plans and delegates — doesn't implement directly |
| **Subtasks** | None (all work in one container) | Spawns child tasks via MCP tools |
| **Best for** | Focused, single-scope changes | Large features, multi-file refactors, complex tasks |
| **Parallelism** | Sequential within one agent | Multiple agents working simultaneously |
Toggle between modes using the **mode selector** in the composer toolbar before launching a task.
## How orchestration works
The orchestrator analyzes your prompt and breaks the work into independent pieces. It determines which parts can run in parallel and which need to be sequential.
The orchestrator calls `create_task` (or `create_batch` for multiple items) via its MCP tools to spawn child tasks. Each child gets a self-contained prompt with a clear objective, all necessary context, and scope boundaries.
Child tasks spin up in their own containers, each on its own branch. They work independently using the same agent capabilities as any other task.
When a child finishes or hits a blocker, it calls `send_prompt` to report results back to the orchestrator. The orchestrator waits for children to report in — it doesn't poll.
After all children complete, the orchestrator synthesizes the results and reports the overall outcome to you.
## How it works under the hood
Orchestration is powered by the same [MCP tools](/whim-agent/mcp-tools) available to every agent. The orchestrator is simply an agent whose instructions are optimized for delegation:
1. **`create_task`** / **`create_batch`** — spawn child tasks with `relationship: "child"` so they nest under the orchestrator
2. **`send_prompt`** — send follow-up instructions to running children or receive reports back
3. **`list_tasks`** — check the status of children
4. **`get_task`** — read a child's conversation to understand its progress
5. **`complete_tasks`** — mark children as done when their work is verified
The orchestrator includes its own display ID in each child's prompt, so children know where to report back. This creates a natural communication loop:
```
Orchestrator Child Task
│ │
├── create_task(prompt + displayId) ──►
│ │
│ (child works autonomously) │
│ │
◄── send_prompt(results) ───────────┤
│ │
├── complete_tasks([childId]) ──────►
│ │
```
The orchestrator is instructed to **wait** for children to report back rather than polling. If a child hasn't reported, it's still working. The orchestrator only intervenes if you explicitly ask it to check on progress.
## Task nesting
Whim supports **one level** of task nesting. An orchestrator (parent) can create child tasks, but children cannot nest further.
* Child tasks appear indented under their parent in the sidebar
* Completing a parent prompts you to also complete active children
* You can manually nest or unnest tasks using the task context menu
If you need deeper decomposition, have a child use orchestrator mode to coordinate its own subtasks. The UI nesting stays at one level, but the coordination still works via MCP tools.
## When to use each mode
* The task has a clear, focused scope
* Work fits in a single agent's context
* You want direct control over execution
* The change is straightforward (bug fix, small feature, refactor of one area)
* The task spans multiple files or modules
* Work can be parallelized across independent pieces
* You want faster completion through concurrent agents
* The scope is large enough that one agent would struggle with context
## Example workflows
### Large refactor
*"Rename the `UserService` class to `AccountService` across the entire codebase, update all imports, and fix any tests."*
The orchestrator might create:
* **Child 1**: Rename the class and update the core module
* **Child 2**: Update all import statements across the frontend
* **Child 3**: Update all import statements across the backend
* **Child 4**: Fix and re-run the test suite
### Multi-feature implementation
*"Add user profile pages with avatar upload, bio editing, and activity history."*
The orchestrator might create:
* **Child 1**: Build the avatar upload component and API endpoint
* **Child 2**: Build the bio editing form and persistence
* **Child 3**: Build the activity history timeline component
* **Child 4**: Create the profile page layout that combines all three
### Cross-cutting concern
*"Add structured logging to all API endpoints in the server."*
The orchestrator might create one child per route file, each independently adding logging to its set of endpoints.
Understand the full container environment and agent lifecycle.
Full reference for the tools orchestrators use to manage subtasks.