Quickstart

Bind a workspace, seed it, register a project, open the first Chair seat, spawn one worker and read your usage.

Seven steps, about ten minutes. Every command below is the real command — nothing here is a placeholder except the paths you choose.

1. Bind a workspace#

Create or cd into the folder that holds your code, then:

orch setup

orch setup is an interactive wizard. It uses the current folder as the workspace (press Enter) or another path you type, writes orch.yaml and .orch/ there, asks for optional project and shared folders as relative names, reminds you that live agents need provider API keys in environment variables, and offers to put the binary's folder on your user PATH.

Confirm the result at any time:

orch workspace

which prints the resolved orch.exe: folder, workspace:, config: and runtime: paths.

Outside a bound workspace orch runs in loose mode: the gateway works, but locks, the bus and project control do not.

2. Seed the workshop#

orch init

Run this inside the bound workshop. It asks for the docs locale, shared folders, projects, optional git identities, and whether to install the guard git hooks. Then it seeds, without ever clobbering a non-empty file you already have:

It also git-inits each project and shared folder (never the workshop root), installs the sealed orch-* skills into the project, and wires includeIf git identities when you gave profiles.

The last lines it prints are the summary and the practices note:

workshop init OK · <workspace> · profile=lite · N shared · N projects · N git inits

Practices (optional — your docs/process win if you prefer them):
  Starter kit: DEV_PRACTICES.md + GATES.md (recommendations, not mandates).
  Built-ins when you want them: orch guard lang|code-lang|ddl|comment|lock|dup|tracker.

Use orch init --dry-run first if you want the plan without the writes, and --recommend to default to the shared/<lang>/ + projects/<app>/ layout.

3. Register a project#

A project is a git repo orch knows about. Registering does not create folders:

orch project add products/billing

Output names the path, the short name derived from the folder, and the config file it was written to:

registered products/billing
  short name: billing
  config: <workspace>/orch.yaml

List them, with the running Chair and worker count per project when there is one:

orch project list

products/billing  (chair: claude, workers: 2)

4. Open the first seat#

From inside the project folder, open the agent you use. The preset names registered by default are agy, claude, codex, commandcode, copilot, cursor, grok, kimi, mimo, opencode and zcode; bare orch lists the ones it actually found on your PATH under Detected agents:

orch claude

orch codex

orch opencode

The agent starts with its normal chat UI. Do not pass your prompt as arguments — orch refuses that and tells you to type inside the agent instead. The first interactive seat in a project becomes the Chair; a second one in the same project is refused with a message naming the session that already holds it.

5. Ask the Chair to spawn one worker#

Type this inside the agent's chat, not in your shell:

Open an orch worker with codex on the failing tests in internal/billing, give it the acceptance criterion that go test ./internal/billing/... passes, and report back.

The Chair calls dispatch_worker with the agent preset and the prompt. It returns as soon as the worker is running: JSON naming the task, the session id, the worker id, the display name, its status (running), the worktree the worker ran in and its log path. By default the worker runs in its own orch/<session> git worktree, so it cannot collide with your own edits; inplace puts it in the project root instead.

A worker may not spawn another worker. If one tries, orch answers:

dispatch_worker denied: ORCH_ROLE=worker — only the Chair may spawn (use orch msg to the Chair)

Before it finishes, the worker calls verify_report with the tests it ran, the symbols it exported or reused, and each acceptance criterion marked met or not.

6. Read your usage#

Back in your shell:

orch usage

The first line is a summary: attempts with their ok and error counts, prompt and completion tokens, the bytes crush kept off the wire with its share, and average latency in milliseconds. Below it come the code-graph block and the breakdowns by session, by worker and by model, then local transcript totals by source. The ledger behind the table never stores prompts, so the whole read-out is content-free.

Machine-readable form, for a script or an agent:

orch usage --format json

7. Keep going#

• orch ui opens the local web console (default http://127.0.0.1:8790) with usage, settings, status, sessions and the board.
• orch worktree status lists session worktrees with dirty and orphan flags; orch worktree promote <session> merges one into the base branch, fail-closed on conflicts and never pushing for you.
• What to read next picks the path that matches your role.