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 init

orch init is the one start command (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, if Orchemax is not installed yet, points you to orch install.

It also offers to wire the IDE guards (Claude Code, Cursor, Copilot — project scope, default yes; --yes accepts) and, only if agy is installed, separately asks to register the orch MCP server in agy's machine-global config (never granted by --yes alone — decline it, or answer once and it is remembered in orch.yaml; a script needs --allow-user-scope). See Hooks and guards for the full scope model and how to rewire by hand.

Confirm the result at any time:

orch workspace

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

Outside a bound workspace Orchemax 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 — bound by orch init or orch workspace <path> in step 1. orch init --yes does not need one: with no prompts to ask, it binds the current folder itself (the same call orch workspace <cwd> makes) and then seeds. Without --yes, an unbound folder is refused and the command to run first is orch workspace <path>.

Plain orch init 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 Orchemax knows about. Registering does not create folders:

orch project add apps/billing
# any layout you already use, e.g.:
# orch project add products/billing
# orch project add services/api
# orch project add .

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

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

It also seeds apps/billing/.sandbox/README.md (agent scratch — notes, experiments, reports; discardable) and marks .sandbox/ in that project's .gitignore; it asks once for a docs folder (--docs, or --yes for the default docs). See Hooks and guards for what counts as litter.

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

orch project list

apps/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 — Orchemax 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 Orchemax 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, Orchemax 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.