One prompt,
a whole team.
Orchestrate turns any task description into a coordinated agent team — plan, review, and execute, all in one session.
Orchestrate generates a plan, shows a summary, and executes on approval:
1. Enhance: Rewrites your prompt into a clear, structured goal statement
2. Review: Shows enhanced prompt + plan summary with interactive buttons (Go, Edit, Use original, Show full plan)
3. Execute: Creates the team, spawns teammates, builds task list, coordinates as lead
The generated plan covers:
Goal · Team Setup · Task List · Communication · Quality Gates · Lead Instructions · Shutdown & Cleanup
Use --auto-run to skip review, or --dry-run for raw prompt text.
The Concept
From task to
coordinated team.
Agent teams are powerful but complex to set up. You need to think about roles, task lists, file ownership, communication rules, quality gates, and shutdown procedures.
Orchestrate does that thinking for you. Describe your task, review the plan, and it executes directly — creating the team, assigning tasks, and coordinating the work in your current session.
Capabilities
Detects what kind of work you're doing and builds the right team.
- Auto-detects prompt type: debugging, feature, refactor, research, or design/UI
- Selects role-appropriate teammates (2-5 based on complexity)
- Generates shared task lists with dependencies and file boundaries
- Reviews plan with you, then executes directly in your session
- Includes communication rules and challenge patterns
- Smart model defaults: Opus for key thinkers, Sonnet for the rest
- Interactive setup wizard to configure settings visually
- Adds type-appropriate quality gates
- Detects installed plugins (frontend-design, feature-dev) and enhances teammates automatically
- Handles shutdown and cleanup automatically
Examples
Five prompt types,
five team shapes.
Orchestrate detects what kind of work you're doing and generates the right team structure.
Generated team:
1. Hypothesis-A Tester - Investigates the most likely root cause
2. Hypothesis-B Tester - Explores an alternative theory independently
3. Repro Builder - Creates a minimal reproduction / failing test
4. Log/Telemetry Digger - Searches logs, git history for clues
5. Fix Proposer - Once hypotheses converge, proposes and reviews the fix
Generated team:
1. Architect - Designs approach, defines interfaces and data flow
2. Backend Engineer - Implements server-side logic, WebSocket, data models
3. Frontend Engineer - Implements notification bell UI, client-side logic
4. Tests/QA Engineer - Writes unit and integration tests
5. Reviewer/Perf Engineer - Reviews for correctness, performance, security
Generated team:
1. Architect / Code Owner - Defines target architecture and migration strategy
2. Implementation-A - Refactors one portion of the codebase
3. Implementation-B - Refactors another portion in parallel
4. Tests/Regression - Updates tests, ensures behavior is preserved
5. Devil's Advocate - Challenges the approach, finds edge cases
Generated team:
1. Researcher - Deep-dives into each option, gathers evidence
2. Critic - Stress-tests each option, finds weaknesses
3. Synthesizer - Compares findings, produces structured comparison
4. Devil's Advocate - Argues against emerging consensus
Generated team:
1. Design Lead - Defines aesthetic direction, color palette, typography, spacing
2. Frontend Engineer - Implements the UI, translates design into production code
3. Accessibility/Responsiveness Reviewer - Reviews WCAG compliance, responsive breakpoints
4. UX Critic - Challenges layout choices, tests edge cases
Flags
Fine-tune when needed.
All flags are optional with strong defaults. Most users won't need them.
| Flag | Default | Description |
|---|---|---|
--auto-run |
off | Skip review and execute immediately. |
--dry-run |
off | Output raw prompt text only (for copy/paste). |
--team-size |
auto |
Number of teammates. Auto picks 2-5 based on complexity. |
--models |
auto |
Model for teammates. Auto assigns Opus to key reasoning roles, Sonnet to rest. |
--require-plan-approval |
auto |
Require lead approval before code changes. System-enforced via mode: "plan". Auto enables for code work. |
--teammate-mode |
auto |
Display mode. Auto lets Claude Code decide (tmux if available). |
--quality-gates |
tests + lint + docs |
Quality standards teammates must meet. |
--output-style |
standard |
Controls task count and detail. Options: concise, standard, verbose. |
FAQ
Common questions.
Agent Teams is an experimental Claude Code feature that lets you spawn multiple AI teammates that work in parallel on a shared task list. A team lead coordinates, and teammates communicate via messages.
It's disabled by default. Enable it by adding "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" to your settings.json env, or set the environment variable before starting Claude Code. Orchestrate checks this automatically and will guide you through setup if it's not enabled.
See Enable Agent Teams for setup details, or the full Agent Teams documentation for how teams work.
By default, Orchestrate enhances your prompt into a clear goal statement, generates an orchestration plan, and shows an interactive review screen with the enhanced prompt and plan summary. You get buttons to approve (Go), edit the prompt, use your original wording, or inspect the full plan — then it executes directly, creating the team and coordinating as lead.
With --dry-run, it outputs the raw prompt text for you to copy/paste into a new session. With --auto-run, it skips review and executes immediately.
Review & Run (default): Enhances your prompt, shows a plan summary, and presents interactive buttons — Go, Edit prompt, Use original, or Show full plan. Safest option for unfamiliar tasks.
Auto-run (--auto-run): Briefly announces the plan and immediately executes. Good for when you trust the defaults and want speed.
Dry-run (--dry-run): Outputs the raw orchestration prompt as text. Useful for saving prompts, sharing them, or pasting into a different session.
By default (--models auto), Orchestrate assigns Opus to the key reasoning role on each team — the one making critical design decisions or synthesizing complex findings — and Sonnet to implementation and support roles. This balances quality where it matters most with cost efficiency.
For example, on a Feature team the Architect gets Opus while Backend, Frontend, Tests/QA, and Reviewer get Sonnet. On a Debugging team, all roles get Sonnet since the work is primarily tracing and analysis.
Use --models sonnet to force all-Sonnet (cheapest), --models opus for all-Opus (max capability), or /orchestrate:config to choose interactively.
Orchestrate analyzes keywords in your prompt to classify it into one of five categories:
Debugging: bug, fix, error, crash, failing, broken, investigate, regression, 500, timeout, flaky
Feature: add, implement, create, build, new, feature, integrate, endpoint, component
Refactor: refactor, restructure, migrate, upgrade, modernize, extract, simplify, rename
Research: evaluate, compare, investigate options, recommend, assess, tradeoffs, RFC
Design/UI: design, UI, UX, interface, layout, landing page, dashboard, wireframe, mockup, theme, dark mode, visual, aesthetic, typography, color palette
If both Design/UI and Feature signals are present, Design/UI wins when the emphasis is visual/aesthetic; Feature wins when the emphasis is functionality. If ambiguous, it defaults to Research/Decision.
No - by design. The generated task list assigns distinct file ownership to each teammate to avoid merge conflicts. If a conflict is discovered, the second teammate must message the lead to resolve ownership.
Yes — it's system-enforced, not just a prompt suggestion. When plan approval is on, Orchestrate spawns teammates with mode: "plan" in the Task tool call. This means teammates physically cannot call Edit or Write tools until the lead approves their plan. This works regardless of your permission settings (including bypass mode).
By default (--require-plan-approval auto), plan approval is enabled for code work (features, refactors, debugging with fixes) and disabled for pure research tasks.
message sends to one specific teammate. Use it for targeted updates, sharing findings relevant to another's work, or challenging assumptions.
broadcast sends to all teammates. Use it sparingly - each broadcast costs tokens for every teammate. Reserve it for announcements that affect everyone (design doc ready, API contract changed).
An interactive setup wizard. Instead of memorizing flags, run /orchestrate:config <your task> and it walks you through choosing execution mode, model strategy, and plan approval using Claude Code's AskUserQuestion tool — then launches /orchestrate:start directly. No copy/paste needed.
It also shows you the detected task type, the team roles that will be created, and which model each role will use, so you can see exactly what you're getting before you run it.
Yes, but through your own settings, not the plugin. Orchestrate doesn't ship hooks because plugin-level hooks fire globally on ALL agent teams, not just Orchestrate's.
You can add hooks to your .claude/settings.json that run automatically on team events:
TaskCompleted — run tests or lint after each task (e.g., npm test, pytest)
TeammateIdle — check for merge conflicts when a teammate pauses
See the Hooks documentation for setup details, or the project README for example configurations.
No session resumption — /resume doesn't restore in-process teammates. If a session ends, start a new orchestration.
One team per session — clean up the current team before starting a new one.
Shutdown can be slow — teammates finish their current work before shutting down gracefully.
Teammates inherit lead's permissions — you can't set per-teammate permission levels at spawn time.
Delegate mode is user-only — the lead prompt says "use delegate mode" but there's no API to set it programmatically. Toggle it with Shift+Tab.
Use Orchestrate (agent teams) when teammates need to communicate, challenge each other's work, or coordinate on shared outcomes. Teams excel at debugging (competing hypotheses), research (critic/advocate patterns), and complex features where design decisions affect multiple implementers.
Use regular subagents (Task tool) for focused, independent parallel tasks where agents don't need to talk to each other — like running tests, searching code, or doing isolated file edits. Subagents use fewer tokens since there's no inter-agent messaging overhead.
Rule of thumb: if the work benefits from debate or coordination, use Orchestrate. If it's "do these 3 things independently," use subagents directly.
Yes, if installed. Orchestrate silently detects them and enhances relevant teammates' instructions — for example, the Frontend Engineer gets a note about the frontend-design skill, and the Design Lead gets a note about the code-architect agent.
No plugins are required — every team works fully standalone. Orchestrate never suggests installing plugins or mentions what it detected.
Orchestrate is pure prompt engineering — the team roles, prompt type signals, and quality gates are all defined in commands/start.md. To customize: fork the plugin or edit the file directly.
Prompt type signals are in the "Prompt Type Detection" section, roles are in "Role Selection", and quality gates are in "Section 6: Quality Gates". Changes take effect immediately — no build step needed.
Just Claude Code with Agent Teams enabled. Orchestrate is a pure prompt engineering plugin — no dependencies, no build steps, no MCP servers.
Orchestrate checks for Agent Teams automatically when you run it. If it's not enabled, you'll get setup instructions and a link to the docs.