orch-kit

A single-file, idempotent orchestration kit for Claude Code. Opus thinks, Sonnet does, Haiku verifies, Codex reviews — and you stay the tech lead.

中文文档 →

Why

This started from a recipe by @diegocabezas01 on X: Fable 5 as orchestrator, Opus/Sonnet as pinned subagents, Codex as a peer engineer. Two real-world constraints then reshaped it into what you see here:

1. Frontier models come and go from subscription tiers. Days after that post, Fable 5's inclusion window on Pro plans was ending. The orchestration architecture must be decoupled from any specific model — switching orchestrators should cost one launch flag, not a config rewrite.
2. Subscription quotas are finite. So the economics get inverted: the cheap model orchestrates (planning and synthesis are token-light), and the expensive models become specialists called sparingly. Deep reasoning is outsourced to a pinned Opus subagent and a cross-vendor Codex peer, which compresses the quality gap at the orchestrator seat.

The design principle underneath everything: stable things (roles, discipline, workflow) live in files; volatile things (the orchestrator's model) live in launch flags. "Switching configurations" then degenerates into "which command you launch with".

What you get

One script, orch.sh. No dependencies beyond bash (macOS 3.2 compatible). Seven subcommands:

orch global   # deploy the two global conduct files (~/.claude/CLAUDE.md, ~/.codex/AGENTS.md)
orch setup    # per-project install: subagents, orchestration block, AGENTS.md (facts auto-detected)
orch light    # launch with Sonnet as orchestrator (daily default)
orch heavy    # launch with Opus as orchestrator (architecture / hard problems)
orch fable    # launch with Fable 5 (when available on your plan / usage credits)
orch status   # health check across all layers
orch smoke    # headless smoke test: model, subagents, orchestration block loaded?
orch doctor   # environment & network diagnostics (binaries, proxy exports, egress region, nvm)
orch update   # self-update from GitHub (syntax-checked, backed up, atomic replace)
orch print claude|codex   # preview the global conduct files without writing
orch uninstall            # clean removal — anything you modified is preserved

What touches your machine (full transparency for a tool that writes to your home directory):

Command	Writes to
orch global	~/.claude/CLAUDE.md, ~/.codex/AGENTS.md — only this command touches these two; overwrites with .bak backup
orch setup	user level: ~/.claude/agents/ (3 subagents), ~/.claude/commands/ (3 slash commands); project level: CLAUDE.md orchestration block, AGENTS.md, .claude/settings.json
orch uninstall	removes the above — but only files whose content still matches what orch generated. Anything you edited is left in place with a warning. Global files are restored from their pre-deployment .bak when one exists. Project AGENTS.md is always kept (the facts in it are yours). The Codex plugin, the script itself, and the shell alias require the manual steps it prints.

The roster it installs:

Agent	Model	Role
deep-reasoner	Opus	Think — architecture, complex debugging, algorithm design, verdicts at commitment boundaries (read-only: it advises and drafts, never edits)
fast-worker	Sonnet	Do — mechanical edits, boilerplate, tests, formatting
qa-runner	Haiku	Verify — run tests/lint/typecheck, report verbatim, never judge
Codex plugin	(OpenAI)	Review — adversarial review, rescue mode, an independent second perspective

Three institutional rules baked into the config:

• Single writer. Only the orchestrator has commit rights. Codex produces but never integrates — its global AGENTS.md explicitly revokes autonomous commit & push. Two autonomous integrators on one repo eventually collide; one writer keeps history linear.
• Perspective isolation. Codex is never told an orchestration system exists. Facts are synchronized between both agents' config files; roles are not. An informed but independent outsider reviews better than a team member.
• Specs in, evidence out. Every delegation carries a five-part spec — objective, files, interfaces, constraints, verification command; a spec you can't finish writing means the decision isn't made yet. Every result is accepted only after the diff is read and verification re-run: a report without command output is a claim, not a completion. And a lane that's unavailable fails loudly — never a silent self-substitution.

Plus a dormant scale-up protocol (spec-driven mode for multi-session features: ADRs, specs as inter-agent contracts, status docs as cross-session relay batons) that activates only when a task exceeds ~1 day or 3+ modules.

Quick start

# 1. Install the script
mkdir -p ~/bin && cp orch.sh ~/bin/ && chmod +x ~/bin/orch.sh
echo 'alias orch="$HOME/bin/orch.sh"' >> ~/.zshrc && source ~/.zshrc

# 2. Global conduct layer (once per machine)
orch print claude   # preview what will be written (also: orch print codex)
orch global

# 3. Per project (auto-detects workspace layouts: multiple git repos under one root)
cd ~/dev/your-project
orch setup

What orch global does to existing files — overwrite, not append. It writes complete conduct files to ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md. If yours already exist with different content, they are backed up to .bak first, then replaced. Overwrite is deliberate: conduct instructions that are duplicated or contradictory (yours appended to ours) are worse than either set alone. If you have global config you care about, read the reference copies in docs/reference/ (or run orch print claude|codex) and merge by hand instead of running orch global. Personal preferences that don't conflict (language, tone) can simply be re-added on top afterwards.

Then install the Codex plugin — once, globally. This step can't be scripted: /plugin is an interactive session command. Launch a session with orch light, then type these four lines into the Claude Code chat box (not your shell):

/plugin marketplace add openai/codex-plugin-cc
/plugin install codex@openai-codex        ← choose "user scope" when asked
/reload-plugins
/codex:setup

Then re-run orch setup once: it now auto-enables the plugin's stop-time review hook for the project — a deterministic Codex review that fires whenever a session stops with unreviewed changes. The hook's toggle is stored per project, so orch setup handles it in each project (manual fallback: /codex:setup --enable-review-gate). It is the only review lane that runs without the model choosing to — a safety net for anything that slips through (it fires at session stop, so it cannot block a commit already made; the pre-commit gate itself is the rescue-agent review below).

Finally verify: orch status && orch smoke. If anything network-ish looks off, orch doctor runs the whole diagnostic chain (proxy export detection, egress region via claude.ai's trace endpoint, nvm isolation warnings).

orch setup also installs two friction-killers:

• A permission allowlist (.claude/settings.json, create-only): safe read-only git commands plus your project's detected test/lint commands are pre-approved, so the permission gate stops nagging about obviously-safe things while writes and pushes still require confirmation.
• Task slash commands (~/.claude/commands/): type /task fix the flaky parser, /bugfix …, or /review-first … inside a session instead of retyping the briefing template.

Usage example

Launch and talk to it like a tech lead — give decision material, not instructions:

cd ~/dev/your-project && orch light

Goal: SRT subtitle parsing drops lines when timelines overlap — fix it and
      add regression tests
Context: src/parser/srt.ts, repro sample at fixtures/overlap.srt
Constraints: don't change the parser's public interface; use the existing
             vitest setup

What happens next (the orchestration block handles all of it — no need to say "delegate" or "show me a plan"):

1. For non-trivial tasks it shows you a plan first — already reviewed by deep-reasoner (Opus), with the verdict and deciding risk attached, so a plausible-but-wrong plan gets caught before it reaches you. The plan names which lane owns each work item; a plan where the orchestrator does everything itself is a red flag it must surface, not a default. You review the split, adjust if needed ("give this one to Codex in parallel, don't show either the other's answer"), then say go.
2. Execution: exploration goes to subagents, mechanical work to fast-worker, verification to qa-runner. Your main thread stays lean — check with /context afterwards.
3. Before commit the orchestrator delegates a review-only pass on the diff to the codex:codex-rescue subagent, explicitly with --wait, and only actual findings count — a job-started receipt means the gate has not run (reported honestly as review: none). (Why not /codex:review? That command is marked disable-model-invocation — only you can type it; the model literally can't.) The stop-time hook is the safety net behind it, reviewing whatever slips through when the session stops. The orchestrator must report review status verbatim — review: rescue-agent, or review: none plus the reason — so a silently skipped review can't pass as a done task. You accept, then let it commit (Conventional Commits, linear history — enforced by the global conduct files).

Escalation mid-task: "hand this to deep-reasoner" (single hard problem), or exit and relaunch with orch heavy (the whole task turned out to be architectural). Codex's other classic entrance: "have Codex try rescue mode on this" when stuck.

Bypass permissions mode

Extra arguments after the subcommand are passed straight through to claude:

orch light --dangerously-skip-permissions   # YOLO mode: no permission prompts
orch heavy --continue                        # resume the previous session

A word of caution before you reach for it: in this system the permission prompt is one of your four control points as tech lead (define task → approve plan → guard permissions → review result). Skipping it is reasonable in a sandboxed/containerized environment or a throwaway repo, and a bad trade on anything you can't afford to lose. If what bothers you is repetitive prompts for safe commands, the finer-grained fix is an allowlist in .claude/settings.json rather than removing the gate entirely.

Design Q&A

The questions that actually shaped this kit, from the design conversation it grew out of:

Q: The orchestrator model I built around is leaving my subscription tier. Is the setup dead? No — that event is what forced the right architecture. Subagent models are pinned in their own files; only the main thread's model is a launch flag. Route around it: cheap model orchestrates daily (light), expensive one on demand (heavy). The deep reasoning was already outsourced to the Opus subagent and Codex, so the orchestrator seat's model gap is compressed by the architecture itself. What the cheap seat can't be trusted with is self-assessment — so the gaps are made structural: every non-trivial plan passes deep-reasoner's verdict before you see it, and every non-trivial diff passes an independent Codex review before commit (rescue-agent lane in-loop, stop-time hook as the safety net). Quality rides on gates, not on the orchestrator knowing its own limits.

Q: Should I add "choose your model wisely" to the orchestrator's instructions? No — it's noise. The orchestrator can't choose models: the main thread's model is fixed at launch, subagents' models are pinned in frontmatter. The real decision is "which subagent gets this work", and that's driven by two concrete things: subagent description fields (trigger conditions, not documentation) and explicit routing rules. Vague adverbs don't change LLM behavior; executable rules do.

Q: Architect on Opus, coder on Sonnet, QA on Haiku — good split? Two-thirds right. The trap is QA: judging code quality is reasoning-heavy, and a weak model's "looks fine" is worse than no review — missed bugs don't announce themselves. So qa-runner is locked to mechanical verification (run tests/lint/typecheck, report verbatim, explicitly forbidden to judge or fix), and the judgment-QA seat goes to Codex — a different vendor's model, in adversarial mode.

Q: What goes in Codex's AGENTS.md? Facts and standards — never the orchestration rules. Codex's entire value is the independent second perspective; telling it "you're part of an orchestration system" contaminates that. Sync the facts (test commands, interface red lines) so it works from correct premises; isolate the roles. Eight words: facts synchronized, perspective isolated.

Q: Two agents can both write code. Who commits? Exactly one — the single-writer principle. Both agents keeping autonomous commit & push means interleaved histories and rebase collisions on the same repo. The integrator is the orchestrator (it does the synthesis); Codex's global config explicitly revokes autonomous commits ("present changes; the integrator commits").

Q: My root folder holds two related git repos. Where does orch setup run? At the root — the script auto-detects this layout. CLAUDE.md loads recursively up the directory tree, so the orchestration block lives once at the root (with an auto-generated workspace map you fill in: each repo's role, and the linkage rules like "changing A's API requires checking B's call sites"). AGENTS.md goes per git repo, because that's Codex's discovery boundary. Launch position becomes a control: single-repo task → launch inside that repo; cross-repo task → launch at root, prefer heavy.

Q: fable-advisor runs the session on the expensive model and implements on Grok/GPT lanes. Should orch-kit adopt that? The delegation discipline, yes; the lane inversion, no. fable-advisor puts the priciest model in the orchestrator seat and routes implementation to Grok/GPT CLIs — the exact mirror of our economics, and its own "advisor-only mode" (cheap session, expensive model consulted at commitment boundaries) concedes the point our light default is built on. A Grok lane would also add a third vendor CLI + auth + billing surface, against this kit's single-file-zero-dependency grain. What we did adopt (v5.2): the five-part spec contract for every delegation, the verdict-style advisor doctrine on deep-reasoner (verdict not survey, read-only tools, commitment-boundary triggers), the claims-are-not-evidence acceptance rule, and no-silent-fallback when a lane is down.

Q: Which manual steps should be automated? Deterministic ones — and only those. File deployment, workspace detection, fact probing (reading package.json scripts, Cargo.toml, go.mod), health checks: scripted. Plan approval, spec approval, confirming detected facts, the workspace map's linkage semantics: kept human. Automation exists to move your time from hauling to judging, not to outsource the judging.

Q: After configuring, do I restart the apps? How do I know it works? Sessions, not apps: configs load at session start, so a new session is all you need. Verification is four layers — static (status + smoke), component (name each subagent once), integration (a real task without naming anyone: pass = the plan proposes delegation, Task calls appear, /context shows a lean main thread), and regression (freeze that task as your smoke eval; re-run after every config/model change). If it won't delegate, fix the subagent's description — it's a trigger condition, write it as "when to use", add "Use PROACTIVELY".

More operational detail (including a pitfall quick-reference: macOS bash 3.2, nvm global-package isolation, /plugin availability, proxy/region diagnostics, shell-vs-environment variables) lives in docs/handbook.md (Chinese).

Credits

• @diegocabezas01's original orchestration recipe on X — the four-role starting point.
• Max Lv's porting mihomo to Rust with Claude — the scale-up protocol (specs as inter-agent contracts, filesystem as cross-session state bus, ADR decision layering, default rules for unspecified edges) is a distillation of that article's practice.
• DannyMac180's fable-advisor — the five-part spec contract, the verdict-style advisor doctrine, and the claims-are-not-evidence acceptance rule adopted in v5.2.
• Anthropic's Claude Code subagents/plugins documentation, and OpenAI's official codex-plugin-cc.

Roadmap

• Package as a Claude Code plugin (one /plugin install instead of a script)
• Scriptable codex exec lane — a subagent driving the codex CLI headlessly (fable-advisor's codex-implementer pattern) would remove the one manual install step (/plugin is session-interactive) and keep perspective isolation cleaner; needs weighing against the plugin's rescue/review commands
• Battle-tested example tasks with before/after context measurements
• Smarter smoke-test assertions

Disclaimer

The Codex plugin is a third-party component by OpenAI; its behavior is governed by its own repository. The AGENTS.md review-posture defaults (e.g. CJK text-encoding vigilance) are examples from the author's projects — adjust to yours.

License

MIT