Talk to orch from your agent

You type a sentence in your agent. The Chair turns it into MCP calls. This is what each sentence becomes.

You never type an MCP call. You type a sentence in whatever agent you opened with orch claude, orch opencode, orch codex — and that seat, the Chair, turns the sentence into tool calls on orch mcp.

These pages exist because the mapping is not obvious. "Open a worker" is not a shell command; it is dispatch_worker. Knowing the mapping is how you phrase the sentence so the Chair does the right thing on the first try.

Why the Chair is the one that calls tools#

The first interactive seat you open in a project is the Chair (role=chair). Everything it spawns is a worker (ORCH_ROLE=worker). Only the Chair may fan out:

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

That denial is not a bug to route around. One Chair per git project keeps a single owner of the ledger, the locks and the spawn budget. A worker that wants more hands asks for them through the bus instead of taking them.

What a worker may and may not do#

Chair Worker
Spawn: dispatch_worker, task_add, task_assign, task_run yes no
Claim an item: task_claim, task_release yes yes — claiming your own item is not fan-out
Bus: msg_send, msg_inbox, msg_ack, msg_peers, msg_roster yes yes
Blocking question: ask — yes, to its Chair
Answer one: ask_answer, ask_list yes —
Locks, symbols, graph, context, memory, usage yes yes
Report evidence: verify_report — yes, before finishing

Two rules sit under the whole table. A worker never opens another vendor CLI outside orch to "be a worker". A worker never invents a second bus — no vendor sockets, no side chats.

The recipe format#

Every page that follows uses the same five parts:

  • Prompt — the sentence you type, in plain language.
  • What the Chair does — one line: role check, project resolution, dispatch.
  • MCP calls — real tool names and real parameter names, with the CLI equivalent where one exists.
  • Expected response — the shape that comes back, per client/docs/PROTOCOL-AGENT.md.
  • Gotchas — the denial, the gate, the preset that is not configured yet.

Arguments that carry your identity (holder, session, from_session) come from .orch/ORCH_RUNTIME.md, which the seat injects. Do not invent them.

The eight recipes#

  1. Two workers that correct each other
  2. Ask another project how it solved X
  3. Claim a ledger item before you start
  4. Who calls this, and what breaks if I change it
  5. Stop reading whole files; compress what you read
  6. Show my usage and my leaks
  7. Promote my worktree
  8. Connect OpenCode to the gateway with my keys

Outside a bound workshop (loose mode) the lock and symbol tools return a soft-skip string instead of an error. Governance applies inside a bound workspace.