CLI reference

Every `orch` command, grouped by top-level verb, generated from the cobra tree.

orch CLI reference

Generated by go run ./cmd/orch-docs from cli.NewRoot() (client/internal/cli). 335 commands total, 52 hidden (see "Power-user / agent protocol" below).

orch#

Orchemax — run AI coding agents together on your projects

orch [flags]

Orchemax sits under the agents you already use (Claude, OpenCode, Cursor, Codex, …). It does not replace their UI. It adds shared-folder locks, a local LLM gateway (token savings + provider failover), and a simple way for sessions to hand off work.

The command-line name is: orch

First-time setup

1. Run orch install (also works on the downloaded file) — it copies Orchemax to its per-OS folder and adds that folder to your user PATH
2. Create or cd into your workshop folder (the folder that holds your projects)
3. Run: orch init → binds this folder as a workshop when it is not bound yet (writes orch.yaml + .orch/) → then offers the ordered layout (shared + projects), thin CLAUDE/TRACKER, git per folder

Connect LLM providers (user-wide — once for all workshops) orch gateway setup --live --name … --url … --key-env MY_API_KEY → writes %LOCALAPPDATA%\Orchemax\ai.yaml → put the secret in a Windows User environment variable (not in yaml) orch gateway

A workshop orch.yaml can still override ai.providers if you need a special case.

Start working (from inside your workshop) Open any agent on your PATH: orch <name> orch ui # optional local web console orch workshop # show resolved workshop for this folder

Tips Type your prompt inside the agent UI — not as arguments to orch. Outside a workshop: loose mode (gateway OK; no locks/bus/project control). Agents that know Orchemax use MCP — see docs/PROTOCOL-AGENT.md. Bare orch prints this help. Use: orch <command> --help Agent-facing commands (mcp, dispatch, msg, ask, task, guard, index, seats) are listed under "Agents & workshop:" below; the learning engine (learn, memory, chair) under "Learning & memory:". A few internal-only verbs stay hidden; they still work if you know their name.

Docs: https://docs.orchemax.com

orch acp#

Agent Client Protocol session commands

orch acp [flags]

orch acp list#

List ACP agent sessions recorded for resume

orch acp list [flags]

orch acp resume#

Continue a recorded ACP session with one more prompt

orch acp resume <session-id> [flags]

Drives one more session/prompt turn against an agent session recorded by a prior ACP dispatch (see: orch acp list), preferring session/resume and falling back to session/load — whichever the agent's initialize response advertises. Fails with an explicit "capability absent" message when the agent advertises neither. Reuses the routing env the original dispatch resolved: a session recorded as opencode-gateway gets its worktree OPENCODE_CONFIG and a freshly minted worker key back, never the operator's own OpenCode config; any other route runs with the environment untouched.

orch agents#

Detect coding agents installed on your PATH

orch agents [flags]

Scans your PATH for known agent CLIs and records what was found. Presets are never written into orch.yaml until you name them.

orch agents scan # look for agents; write a snapshot orch agents show # print last scan orch agents apply <id>… # add ONLY the agents you name to orch.yaml

Tool execution permissions: Orchemax oversees sandboxes, worktrees, and quality gates. Dispatched workers and interactive seats configure tool auto-approval (e.g. agy --dangerously-skip-permissions, cursor --approve-mcps --trust (interactive) / --force --trust --approve-mcps (headless), opencode run --auto) so child CLIs run smoothly without prompting for confirmation on every command.

orch agents apply#

Add named agents to orch.yaml (only what you list)

orch agents apply [id...] [flags]

Add the named agent id(s) to orch.yaml. Never applies the whole PATH scan.

orch agents apply openclaude orch agents apply openclaude cursor

--yes is accepted for CLI consistency with init/setup (apply has no prompts).

orch agents scan#

Scan PATH and save results (does not change orch.yaml yet)

orch agents scan [flags]

orch agents show#

Print the last agents scan (scans PATH first if none exists yet)

orch agents show [flags]

orch agents-md#

Regenerate AGENTS.md from the live ledger/board

orch agents-md [flags]

orch agents-md refresh#

Regenerate the workshop root AGENTS.md

orch agents-md refresh [flags]

Rebuilds AGENTS.md's Tools section from the registered MCP tools and its Ledger/Board sections from .workflow/LEDGER.md and .workflow/BOARD.md.

Non-clobber like every other seed: an existing non-empty AGENTS.md is left alone unless --force.

orch ask#

Answer blocking questions raised by workers

orch ask [flags]

orch ask answer#

Answer an open ask; the blocked worker resumes immediately

orch ask answer <id> [text] [flags]

orch ask list#

List asks (default: the open ones) as id, seat, age, question

orch ask list [flags]

orch audit#

Independent audit of a worker branch: start a clone with a lease, record the result (accept/fix/reject)

orch audit [flags]

orch audit destructive#

List the destructive commands seats ran or were refused (masked of secrets)

orch audit destructive [flags]

orch audit done#

Finish an audit: release its load and store the verdict with its whole report

orch audit done <session> accept|reject|fix --file <report> [flags]

orch audit export#

List sessions sealed since a cutoff: guard verdicts, files-changed count, promote eligibility, usage

orch audit export [flags]

orch audit start#

Start an audit of a session: count its load, gate its brief, clone the branch into the sandbox

orch audit start <session> --brief <file> [flags]

orch brief#

Write worker brief skeletons

orch brief [flags]

orch brief new#

Write a brief skeleton with every section the brief lint requires (--out file, else stdout)

orch brief new <item> [flags]

orch budget#

Daily token budget (orch.yaml budget.*)

orch budget [flags]

orch budget status#

Used/cap per seat and workspace for today

orch budget status [flags]

orch bus#

Bus diagnostics

orch bus [flags]

orch bus selftest#

Time a health check + phrase exchange over the bus with no model in the loop; --live repeats it with real models

orch bus selftest [flags]

Exercises the bus mechanism (notify.CommitSend / bus.Wait / bus.AckMessage) with a constant phrase and no model in the loop, so a failure is the bus and not an LLM. Phase 1 is a health handoff every seat must see from every other seat; phase 2 has each seat send the phrase and return every phrase it collected. Each leg reports measured dispatch, delivery, ack and round-trip milliseconds. Runs push and poll (the daemon-off fallback) so the two are comparable; --live repeats the identical exchange through the seats' real models. A seat with nothing running is reported as not live, with what was tried. One evidence file per run lands under the data dir.

orch chair#

Configure orchestration guidance for your main (lead) agent session

orch chair [flags]

Optional rules for how the lead session should break work into tasks and coordinate workers. You can accept or reject each suggestion.

orch chair setup # interactive Y/n orch chair show orch chair install # write skill/guidance files agents can discover

orch chair brief#

Print the sections a new Chair seat receives, each with its size (read-only)

orch chair brief [flags]

orch chair install#

Write guidance files + MCP from chair.guidance flags

orch chair install [flags]

orch chair next#

List the preparation actions a Chair can take while work is in flight (read-only)

orch chair next [flags]

orch chair setup#

Suggest guidance flags (Y/n), save orch.yaml, reinstall project files

orch chair setup [flags]

orch chair show#

Show effective chair.guidance flags

orch chair show [flags]

orch cycle#

Learning cycle: detected errors until each is memorized as a lesson

orch cycle [flags]

orch cycle link#

Link a row to the ledger item or gate that improves it

orch cycle link <row> <item> [flags]

orch cycle list#

List the rows not yet memorized, each with the command that advances it

orch cycle list [flags]

orch cycle tick#

Advance the cycle once: landed items, proposals for unowned needs-gate lessons, repeated rows; prints a digest

orch cycle tick [flags]

orch dispatch#

Run one agent once without its interactive UI (automation)

orch dispatch [flags]

Runs an agent headlessly with a prompt (CI / scripts).

For the normal interactive agent UI, prefer: orch <name> (any coding-agent CLI on your PATH)

Refusals exit with their own code (any other error exits 1): 80 done-means 81 brief-lint 82 clarify 83 needs-gate 84 unknown-names 85 load 86 overlap 87 audit-rerun

orch doctor#

Report what is running, what is stale, and what is down — non-zero when something is broken

orch doctor [flags]

orch evidence#

Print a session's evidence bundle (verdict, files, commands, tests, usage)

orch evidence <session> [flags]

orch gateway#

Local LLM proxy: savings, providers, and agent connection helpers

orch gateway [flags]

The Orchemax gateway is a small local proxy (default http://127.0.0.1:8788). Agents talk to Orchemax; Orchemax talks to your providers. That enables token savings and failover across the URLs you configured.

Typical flow orch gateway setup --live --name … --url … --key-env MY_API_KEY orch gateway # start the proxy (same as: orch gateway run) orch gateway connect claude # print settings to paste into your agent orch gateway show # list providers (secrets hidden) orch gateway usage # calls / tokens / savings (no prompt text)

Power users can edit ai.providers and ai.passthrough in orch.yaml instead of setup.

Docs: https://docs.orchemax.com/how-to/gateway-keys-and-connect/

orch gateway autostart#

Manage gateway background autostart/service (alias for: orch gateway service)

orch gateway autostart [flags]

Installs, starts, stops, or inspects the Orchemax Gateway running as a background service (systemd user service on Linux, launchd on macOS, schtasks watchdog on Windows).

Commands: orch gateway service install [--start] # install native service orch gateway service start # start service in background orch gateway service stop # stop running service orch gateway service restart # restart service orch gateway service status # check health and PID orch gateway service uninstall # remove service registration

orch gateway autostart install#

Register gateway background service (systemd / launchd / schtasks)

orch gateway autostart install [flags]

orch gateway autostart restart#

Restart the gateway background service

orch gateway autostart restart [flags]

orch gateway autostart start#

Start the gateway background service

orch gateway autostart start [flags]

orch gateway autostart status#

Show gateway service state (registered, running, listening, PID)

orch gateway autostart status [flags]

orch gateway autostart stop#

Stop the gateway background service

orch gateway autostart stop [flags]

orch gateway autostart uninstall#

Remove gateway background service

orch gateway autostart uninstall [flags]

orch gateway connect#

Point any agent at this gateway (protocol: OpenAI-compat or Anthropic)

orch gateway connect [openai|anthropic|opencode] [flags]

Prints (or, for OpenCode only, writes) how to reach the local Orchemax gateway.

Protocols — not per-CLI special cases. Hundreds of agents share two wires:

orch gateway connect / connect openai # OpenAI-compat: Base URL + virtual key orch gateway connect anthropic # Anthropic Messages (/v1/messages) orch gateway connect opencode --allow-user-scope # optional: write OpenCode's own JSON orch gateway connect commandcode --allow-user-scope # optional: write ~/.commandcode/providers.json

Aliases (still print the same openai block): copilot, cursor, openclaude, … Alias for anthropic: claude.

Any OpenAI-compatible agent: set Base URL to http://127.0.0.1:8788/v1 and the printed orch_gk_… key; models come from GET /v1/models (real upstream ids).

Command Code: the cloud Command Code plan key ≠ Orchemax gateway. BYOK lives in ~/.commandcode/providers.json; pick an orch/… model in /model.

Start the gateway first: orch gateway

orch gateway enable#

Turn on gateway savings and auto-route for agent runs

orch gateway enable [flags]

Updates orch.yaml so agent runs can use the local gateway (token savings). Creates a workspace gateway key file if needed and prints the next step.

Stub mode costs $0. For real providers: orch gateway setup --live … orch gateway (or: orch gateway service start)

orch gateway guide#

Print telegraphic guide for LLMs and admins to configure Orchemax and Gateway

orch gateway guide [flags]

Prints the sealed markdown guide covering workspace setup, agent registration, gateway upstreams, keys vault, and user-level background services. Agents and LLMs can consult this guide to configure Orchemax end-to-end.

orch gateway health#

Ask each worker's model to answer, and report which ones are alive

orch gateway health [flags]

One minimal completion per seat in agents.workers, through the gateway — the same path a dispatched worker takes, so it proves key, route, model id and upstream in one call. gateway status only reports the circuit breaker: "nothing has failed yet" is not "it answered".

Exit 1 when any target is dead, so a script can gate a dispatch on it. A dead target is a real failure for the router too, so it enters cooldown: the next run reports those routes as cooling until the wait passes.

orch gateway key#

Manage virtual keys agents use to call the local gateway

orch gateway key [flags]

orch gateway key check#

Probe the running gateway with the key an agent actually sends

orch gateway key check [flags]

Reads the configured key source and asks the gateway that is really listening whether it accepts it (GET /v1/models).

orch gateway key check # .orch/gateway.agent.key vs gateway.addr orch gateway key check --opencode # the key and baseURL in your opencode.json

A key can be live in this workspace's orch.db and still be rejected: the gateway on that port may have been started from another workspace.

orch gateway key issue#

Create a gateway key (secret is printed once — save it)

orch gateway key issue [flags]

orch gateway key list#

List gateway keys (secrets are never shown again)

orch gateway key list [flags]

orch gateway key revoke#

Revoke a gateway key by id

orch gateway key revoke <id> [flags]

orch gateway key workers#

List the live per-worker keys (id, session, role, expiry — never the secret)

orch gateway key workers [flags]

Every dispatched worker gets its own gateway key (orch_wk_…), bound to its session, expiring with its dispatch and revoked at sealing. The workspace key (orch_gk_…) never enters a worker's environment.

This prints the keys that still authenticate right now. The secret itself was printed once, into the worker's environment, and only its hash is stored.

orch gateway keys#

Manage upstream provider API keys (a rotation ring per provider)

orch gateway keys [flags]

Keys live in the same vault as everything else (machine-home keys.env), one env var per provider — several keys, comma-separated, is a rotation ring the gateway already knows how to fail over into on 429s (see: orch gateway status).

Never prints a full key: add/list/remove only ever show a hint ("sk-…abcd").

orch gateway keys add#

Add a key to a provider's rotation ring (probes connectivity first)

orch gateway keys add <provider> [key] [flags]

orch gateway keys list#

List configured keys per provider (hints and tier only)

orch gateway keys list [provider] [flags]

orch gateway keys remove#

Remove a key from a provider's ring by hint

orch gateway keys remove <provider> <hint> [flags]

orch gateway presets#

List known LLM upstream URLs (for setup / agents)

orch gateway presets [flags]

Prints the built-in catalog of OpenAI-compat / Anthropic endpoints Orchemax knows. Agents should use this when the user asks to add another LLM provider. Secrets never go in chat — user fills keys.env or Windows User env.

orch gateway prices#

Model rates fetched from a provider's catalogue, with their source

orch gateway prices [flags]

A price belongs to the provider that charges it. Orchemax asks the provider's catalogue, caches each rate with the URL it came from and the time it was read, and prices spend against that. It ships no rate table of its own: a model with no fetched rate is refused by the USD ceiling rather than metered at $0 or at a number somebody remembered.

orch gateway prices refresh#

Ask each configured provider for its rates and cache them

orch gateway prices refresh [flags]

Reads every enabled provider in orch.yaml that has a prices_url (or a base_url to derive <base>/models from) and caches the rates it answers with. --endpoint asks one URL instead. Orchemax names no provider: the catalogue is the owner's, like the key.

orch gateway prices status#

How many rates are cached and how old they are

orch gateway prices status [flags]

orch gateway restart#

Restart the gateway background service (same as: orch gateway service restart)

orch gateway restart [flags]

orch gateway run#

Start the local LLM proxy (same as: orch gateway)

orch gateway run [flags]

orch gateway service#

Manage the local LLM router background service (Windows, Linux, macOS)

orch gateway service [flags]

Installs, starts, stops, or inspects the Orchemax Gateway running as a background service (systemd user service on Linux, launchd on macOS, schtasks watchdog on Windows).

Commands: orch gateway service install [--start] # install native service orch gateway service start # start service in background orch gateway service stop # stop running service orch gateway service restart # restart service orch gateway service status # check health and PID orch gateway service uninstall # remove service registration

orch gateway service install#

Register gateway background service (systemd / launchd / schtasks)

orch gateway service install [flags]

orch gateway service restart#

Restart the gateway background service

orch gateway service restart [flags]

orch gateway service start#

Start the gateway background service

orch gateway service start [flags]

orch gateway service status#

Show gateway service state (registered, running, listening, PID)

orch gateway service status [flags]

orch gateway service stop#

Stop the gateway background service

orch gateway service stop [flags]

orch gateway service uninstall#

Remove gateway background service

orch gateway service uninstall [flags]

orch gateway setup#

Add an LLM provider to the user-wide catalog (ai.yaml)

orch gateway setup [flags]

Writes one LLM provider into your user config (machine-home ai.yaml), shared by every workspace. Secrets stay in OS User environment variables.

Example set OPENROUTER_API_KEY=… # Windows: User environment variable orch gateway setup --live
--name openrouter
--url https://openrouter.ai/api/v1
--model qwen/qwen3-32b
--key-env OPENROUTER_API_KEY
--tier cheap
--priority 10

Prefer --key-env over --api-key so secrets never sit in yaml. Then start the proxy: orch gateway

File: %LOCALAPPDATA%\Orchemax\ai.yaml (override with ORCH_HOME)

A workspace orch.yaml may still list ai.providers to override this user catalog. Claude / Anthropic Messages: ai.passthrough.anthropic in the same user file (or workspace override).

orch gateway show#

List providers from orch.yaml (API keys hidden)

orch gateway show [flags]

orch gateway start#

Start the gateway background service (same as: orch gateway service start)

orch gateway start [flags]

orch gateway status#

Per-provider live/cooldown state, key-ring position, rotation and cooldown counts

orch gateway status [flags]

Reads /v1/providers/stats from the running gateway (orch gateway). Counters are in-memory and reset when the gateway restarts — this is "since start", not a historical ledger (see: orch gateway usage for that). Never shows keys.

orch gateway stop#

Stop the gateway background service (same as: orch gateway service stop)

orch gateway stop [flags]

orch gateway usage#

Show gateway call stats and token savings (never stores prompts)

orch gateway usage [flags]

orch guard#

Local guardrail checks

orch guard [flags]

orch guard add-all#

Deny blanket git add (-A/.) when cwd is a shared repo

orch guard add-all [git-command] [flags]

Field lesson: on shared layers, git add -A steals other sessions' WIP. Pass the shell command (default reads first arg). Soft-skip when cwd is not under a registered shared path.

orch guard allow#

Deny an orch:allow override marker that silences nothing (unwaivable gate, or no reason)

orch guard allow [files...] [flags]

An inline orch:allow <gate> — <reason> waives one finding on the line it sits on, or alone on the line directly above it. Matched as a substring, so any comment syntax carries it. This check reports the markers that silence nothing: a gate name no marker can waive, or a reason shorter than a cause. Waivable gates: comment-prose, litter, minimal-code, secrets, signature. Honoured overrides are recorded as verdict override and counted by orch stats.

orch guard artifacts#

Deny disposable build junk (.o, .pyc, .exe, …) beside source

orch guard artifacts [files...|dir] [flags]

Field lesson: compiler outputs next to shared source poison multi-agent floors. Flags staged paths or walks a directory (skips tests/, out/, build/, .git). Extensions: .o .obj .pyc .class .exe .map .dll/.so … plus IDE junk and numbered backups (file.ext.1).

orch guard banned-stack#

Deny an import or manifest dependency the owner declared banned

orch guard banned-stack [files...] [flags]

DEV_PRACTICES.md:65-66 — "declare your stack (anti LLM fashion)". Declare each banned name once under workspace.banned_stacks in orch.yaml (name + reason); an empty list means this gate says nothing.

Checks both surfaces: an import in source (same per-language resolution as orch guard cross-project) and a manifest entry (package.json, requirements.txt, pyproject.toml, Gemfile, *.csproj, Cargo.toml, go.mod).

With no args, checks staged files.

orch guard code-lang#

Check code identifiers/strings against workspace.code_lang

orch guard code-lang [root] [flags]

Uses workspace.code_lang from orch.yaml (owner decision for shipping code) — any supported ISO 639-1 code (en es pt fr de it), also "xx-YY": — identifiers + user-visible strings in that language; comments may be any language unset — skip other — no checker yet

English is never flagged inside identifiers (library APIs and language keywords are English by convention) unless guard.code_lang_strict: true. UI copy belongs in i18n dictionaries (paths like i18n/, es.json are exempt). Field lesson: chatting with the LLM in your own language must not leak into identifiers or raises.

--count walks the tree and prints hits per detected language without denying (exit 0 always) — run it before switching guard.profile to strict on an existing codebase.

orch guard comment#

Deny if exported shared symbols lack a one-line purpose comment

orch guard comment <shared-file> [flags]

orch guard comment-prose#

Note long/narrative comment blocks (advisory, never denies)

orch guard comment-prose [path] [flags]

Flags, per code file: comment blocks of 6+ consecutive lines outside the file header, package/module doc, license blocks and generated files; and any comment block with a narrative marker (ISO date, "before the fix", "used to", "we saw", "the founder", "historically"). Advisory in every guard.profile — exit code is always 0.

--count prints one summary row instead of every hit.

orch guard conflict-markers#

Deny git merge-conflict markers left in a file

orch guard conflict-markers [files...] [flags]

orch guard control-bytes#

Deny invisible control bytes in source (except tab/LF/CR)

orch guard control-bytes [files...] [flags]

orch guard cross-project#

Deny a file inside one registered project importing another registered project

orch guard cross-project [files...] [flags]

DEV_PRACTICES.md:30 — "products compose shared code; they do not import product-to-product." Needs 2+ entries in cfg.Projects; fewer means there is no second owner to hit and this is a no-op. Resolves imports per the file's own language (internal/langspec): Go, TypeScript/JavaScript (relative and aliased), Python, C# and Ruby. An import that resolves to the shared root instead of a registered project always passes.

With no args, checks staged files.

orch guard ddl#

Require seeder/repository companion for migration/CREATE TABLE changes

orch guard ddl [files...] [flags]

Defaults are Go globs plus workspace.primary_languages' own conventions; override with guard.ddl.{seeder,repository,migration}_globs in orch.yaml.

orch guard docs#

Deny an unreferenced new doc, or a header count that does not match the file

orch guard docs [root] [flags]

Genesis origin: gate-docs.mjs R1/R3, generalized (no TRACKER/DECISIONES naming). R1 a .md under any docs/ folder that no sibling doc, README.md, AGENTS.md or CLAUDE.md references by name. R3 "N items/lines/tables" claimed in the first 20 lines vs the real count in the same file. Only files <= 200 KB. Advisory in profile lite, blocking in strict/shared.

--count walks the tree and prints hits without denying (exit 0 always).

orch guard dup#

Deny if file duplicates a shared symbol; report copied function bodies (clones)

orch guard dup <file> [flags]

orch guard encoding#

Deny missing UTF-8 charset / mojibake in HTML, email, and source a compiler reads in a legacy code page

orch guard encoding [files...] [flags]

LLMs often forget charset when writing HTML or emails (especially non-English copy). Checks: meta charset=utf-8 or Content-Type charset=utf-8; classic mojibake patterns (café). Also: a source file in a language whose seed sets bom_required (Delphi today) holding any byte above ASCII and no UTF-8 byte-order mark — the compiler reads the file in the machine's legacy code page and every such character ships as two, in every script. Stack-specific DB/string APIs belong in that layer's SHARED.md — not this gate.

orch guard env-drift#

Deny keys lost or emptied between an .env example and its instance

orch guard env-drift [root] [flags]

Genesis origin: check-env-key-loss.py + the emptied-secret case of check-env-value-drift.py, scoped to what needs no server access: compares .env.example/.env.template/.env.sample against .env/.env.local in the same folder. Reports KEY NAMES ONLY — never a value — for a key missing in the instance, or present but emptied where the example has a non-empty placeholder.

--count reports hits without denying (exit 0 always).

orch guard explain#

Say what every rule would answer about one file, and whether a commit carrying it would be denied

orch guard explain <file> [repo] [flags]

orch guard gofmt#

Deny a Go file whose content is not what gofmt would write

orch guard gofmt [files...] [flags]

orch guard hooks#

Install git pre-commit/pre-push hooks that run orch guard

orch guard hooks [flags]

orch guard hooks install#

Write .git/hooks/pre-commit + pre-push (orch-marked)

orch guard hooks install [repo] [flags]

orch guard hooks run#

Run pre-commit checks on staged files (used by git hooks)

orch guard hooks run [repo] [flags]

orch guard hooks status#

Show whether orch git hooks are installed

orch guard hooks status [repo] [flags]

orch guard hooks uninstall#

Remove orch-marked pre-commit/pre-push hooks only

orch guard hooks uninstall [repo] [flags]

orch guard ide-hook#

Internal: Claude/Cursor wire entry (soft-skip outside workshop)

orch guard ide-hook [flags]

orch guard json-dup#

Deny a key declared twice inside one JSON object

orch guard json-dup [files...] [flags]

Every decoder keeps the last of a repeated key and drops the rest in silence, so the file says one thing and the program reads another. Decoding into a map cannot answer this: the duplicate is gone by the time the map exists.

Found on this repo's own dictionaries: one key was a string at one line and an object at another, the object won, and the template asking for the string had been falling back to its default. The test comparing the two locales could not see it, because it compared maps that had already collapsed.

Language-agnostic, and a duplicate key has one possible verdict, so it denies.

orch guard lang#

Check workshop docs against workspace.docs_lang

orch guard lang [root] [flags]

Uses workspace.locale from orch.yaml (owner decision for docs/prose) — any supported ISO 639-1 code (en es pt fr de it), also "xx-YY": — deny prose in any other supported language (own language allowed) unset — skip other — no marker set yet

This is separate from workspace.code_lang (see orch guard code-lang). Chat/docs may be in one language while code stays in another.

--count walks the tree and prints hits per detected language without denying (exit 0 always) — run it before switching guard.profile to strict on an existing codebase.

orch guard litter#

Deny new agent-scratch files/dot-directories outside .sandbox// or docs

orch guard litter [files...] [flags]

New paths only — editing an existing file is never litter. Denies:

• any new dot-directory an agent creates (.notes/, .scratch/, .claude/state/, …); only .sandbox/, .orch/, .git/, .cursor/rules/, .github/, .claude/settings.local.json (and the legacy .claude/settings.json), .gitignore, .gitattributes, .editorconfig, .mcp.json are wired by orch itself.
• a new .md/.txt/.log/.rtf/.out/.csv/.html (outside web/assets) or a notes/report/summary/plan/todo/scratch/analysis/findings/research-named file.
• a new test/fixture (_test.go, .test., .spec., or under tests/ test/ tests/ spec/ fixtures/ testdata/) with no source file it belongs to in the same change set — exploratory tests belong in .sandbox//tests/.
• any test/fixture under a configured shared layer — shared trees stay library code only; agent tests go under the project's .sandbox//.

Falls back to git's changed files with no args. --count reports hits without denying (exit 0 always).

orch guard lock#

Deny if shared/** path has no valid lock for --holder

orch guard lock <path> [flags]

orch guard machine-path#

Deny one machine's absolute home path (Users/, /home/) in a versioned file

orch guard machine-path [files...] [flags]

orch guard minimal-code#

Report a single-implementation interface, an unread field or a single-use wrapper (advisory)

orch guard minimal-code [files...] [flags]

Principle 2. Minimum code for what was asked — check: nothing speculative, no single-use abstraction.

Narrowed to three shapes a check can see, each named in its own message: single-implementation interface an interface this change declares that one type in the same change implements field nothing reads a struct field or config key no .go file in the repo mentions again single-use wrapper a function whose body is one call forwarding its own arguments, with one caller

Advisory, exit 0 always. Go only: readers are counted by identifier occurrence across the repo's .go files, so a name used in a comment or a string counts as read — the check under-reports rather than accuse.

orch guard principles#

Show which elemental principles orch enforces and which are guidance

orch guard principles [flags]

orch guard profile#

Show or set guard.profile in orch.yaml

orch guard profile [lite|shared|strict|bring|none] [flags]

orch guard race-test#

Report concurrency added to a package whose tests only run sequentially (advisory)

orch guard race-test [files...] [flags]

A change that adds a goroutine launch, a channel or a sync/atomic reach to a package, where no test in that package runs two things at once — no goroutine of its own, no WaitGroup, no t.Parallel.

The defect it exists for is recent and real: an ask launched its escalation with nothing waiting on it, and the write that escalation performed landed after the call had returned. No sequential test could see that, and none did for a round.

Advisory, exit 0 always. Plenty of concurrent code is exercised from another package and a check reading one package cannot see that. Go only.

orch guard reproduce#

Deny a change whose own new tests pass against the pre-change source

orch guard reproduce [repo] [flags]

Principle 5. Reproduce before you fix — check: a failing test or repro exists before the patch.

Every Test* the change adds or modifies runs with the change's non-test .go files reverted to the git base, through go test -overlay: a test that passes there did not reproduce the bug, so it does not prove the fix.

Nothing is written into the checkout, and the scope is the change's own tests (mutate.DefaultReproMax at most, each run bounded). Skips with a named reason when the checkout has no base commit, when the change adds no test, and when a test does not compile against the base.

orch guard rules#

List and validate the workshop's own gates (.orch/gates/user/manifest.json)

orch guard rules [flags]

orch guard rules run#

Dry-run the user gates over an explicit file list

orch guard rules run --files a,b [flags]

orch guard schema-bump#

Deny a column added to a table definition with no schema version bump

orch guard schema-bump [repo] [flags]

An additive schema change only reaches a database that already exists when the version it compares itself against moves. Columns were added here with the constant left alone: every existing database stayed without them and a command died with no such column, while a fresh database passed every test.

orch guard scope-growth#

Report a change set that outgrew its ledger item with no ask raised (advisory)

orch guard scope-growth [repo] [flags]

Principle 8. Stop and ask when blocked or scope grows — check: blocker named, no guessing past it.

Measured instead of asserted. The clarify gate already covers delegation; this is the other half: the open .workflow/LEDGER*.md item naming the most files this change touches declares N files, the change touches 2N or more, and the session has no row in agent_asks.

Advisory, exit 0 always. Silent when one ask exists, when no open item names any changed file, and when the item declares folders only (a folder is not a count).

orch guard secrets#

Deny a credential (provider key, PEM block, high-entropy assignment) in source

orch guard secrets [files...] [flags]

Provider key shapes (AWS, GitHub, OpenAI/Anthropic, Google, Slack, Orchemax's own), a PEM private-key header, or an assignment to a credential-looking name (token/secret/password/api_key/private_key) whose value is long and high-entropy. Never prints the matched text — only the file, the line and which pattern fired. Skips .env.example/.env.template outright.

orch guard shared-brand#

Deny registered project id / path references inside shared layers

orch guard shared-brand [files...] [flags]

orch guard shared-root#

Deny loose source files at shared-layer roots (must live in a subfolder)

orch guard shared-root [dir...] [flags]

Agents often drop new modules at a shared-layer root instead of the right package folder. With no args, scans every shared root from orch.yaml. With args, each path is a shared-layer root to check (non-recursive: only direct children).

Allowed at the root: docs/meta (.md, .gitignore, .gitattributes, …). Denied: source extensions for any language (.go .ts .js .py .rs .cs …).

orch guard shared-shadow#

Deny a project file whose path mirrors one already under a shared root

orch guard shared-shadow [files...] [flags]

Genesis origin: check-shared-not-shadowed.mjs. A product with its own copy of a file that a shared layer already provides silently wins over the shared version wherever local beats shared — the shared code is never exercised, and the gap surfaces months later in a different product. Uses the shared roots already registered in orch.yaml.

--count reports hits without denying (exit 0 always).

orch guard shell-check#

Internal: pi-extension sibling of ide-hook; reads a shell command on stdin

orch guard shell-check [flags]

orch guard signature#

Deny non-constant-time comparisons on a signature/HMAC/token

orch guard signature [files...] [flags]

Denies ==, !=, ===, strcmp(, .equals( on an operand whose identifier looks like hmac/signature/sig/token/digest/mac — those exit at the first differing byte, so response time leaks how much of the expected value the caller already guessed. Suggests the constant-time helper for the file's language (Go subtle.ConstantTimeCompare, Node crypto.timingSafeEqual, Python hmac.compare_digest, PHP hash_equals, and equivalents elsewhere). Already-safe lines (ConstantTime*, EqualHashString, timingSafeEqual, …) are skipped.

--count reports hits without denying (exit 0 always).

orch guard template-drift#

Deny a key-set mismatch between a .template.json/.example.json and its instance

orch guard template-drift [template-files...] [flags]

Genesis origin: check-config-template-drift.py. A deployment does not overwrite the live config.json on purpose (it holds machine-only state), so a key the template just added never arrives on its own — the feature it gates goes disabled without an error. Compares key PATHS only; values are never read. config.template.json / config.example.json diff against config.json next to it.

--count reports hits without denying (exit 0 always).

orch guard test-dup#

Report a test whose body repeats another test's, literals included (advisory)

orch guard test-dup [files...] [flags]

A Test function whose body, as gofmt renders it with comments dropped, is another test's body. Two tests asserting the same thing with the same literals are one test under two names, and the second name is a claim the suite does not keep.

The criterion is the whole body, not "covers the same symbol": measured over 2040 test functions, shared symbols gave 774 notes and identifier-blind shapes gave 33 — nearly all legitimate parameterized siblings, a Python case beside a Ruby one. Identical literals gave one, and it was a test whose name promised something its copied body never asserted.

Advisory, exit 0 always: a deliberate regression pin is a real reason to keep a twin, and no check can tell that from an accident. Go only.

orch guard test-residue#

Deny paths a test run creates under a source root, gitignored included

orch guard test-residue <snapshot-file> [repo] [flags]

Two calls around the suite: orch guard test-residue .sandbox/tree.snap --save go test ./... orch guard test-residue .sandbox/tree.snap

The snapshot is git status --porcelain --ignored, the only listing that shows gitignored litter: a suite that seeds .orch/ in its own package is invisible to plain git status, which is how it survived. Any path the second call finds under a source root that the first did not have is denied. Source roots default to internal, cmd, src, app, lib and pkg; a registered project's own roles replace that default when they resolve. The snapshot also carries a sha256 per live agent config (.claude/, .openclaude/ and .cursor/ hook files) at the root and in every registered project: those are gitignored, so a run that EDITED one is invisible to a path diff — and a hook command a test left behind blocks the next session.

orch guard tracker#

Validate TRACKER state table (T1–T5: status · SPEC · evidence · no prose · row shape)

orch guard tracker [TRACKER.md|dir] [flags]

Agnostic checks inspired by workshop field experience: T1 — only SPEC|TODO|WIP|DONE|VERIFIED|BLOCKED|DROPPED T2 — SPEC rows must point at an existing .md T3 — VERIFIED rows need real evidence (not empty/ok/done) T4 — table present ⇒ no narrative dump (>12 consecutive prose lines)

Prose-only trackers without a status table soft-skip (exit 0). When PATH is a directory, walks **/TRACKER.md (bounded).

orch guard unproven-gate#

Deny new gate source added with no test touched in the same change set

orch guard unproven-gate [files...] [flags]

The mirror of the litter rule: a new test with no source change is litter, and new gate source with no test is a gate nobody has watched fail.

The shape is measured. Over the 49 commits that added gate source to internal/guardrails, exactly one touched no test, and that one shipped a filter hiding six gates from a whole directory with two surviving mutants. Two stricter shapes were tried against the same history and rejected: "a test file of the same name" flags 8 of 66 sources, and "a test naming one of its symbols" flags 5 of 9, because an unexported symbol cannot be named from an external test package.

A MODIFIED test counts. Only ADDED source counts: editing a gate that already has tests is ordinary work.

orch guard unwire#

Remove what Orchemax wrote to disk: IDE hook entries, .mcp.json Orchemax servers, git hooks — workshop and every registered project

orch guard unwire [flags]

orch guard upsert#

Deny ON CONFLICT/ON DUPLICATE KEY/MERGE upserts with no matching UNIQUE/PK

orch guard upsert [files...] [flags]

Genesis origin: check-upsert-has-unique.py. PostgreSQL refuses an ON CONFLICT without a matching constraint (loud); MSSQL/MySQL silently duplicate the row instead (quiet, permanent). Reads UNIQUE/PRIMARY KEY declarations from CREATE TABLE / CREATE UNIQUE INDEX / ALTER TABLE ADD CONSTRAINT across the given files, then checks every ON CONFLICT(cols)/ON DUPLICATE KEY UPDATE/MERGE ON(...) in them. A table never seen declared here is skipped (doubtful, not a fail).

--count reports hits without denying (exit 0 always).

orch guard weakened#

Report a test that survived a change and now verifies less (advisory)

orch guard weakened [files...] [flags]

A Test function still present in the change whose body gained a Skip, or whose assertion count fell, read against the file's copy at HEAD.

Principle 7 — never make a check pass by weakening it — had no gate, and prose does not stop a model that has already convinced itself. A suite stays green precisely because the check stopped looking, which is why this is the shape a green run hides.

Narrow on purpose: a deleted test is visible in the diff and is somebody's decision, a new test is not a weakening, and a rewrite with the same count is refactoring. Assertions inside same-file helpers count, so moving one into a helper is not a loss.

Advisory, exit 0 always. Go only.

orch guard wire#

Install marked git/Claude/OpenClaude/Cursor/Copilot/agy adapters for this workshop

orch guard wire [flags]

orch home#

Show where account files live vs this workshop's .orch folder

orch home [flags]

orch index#

Index the workshop (every registered project and shared path) into the symbol registry

orch index [flags]

orch index shared#

Alias for orch index — it never covered only paths.shared

orch index shared [flags]

orch init#

Start a workshop: bind this folder if needed, then lay out projects, shared, AI doctrine, git

orch init [flags]

Run in the folder you want as your workshop. If it is not bound yet, init binds it first (bind + layout in one step), then offers the layout. With --dry-run it only reports it would bind.

Asks docs locale, shared folders, project/apps, optional git identities, and whether to install orch guard hooks. Seeds English thin CLAUDE.md + DEV_PRACTICES.md + GATES.md + doctrine/README.md + per-project docs/TRACKER, installs sealed orch-* skills, git-inits each project/shared (never the workshop root), and wires includeIf identities when profiles are given.

Layout hint: doctrine/ = cross-project law (you fill); workshop-root docs/ = optional workshop notes; each project's docs/ = that project's TRACKER/PRODUCT.

Existing workshop: decline the recommended layout and enter your real shared/product paths. To replace doctrine after a wipe, delete old CLAUDE.md / AGENTS.md / gates docs (or pass --force).

orch init orch init --recommend # suggest shared// + projects// orch init --dry-run orch init --force # overwrite non-empty seeded docs orch init --yes # accept defaults for every prompt — no stdin required orch init --refresh-seeds # update only DEV_PRACTICES.md's principles section # + every project's AGENTS.md pointer; nothing else touched

--yes skips the interactive wizard entirely and applies defaults (docs locale/code_lang/comment_lang en, address informal, no shared/projects, no git identities, guard.profile unset → lite). Combine with --recommend to seed the recommended shared// + projects// layout instead of an empty one, still with no prompts.

Docs: https://docs.orchemax.com/how-to/organise-a-workshop/

orch install#

Copy this Orchemax binary to its per-OS folder and add it to your user PATH

orch install [flags]

Windows: %LOCALAPPDATA%\Programs\orch\orch.exe, folder added to the user PATH (no admin). macOS/Linux: ~/.local/bin/orch (mode 0755), one export PATH line added to your shell profile when missing. Running it again changes nothing and says "already installed". orch uninstall --scope user removes it.

orch land#

Land audited branches as one merge train: merge, regenerate, verify, fast-forward main and the checkout

orch land <session|branch>... [--push <remote:branch>] [--install] [flags]

Lands audited session branches as one merge train. Each branch needs an accept verdict on its current head (orch verdict). The train starts from main, merges every branch and then the checkout branch, runs land.regenerate and commits what they changed, runs land.verify, then fast-forwards main and the checkout and checks that main, the checkout and the train tip are the same commit. Refuses a checkout that is bare or has uncommitted changes.

--push remote:branch pushes the landed tip. --install runs land.build, copies land.install into the install directory keeping one rollback copy, prunes older copies, and restarts the gateway only when no worker runs.

With --push and land.ci_workflow set, Orchemax first reads the latest remote CI run of the push branch (needs gh on PATH): a failed run refuses the landing unless --ci-override ""; a running one is waited for up to land.ci_wait_sec (default 600).

Config: land.regenerate and land.verify (command lists), land.build (command), land.install (path of the built binary, relative to the checkout), land.ci_workflow, land.ci_wait_sec.

orch learn#

The lesson playbook: add, list, reject, restore (delta-updated, never rewritten)

orch learn [flags]

orch learn add#

Add a lesson (an active rule_key bumps helpful instead)

orch learn add --rule-key <key> --title <title> --evidence <commit/audit/session id> [body...] [flags]

orch learn curate#

Propose merging near-duplicate lessons (dry run; --apply snapshots then supersedes)

orch learn curate [flags]

orch learn list#

Print the playbook: id, scope, helpful/harmful, status, title, evidence

orch learn list [--all] [flags]

orch learn mechanism#

Mark a lesson as enforced by a built mechanism, with the gate and the test that prove it

orch learn mechanism <id|rule_key> --gate <file:line> --test <TestName> [--item <id>] [--commit <ref>] [flags]

orch learn propose#

Propose lessons from repeated guard denies (proposed, never active)

orch learn propose [flags]

orch learn recur#

Record that a failure matched an existing lesson (never creates one)

orch learn recur <id|rule_key> --evidence <session id / what happened> [flags]

orch learn reject#

Retire a lesson with reason "rejected by user"

orch learn reject <id> [flags]

orch learn restore#

Re-activate a retired lesson

orch learn restore <id> [flags]

orch load#

Mark a heavy load (a test run) that runs outside dispatch

orch load [flags]

orch load hold#

Count a heavy load until its lease expires (--for), or until a process exits (--pid), or orch load release

orch load hold <reason> [flags]

orch load release#

Drop a heavy-load hold: a lease (--lease) or a process's; with no flag, the default leases and the parent's hold

orch load release [flags]

orch locale#

Show or set the workshop language knobs

orch locale [flags]

The language knobs in orch.yaml under workspace: locale the language Orchemax and the agents address you in docs_lang what files on disk are written in (default: locale, else en) code_lang what code identifiers and config/rule strings are written in comment_lang what code comments are written in (default: code_lang) address informal | formal | vos

orch locale show # effective value and where it came from orch locale set <knob> <value> # write one key (orch.yaml is backed up first)

orch locale set#

Write one workspace language key into orch.yaml

orch locale set <knob> <value> [flags]

orch locale show#

Print the effective language knobs and their source

orch locale show [flags]

orch map#

What a file or symbol is for, and who calls it

orch map [path|symbol] [flags]

Prints the purpose of a file (its header comment or a docs/PURPOSES.tsv row), its package and its callers; for a symbol, its orch:export purpose, file and callers. With no argument it lists every file with its purpose. Reads the index built by orch index.

orch mcp#

Start the orch tools server for agents (stdio)

orch mcp [flags]

orch memory#

Save and recall durable notes for agents (local)

orch memory [flags]

orch memory condense#

Shrink oversized workshop memory files through the gateway (never automatic)

orch memory condense [flags]

Condenses .workflow/BOARD.md and .orch/LAST_SESSION.md when they pass the size threshold. ## Clarified and ## Ownership sections and every open checkbox item are preserved byte-for-byte — only narration and finished notes are summarized. The original is kept beside the file. Requires a running gateway (orch gateway) with a working upstream.

orch memory conflicts#

List active memories with same type+title but different body

orch memory conflicts [flags]

orch memory export#

Export estate as OKF-lite markdown (v0.2-compatible)

orch memory export [dir] [flags]

orch memory forget#

Expire a memory (soft)

orch memory forget <id> [flags]

orch memory import#

Import OKF-lite markdown into the estate

orch memory import [dir] [flags]

orch memory list#

List recent active memories

orch memory list [flags]

orch memory recall#

Search saved memories

orch memory recall [query...] [flags]

orch memory remember#

Store a typed memory

orch memory remember [text...] [flags]

orch memory supersede#

Mark old memory superseded by new id, recording why

orch memory supersede <old-id> <new-id> <reason...> [flags]

orch memory sweep#

Expire memories past retention_days

orch memory sweep [flags]

orch msg#

Send messages between agent sessions

orch msg [flags]

orch msg ack#

Ack message as recipient (session and/or agent must match)

orch msg ack <id> [flags]

orch msg age#

Backdate message created_at (dogfood / tests)

orch msg age <id> [flags]

orch msg gc#

Purge old bus history (acked/unread/log/notices) per bus.* retention

orch msg gc [flags]

orch msg handoff#

Write brief under data/handoffs and send kind=handoff

orch msg handoff [flags]

orch msg inbox#

List messages for session and/or agent

orch msg inbox [flags]

orch msg log#

Show bus activity log (.orch/bus.log)

orch msg log [flags]

orch msg peers#

List other sessions (optional: family view with --session)

orch msg peers [flags]

orch msg read#

Mark message read (legacy; prefer ack)

orch msg read <id> [flags]

orch msg roster#

Show parent/child/sibling sessions for a session

orch msg roster [flags]

orch msg send#

Send a note, handoff, or alert to another session or agent

orch msg send [flags]

Send a note, handoff, or alert to another session or agent.

--to-project takes a project id of this workshop, or a project in another trusted Orchemax workshop as <workshop>/<project>: the id exactly as orch project list prints it there, <workshop>/<project-id>, or <workshop>/<short-name>. Cross-workshop mail is marked with its origin workshop; the receiver replies by passing that origin back to --to-project.

Example:

  orch msg send --to-project beta/invoicing --body "invoice API changed"

orch msg stale#

List unread alerts older than --older-min

orch msg stale [flags]

orch msg wait#

Block until a message newer than --after arrives for the session, print it, exit 0 (prints timeout otherwise)

orch msg wait [flags]

orch nightly#

Land every accepted session in one train and leave a morning report

orch nightly [flags]

orch nightly run#

Land every accepted, unlanded session of the project (orch land <ids> --install) and write nightly/.md

orch nightly run [--dry-run] [flags]

Collects the sessions of the project with an accept verdict that are not landed, in acceptance order, and runs the same land as orch land <ids> --install. The report (landed, refused with the land's reason, duration, installed build) is written under the data dir; the Chair start brief carries its summary until orch nightly status is read. --dry-run prints the land command and writes nothing.

orch nightly status#

Print the latest nightly report and mark it read

orch nightly status [flags]

orch notify#

Outbound webhooks and Telegram notifications on sealing/promote events

orch notify [flags]

notify.webhooks and notify.telegram in orch.yaml deliver sealed/failed/promoted/ needs_approval/needs_answer events — status and summary only, never diffs or file contents. needs_answer also carries the worker's question, so the human who reads it can answer with /answer or orch ask answer.

orch notify events#

Print the versioned outbound event catalog (n8n/Zapier contract)

orch notify events [flags]

orch notify telegram#

Telegram long-polling bot (notifications + /status /approve /reject /answer)

orch notify telegram [flags]

orch notify telegram pair#

Link this workspace to your Telegram chat (prints a link, waits for /start)

orch notify telegram pair [flags]

Prints the bot's t.me link, waits for you to send /start, then adds that chat to notify.telegram.chat_allowlist in orch.yaml and sends one test event. Requires notify.telegram.bot_token_env to already name an env var holding the BotFather token.

orch notify telegram run#

Run the Telegram long-poll worker standalone (foreground)

orch notify telegram run [flags]

orch notify test#

Send a synthetic event to every configured webhook, Telegram chat and the desktop

orch notify test [flags]

orch pack#

Install/update/remove team gates, rules and skills from a pack

orch pack [flags]

orch pack install#

Install a pack's gates/rules/skills into this workspace

orch pack install <path|git-url> [flags]

is a local directory holding MANIFEST.yaml at its root. A git URL is cloned fresh with "git clone --depth 1" (add --ref for a branch/tag).

Orchemax ships no pack of its own — every language gets the same starting point; bring your own pack, local or from a git remote.

orch pack list#

List installed packs

orch pack list [flags]

orch pack remove#

Uninstall a pack, keeping any file the workshop edited

orch pack remove <name> [flags]

orch pack update#

Refresh an installed pack's unmodified files from its recorded source

orch pack update <name> [flags]

orch policy#

Effective guard/review/budget/notify policy from orch.yaml

orch policy [flags]

orch policy diff#

Diff the effective policy sections against a git ref (git diff --no-index)

orch policy diff <git-ref> [flags]

orch policy show#

Print the policy sections orch.yaml actually has

orch policy show [flags]

orch presence#

System tray presence (opens orch ui; not a TUI)

orch presence [flags]

Orchemax presence is a small system-tray helper for the local workshop.

It is not a TUI and never shows Team commerce (billing, members, overlook). Left-click opens orch ui (the workshop). The menu shows plan / link / gateway / workers / HITL at a glance, can restart the gateway service, and quits only the tray helper — the gateway keeps running.

orch presence run # tray in background (terminal returns) orch presence run --foreground # keep this terminal attached (Ctrl+C quits) orch presence install # start at user login orch presence uninstall orch presence status

Use orch ui directly when you want the full board without the tray.

orch presence install#

Register presence to start at user login

orch presence install [flags]

orch presence run#

Run the system tray helper (background by default)

orch presence run [flags]

orch presence status#

Show presence login autostart registration

orch presence status [flags]

orch presence uninstall#

Remove presence login autostart

orch presence uninstall [flags]

orch procs#

List the long-lived orch processes and the build each one is running

orch procs [flags]

orch project#

Register projects in orch.yaml (does not create folders)

orch project [flags]

orch project add#

Register an existing folder as a project

orch project add <path> [flags]

Register an existing folder. Relative paths resolve from cwd first, then workspace root. Examples (any layout you already use): orch project add . orch project add apps/billing orch project add products/billing orch project add services/api

orch project list#

List registered projects (shows a project's running Chair, if any)

orch project list [flags]

orch project remove#

Unregister a project (does not delete folders)

orch project remove <path-or-name> [flags]

orch project set#

Set a project field (chair_goal: the Chair goal file, relative to the project root)

orch project set <id> chair_goal <path> [flags]

orch recover#

Rebuild a project from its newest local backup bundle (never into a non-empty folder)

orch recover <project> [flags]

orch repro#

Run one test N times on HEAD and on the base and print both fail rates

orch repro <TestName> [flags]

Runs the test N times on HEAD and N times on the base (a temporary worktree under .sandbox/, removed afterwards) and prints head: F/N failed · base: F/N failed · host cpu X%. Cite that line before blaming a branch for a failure. A Go package (--pkg) is built once per side and run with -test.run '^<TestName>$'; any other language runs its test adapter's command ({test} is the name). A language with no adapter fails naming the file to add. Orchemax never changes your working tree.

orch seat#

Live seat status, wait, report, and read (PTY host observability)

orch seat [flags]

Observe interactive seats without scraping vendor UIs as policy truth. Authoritative states come from orch seat report (or process exit marks). Tail-buffer hints may set maybe_blocked for UX only — never for wait --until blocked.

orch seat attach#

Reattach this terminal to a detached seat-hold

orch seat attach [session-id] [flags]

Dials the hold ipc_addr from seat state and runs the seat host UI until disconnect. Parent console modes are restored on exit.

orch seat detach#

Mark seat UI detached (hold keeps the agent PTY alive)

orch seat detach [session-id] [flags]

Detach the UI from a hosted seat-hold: the hold keeps the agent PTY alive. Requires ipc_addr in .orch/seats/<id>.json. Not a mux sidebar — Orchemax has no session TUI. Native-child seats (default OpenCode) cannot detach — exit kills the agent.

orch seat read#

Read seat tail file (.orch/seats/<id>.tail.txt)

orch seat read [session-id] [flags]

Reads the live seat transcript snapshot. With --deep, asks seat_host to page child alt-screen history (OpenCode-style) or dump a larger VT scrollback (Claude-family), then prints the refreshed tail.

orch seat report#

Write authoritative seat state (source=report)

orch seat report <session-id> [flags]

orch seat status#

Show seat lifecycle state (and optional maybe_blocked hint)

orch seat status [session-id] [flags]

orch seat wait#

Poll until authoritative seat state matches --until

orch seat wait [session-id] [flags]

orch server#

Link this workshop to your Orchemax account (optional)

orch server [flags]

orch server entitlements#

Pull policy hints from server (fallback: local policy when offline)

orch server entitlements [flags]

orch server keys#

Provider keys held by your Orchemax account (Team and above)

orch server keys [flags]

On Team and Enterprise the provider key lives on the server and every machine leases a short-lived copy, so rotating here rotates everywhere.

orch server keys add <provider> <key>… # park or rotate a ring orch server keys list # hints only, never the secret

Below Team the keys stay on your own machine: use orch gateway keys.

orch server keys add#

Park or rotate one provider's key ring on the server

orch server keys add <provider> <key>... [flags]

orch server keys list#

What the server holds, by hint

orch server keys list [flags]

orch server language#

Show or set the language your account notifications are written in

orch server language [en|es-US] [flags]

A team seat never signs into the web platform, so this is where its holder changes the language Orchemax writes to them in. Authorization is the device link: the server only ever sets the language of the person this device belongs to. With no argument it shows what is stored and what the server accepts.

orch server link#

Store token and verify ping

orch server link [flags]

orch server login#

Sign in to Orchemax and link this device

orch server login [flags]

orch server notices#

Fetch member notices from server (channels are server-side)

orch server notices [flags]

orch server push-event#

Push a work event to the server

orch server push-event [flags]

orch server status#

Ping server.url healthz

orch server status [flags]

orch server unlink#

Remove local server token/link state

orch server unlink [flags]

orch server watch#

Hold the live server channel open and drain mail as it arrives

orch server watch [flags]

Subscribes to the server's doorbell (SSE) and drains through the same sync pull orch server entitlements uses. The doorbell only says an outbox id exists, so a workshop several events behind still catches up in one pull. When the stream does not hold, the fallback poll keeps draining.

orch session#

Session commands

orch session [flags]

orch session close#

Close a running seat (the id in the open-agents message)

orch session close <session-id> [flags]

Ends the seat so another agent can open in that workshop.

Copy the id from the message:

already N open agents (plan allows N); Chair session (…) — orch session close <id>

A live process for that seat is stopped first.

orch session last#

Print .orch/LAST_SESSION.md (resume card for your last seat)

orch session last [flags]

orch session leadership#

Content-free CTO 1-pager from local gateway usage + session pulses

orch session leadership [flags]

orch session list#

List session snapshots

orch session list [flags]

orch session overlook#

Content-free CTO overlook as one self-contained offline HTML file (guard, session shape, tool catalogue, savings, governance)

orch session overlook [flags]

orch session rename#

Set display name (like claude /rename)

orch session rename <session-id> <name> [flags]

orch session seal#

Write the session card from a snapshot (default: this Chair seat, else the newest Chair)

orch session seal [session-id] [flags]

orch session show#

Show one session: plan, status, exit, verification, log, supervisor, usage

orch session show <session-id> [flags]

orch session transcript#

Print Claude/OpenClaude chat text (scroll outside the broken TUI mouse)

orch session transcript [vendor-uuid] [flags]

Reads the newest local JSONL under ~/.openclaude/projects// (or ~/.claude/) and prints user/assistant turns as markdown. Agent TUIs often trap the mouse wheel in the prompt box; this is the reliable way to re-read a long reply.

Omit the uuid to use the newest transcript for this workshop. Saves a copy to .orch/transcripts/latest.md. Pass --open to open that file in the default editor.

orch shared#

Register shared folders in orch.yaml by language (does not create folders)

orch shared [flags]

orch shared add#

Register an existing folder under shared.

orch shared add <path> [flags]

Path only. Language defaults to workspace.primary_languages (or the only shared.* bucket). Pass --lang only to override (e.g. assets for css/js). Example: orch shared add C:\Dev\my-workshop\features

orch shared list#

List shared folders by language

orch shared list [flags]

orch shared remove#

Unregister a shared folder (does not delete folders)

orch shared remove <path> [flags]

orch stats#

Gate verdicts recorded so far: denies/warns/oks by guard, surface, and the top rules

orch stats [flags]

orch status#

Show the workshop for this folder, including host load and the scheduler queue depth (same view as orch workshop show)

orch status [flags]

orch task#

Create and run tasks for worker agents

orch task [flags]

orch task add#

Create a task (optionally pre-assign agent)

orch task add [flags]

orch task assign#

Assign task to an agent

orch task assign <id> <agent> [flags]

orch task claim#

Atomically claim one ledger checklist item (shared_locks key ledger:#)

orch task claim <ledger-file> <item-number> [flags]

orch task done#

Mark task done/failed

orch task done <id> [done|failed] [flags]

orch task list#

List tasks

orch task list [flags]

orch task release#

Release a ledger item claim (holder must match, or --holder *)

orch task release <ledger-file> <item-number> [flags]

orch task run#

Dispatch assigned task (chair → agent session)

orch task run <id> [flags]

orch task show#

Show a task with its verification report (guardrails, tests, review)

orch task show <id> [flags]

orch test#

Run the project's tests, skipping the ones already proven on identical inputs

orch test [test args] [flags]

Orchemax runs the project's tests for you: Go packages through go test, serving the tests it already proved on identical inputs; any other language through its test adapter (projects[].tests or the shipped default), whole. Proofs come from the seal's store and this seat's own; only this seat's store is written here. ORCH_TEST_REUSE=0 forces a real run. A language with no adapter fails naming the file to add.

orch try#

Build and install audited branches to test them live, without the land's test suite

orch try <session|branch>... [--rollback] [flags]

Merges the audited branches (the same candidates orch land takes, each with an accept verdict on its current head) onto main in a train directory, runs land.build and installs land.install keeping one rollback copy. It runs no land.verify and no test suite, and moves no branch, the checkout or any remote. orch status labels the installed build (orch try, unverified) until a later orch land --install replaces it; orch land verifies and integrates.

--rollback restores the previous install and clears the label.

orch ui#

Open the local web console (background by default)

orch ui [flags]

Starts a small local web UI (default http://127.0.0.1:8790) for usage, settings, and status. By default the UI runs in the background, the browser opens, and your terminal returns. Use --foreground to keep the server in this terminal (Ctrl+C stops it). Everything it edits also lives in orch.yaml.

orch uninstall#

Remove everything orch left — workshop state, and (with --scope user) machine-wide wiring

orch uninstall [flags]

--dry-run by default: prints the full plan, deletes nothing.

Workspace scope (default):

1. deletes orch-regenerated + orch-runtime + agent-litter, same as orch workspace clean --apply --group orch-regenerated --group orch-runtime --group agent-litter
2. with a second confirmation, also relocates orch.yaml and the rest of .orch/ — including .orch/gates/user/, .orch/packs/ and orch.db — into /orch-uninstall-<timestamp>/. Nothing is ever hard-deleted unless --purge is given; <workspace>/gates/ is never touched; "yours-keep" paths are moved there too, never destroyed, so they can be recovered after the fact.

User scope (--scope user): removes only what orch itself wrote outside this workspace — ~/.claude/settings.json hooks + mcpServers.orch, ~/.claude/orch-mcp.json, ~/.cursor/mcp.json's mcpServers.orch, the home skill trios, agy's global MCP entry, the OpenCode plugin + its opencode.json provider block, and User env ORCH_GATEWAY_KEY (also clears leftover OPENCODE_DISABLE_MOUSE from older installs). Never touches a file it did not write into. Needs --allow-user-scope for a non-interactive run; --yes alone never grants it (mirrors orch guard wire --scope user).

orch uninstall --dry-run orch uninstall --yes orch uninstall --yes --scope user --allow-user-scope orch uninstall --yes --purge

orch usage#

Tokens by session, worker and model, plus bytes crush kept off the wire

orch usage [flags]

orch usage export#

Export usage as OTLP/HTTP JSON traces to a collector, or as gen_ai.*-keyed JSONL

orch usage export [flags]

Sends one CLIENT span per gateway model call, carrying the OpenTelemetry GenAI attributes (gen_ai.system, gen_ai.request.model, gen_ai.operation.name, gen_ai.usage.input_tokens/output_tokens) plus orch.session and orch.agent.

Nothing leaves the machine until you name a collector: no prompt, no completion, no file content — the attempt ledger behind this never stored any. Counters, model names and session ids only.

orch usage export # JSONL on stdout orch usage export --otlp http://127.0.0.1:4318 # /v1/traces is appended orch usage export --otlp $URL --since 24h --header "authorization=Bearer $T"

orch verdict#

Record an accept, reject or fix verdict (needed before promote); --file stores the whole report

orch verdict <session> accept|reject|fix --evidence "<line>" | --file <report> [flags]

orch verify#

Checks that judge the change, not the whole repo

orch verify [flags]

orch verify mutate#

Alter changed lines and report the mutations the tests fail to catch

orch verify mutate [path] [flags]

Mutates only inside the changed Go lines: working tree and staged against HEAD, plus what the branch committed since the merge base. Operators are comparison flips, && <-> ||, true <-> false, and removing the body of an err guard.

--base replaces the merge-base diff with a straight diff from to HEAD, so a whole closed round (many commits, no open branch to detect a merge base from) can be audited in one run instead of reporting nothing.

Each mutant reaches the compiler through go test -overlay from a temp dir, so nothing is written into the checkout, and only that package's own tests run. A surviving mutation means the line changed and every test still passed. A mutant that does not compile is reported as not done, never as a survivor.

orch verify precheck#

Run the seal's cheap checks (call lines, dead code, generated files) on this branch

orch verify precheck [path] [flags]

Runs the checks the seal runs, against merge-base..HEAD plus the working tree, prints the same notes, and exits non-zero when the seal would deny. Run it before the final report; the seal notes a precheck that never ran.

orch verify receipt#

Checks the dispatch/seal/promote hash chain end to end and names the first broken line

orch verify receipt [path] [flags]

Recomputes each line's hash and checks it links to the line before it. An altered line fails at that line's own content hash; a removed line fails at the line right after it, whose prev no longer matches its new predecessor.

Defaults to the workspace receipt (.orch/receipt.ndjson) resolved from --config; pass a path to check any other receipt file.

orch version#

Print version

orch version [flags]

orch webhook#

Inbound webhook receiver: turn a signed POST into a task

orch webhook [flags]

orch webhook serve runs a small local HTTP server (loopback by default) with three routes — /task, /github, /slack — each verified by HMAC and, unless already approved, gated behind webhook.require_approval (see "orch notify" for the outbound side). Configure webhook.secret_env, webhook.allow and webhook.templates in orch.yaml.

orch webhook serve#

Run the inbound webhook HTTP server

orch webhook serve [flags]

orch webhook test#

POST a signed sample payload to a running orch webhook serve

orch webhook test [flags]

orch worker#

Tools for the worker seats Orchemax dispatches

orch worker [flags]

orch worker brief#

Print the sections an Orchemax worker receives for a brief, each with its size (read-only)

orch worker brief <prompt-file> [flags]

orch workshop#

Show the workshop for this folder, or bind another path

orch workshop [path] [flags]

Workshop = folder with orch.yaml + .orch/ (where you run orch day to day).

orch workshop # print resolved workshop for the current folder orch workshop list # trusted workshops on this machine orch workshop forget <path> # drop from trust list (files stay) orch workshop <path> # create/init that folder as a workshop (then cd there) orch workshop show orch workshop use <path> orch status # alias for: orch workshop show

orch.exe on PATH is unrelated — it does not store a workspace pointer. Outside a workshop: loose mode. Relative paths are from the current directory.

orch workshop check#

List what this workshop has on disk and orch.yaml does not declare

orch workshop check [flags]

An undeclared folder is not an error — it is why a gate goes quiet. A project nobody registered is outside quota, locks and cross-project alerts; a shared root nobody declared is a place search-before-create never looks. Each line names the command that fixes it.

orch workshop clean#

Inventory (and, with --apply, remove) everything orch or its agents left here

orch workshop clean [flags]

Dry-run by default — this command never deletes without --apply.

Walks the workspace and every registered project/shared root, grouping what it finds: orch-regenerated everything init/setup/project add/wire recreate orch-runtime worktrees, dispatch logs, supervisor state, sandbox scratch agent-litter dot-directories/scratch files an agent left outside .sandbox/ yours-keep orch.db, .orch/gates/user/, .orch/packs/ — never a valid --group

Only orch-touchable or litter-shaped paths are listed; ordinary project files are never enumerated.

orch workspace clean orch workspace clean --json orch workspace clean --apply --group agent-litter --group orch-runtime --yes orch workspace clean --apply --group orch-regenerated --purge --yes

--apply moves matched paths to /.orch/trash/<timestamp>/ unless --purge hard-deletes them instead. To wipe a workspace entirely (including orch.yaml itself), see: orch uninstall.

orch workshop forget#

Remove a folder from this machine's trusted workshop list

orch workshop forget [path] [flags]

orch workshop list#

List trusted workshops registered on this machine

orch workshop list [flags]

orch workshop show#

Print the workshop this install is bound to (same view as orch status)

orch workshop show [flags]

orch workshop use#

Point this install at a workshop folder

orch workshop use [path] [flags]

orch worktree#

Git worktree lifecycle for orch sessions (status, prune, promote)

orch worktree [flags]

Repos are first-class: each dispatch session gets branch orch/<session> under paths.worktrees. Promote merges into the base branch (fail-closed on conflicts). Never auto-pushes to remote.

orch worktree base#

Show resolved base branch for promote

orch worktree base [flags]

orch worktree promote#

Merge orch/<session> into base (fail-closed on conflicts; no auto-push)

orch worktree promote <session> [flags]

orch worktree prune#

Remove orphan worktree dirs and orphan orch/* branches

orch worktree prune [flags]

orch worktree remove#

Remove a session worktree and its orch/<session> branch

orch worktree remove <session> [flags]

orch worktree status#

List orch session worktrees (dirty / orphan flags)

orch worktree status [flags]

Power-user / agent protocol#

52 commands. Not part of the default orch --help listing — they exist for agent-driven workflows and power users, and can change without a deprecation cycle. Collapsed by default; expand to read.

orch context [flags]

orch context get <id|marker> [flags]

orch context setup [flags]

orch context show [flags]

orch daemon [flags]

orch discover [flags]

orch discover apply [flags]

orch discover run [flags]

orch discover show [flags]

orch gateway login <openai|copilot> [flags]

orch gateway logout <openai|copilot> [flags]

orch harness [flags]

orch harness doctrine [file...] [flags]

orch harness scan [flags]

orch hook [flags]

orch hook cursor-post-tool [flags]

orch hook notification [flags]

orch hook post-tool [flags]

orch hook pre-compact [flags]

orch hook session-end [flags]

orch hook write-dup [flags]

orch housekeeping-pass [flags]

orch inventory [flags]

orch ledger [flags]

orch ledger board <file> [flags]

orch ledger check [dir] [flags]

orch lock [flags]

orch lock acquire <path> [flags]

orch lock release <path> [flags]

orch lock status [path] [flags]

orch notify-hook [flags]

orch refine [flags]

orch refine history [flags]

orch refine run [flags]

orch refine show [flags]

orch refine undo [flags]

orch resume <session-id> [flags]

orch seat hold --session ID --root PATH -- -- agent argv... [flags]

orch skill [flags]

orch skill [flags]

orch skill export [flags]

orch skill export [flags]

orch skill lint [flags]

orch skill lint [flags]

orch symbols [flags]

orch symbols arch [flags]

orch symbols impact [path...] [flags]

orch symbols search <q> [flags]

orch symbols seed [path...] [flags]

orch symbols snippet <symbol> [flags]

orch symbols trace <symbol> [flags]

orch worker-run [flags]