orchid turns the agent CLIs you already subscribe to into a team that plans, implements, reviews and merges. Independent engines check each other's work, your own tests decide what passes, and your phone buzzes only when a human decision is needed.
brew install bilal-/tap/orchidcurl -fsSL https://raw.githubusercontent.com/bilal-/orchid/v1.0.0-beta.1/install.sh | bashModels do the judgment. Everything else is a bash state machine you can read in an afternoon, and every decision it makes is a file in git.
Engines are vendor CLIs in their own headless modes. orchid never holds an API key, never meters tokens and never proxies a request.
A different engine, or at least a fresh session, reviews every candidate. Research shows models favour their own output.
orchid verify runs the command you configure. An engine saying "tests pass" is a diagnostic, never evidence.
No daemon, no database. Tasks, reviews, the journal: committed on the integration branch.
Durable state is single-writer and epoch-fenced. A crash loses at most the tick in flight.
Roles are capability requirements, not vendor names. A new binding stays disabled until the capability suite proves it, and orchid doctor says so.
orchid jobs ls is the process table: each job's task, role, engine, state and budget. Liveness is computed, never read off a file.
A transition is refused unless its gate holds: a passing verify log, review envelopes bound to this exact commit, a journaled reason. Pick a state to see what moves it on.
On the roadmap, waiting for the tasks it depends on.
orchid task advance T001 implementingThe implementer engine (codex by default) edits a worktree of its own. The adapter, not the engine, commits.
runners/orchid-launchYour own test command runs against the recorded candidate commit.
orchid verify T001One or two reviewers, by risk tier, each from a different engine or at least a fresh session. Nobody signs off on their own work.
orchid task advance T001 reviewingAgreement is recorded with a reason. Disagreement goes to the orchestrator, which reads the diff and decides.
orchid task arbitrate T001 --result approve --reason "…"The suite runs again in a temporary worktree before the integration branch moves.
orchid merge T001Merged on the integration branch, with its evidence beside it. Task done is not run accepted: that stays your call.
orchid run acceptBack to the implementer with the failing output or the review attached. Three attempts by default.
rework spec writtenA real decision, an exhausted budget, or something orchid will not do on its own. One message reaches your phone.
orchid task unblock T001 --reason "…"Every engine gets a request document and leaves a result envelope. The kernel reads both and commits the outcome, and nothing an engine says is taken at face value.
This is source-level mediation, not OS containment: a shell-capable engine is still a process on your machine. The README says exactly what is enforced and what is policy. Architecture, in five diagrams
orchid doctor names what is missing, like a verify= line or an engine CLI, and how each role resolves.
❯ orchid doctorWARN: unattended trust (headless execution gated): deniedok: plugin discovery: no collisionsok: plugin manifests: validate cleanok: git repositoryok: jqok: worktree supportok: verify command configuredok: role orchestrator -> claude, codexok: role implementer -> codex, claudeok: role reviewer -> agyok: role arbiter -> claude, codexok: role plan_critic -> codex, claudeok: notify return leg: no notify channel configured (notify.channel unset)ok: integration branch exists or creatableok: no split-brain checkout stateok: task files: none on disk yet (nothing to check)ok: no stale integration checkout stateorchid init creates an integration branch and installs a pre-push guard. Your own branches are never touched.
❯ orchid initpre-push guard installed: ~/acme/api/.git/hooks/pre-push (integration branch: orchid/integration)initialized: orchid/integrationintegration branch: orchid/integrationnext: git worktree add ../api-orchid orchid/integration && cd ../api-orchidWrite requirements.md: the goal, constraints and acceptance criteria. A second engine critiques the plan before it becomes work. One command does the rest of the setup:
❯ orchid start requirements.md --verify "npm test"Stay in the session, or review the repository and install a heartbeat so it runs without a terminal open. Come back to merged, verified code with every decision journaled.
❯ orchid trust unattended "$PWD" --reason "reviewed for unattended runs"
❯ orchid service installA design fork, an exhausted rework budget, something orchid won't do on its own: one message reaches your phone over Telegram or WhatsApp, with the exact command to answer it.
BLOCKERS.md and the terminal do the same job.q-4-7f2a: Sign-in: keep magic links, or move to passkeys?task: T003 — sign-in with passkeysattempt: 2choices: magic-links | passkeysreply: ORCHID_REPO="/Users/sam/acme/api" orchid answer q-4-7f2a <choice> --nonce 9c1e04b7d2a85f36
passkeys
nonce checked · answer recorded
An engine can hold any role its declared capabilities satisfy. The tested defaults are what orchid's own suite and dogfood runs exercise; anything else is labelled unverified until orchid plugins test passes it.
| Engine | orchestrator | implementer | reviewer | arbiter | plan_critic |
|---|---|---|---|---|---|
claudeshell, git, workspace write | default | eligible | eligible | default | eligible |
codexshell, git, workspace write | eligible | default | eligible | eligible | default |
codex-reviewworkspace read, git | – | – | eligible | – | eligible |
agystructured text | – | – | default | – | – |
hermesstructured text | – | – | eligible | – | eligible |
orchid's verbs have no push, deploy or publish. Engines are told to raise external changes as a blocker, and moving the branch to origin stays yours.
Plugins are trusted code. Vendor sandbox flags are a real second layer; full OS containment is on the roadmap, not claimed.
No server, no dashboard, no accounts. orchid status --html writes a local file.
A merged task is a fact about one commit. Accepting the run is a separate decision, and it is yours.
The docs live with the code on GitHub, so they never drift from it.
An existing repository, from install to the first merged task.
start hereA new product with no code yet.
start herePinned one-liner, Homebrew, channels, uninstall, from a clone.
Dual review, epoch fencing and the rest of the visual tour.
diagramsThe tick, step by step: the procedure every orchestrator follows.
Every key, its default, and where it is read from.
Drive orchid from any agent product, tested or not, said plainly.
Each adapter, the exact CLI invocation it verified, and why.
From mkdir to a green conformance run, in under an hour.
extendThe seven checks an engine plugin has to pass.
extendIncident by incident, with the operator verb that fixes it.
The annotated bibliography behind the design, link-checked.
macOS and Linux, Bash 3.2 or newer. Install pins to v1.0.0-beta.1; upgrade with the next version's pinned line.
brew install bilal-/tap/orchidcurl -fsSL https://raw.githubusercontent.com/bilal-/orchid/v1.0.0-beta.1/install.sh | bashorchid is the third of shellbell and sous. Read the README or star it on GitHub.