Orch

Your coding agent doesn't choose its own model, and Orch puts mechanical bounds on what it may write.

Left to itself, a coding agent picks its own model for every task, and it can write to any file it can reach. That's fine until the model is wrong for the job — too expensive for something trivial, or too weak for something that actually matters — or until a change lands somewhere you didn't intend it to.

Orch sits underneath the CLI you already use (Claude Code or Codex CLI) and takes over those two decisions. By default it puts the repository in Assist: a mechanical, read-only mode where the agent can look around, search, explain and plan, but a write to a file git does not ignore is refused before it happens. When you approve a plan, Orch enters Delivery: each task becomes a GitHub issue with its own isolated git worktree, gets implemented there, is reviewed by a separate agent dispatch, runs CI, and is merged only after you approve it. Which model handles which job is not the agent's call either — you route it, per role, to an exact model version and effort level.

The payoff: cheap, fast models handle read-only exploration and mechanical work, a frontier model gets spent only where the plan calls for it, and every change that lands is auditable and gated by a human at the one step that matters — the merge.

What you actually get

• Read-only by default. Assist mode mechanically denies every write to a file git does not ignore — not a convention the agent is asked to honor, but a decision orch guard makes before the write happens.
• You route the model, not the agent. Six roles — architect, scout, implementer, specialist, reviewer, and a cheaper review downgrade — each pin an exact model version and effort level you choose, so a cheap model handles read-only work and a frontier model is spent only where the plan calls for it.
• Every issue gets its own worktree. Delivery work happens on its own branch, in its own isolated git worktree, never in your primary checkout.
• A separate dispatch reviews the work. The pull request is reviewed in a dispatch separate from the one that wrote it — never the same run marking its own homework.
• You hold the merge gate. Nothing lands on your default branch until you approve it, and the merge fails closed if the pull request moved after your approval.
• Every issue and PR carries an audit record. The exact model, the effort, how the host actually delivered that effort, and the routing rationale are recorded on the issue and mirrored onto its pull request.
• Works with the CLI you already use. Orch works with both Claude Code and Codex CLI, so you keep working in the agent you already have.

How it works

Two modes. A repository running Orch is in exactly one of two states. Assist is the default and is read-only: the agent can read anything, search, explain and plan, but a write to a file git does not ignore is refused. Delivery is entered only for a plan you have read and approved. Each task in that plan becomes a GitHub issue, a branch, and its own git worktree; the work happens there, lands as a pull request, is reviewed by a separate agent, runs CI, and waits for you to approve the merge. When every task is merged or abandoned, the run's last step puts the repository back in Assist.

Six roles. Delivery work is split across roles, and you pin each one to an exact model version and reasoning-effort level:

Which role gets an issue is derived from the issue's own facts by a deterministic table, not chosen by the model that will run it. The reviewer is always a separate dispatch and never the session that wrote the code, but under the shipped defaults it is often not a different model: on Claude every role runs claude-opus-5, so both sides always match; on Codex the specialist and the reviewer share gpt-5.6-sol while the implementer runs gpt-5.6-terra and the downgraded reviewer gpt-5.6-sol, so a specialist run has the same model on both sides but a downgraded review pairs different ones. Effort is where the hosts diverge: a specialist run's reviewer matches the specialist's effort on Claude (high on both) but not on Codex (max executor, xhigh reviewer), and a downgraded review drops effort below the implementer's on Codex (max to high) but not on Claude (medium on both).

The guard. None of the above is an instruction the agent is asked to honor. Both host adapters wire the CLI's pre-write hook to orch guard, a subcommand of the same binary, which is consulted before the agent writes a file and answers allow or deny. In Assist it denies every write to a file git does not ignore. In Delivery it allows a write only inside a worktree registered to the running plan, on that worktree's registered branch, in a phase where writing is allowed. Git internals are never writable, and neither is the orchestrator state your session is running against. It fails closed: anything it cannot establish is a denial. What it enforces is containment — it cannot tell which role is writing, and a file written by a shell command never reaches it at all (see Known issues).

Concretely, asking for a change goes like this:

1. You describe what you want. The Architect plans it in Assist and shows you the plan: one issue per task, each carrying the model, effort and reviewer it will get and why.
2. You approve it or send it back. Approving is what enters Delivery.
3. Each issue gets a branch and a worktree. An implementer or a specialist does the work there and pushes.
4. A reviewer reviews the pull request. CI runs.
5. You approve the merge, and it runs against GitHub pinned to the commit that approval names — it fails closed if the pull request moved after that.

The full product definition lives in ORCH-PRD.md.

Status

Early software. What can be stated as fact: 15 tagged releases, v0.1.0 through v0.6.0, and every pull request merged since PR #40 carries an Orch audit record in its body — apart from the configuration deliveries, which orch configure writes in its own body format. Since PR #40, this repository has been built through the pipeline described above: a plan gate, an isolated worktree per issue, a review dispatched separately from the work, CI, and a merge that fails closed unless it carries an approval pinned to the commit merge-report recorded.

All of that evidence comes from one repository: this one.

Install

Have your agent do it

Paste this into a Claude Code or Codex CLI session, started anywhere. It does not assume you have cloned this repository.

Install the Orch development orchestrator (https://github.com/kninetimmy/orch)
on this machine. Work in a scratch directory, not in one of my projects.

1. Detect my OS and run the matching installer:
     - Linux or macOS: download
       https://raw.githubusercontent.com/kninetimmy/orch/main/install.sh
       and run it with `sh install.sh`
     - Windows: download
       https://raw.githubusercontent.com/kninetimmy/orch/main/install.ps1
       and run it with
       `powershell -ExecutionPolicy Bypass -File .\install.ps1`
   The installer downloads the release binary for this OS and architecture
   and verifies its SHA-256 against the release's published SHA256SUMS
   before installing anything. If that verification fails, STOP and report
   the failure to me. Do not retry with verification skipped, do not fetch
   the binary another way, and never install an unverified binary.

2. Confirm that `orch` resolves on PATH and that `orch status` prints a
   release version on its first line — a line beginning `orch:` and giving
   a release tag such as v0.6.0. Run it from anywhere: outside an
   initialized repository it prints that version line first and then exits
   non-zero saying the repository is not initialized, which is expected
   here. On Windows the installer adds its install directory to my user
   PATH and a new terminal is needed to pick that up: if `orch` is not
   found, ask me to open a new terminal rather than guessing or editing
   PATH yourself.

3. Install the plugin for the host you are running in. Use exactly these
   commands:
     - Claude Code:
         claude plugin marketplace add kninetimmy/orch
         claude plugin install orch-claude@orch
     - Codex CLI:
         codex plugin marketplace add kninetimmy/orch
         codex plugin add orch@orch

4. Codex CLI only. Skip this entire step on Claude Code, which needs no
   clone:
   a. Codex plugins cannot ship agent definitions, so clone the repository
      into a temporary directory outside my projects:
        git clone --depth 1 https://github.com/kninetimmy/orch.git <tmp>/orch
   b. Copy these five files from <tmp>/orch/adapters/codex/agents/ into
      that repository's own .codex/agents/:
        orch-scout.toml
        orch-implementer.toml
        orch-specialist.toml
        orch-reviewer.toml
        orch-reviewer-safe.toml
   c. Delete <tmp>/orch afterwards. Nothing else from the clone is needed.
   d. Add both of these stanzas to ~/.codex/config.toml, leaving any
      existing content in place:
        [tools.experimental_request_user_input]

        [features]
        default_mode_request_user_input = true
   e. Tell me that Codex CLI shows a one-time trust prompt for the
      plugin's bundled hooks, that approving it is an action only I can
      take, and that the hooks do not run at all until I approve it. Do
      not report the install as finished as though the hooks were live.

5. Run `orch doctor` and report its full output to me, including every
   note and every failing check. When run outside an initialized
   repository it reports the git-repository and configuration checks as
   failures; say so rather than hiding it.

6. Tell me to restart this CLI before relying on any of it, and to treat
   the hooks as not yet running until I have. Do not assume a plugin
   installed mid-session is live in this session. The tell that it took
   is an Orch block at session start inside an initialized repository.

7. Finish by telling me all three of these: `orch init` has to be run once
   inside every repository I want orchestrated; Orch does nothing at all
   in a repository that has not been initialized; and `orch init` does not
   write the configuration into my working tree — it opens a pull request
   carrying .orchestrator/config.toml for me to review and merge.

Then initialize each repository you want orchestrated

Installing the binary and the plugin sets up the machine. It does not touch any repository. In a repository that has not been initialized, Orch does nothing.

Run orch init from the root of each repository you want orchestrated. It detects your environment (hosts, git, gh, memhub), interviews you about which hosts to enable and which models each role should use — every question has a default — and then bootstraps itself through its own pipeline: .orchestrator/config.toml arrives as a pull request you review and merge, not as a silent write to your working tree.

Delivery additionally needs git and the GitHub CLI (gh) authenticated against the repository's remote. Assist works without a remote.

Each adapter's README carries its host's exact install order and its own known limitations, worth reading once for the host you use: Claude Code, Codex CLI.

curl -fsSLO https://raw.githubusercontent.com/kninetimmy/orch/main/install.sh
# inspect it, then:
sh install.sh

iwr https://raw.githubusercontent.com/kninetimmy/orch/main/install.ps1 -OutFile install.ps1
# inspect it, then:
powershell -ExecutionPolicy Bypass -File .\install.ps1

# Claude Code
claude plugin marketplace add kninetimmy/orch
claude plugin install orch-claude@orch

# Codex CLI
codex plugin marketplace add kninetimmy/orch
codex plugin add orch@orch

# Claude Code
claude plugin marketplace update orch
claude plugin update orch-claude@orch

# Codex CLI
codex plugin marketplace upgrade orch

# Linux / macOS
sha256sum --check --ignore-missing SHA256SUMS

# Windows (PowerShell): compare against the matching SHA256SUMS line
(Get-FileHash orch_windows_amd64.exe -Algorithm SHA256).Hash

git clone https://github.com/kninetimmy/orch.git
cd orch
go build ./cmd/orch        # produces ./orch (orch.exe on Windows)

go install github.com/kninetimmy/orch/cmd/orch@latest

Day to day

orch help lists every command, human and plumbing, in one place:

usage: orch <command>

commands:
  init             Interview and bootstrap this repository
  status           Show mode and configuration summary
  doctor           Check environment and configuration health
  configure        Interview and deliver committed configuration changes
  configure-local  Interview and apply machine-local overrides
  resume           Reconcile an interrupted Delivery run against GitHub and continue
  abort            Stop dispatch and return to Assist
  metrics          Show local metrics
  render-agents    Render the five Codex agent TOMLs from configuration into .codex/agents/
  run              Adapter plumbing: Delivery run verbs (JSON stdin/stdout; not a human command)
  guard            Adapter plumbing: pre-write enforcement for host hooks (not a human command)
  hook             Adapter plumbing: host lifecycle-event verbs (not a human command)

The last three rows — run, guard, hook — are what the host adapters call for you; you never invoke them by hand.

On Claude Code the three interviews also have slash commands: /orch:init, /orch:configure, /orch:configure-local.

Settings — what you can tune

Configuration lives in two TOML files under .orchestrator/:

• config.toml — committed to git, shared by everyone working on the repository. Changed with orch configure, which delivers the edit as a reviewable pull request.
• config.local.toml — machine-local and gitignored, for personal preferences. Changed with orch configure-local, applied directly.

The split is a closed table over every key in the schema, not a convention: policy keys can only live in the committed file, so a local override can never weaken a shared workflow rule.

Every enabled host carries the same six roles: architect, scout, implementer, specialist, reviewer, and review_downgrade (the cheaper reviewer Orch may use only when the plan affirms all four of mechanical, low-risk, fully specified and unsurprising — claims routing takes at face value rather than checks). Each role names one model string; the interview offers exact versions rather than tier aliases, and whatever string is configured is the one that lands in the audit record, so the record says what ran instead of what tier it belonged to. The defaults orch init offers:

Typical tuning: point a role at a bigger or smaller model on one machine with configure-local (run the Architect on a frontier model only where you have the subscription), raise max_subagents on a machine that can take it, or turn on local metrics while experimenting. orch status reports how many overrides are in effect and orch doctor names the exact keys they set, so a machine-local change is never invisible.

Memhub integration

memhub is an external, optional, local-first per-repository project-memory CLI. Orch talks to it when it is present but neither requires it nor ships it: set memhub.mode to off and Orch never looks for it.

memhub.mode is committed, in config.toml, and has three values:

• off — memhub is skipped entirely: no probes, no doctor checks.
• best-effort — memhub's health and recall are probed and reported, but a failure never blocks anything.
• required — Delivery planning fails closed if either probe fails: the plan gate refuses to activate the run.

Both the plan gate and orch doctor run the same two-step check: a memhub status health probe, then — only if that succeeds — a memhub recall against a fixed canary query, so a wedged retrieval path that still exits 0 is caught rather than trusted. orch doctor is mode-aware: off prints a skip note, best-effort reports the result as a note without failing, and required fails the check outright.

Orch's own memhub client is read-only: it probes and recalls, and never writes, renders, reindexes or syncs. Writes are the Architect's alone, and that boundary is stated in the skills rather than enforced mechanically — a subagent carrying a shell can reach the memhub CLI too. Anything a subagent wants remembered comes back in its report. Every memhub command runs with the primary checkout as its working directory, never inside a per-issue worktree, because worktrees never receive a copy of the memhub database.

Known issues and limitations

Fixed

Under the hood

This section is for contributors and the curious; none of it is needed to use the tool.

Enforcement, not convention

The mode rules are resolved by a closed decision table in internal/guard, reached through the host CLI's pre-write hook. In Assist, a write to any in-repo file git does not ignore is denied; git-ignored paths are allowed as local scratch. In Delivery, a write is allowed only inside a worktree registered to the active run, in a writable phase, with that worktree's HEAD on its registered branch. If the guard cannot determine a fact — an unreadable state file, a path it cannot canonicalize, an ignore probe that fails to run — it denies.

Two things are off limits in either mode, and one that looks like it is, is not. Anything under .git is denied before the mode is even consulted. The orchestrator state a session runs against — state.json and the lock, in the primary checkout — is never writable by an agent either: Assist denies it as orchestrator internals, Delivery denies it as lying outside every registered worktree. A worktree's own committed .orchestrator/config.toml is covered by neither rule. Inside a registered worktree it is repository content on a branch under review, so an executor can edit it, and that edit reaches your configuration the way every other change does — through the pull-request diff and the human merge gate. It cannot alter enforcement mid-run, because the guard resolves state from the outermost .orchestrator root, which is the primary checkout and never the worktree's copy.

What the table decides is containment. The guard is given the write's target paths, not the identity of the agent making the write, so it cannot make one role read-only and another writable; the --role narrowing that exists for that purpose is passed by neither adapter. Nor does it see writes the host does not route through a guarded tool, which is why shell-mediated writes escape it entirely. Both gaps are in Known issues.

Delivery is exclusive across hosts and machines: a lock file (.orchestrator/delivery.lock, created with O_EXCL) is the lock, and there is no automatic staleness takeover — recovery is always an explicit orch abort or orch resume. Run state is schema-versioned JSON at .orchestrator/state.json (machine-local, atomic writes, fail-closed loads), persisted after every sub-step, so a crash at any point is recoverable.

The Delivery pipeline

A run starts at the plan gate: a schema-versioned plan document (issues, dependency waves, risk facts) is validated fail-closed, and a gate document derives each issue's executor and reviewer from those facts alone through the routing table — the model never picks its own reviewer. The gate also runs the memhub health and recall check described above, gated by memhub.mode. Activation then creates the GitHub label taxonomy, one issue per task carrying a structured audit record (rendered markdown plus canonical JSON in a managed body region: the approved objective, acceptance criteria and required tests, plus the exact model, the effort, how the host actually delivered that effort, and the routing rationale, mirrored onto the pull request), and one branch and isolated worktree per issue under .orchestrator/worktrees/.

Each issue then walks a closed lifecycle driven by plumbing verbs: dispatch (dependencies must be merged; the branch is fast-forwarded onto the default branch) → pr-open (clean, strictly-ahead, orphan-PR guarded) → review-worktree (a disposable detached worktree of the pull request head, so the review does not run in the primary checkout) → review (the routed reviewer, verified against the live PR head) → ci (reads required checks as one of four honest states — passing, failing, pending, or the explicit no-checks, which is never conflated with passing) → merge-report (pins the approved head SHA, and carries a no_ci_statement whenever no-checks is what gates the merge, so "nothing gates this" is always said outright) → merge (human-approved, re-checked against the live PR, pinned with --match-head-commit, setting the issue's terminal delivered label) → cleanup → complete (fast-forward the primary checkout, return to Assist). Failures route through escalate (the routing ladder), block (closed failure classes; a secret found stops the whole run) or abandon. Errors never mutate state; state advances only on success.

orch resume reconciles an interrupted run against GitHub reality in three strict stages — observe (all reads up front), classify (a pure 30-row decision table), apply (one state write, skipped when the run has already converged). It never fabricates approval, never advances past the human merge gate, and never deletes or recreates anything.

Routing and escalation

internal/routing is pure and deterministic: a five-row, first-match-wins table over four task facts — whether the work is read-only, whether it is unusually difficult, which of a closed nine-domain risk enum it touches, and four affirmative claims (mechanical, low-risk, fully specified, unsurprising) that alone permit a cheaper reviewer — plus the models that have already failed this issue. Read-only work goes to a scout, on the specialist model when it is risky, difficult, or the scout model has already failed. Risky, difficult or previously-failed work goes to a specialist with a strong reviewer and refuses the downgrade there even when all four claims hold, recording the refusal in the rationale. Everything else goes to an implementer. Any conflict takes the stronger route and says so in the rationale.

On failure, escalation retires the failed model permanently for that issue (an effort bump is still a retry; a model swap is not), restores the strong reviewer on any reroute, and resolves exhaustion to an explicit return-to-Architect. The code never ranks model strength on its own.

Package layout

Design principles

• Fail closed. Unknown config keys, schema drift, unreadable locks, indeterminate checks — everything unprovable is denied with a named remediation.
• Mechanics are policy-free. gitops/ghops/manifest know how; internal/run alone decides when and why.
• Humans gate merges. Orch pins the approved head SHA and refuses if the pull request moved after approval; the merge itself happens on GitHub.
• Everything auditable. The exact model, the effort, how the host actually delivered that effort, and the routing rationale live in the issue's audit record and are mirrored onto its pull request.

Build / test

Requires Go 1.26+.

go build ./...            # build everything
go test ./...             # run the test suite
go vet ./...              # static checks
gofmt -l .                # list unformatted files (CI fails on any)
go run ./cmd/orch status  # or: doctor, help

License

MIT — see LICENSE.