orchestrator

a real fleet run — recorded, not rendered (raw transcript in docs/realrun-2026-06-06/)

No orchestrator is perfect — this one just refuses to trust its own workers.

the-perfect-orchestrator.vercel.app — the site (built and QA'd by its own fleet)

---

You talk to one Claude Code session — the LEAD. It spawns N fully interactive Claude Code workers in tmux panes, writes each a task brief, watches their screens, nudges the ones that drift, lets them coordinate through a shared message bus — and then has the workers adversarially verify each other's results before reporting anything back to you.

┌─ tmux: orch-audit ───────────────────────────────────────────────┐
│ ┌─ W1: scanning auth/ ──────────┐ ┌─ W2: scanning api/ ────────┐ │
│ │ ✻ Found unsafe redirect in    │ │ ✻ 3 endpoints missing rate │ │
│ │   login_v2.js:114 → bus.md    │ │   limits → bus.md          │ │
│ └───────────────────────────────┘ └────────────────────────────┘ │
│ ┌─ W3: scanning jobs/ ──────────┐ ┌─ W4: VERIFIER ─────────────┐ │
│ │ ✻ cron job runs as root,      │ │ ✻ Re-checked W1's finding: │ │
│ │   writing world-readable tmp  │ │   CONFIRMED. W2's #2 is a  │ │
│ └───────────────────────────────┘ │   FALSE POSITIVE — rejected│ │
│                                   └────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
        ▲ the LEAD (your session) reads panes, nudges, collects

Why this exists

Anyone who has run multi-agent setups knows the real problem isn't spawning agents — it's that workers lie. They rubber-stamp, declare victory early, and hallucinate "done". Most orchestration harnesses trust worker output blindly.

This one is built around a different rule, learned in production: findings don't count until a different worker has tried to tear them apart. In real use this has repeatedly caught not just worker mistakes — but the lead's own wrong assumptions.

How it works

graph TB
    U["you"] -->|one prompt| L["LEAD<br/>(your Claude Code session)"]
    subgraph T["tmux session: orch-&lt;name&gt;"]
        W1["worker 1"]
        W2["worker 2"]
        WN["worker N"]
    end
    L -->|"spawn / send / read / nudge"| T
    subgraph S["shared workspace"]
        BUS[("bus.md<br/>message bus")]
        TASK["agent-n.task.md (briefs)"]
        RES["agent-n.result.md + .done flags"]
    end
    W1 & W2 & WN <-->|"post + read findings"| BUS
    L -->|"writes briefs"| TASK
    W1 & W2 & WN -->|"write results, touch done-flags"| RES
    RES -->|"cross-verified by a DIFFERENT worker"| L
    L -->|"verified report"| U

Every worker is a full interactive Claude Code session — its own context window, its own tools, its own TUI you can watch live. Coordination is plain files: no servers, no daemons, no message broker. The lead is alive — it monitors, corrects, and re-plans mid-flight; it isn't a cron job poking a prompt.

The worker protocol

Each worker is told: you are Worker n of N; your task is in agent-<n>.task.md; coordinate via bus.md (append lines prefixed [Wn], read it to see peers); when finished write agent-<n>.result.md then touch agent-<n>.done; work autonomously, never wait.

Install in 10 seconds

claude plugin marketplace add daman8271/the-perfect-orchestrator
claude plugin install orchestrator@the-perfect-orchestrator

That gives your Claude Code session the /orch skill — the lead playbook. The plugin ships the skill only; the orch CLI itself installs via the classic path: