# Orchestrator Mode

Orchestrator is a long-running agent mode that breaks complex tasks into phases and delegates to specialized sub-agents. Instead of one agent doing everything, the orchestrator coordinates multiple agents working together.

## Requirements

- Invoke subscription with available credits (does not work with direct API keys)
- Credits are consumed per-step for the orchestrator and each sub-agent

## How to Use

1. Click the mode selector in the input area (bottom-left, next to the send button)
2. Select **Orchestrator** from the dropdown
3. You'll see an amber **Workflow** icon and an info toast
4. Type your task and send

## How It Works

The orchestrator receives your task and decides how to handle it:

- **Simple tasks** (read a file, check something) — it uses its own tools directly
- **Complex tasks** (analyze a codebase, implement a feature) — it delegates to sub-agents

## Sub-agents

| Agent          | What it does                                                             | When the orchestrator uses it                                     |
|----------------|--------------------------------------------------------------------------|------------------------------------------------------------------|
| **Plan Agent** | Creates implementation plans, architecture strategies                    | When a structured plan is needed before coding                    |
| **Coding Agent**| Reads, searches, edits, and writes code files                           | For any codebase exploration or implementation                    |
| **Browser Agent**| Navigates web pages, clicks, types, scrapes                            | For browser automation (requires browser tools enabled)          |

Each sub-agent runs autonomously with its own tool loop — it can read files, search, grep, edit, and write on its own. When it finishes, it reports back to the orchestrator with a summary of what it did.

### Background Execution

The orchestrator can run sub-agents in the background for parallel work. It launches them, continues with other tasks, and checks results later. You'll see background task cards in the UI.

## Plans and Specs

When the orchestrator delegates planning work, plans are automatically saved to `.invoke/specs/` in your project directory as markdown files with checkboxes:

```
- [ ] Pending task
- [~] In progress
- [x] Completed
```

After the coding agent implements something, the orchestrator tells the plan agent to update the spec and mark completed items.

## Token Usage

Orchestrator mode consumes more tokens than regular agent mode because:

- The orchestrator itself uses tokens for each step
- Each sub-agent runs its own multi-step loop
- Context grows as sub-agents explore files

A typical orchestrator run might use 10-50x more tokens than a single agent response.

## Tips

- **Use orchestrator for big tasks:** "implement this feature", "refactor this module", "analyze the entire codebase"
- **Use regular agent mode for small tasks:** "fix this bug", "explain this function", "read this file"
- The orchestrator works best with clear, specific task descriptions
- You can switch back to agent mode anytime via the mode selector or **Shift+Tab**

## Limitations

- Invoke subscription required (no direct API key support)
- Sub-agent results don't stream live — you see a loading card until complete, then the full result
- No cross-conversation memory between sub-agents — each call starts fresh