# Orch > - Skill: `daman8271/orch` (Agent Skill) - Install (CLI): `npx skillmds@latest add daman8271/orch` - Raw SKILL.md: https://api.skillmd.com/api/skills/daman8271/orch/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: daman8271 (https://skillmd.com/u/daman8271) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/daman8271/orch --- # The Perfect Orchestrator — lead playbook You are the **LEAD**. This harness lets you spawn N autonomous Claude Code workers (each its own tmux pane), brief each one, watch them, correct them, verify their results, and drive them to completion — all from this one session. The CLI is `orch` (run `orch --help` for usage; state lives under `$ORCH_HOME`, default `~/.orch`). ## The harness commands | command | what it does | |---|---| | `orch spawn [workdir]` | Create tmux session `orch-` with N worker panes + a shared workspace at `$ORCH_HOME/runs//shared/` (contains `bus.md`; `panes.txt` lives one level up). Workers are numbered 1..N. Workdir defaults to the current directory. | | `orch send <#> --file ` | Dispatch a task: tells worker # "Read and follow `` then begin, work autonomously." | | `orch send <#> ` | Send a short single-line nudge (NO newlines — newline submits). | | `orch read <#> [lines]` | Capture a worker's pane (to see what it's doing). | | `orch status [session]` | Overview of all live fleets, or one fleet's panes + done-flags + bus tail. | | `orch kill ` | Tear down a fleet when done. | Workers launch with an **isolated config** (no hooks → no notification spam on every turn, a generous allowlist → no permission prompts, shared live credentials, `ORCH_WORKER=1`). When a worker's `claude` exits, its pane ends. ## The workflow (do it in this order) 1. **PLAN** — split the job into N *independent* sub-tasks (one per worker). Pick N deliberately (see Limits). 2. **SPAWN** — `orch spawn [workdir]`. Give workers a few seconds to boot (a pane showing a ready prompt = booted). 3. **BRIEF** — write each worker's brief to `$ORCH_HOME/runs//shared/agent-.task.md`. A good brief is self-contained: the goal, hard constraints (what NOT to touch), exactly what to produce, **where to write its result + a done-flag to `touch`**, and how to use the bus. 4. **DISPATCH** — `orch send --file .../agent-.task.md` for each booted worker. 5. **COORDINATE via the bus** — tell workers to post findings to `shared/bus.md` (lines prefixed `[Wn]`) and to read it. When one discovers something (a bug class, a shared fix needed), the others act on it. The bus is the fleet's shared memory. 6. **MONITOR (your core job)** — periodically `orch read` each pane + read `bus.md`. Catch wrong-roads *early* and correct them with a nudge. Watch for: off-task drift, dead-ends, forbidden actions, or stalls. Re-check on a cadence (~80–600s) so you stay free between passes; a tighter cadence = closer watch. 7. **COLLECT** — each worker `touch`es a done-flag (e.g. `shared/agent-.done`) + writes `agent-.result.md`. Poll the flags (background loop or `orch status`) so you know when all are done. 8. **VERIFY + TEAR DOWN** — read the results, *verify them adversarially* (don't trust blindly — have a DIFFERENT worker try to refute each finding), then `orch kill `. **Report a consolidated sign-off BEFORE killing sessions.** ## Patterns that work (battle-tested) - **Find → verify:** some workers FIND issues; a *different* worker VERIFIES each finding. Independent eyes kill false positives. - **Brief neutrally:** don't pre-declare the cause ("verify *whether/why* X is wrong", not "fix the X bug") — workers investigate instead of rubber-stamping your assumption. (This repeatedly caught the lead being wrong.) - **One owner per shared file:** if several workers would edit the same shared file, assign ONE owner; the rest request changes via the bus — else their git commits collide. - **Commit-local, lead pushes:** workers commit only their own files (behind a `flock` on a repo-local lockfile), do NOT push; the lead verifies then pushes. Use `git show --stat ` to confirm each commit is own-files-only (workers must `git add `, never `-A`). - **3× cross-verify for high-stakes:** R1 audit → R2 adversarially refute R1 → R3 confirm survivors. ## Nudging / un-sticking a worker - `orch send` only sends **single-line** messages (or `--file`). Long text with newlines will submit early — put it in a file. - To clear a stuck/garbled input draft, drive tmux directly: `pane=$(sed -n '1p' $ORCH_HOME/runs//panes.txt)` then `tmux send-keys -t "$pane" Escape; tmux send-keys -t "$pane" C-a; tmux send-keys -t "$pane" C-k` then your clean message, then a **separate** `tmux send-keys -t "$pane" Enter`. - A long message typed via send-keys sometimes needs `Enter` sent **twice** to submit. Never type onto an existing draft (it concatenates). ## Limits / gotchas - **PERMISSIONS (the #1 blocker):** the permission classifier may *deny* autonomous spawns/sends. If `orch`/`tmux` calls get blocked, the user must add allow-rules to `~/.claude/settings.local.json`: `Bash(orch:*)` and `Bash(tmux:*)`. Run `orch doctor` to print them. - **SCALE:** workers are real sessions consuming real usage — size the fleet to the work AND to the user's plan. If the account rate-limits, fleets degrade; prefer fewer, better-briefed workers. - **TUI height:** don't cram many panes into one window — the worker TUI needs rows. For many workers, spawn separate sessions (one `orch spawn` per target) or batch them. - **Tear down finished fleets** (`orch kill`) to free resources + your attention. Check live sessions with `orch status`. ## When NOT to use this For a single quick task, just do it yourself or use one subagent. Reach for the fleet only when the work is genuinely parallel, multi-target, and long enough that one lead managing many workers beats serial execution.