Orchestra

CLI-first task orchestration for Claude Code. Decompose goals, execute in parallel iTerm2 tabs, verify results.

Quick Start

# Create a goal — launches architect in a background tab instantly
/o-goal "Add dark mode support with system preference detection"

# View the board
/o-board

# Run a single task in a new iTerm2 tab
/o-run t-33

# Run all unblocked tasks in parallel
/o-run --all

# Check what's running
/o-status

# Review and approve completed work
/o-verify

Installation

Prerequisites: macOS, iTerm2, Claude Code

git clone <repo-url> ~/Orchestra
cd ~/Orchestra
./install.sh

The installer creates symlinks from the repo into your environment:

Source	Destination	Contents
Orchestra/skills/*	~/.claude/skills/	Slash command definitions (SKILL.md files)
Orchestra/scripts/*.sh	~/scripts/	Shell scripts (orchestra.sh, iterm-tab.sh, fan-out.sh)

The installer is idempotent — running it again skips existing links. To update Orchestra, just git pull in the repo directory.

Commands

Command	Flags	Description
/o-goal <description>	--image	Decompose a high-level objective into 3-8 child tasks. Async — registers instantly, architect runs in a background tab.
/o-task <title>	--quick	Create and launch a task. Async — registers instantly, workflow runs in a background tab. Use --quick for small fixes.
/o-board	--queued, --running, --all	View all tasks grouped by status. Use flags to filter.
/o-run <t-ID>	--interactive, --all, --max N	Execute a task in a new iTerm2 tab. --all for parallel fan-out, --interactive for guided execution.
/o-status [t-ID]		Show running tasks and queue. Pass a task ID for detailed step-by-step progress.
/o-docs <t-ID> [type]	plan, subtasks, architect, files, log	Browse task documentation. Specify a type to view a specific doc.
/o-verify [t-ID]	--pass, --fail	Review completed tasks. --pass to approve, --fail to auto-create a fix task.
/o-tail <t-ID> [step]		Show recent log output from a running task. Defaults to latest active step.
/o-attach <t-ID> <file>		Attach images or reference files to a task for the executing agent to use.
/o-plan <t-ID>		Generate an implementation plan (PLAN.md) and structured subtasks (subtasks.json).

Async Command Processing

/o-goal and /o-task are async by design. They keep your main Claude Code session interactive by doing the minimum work inline and launching heavy processing in background iTerm2 tabs.

Main Session (instant, stays interactive)
  1. Parse user input (title, context, priority)
  2. Register task in board.json (write one JSON entry)
  3. Create task directory (.orchestra/tasks/t-ID_slug/)
  4. Launch iterm-tab.sh with orchestra.sh
  5. Print confirmation & return control to user

Background Tab (runs autonomously)
  orchestra.sh picks up the task and runs:
    goal:      architect → decompose → register children
    standard:  brief → plan → declare → execute → verify
    quick:     execute → verify
  Tab name updates to show progress: "t-5: Title [execute]"
  On completion: auto-launches any unblocked dependent tasks

You type /o-goal "build a preset browser", get confirmation in under 5 seconds, and immediately issue more commands. The architect decomposition happens in a background tab you can check anytime.

Task Types

Type	Workflow	Best For
standard	brief → plan → declare → execute → verify	Most feature work, refactors, new modules
quick	execute (skips brief/plan)	Small fixes, typos, config changes
goal	architect → creates 3-8 child tasks	Large features, multi-part objectives

Task Lifecycle

Status Flow

Standard task:

queued → brief → plan → declare → execute → verify → review → done

Goal task:

queued → architecting → done + N child tasks

Workflow Steps

Step	What Happens	Output
brief	AI generates a feature specification	README.md
plan	AI creates implementation plan and subtask list	PLAN.md, subtasks.json
declare	AI identifies files to be created/modified	declared-files.json
execute	AI implements the feature, following the plan	Code changes
verify	Automated build/test commands run	verify.log
review	You review via /o-verify and approve or reject	Task → done or fix task created

Execution Model

iTerm2 Tabs

Each /o-run opens a named iTerm2 tab with live Claude Code output. Switch tabs with Cmd+1/2/3. /o-goal and /o-task also auto-launch tabs.

iTerm2 Window
┌─────────────────────────────────────────────────────────────┐
│ [Main Session] │ [t-3: FFT Analysis] │ [t-4: GUI Layout] │ │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Your interactive Claude Code session (always free)         │
│  /o-goal, /o-board, /o-status, /o-verify, /o-docs          │
│                                                             │
│  /o-goal "..."  → registers + opens architect tab instantly │
│  /o-task "..."  → registers + opens workflow tab instantly  │
│  /o-run t-3     → opens tab "t-3: FFT Analysis"            │
│  /o-run --all   → opens one tab per unblocked task          │
│                   each in its own git worktree              │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Two Execution Modes

Mode	Command	Behavior
Headless (default)	/o-run t-3	Fully autonomous. Uses claude --print --dangerously-skip-permissions. Output scrolls in the tab.
Interactive	/o-run t-3 --interactive	Full Claude Code session. Switch to the tab to approve/reject tool calls or ask questions.

Parallel Fan-out

/o-run --all launches every unblocked queued task simultaneously, each in its own git worktree for file-level isolation. Branches merge back on completion.

Set maxParallel in ~/.orchestra/config.json to limit concurrent tasks (default: 3). Override per-run with /o-run --all --max 5.

Verification

When a task finishes execution, automated verify commands run (build, tests). Then it enters review status for you to sign off.

/o-verify

Tasks Ready for Verification
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[t-3] Implement FFT Analysis Engine
  [ ] Load plugin in DAW, verify it loads
  [ ] Test with pink noise — check frequency display
  [x] Build passes (automated)
  [x] Tests pass (automated)

  /o-verify t-3 --pass           Mark all passed → done
  /o-verify t-3 v-1 --fail "…"   Mark item failed → creates fix task

When you --pass a task, Orchestra automatically unblocks any dependent tasks that were waiting on it.

On failure, /o-verify t-3 v-1 --fail "description" auto-creates a quick fix task with the failure context pre-loaded.

Dependencies

Goal decomposition creates tasks with depends_on relationships. Blocked tasks automatically become queued when all their dependencies are marked done.

# Example: /o-goal creates this dependency graph

t-33 Setup project scaffold        ← queued (no deps)
t-34 Research DSP algorithms        ← queued (no deps)
t-35 Implement DSP engine           ← blocked (depends: t-33, t-34)
t-36 Build GUI components           ← blocked (depends: t-35)
t-37 Integration tests              ← blocked (depends: t-35, t-36)

File Structure

Repository (~/Orchestra/)

Orchestra/
├── scripts/                Shell scripts for task execution
│   ├── orchestra.sh            Single-task workflow executor
│   ├── iterm-tab.sh            AppleScript iTerm2 tab launcher
│   └── fan-out.sh              Parallel task launcher (worktree-based)
├── skills/                 Claude Code skill definitions
│   ├── o-goal/                 /o-goal  — async goal + architect
│   ├── o-task/                 /o-task  — async task + launch
│   ├── o-board/                /o-board — view task board
│   ├── o-run/                  /o-run   — execute in iTerm2 tab
│   ├── o-status/               /o-status — running tasks
│   ├── o-docs/                 /o-docs  — browse task docs
│   ├── o-verify/               /o-verify — review checklist
│   ├── o-tail/                 /o-tail  — stream log output
│   ├── o-attach/               /o-attach — attach images
│   ├── o-plan/                 /o-plan  — generate PLAN.md
│   ├── architect/              Goal decomposition engine
│   ├── brief/                  Spec generator
│   └── declare/                File declaration
├── docs/
│   └── help.html           Interactive help page
├── examples/
│   ├── config.json         Example configuration
│   └── board.json          Empty board template
├── install.sh              Symlink installer
├── LICENSE
└── README.md

Runtime State (~/.orchestra/)

~/.orchestra/
├── board.json                    All tasks, statuses, dependencies
├── config.json                   Settings (max parallel, verify cmds)
├── memory.json                   Cross-task learnings
├── verify/
│   └── pending.json              Tasks awaiting user verification
└── tasks/
    └── t-{id}_{slug}/
        ├── README.md             Feature specification (brief output)
        ├── PLAN.md               Implementation plan
        ├── subtasks.json         Structured subtask checklist
        ├── declared-files.json   Files this task will modify
        ├── architect-output.json Goal decomposition (goal tasks only)
        ├── images/               Attached screenshots, mockups
        └── logs/
            ├── brief.log         Raw output from each step
            ├── plan.log
            ├── execute.log
            └── verify.log

Configuration

Edit ~/.orchestra/config.json:

{
  "maxParallel": 3,
  "defaultMode": "headless",
  "verifyCommands": {
    "my-project": "cd my-project && npm test"
  },
  "worktreeBase": "/tmp/orchestra-worktrees",
  "repoPath": "/path/to/your/repo",
  "logLevel": "normal"
}

Field	Type	Default	Description
maxParallel	number	3	Maximum concurrent iTerm2 tabs for fan-out
defaultMode	string	"headless"	Default execution mode: "headless" or "interactive"
verifyCommands	object	{}	Build/test commands to auto-run after the execute step, keyed by project name
worktreeBase	string	"/tmp/orchestra-worktrees"	Directory for git worktree isolation during parallel execution
repoPath	string		Absolute path to the repository root
logLevel	string	"normal"	Log verbosity level

Examples

Create and run a quick fix

/o-task --quick Fix typo in ParameterIDs.h namespace comment
# Registers task AND launches it in a background tab instantly

Decompose a large feature

/o-goal "Build a preset browser with category filtering, search, and drag-to-load"
# Registers goal instantly, architect runs in background tab
# You can immediately type more commands:

/o-board
# See the decomposed tasks once architect completes

/o-run --all
# Fan-out: all unblocked tasks launch in parallel iTerm2 tabs

Attach a design mockup

/o-attach t-35 ~/Desktop/eq-mockup.png "Target UI layout for the EQ plugin"
/o-run t-35
# The executing agent will see the mockup image

Monitor and verify

/o-status
# See what's running

/o-tail t-35
# Check latest log output

/o-docs t-35 subtasks
# See subtask progress

/o-verify
# Review completed tasks

/o-verify t-35 --pass
# Approve → unblocks dependents

License

MIT