Orchestra is a set of CLAUDE.md rules and subagent definitions that turn Claude Code into an intelligent orchestration system. When you ask Claude Code to do something, Orchestra:
- Assesses the task complexity against a weighted scoring system
- Decides whether to handle it directly or decompose into parallel work units
- Routes each unit to the right model tier (Opus/Sonnet/Haiku) and effort level
- Spawns subagents that execute in isolated contexts (preserving your main context window)
- Consolidates results and runs validation on any code output
- Reports back with a structured summary of what was done
The system is optimized for a Pro plan — it minimizes token waste through context-economy rules, effort-level tuning, and thinking-token awareness on Opus. It will also apply any learnings based on the retrospective.
If changes are needed: Report to the user: "Retrospective finding: [specific issue]. Recommend adjusting [threshold/tier/effort] for future similar tasks. Apply this change? [Y/N]"
If the user approves, the orchestrator updates the relevant CLAUDE.md section or agent frontmatter directly.
If no changes are needed: Report to the user: "Retrospective: All systems performed as expected. No adjustments."
orchestra/
├── CLAUDE.md # The decision engine (orchestration rules, routing, thresholds)
├── INSTALL.md # This file
├── QUICKREF.md # One-page cheat sheet for daily use
└── agents/ # Subagent definitions (10 agents)
├── orchestrator-planner.md # Opus, high effort — decomposes tasks
├── code-worker.md # Sonnet, medium effort — generic code worker
├── research-worker.md # Sonnet, medium effort — investigates (read-only)
├── project-worker.md # Haiku, low effort — file ops and scaffolding
├── validator.md # Haiku, low effort — lint/build/test checks
├── code-reviewer.md # Sonnet, medium effort — code review (read-only)
├── astro-supabase-worker.md # Sonnet, medium effort — Astro + Supabase stack
├── swiftui-worker.md # Sonnet, medium effort — SwiftUI / SwiftData / MV
├── react-worker.md # Sonnet, medium effort — React (non-Next.js)
└── nextjs-worker.md # Sonnet, medium effort — Next.js App Router
Before installing, confirm you have:
- Claude Code installed and functional in your terminal
- Pro plan active (provides access to Opus 4.6, Sonnet 4.6, and Haiku 4.5)
- Overage credits enabled (allows Orchestra tasks to complete uninterrupted if you hit a usage window reset mid-execution)
--dangerously-skip-permissionsmode enabled (Orchestra subagents need to read, write, and execute without per-action approval prompts)
To verify your Claude Code setup:
# Check Claude Code is installed
claude --version
# Check your current model (should show opus or sonnet)
# Once in a session, run:
/statusIf you downloaded the .tar.gz:
# Extract to a temporary location
cd ~/Downloads # or wherever you saved it
tar -xzf orchestra-system-v3.tar.gz
# You should now have an orchestra/ directory
ls orchestra/If you received the individual files, place them in a folder called orchestra/ with
the directory structure shown above.
If you already have a global CLAUDE.md, back it up first:
cp ~/.claude/CLAUDE.md ~/.claude/CLAUDE.md.backup 2>/dev/null
echo "Backup complete (or no existing file found — that's fine)"You have two options depending on whether you already have a global CLAUDE.md:
Option A — You have NO existing global CLAUDE.md:
cp orchestra/CLAUDE.md ~/.claude/CLAUDE.mdOption B — You ALREADY have a global CLAUDE.md:
Append the Orchestra rules to the end of your existing file:
echo "" >> ~/.claude/CLAUDE.md
echo "# ============================================" >> ~/.claude/CLAUDE.md
echo "# ORCHESTRA ORCHESTRATION SYSTEM RULES BELOW" >> ~/.claude/CLAUDE.md
echo "# ============================================" >> ~/.claude/CLAUDE.md
echo "" >> ~/.claude/CLAUDE.md
cat orchestra/CLAUDE.md >> ~/.claude/CLAUDE.mdThe Orchestra rules are designed to coexist with existing instructions. They add a decision framework on top of whatever workflow rules you already have. Your existing CLAUDE.md content (coding conventions, project context, etc.) will still be respected.
# Create the global agents directory if it doesn't exist
mkdir -p ~/.claude/agents
# Copy all Orchestra agents
cp orchestra/agents/*.md ~/.claude/agents/This installs agents globally — they'll be available in every project you open with Claude Code. The full agent roster:
Core agents (used in every project):
| Agent | Model | Effort | Role | Tools |
|---|---|---|---|---|
orchestrator-planner |
Opus | High | Decomposes complex tasks into work units | Read, Grep, Glob |
code-worker |
Sonnet | Medium | Generic code — writes and modifies code | Read, Write, Edit, Bash, Glob, Grep |
research-worker |
Sonnet | Medium | Gathers and analyzes information | Read, Grep, Glob, WebFetch, WebSearch |
project-worker |
Haiku | Low | File operations, scaffolding, organization | Read, Write, Edit, Bash, Glob, Grep |
validator |
Haiku | Low | Automated quality checks (lint/build/test) | Read, Bash, Glob, Grep |
code-reviewer |
Sonnet | Medium | Independent code review | Read, Grep, Glob |
Stack-specific agents (auto-selected when project stack is detected):
| Agent | Model | Effort | Stack | Key Conventions |
|---|---|---|---|---|
astro-supabase-worker |
Sonnet | Medium | Astro + Supabase | File-based routing, content collections, island architecture, RLS, SSR client patterns |
swiftui-worker |
Sonnet | Medium | SwiftUI | MV architecture (no MVVM), SwiftData, @Query, @Model, Apple HIG |
react-worker |
Sonnet | Medium | React | Functional components, hooks patterns, state management, TanStack Query |
nextjs-worker |
Sonnet | Medium | Next.js | App Router, Server Components, Server Actions, ISR, metadata API |
The orchestrator-planner automatically selects stack-specific agents when it detects
the project's tech stack. You can also invoke them directly with @astro-supabase-worker,
@swiftui-worker, etc.
The .orchestra/ directory is workspace scaffolding — it should never be committed:
# Add to global gitignore
echo ".orchestra/" >> ~/.gitignore_global
# Tell git to use the global gitignore (safe to run if already configured)
git config --global core.excludesfile ~/.gitignore_globalKeep the cheat sheet somewhere accessible:
cp orchestra/QUICKREF.md ~/.claude/ORCHESTRA-QUICKREF.mdStart a new Claude Code session (the agents load at session start):
claude/agents
You should see all six Orchestra agents in the list: orchestrator-planner,
code-worker, research-worker, project-worker, validator, code-reviewer.
If any are missing, verify the files exist in ~/.claude/agents/ and that the YAML
frontmatter at the top of each file is valid (no stray characters before the ---).
Type this prompt:
Assess the complexity of: "Add a dark mode toggle to the site header that persists
the user's preference in localStorage"
Claude should respond with something like:
Assessed complexity: 3 → GUIDED mode. Single component change with local storage, straightforward implementation.
Type this prompt:
Plan this but don't execute: "Rebuild the navigation system to support nested dropdowns,
add breadcrumbs to all pages, create a sitemap generator, and add structured data markup
to every page template"
Claude should invoke the orchestrator-planner and produce a task manifest with
multiple work units, model tier assignments, and dependency ordering.
Navigate to one of your projects (e.g., a project with astro.config.mjs) and type:
What agents are available for this project?
Claude should identify the stack and confirm that the stack-specific agent (e.g.,
astro-supabase-worker) will be preferred over the generic code-worker.
If Orchestra mode triggers too often (feels like overkill), raise the threshold in
~/.claude/CLAUDE.md. Find this line:
- **Score 6+ → ORCHESTRA MODE**
Change 6 to 7 or 8. If you want more orchestration on smaller tasks, lower it to 5.
Edit the model: field in any agent's frontmatter file in ~/.claude/agents/.
Example — temporarily run code-worker on Opus for a complex refactor:
model: opusOr set a global override for ALL subagents via environment variable:
export CLAUDE_CODE_SUBAGENT_MODEL="claude-sonnet-4-6"This overrides every agent's model: field. Useful for cost control or testing.
Edit the effort: field in any agent's frontmatter. Valid values: low, medium,
high, max.
The defaults are tuned for Pro plan efficiency:
highfor the planner (decomposition quality matters)mediumfor builders and reviewers (standard implementation reasoning)lowfor validators and project workers (mechanical tasks)
If you find a worker producing poor output, try bumping its effort level up one notch before switching to a more expensive model tier.
For project-specific workers, create agents in your project's .claude/agents/ directory.
These override global agents with the same name within that project only.
Example: A SwiftUI-specific code worker for COOLGAME:
mkdir -p ~/projects/COOLGAME/.claude/agentsThen create ~/projects/COOLGAME/.claude/agents/code-worker.md with SwiftUI-specific
conventions in its system prompt. The global code-worker will still handle all other
projects.
| You Say | Orchestra Does |
|---|---|
| (any request) | Auto-assesses complexity, picks SINGLE/GUIDED/ORCHESTRA mode |
| "Just do it" or "Quick and dirty" | Forces SINGLE mode — no orchestration |
| "Full orchestra" or "Go deep on this" | Forces ORCHESTRA mode regardless of score |
| "Plan this but don't execute" | Runs planner only, shows manifest, waits for approval |
| "@orchestrator-planner" | Directly invokes the planner agent |
| "@validator" | Directly invokes validation on recent changes |
| "@code-reviewer" | Directly invokes code review on specified files |
Agents don't appear in /agents list:
- Verify files exist:
ls ~/.claude/agents/*.md - Check that each file starts with valid YAML frontmatter (the
---delimiters must be the very first line, no blank lines before them) - Start a new session — agents load at session start
Orchestra mode never triggers:
- Check that the CLAUDE.md content is actually present:
cat ~/.claude/CLAUDE.md | grep "Orchestra" - The complexity threshold may be too high for your typical tasks — try lowering from 6 to 5
- Try the explicit override: say "Full orchestra" before your request
Subagent fails or produces garbage:
- Check which model tier it's running at — Haiku may struggle with tasks that need Sonnet
- Try bumping the effort level before changing the model
- Check that the agent's
tools:list includes what it needs (e.g., code-worker needs Bash)
Hit rate limit mid-Orchestra:
- Your overage credits will kick in automatically
- If you want to avoid overage charges in the future, run large Orchestra tasks early in your usage window (shortly after a reset)
Workers seem to read too many files:
- The context-economy rules are in each agent's system prompt, but they're guidance, not
hard enforcement. If a worker is being wasteful, you can strengthen the language in its
.mdfile or add specific file scope restrictions to the planner's manifest format.
# Remove all Orchestra agents
rm ~/.claude/agents/orchestrator-planner.md
rm ~/.claude/agents/code-worker.md
rm ~/.claude/agents/research-worker.md
rm ~/.claude/agents/project-worker.md
rm ~/.claude/agents/validator.md
rm ~/.claude/agents/code-reviewer.md
# Restore your original CLAUDE.md
cp ~/.claude/CLAUDE.md.backup ~/.claude/CLAUDE.md
# Or if you appended, manually edit ~/.claude/CLAUDE.md and remove everything
# below the "ORCHESTRA ORCHESTRATION SYSTEM RULES BELOW" separator
# Remove the quick reference if you copied it
rm ~/.claude/ORCHESTRA-QUICKREF.md
# Remove .orchestra/ from any projects where it was created
find ~/projects -name ".orchestra" -type d -exec rm -rf {} + 2>/dev/null