What the relay is
Each world runs in a browser page, and nothing outside the browser can call into a page directly. The relay (relay/server.js, Node 18 or later, no dependencies) sits in the middle. Callers such as curl, a script or an agent send commands to the relay over HTTP. The relay passes each command to the page, waits for the result and sends it back. The page also sends every event to the relay, where callers can read them or have them posted to a webhook. shared/relay.js connects a world page to the relay when it is opened with ?channel=, and uses only window.run.
The relay also serves the page, so the world and the relay share one address. That avoids the browser's cross-origin and local-network blocks, and once the relay is behind a tunnel the same URL works for any caller and any browser. It serves files from the repo folder (RELAY_ROOT): the room at /office/, any other world at its folder's name, this manual at /docs/manual/, and the root links to the room. It does not serve dot folders such as .git, or any folder named relay or node_modules, in any case, so /RELAY/server.js gets 404 too. It refuses any path with a character that is not ASCII, since macOS reads some of them as plain letters. A path with a malformed escape, such as /%E0%A4%A, gets 404. A path that starts with two slashes, such as // or //office/, gets 404 for any method. An unknown route under /channels/ gets 404 with not_found, and a channel name with a malformed escape, such as /channels/%E0%A4%A/tickets, gets 400 with the relay key with bad_channel.
Worlds. The relay does not know any world by name. A world is a folder in RELAY_ROOT with a world.json: name and channel make its link, port is where its own relay listens, and "sessions": true says its page runs Claude Code sessions, the Board and Autopilot. For example, { "name": "the office", "channel": "office", "port": 8787, "sessions": true }. A folder with no world.json, or one that is not valid JSON, is not a world, but with no RELAY_WORLD its files are still served. A world's own scripts live in its folder. A world can live in a repo of its own and be linked into RELAY_ROOT as a folder link: the relay serves it like any other folder. The rule is in CLAUDE.md and article 13 of the constitution, and relay/test/worlds-apart.test.js fails if code in relay/, office/ or shared/ names another world.
One relay per world. RELAY_KEY=a-key npm run world -- <folder> (relay/world.js) starts a relay for that world alone, on the port in its world.json. It sets RELAY_WORLD, which you can also set yourself, and PORT to the world's port unless you set it. RELAY_WORLD is one folder name: a trailing slash, as tab completion gives, is dropped, and anything else, such as a/b or /, stops the relay with the reason. Give each world its own key. The rollback check is for the room's relay: it looks for the room page and its sessions, so leave RELAY_ROLLBACK off for another world. Such a relay:
- prints one link, its world's, and sends its root (
/) to its world's folder; - serves only its world's folder,
shared/,docs/and the files at the top of the repo, such asREADME.md. Another world's folder gets404, so a link into another world works only on that world's relay; - for a world without
"sessions": true, never loads the room's parts: no sessions, tasks, tickets, Board, chat board, reviews or Autopilot, no polls to GitHub, and no files in the state folder. Their routes get404. Commands, results and events work as for any world; - keeps running when another world's relay restarts or stops, and its key opens nothing in another world.
npm run office starts the room's relay this way, with RELAY_WORLD=office. npm run relay, with no RELAY_WORLD, still serves every world from one relay with the room's parts, on port 8787. /health says which world a relay serves, as world, or null for every world.
The page
The page connects to a relay only when its address has a channel:
| Parameter | Meaning |
|---|---|
channel | The channel to join: 1 to 64 letters, numbers, dashes or underscores. |
key | The relay key. |
relay | The relay's address, if it is not the server the page came from. |
| others | A world can read parameters of its own, such as the room's below. |
time | The room only: day, evening or night, the same as picking the light. |
holiday | The room only: a holiday to show now (newyear, easter, july4, halloween, thanksgiving or christmas), the same as picking it under Holiday, or off for no decorations on that page. See Holidays. |
look | The room only: baked for the room's light baked in Blender, for each time of day, with fx=off to leave out its effects. See The baked look. |
The world only runs while its page is on screen. Each page tells the relay when its tab is hidden or shown, and the relay log says so. If more than one page joins the same channel, commands go to the newest page that is on screen, or to the newest page if none is. A command sent to a hidden page waits and then times out, and the reply says that the tab is hidden (pageHidden: true). It is simplest to use a different channel for each page.
Calls
All calls to /channels/... need the key, as Authorization: Bearer <key> or ?key=<key>. Bodies are JSON.
| Call | What it does |
|---|---|
POST /channels/{channel}/commands | Send a command and, by default, wait for its result. |
GET /channels/{channel}/commands/{id} | Get the result of a command sent with wait: false. |
GET /channels/{channel}/events | Read events the page has sent. |
GET /channels/{channel} | How many pages are connected (pagesConnected) and on screen (pagesVisible), and other counts. |
POST /channels/{channel}/pages/{page} | Used by the page: {"visible": false} when its tab is hidden, true when it is shown. |
GET /health | The relay is up, and which channels have pages. No key needed. With the key, from this computer, it also has restore: whether bringing back the saved sessions is done, and which could not come back, for the rollback check. |
For example, with the room open on channel office, on its own relay (npm run office, port 8787):
curl -s -X POST http://localhost:8787/channels/office/commands \
-H "Authorization: Bearer pick-a-long-random-key" \
-d '{"action": "say", "who": "marcus", "text": "Hello", "source": "curl"}'
Send a command
POST /channels/{channel}/commands. The body is a command, the same as run.do() takes (see the world's own API, such as the room's API), plus fields for the relay:
| Field | Default | Meaning |
|---|---|---|
action | required | One of the world's actions. The room's are below. |
source | "relay" | Your name, shown on every event the command causes. For a script, something like "script:standup". |
at | none | Run the command at this many seconds into the run. |
wait | true | Wait for the result. With false, the reply is 202 with an id to poll. |
timeout | 30 | Seconds to wait, from 1 to 120. |
{ "action": "say", "who": "marcus", "text": "Hello", "source": "script:standup" }
The reply is the world's result with the command's id, channel and action added:
{ "id": "ba29db55-d4bf-40e1-a99b-9ba42c0652b6", "channel": "office", "action": "say",
"ok": true, "who": "marcus" }
When the world refuses a command, the reply is still 200, with ok: false, an error and a message (each world lists its own errors):
{ "id": "30b74e34-...", "channel": "office", "action": "dance",
"ok": false, "error": "unknown_action", "message": "Unknown action \"dance\". Actions: ready, state, roster, ..." }
So a caller checks ok to see whether the world did it, and the HTTP status to see whether the relay could deliver it:
| Status | error | Meaning |
|---|---|---|
200 | The world answered. Check ok. | |
202 | Accepted with wait: false. Poll /commands/{id}. | |
400 | bad_command, bad_request, bad_channel | No action, the body is not JSON, or a bad channel name. |
401 | unauthorized | Missing or wrong key. The message says which. |
403 | local_only, and others such as not_allowed or lead_only | A room route asked from anywhere but the room page on this computer, or a token asking for what it cannot do. See the room's routes. |
409 | such as wip_limit, lead_limit, bad_move | A room route refused a move or a start, and the message says why. |
404 | not_found, unknown_command | No such route or command id. |
413 | bad_request | The body is over 256 KB. |
503 | no_page | No page is connected to the channel. |
504 | timeout | The page did not answer in time. The command may still finish; poll its id. pageHidden: true means the page's tab is hidden, so its world is paused. |
Some commands take time in the world, such as wait, which takes as long as you ask. Set the caller's own HTTP timeout above the longest command you send.
Poll a command
GET /channels/{channel}/commands/{id} returns { "status": "pending" } or { "status": "done", ...the same reply as above }. The last 500 commands per channel are kept.
Read events
GET /channels/{channel}/events?since=0&types=result,worker.assigned&limit=200
{ "ok": true, "channel": "office", "lastEventSeq": 42,
"events": [ { "rseq": 41, "type": "worker.assigned", "who": "marcus", "label": "T-17", "source": "relay", ... } ] }
rseq is the relay's own sequence number for the channel. Pass the last one you saw as since to get only newer events. Every event also keeps its fields from the page. The last 2,000 events per channel are kept. The relay keeps them in memory, so a restart clears them.
Webhook
With RELAY_WEBHOOK_URL set, the relay posts batches of events as they arrive:
{ "channel": "office", "events": [ { "type": "worker.assigned", "who": "marcus", ... }, { "type": "result", "action": "say", ... } ] }
RELAY_WEBHOOK_AUTH is sent as the Authorization header, and RELAY_WEBHOOK_TYPES picks which event types are sent. A failed post is logged and not retried.
The room's API
The room has window.run, the same contract as every world, so shared/relay.js and the relay work unchanged. Every action can be sent through the relay as {"action": ...}. The Claude Code hook sends {"action": "hook", "event": {...}, "wait": false} (see hooks).
| Action | Parameters | What it does |
|---|---|---|
hook | event: a hook payload | What the Claude Code hook sends. See How events become work. |
work | who or skill, label | Sends someone to work, from outside a session. With skill, a free person with that skill in the roster. |
activity | who or skill, text, kind | A line on their monitor. kind: edit, read, bash, web, tool or fail. |
done | who, skill or all: true | Finishes work. |
sessions | list | The sessions the relay runs. The panel sends this so each has a person. |
tasks | list | The tasks for the wall board. The Tasks panel sends this. |
waiting | message | The lead raises a hand. Send no message to clear it. |
idle | who, do | Sends someone who is not working to coffee, couch, window, chat, board, desk, fridge or pingpong. Someone in a ping pong game who is sent anywhere else ends the game, and the other player leaves the table too. |
say | who, text | A speech bubble. |
manager | none | Sends the manager out of his office on a round now. |
leadVisit | none | Sends the Lead into the manager's office for a moment. Refused while the Lead has real work, or when both guest chairs are taken. |
party | on: true or false (anything else is refused), or left out to toggle; seconds: 5 to 600, 60 if left out | Throws a party for that long, or ends the one going on. See Throw a party. run.state().party says whether one is on, how many seconds are left and who is at it. |
reset | none | Ends all work and clears the board. |
state, roster, ready | none | A snapshot, the people, and a wait until the room is built. |
speed | value: 0 to 8 | How fast people move. Work state does not depend on it. |
wait | seconds | Waits. |
Events: office.started, office.live, time, worker.assigned, worker.finished, worker.doing, lead.waiting, lead.unblocked, manager.arrived, manager.left, lead.visit, party.started, party.ending (the candles go out), party.ended, hook, and action and result for everything except hook.
In the browser console, run.view('desks') moves the camera (home, desks, lead, coffee, lounge, board, office), run.focus('marcus') follows someone, run.time('night') changes the light, and run.holiday('christmas') shows a holiday's decorations ('auto' goes back to the date, 'off' and 'on' set the switch this browser keeps). run.state().holiday says what is up and which holiday is next.
The room's routes
These are under /channels/{channel} and answer only the room page on this computer (see the local-only rule), while RELAY_TERMINAL=1. They take the relay key, or a session's token as described below.
| Route | What it does |
|---|---|
GET, POST /tickets | List or file tickets. The list comes in Board order: open tickets high, normal, low, in work order (rank) within each, then done and rejected ones, the latest changed first. It also has kinds (the kinds a ticket can have, see Kind), labels (the labels tickets have, A to Z, see Labels), wipLimit, leadStarts (the number you let the Lead start tickets up to, or 0) and leadStartsLeft. A ticket has approvedBy (you or Lead) once it is put in Ready. The room page gets the same list as a tickets event on its GET /stream when it opens the stream with board=1, with people, who sits on each ticket, and without the time each pipeline was checked. The stream's hello says whether it will (tickets). It is sent once as the stream opens, then only when it changes, and only to the room page on this computer. |
GET /tickets/{id} | One ticket. |
POST /tickets/approve-ready | Marks the Ready tickets that no person approved as approved by you, as Approve all Ready does: those in ids, or every one with no ids. It skips a ticket that is starting. Answers with the ids in approved. No session's token reaches it. |
POST /tickets/{id}/move | {"to": ...}: move a ticket that has no task, as Approve, Reject, Back to Triage and Merged elsewhere do (with pr for done). |
POST /tickets/{id}/start | Start a Ready ticket: a task, a checkout and a worker. A Lead's token is held to its limits. |
POST /tickets/{id}/priority | {"priority": ...}: high, normal or low for a Triage or Ready ticket. It goes last in its new priority. A priority it already has changes nothing, and the answer has unchanged. The person's key, or the token of a PM or Lead you let set the order (The PM sets the order, The Lead sets priority). Any other session's token gets 403. |
POST /tickets/{id}/order | {"before": id} or {"after": id}: a Triage or Ready ticket goes next to another Triage or Ready ticket with the same priority. Usually only the moved ticket is written. When there is no room between two ranks, the Triage and Ready tickets of that priority are numbered again. If the store fails partway, the ranks already written are put back and the answer is 502. Those tickets keep a new updatedAt. The person's key, or the token of a PM or Lead you let set the order. Any other session's token gets 403. |
POST /tickets/{id}/mark | {"mark": "hold"}, {"mark": "replaced", "replacedBy": "T-12"} (the id is optional), or {"mark": null} to clear it: puts a ticket in Triage or Ready on hold or marks it replaced, so Autopilot and the Lead do not start it. The ticket then has heldBack, the reason its card shows. Only the person's key. |
POST /tickets/{id}/shapes | {"shapes": ["T-7", "T-9"]}: the tickets this design ticket shapes. While it is in Triage, Ready or Started, Autopilot and the Lead start none of them. The list replaces the one there, and [] takes it away. Each id must be on the Board, and not the ticket itself. A ticket that is Done or Rejected gets 409 not_ready. Only the person's key. |
POST /tickets/{id}/labels | {"labels": [...]}: a ticket's labels, up to 5, at any status. The list replaces the one there, and [] takes them all away. A new label adds it. Only the person's key. |
POST /tickets/{id}/kind | {"kind": ...}: a Triage or Ready ticket's kind. A new word adds a kind, and "" takes it away. Refused while it is starting, and once it has started. |
POST /tickets/{id}/base | {"base": ...}: a Triage or Ready ticket starts from another local branch. Refused while it is starting, or when another open ticket has that title on that branch. |
POST /tickets/{id}/propose | {"action", "ids", "why"}: proposes to change a Triage or Ready ticket. action is replace (with one or more ids), merge (with one), close (with none) or blockers (the whole new list, which can be empty). why is up to 500 characters. Nothing changes but the ticket's proposal, which holds it back. The PM's and the Lead's tokens propose, and so does the person's key, when the proposal then says You propose. Refused with 400 when an id is not on the Board, is the ticket itself, or was rejected, for every kind, and when a new blocker already waits for the ticket. A ticket that is starting, started, done or rejected gets 409, or 403 for a session's token. See Proposals. |
POST /tickets/{id}/proposal | {"decision": "approve"} or {"decision": "decline"}: answers the ticket's proposal. Approving a replace, merge or close rejects the ticket and sets closedAs (replaced, merged or closed) and closedFor (the ids). Approving blockers sets blockedBy. 409 when no proposal waits, or when it no longer fits the Board: then decline it. Only the person's key. |
POST /tickets/{id}/edit | {"title", "body", "priority"}, any of them: changes a Triage or Ready ticket's words, with the limits of filing one (a title of 1 to 80 characters, a body of up to 8000, high, normal or low). Only the fields that differ are written, and the answer has unchanged when none do. Refused while it is starting or once it has started, is done or is rejected (409, or 403 for a session's token), and when another open ticket in the repo has the new title on its branch (409). For the PM and the Lead, a ticket you rejected counts too, as in filing. The answer's edited lists the fields that changed. A new priority puts it last in that priority, as /priority does. See Editing a ticket. |
POST /tickets/ask | {"idea", "repo"}: starts the PM. |
GET, POST /tasks | List or start tasks. |
GET /tasks/{id} | One task. |
POST /tasks/{id}/move | {"to": ...}: building, in_review, changes_requested, waiting_on_you or done. |
POST /tasks/{id}/resume, /clean | Bring back its worker, or remove its checkout. If the checkout holds only files git ignores, Clean up answers 409 with error: "ignored" and the list in ignored. Send that list back as { "ignored": [...] } to delete them too. A file not on the list is asked about again. |
GET, POST /checkouts | List checkouts, or start a session in a new one. A prompt can have up to 8000 characters, and a longer one is refused with bad_prompt. For a review of a PR, the relay then adds the reviewer's brief, and the verdict ask unless the body has auto. Those do not count toward the limit. A review of a PR can send unlessAt, the commit its last review read. While the PR is still at that commit, nobody starts and the answer says unchanged. |
POST /checkouts/{id}/clean | Remove one. Files git ignores are asked about as for a task's Clean up. |
GET, POST /reviews | The automatic reviews (see Automatic review). auto and again are the two switches, and a POST with either one, true or false, sets it. The answer also has max, each PR with its count, head, pending and waits, and news, what the relay said about the reviews it started, which the page shows once. |
GET, POST /terminals | List or start sessions. A start can have a prompt, up to 8000 characters, which the relay types as the session's first prompt. A longer one is refused with bad_prompt. The list also has finished: the latest automatic reviewers that posted and left. Each session has its seat, the id of the person the relay gave it, and who, that person's name (see Which person gets it), its work label (see labels), and its starts, startsLeft, lastStart, refresh, refreshNote and tired (how full its context is, or null: see How tired the Lead is), and the list has the wipLimit. |
POST /terminals/lead | Make a plain session the Lead (terminal), which saves it and gives it the Lead's brief. Answer the offer to bring it back (asked: true; POST /terminals with resume and lead: true is what Bring back sends). With board: true or false, give or take away its permission to move the board. With starts and total, give it permission to start tickets while fewer than starts tasks are building (1 to one under the WIP limit), total in all (1 to 20), or take it away (starts: 0). With refresh: true or false, start or stop Refresh the Lead. With "lead": true, as Settings sends, a grant goes only to the session that is the Lead now, and is refused with not_lead otherwise, so a page that has not seen another session made the Lead does not make the old one the Lead again. |
POST /terminals/failed | {"sessionId"}: forget a session that could not come back after a restart. |
GET /terminals/{id}/stream | A session's output. |
POST /terminals/{id}/input, /resize, /stop | Type into, resize or stop a session. A stop of the Lead is refused with 409 and lead unless the body says {"lead": true}, as the page sends once you confirm, so a script or test that stops sessions does not stop the Lead by accident. See When the Lead's session ends. |
POST /terminals/context | Only with a session's own token, as its status line (relay/status-line.js) sends it: {"session_id", "percent", "size"}, how much of its context window that conversation has used. A session_id that is not the session's conversation now is refused with 409, and the relay key with 403. See How tired the Lead is. |
GET /floor | What the Lead sees of the Floor, and each session's desk: ticket, title, column, pr, ciWords, review, doing, next (text and owner) and stop (safe and reason). The Lead's row also has tired, and every other row has null there. A Dev's row has waitsOn while the PR watch is on and its task has an open PR: owner, minutes, why, late and words. Every other row has null there. See What the Lead sees and What each desk says. |
GET /pr-watch | Only with the relay key. Whether the PR watch is on, how often it looks (every, seconds), waitMinutes, and one entry for each task with an open PR: pr, task, ticket, the head it last read, and while it is on, who it waits on (owner), minutes, why, late and words. |
POST /floor/stop | With a session's token, {"who"}: the Lead stops one session. Only the token of a Lead you let move the board, and only while Let the Lead stop sessions is on (or RELAY_LEAD_STOPS=1). See What the Lead stops. With the relay key, as the page sends it, {"who": terminal id} or {"all": true}: you stop one desk, or every desk, that its desk calls safe to stop at that moment. The Lead's desk is never safe to stop. GET /floor also gives leadEnded: null while a Lead runs or nothing is offered back, or, once the Lead's session ended in this run, how it ended (stopped, ended or crashed) and a sentence that says so. One that is not safe is refused with not_safe and the reason. See What each desk says. |
POST /ready | {"pr", "head", "text"}: marks a PR ready to merge. Only the Lead's token, or the relay key. The relay checks the PR with gh, posts one comment headed Ready to merge, adds the ready to merge label, and takes the label off when a new commit lands. A PR that fails a check gets 409 and not_ready, a note with a part missing gets 400, and a gh failure gets 502. See Ready to merge. |
GET /update | The relay's folder, and the update under way, if any, with who it waits for. rollback says which commit failed its check, why, and which commit runs, while the relay runs the commit it went back to, or while the folder is on it after a page-only step went back. While Update goes through merges one at a time, update.step has at, of, name, pr, sha, later, reloads and stopping. note and noteAt say how the last update ended, reloads how many page steps it made, and steps whether Update goes one merge at a time. |
POST /update | Fetches for the relay's folder and pulls when the plan says, as Update does. {"cancel": true} calls off a restart that is waiting, or stops a loop through merges between steps (One merge at a time). |
GET /needs-you | Only with the relay key. count, and items: one for each thing that needs you, most urgent first, each with kind, who, terminal, task, ticket, pr, line and link (terminal, url, ticket or stop, and fix, a task id, on a hand-over whose Dev says a finding is a bug). Calls neither gh nor git. See Needs you. |
GET /old-relays | Only with the relay key. relays: the other relays on this room's state folder that the relay found when it started and that still run, each with pid, file, port, started, paused and worker. See Old relays. |
POST /old-relays/<pid>/stop | Only with the relay key. Stops a relay on that list, after ps shows again that it is a relay on this folder: {"ok": true, "stopped": 48435}. A pid not on the list gets 404 with unknown_relay. |
GET /huddle | The last report, who can be asked, and whether a huddle is open. Calls neither gh nor git. |
GET /coo | The last COO report's text, and the COO's session if one is running. |
GET /coo/measures | The measures, worked out now, with the load and headline the last report saw. See What the relay measures. |
POST /coo/ask | Starts the COO with its brief. 409 while one is running. |
POST /coo/report | {"text"}: saves a report of up to 20000 characters, with the measures. |
GET /security | The last security report's text, and the security officer's session if one is running. |
GET /security/measures | What access the sessions run with, worked out now, by name only, with the gaps the last report saw. See What the relay reports on access. |
POST /security/ask | Starts the security officer with its brief. 409 while one is running. |
POST /security/report | {"text"}: saves a report of up to 20000 characters, with the measures. 400 with holds_a_secret when a line looks like it holds a key, and which line, never the value. |
POST /huddle | {"ask", "lead", "names"}: runs a huddle. ask sends idle sessions the question. lead: false keeps the report from the Lead. |
GET /chat | The chat channels: name, kind (office, ticket or fun), about, how many posts each keeps now, and archived: null, or when and why a ticket's was archived. |
POST /chat | {"name"}: the person makes a fun chat channel. 1 to 24 lower-case letters, digits or dashes. Names like t-5 are kept for tickets. Up to 10. |
GET /chat/{name} | Its posts, oldest first. ?since=N gives only posts after number N, and ?limit=N the newest N. For a ticket in Triage, Ready or Started with no chat channel, such as one filed before tickets had one, it makes the chat channel first. Each post has from, by (relay, person or session), text, and mention or note. |
POST /chat/{name} | {"text"}: a post, up to 500 characters. A session cannot post in #office, and posts at most once every 5 seconds in each ticket's chat channel and once a minute in each fun one. 409 archived in an archived chat channel, for the person too. Like the read, it makes an open ticket's missing chat channel first. |
GET /games | The games in GAMES_REPO: each folder with a game.json, with its name, version, players, needs, ok, and a reason when the relay cannot run it, and the game's own about and metrics when it has them. See Games. |
POST /rounds | {"game", "seed", "settings", "seats", "watch", "capUsd"}: starts a round of a game, with a fresh session for each seat. 409 while a round runs, and 409 no_boundary where seats cannot get their boundary. 400 for a game that is not ok, with need when a need is what stops it, a seat count outside its players, or a watch that is not all or none. |
GET /rounds/current | The round that runs, or null: its id, game, state, watch, spentUsd at API prices, unpriced (models with no price here), and its seats (seat, terminal, waiting: "trust" while that seat waits on the question about trusting its folder, or null, state, worked, tokens and usd). Never a brief, a role or the truth. |
POST /rounds/current/finish | Asks the game for its score and reveal, and ends the round. The answer has both. |
POST /rounds/current/stop | Ends the round with no score. |
GET /rounds | Past rounds, newest first, kept while the relay runs: id, game, time, spentUsd, seatNames and score only. A round that failed or was stopped has score: null. |
GET /rounds/{id}/seats/{seat}/steps | What one seat did, read now from Claude Code's transcript of its session: steps, each with kind (brief, prompt, says, runs with its tool, or result) and text, and the seat's tokens, usd and models. found: false before Claude Code writes it. For the round that runs only under Watch all (403 watch_none), and for a past round the relay still keeps. See Games. |
POST /play | Only with a seat's own token, as relay/play.js sends it (a seat runs it as node "$OFFICE_PLAY"): {"kind", "args"}, one action for that seat. The answer has the game's answer. A body that names a seat gets 400, and any other caller 403. |
POST /chat/{name}/delete | The person deletes a chat channel. A ticket's leaves a short summary on the ticket first, with the local store only. If that fails, the answer is 502, and the chat channel stays. While the relay is deleting it already, the answer is 409. |
What a session's token reaches
Each session the room starts gets OFFICE_TICKET_TOKEN, sent as X-Office-Token. Tokens reach nothing but this:
- Any session's token can
GETandPOST/tickets, except the COO's, which can onlyGETit. - Any session's token can
POST/commands, but only{"action": "hook"}with an event about its own session: the hook sends that way toOFFICE_HOOK_URL. The relay sets the event'sterminalto that session's desk. ASessionStartmay carry a new session id, after/clear. Anything else gets 403. - Any session's token can
POST/terminals/context, but only for the conversation its session is in now: its status line says how full its context is (How tired the Lead is). - Any session's token but the COO's and the security officer's can
GET/chatand/chat/{name}, andPOST/chat/{name}. A post that mentions a session is typed into it, and those two only propose. Their tokens can list tickets but not file them. - A reviewer's token can also
POST/autopilot/verdict, for the PR it reviews. No token reaches/autopilotitself. - The Lead's token can also
POST/autopilot/fixwith{"task"}, a task id, ticket id or PR link, while Let the Lead merge is on. With the switch off it gets 403. Any other session's token gets 401. The person's key reaches it too: it is Fix it on Needs you. It answers 404 withnot_a_taskwhen no task matches, and 409 withno_merge_verdictwhen the latest posted verdict on its PR does not say merge. See The push hold. - The Lead's token can also
GET/floor, andPOST/readyto mark a PR ready to merge. - The token of a session you made the Lead and let move the board can also
POST/tasks/{id}/moveand/tickets/{id}/move, andGET/tasks, which then shows only each task's id, state, title, branch and PR. WithRELAY_LEAD_STOPS=1it can alsoPOST/floor/stop. While Autopilot is on, a move is refused with403andautopilotunless it takes a task, or a ticket with no task, to Done once the relay has seen its PR merge. See The Lead under Autopilot. - The COO's token can also
GET/coo/measuresandPOST/coo/report. - The Lead's token can also
POST/reviews/leadwith{"pr": ...}. A session that is no longer the Lead gets 401. The Lead gets 403 while Let the Lead start reviews and Autopilot are both off, 400 for a link that is not a PR, 404 withnot_a_taskfor a PR that is not a task's, and 409 withreviewing,fullorlimitfor a PR a reviewer is on, no free desk, or a PR past its reviews. See The Lead starts a review. The person's key gets 403 here: the page has Get a review. - The security officer's token can also
GET/security/measuresandPOST/security/report. - The token of a session you made the Lead and let start tickets can also
POST/tickets/{id}/start, within the limits in The Lead starts tickets, and never while Autopilot is on. While a round of a game runs, it gets 409 withheld(see Games). - A seat's token, in a round of a game, reaches only
POST /play, its own hooks on/commandsand its status line on/terminals/context. Everything else, tickets and the chat board included, gets 403.
POST /tickets/{id}/priority and /tickets/{id}/order, but only while Let the PM set the order is on, only for a ticket in Triage or Ready, and only for the PM that started last on the channel. Otherwise it gets 403. The relay checks the switch again when the request's turn comes, so a request that was waiting when you turned the switch off is refused too. A ticket set this way has orderedBy PM, and one you set has you, with orderedWhat priority or place.POST /tickets/{id}/propose, for a ticket in Triage or Ready. The proposal waits for the person, and no session's token can answer it on /tickets/{id}/proposal.POST /tickets/{id}/edit, for a ticket in Triage or Ready. A new priority in it needs the same switch as /priority, or the whole edit gets 403. A ticket that is starting, started, done or rejected gets 403. A new title or body on a Ready ticket you approved takes your approval back, and the answer has approvalTaken.POST /tickets/{id}/priority and /tickets/{id}/order, but only while Let the Lead set priority is on, only for a ticket in Triage or Ready, and only while the session is still the Lead. It does not need Let the Lead move the board. Otherwise it gets 403. The relay checks the switch again when the request's turn comes. A ticket set this way has orderedBy Lead.Other routes answer a token with 401. /tickets/{id}/priority and /tickets/{id}/order answer every other token with 403, and so do /tickets/{id}/edit and /tickets/{id}/propose for every token but the PM's and the Lead's. The PM's token gets 403 on /tickets/{id}/move, /start, /base and /kind.
The ticket.js command
relay/ticket.js is the command sessions use to list and file tickets and to read and post on the chat board, the Lead to read the Floor, mark PRs ready to merge, move tasks and tickets, start tickets and stop sessions, and the COO to read the measures and save its report. It reads OFFICE_TICKET_URL and OFFICE_TICKET_TOKEN, so it works only in a session the room started. Anywhere else it says This only works in a session the office started.
| Command | Who | What it does |
|---|---|---|
create "Title" --priority high --kind bug --blocked-by T-1,T-2 --body - <<'EOF' | Any session | Files a ticket, which waits in Triage. The body is read from stdin as written: it goes on the lines below, and a last line of only EOF ends it. --kind is one of the kinds kinds prints (see Kind). --label flaky,follow-up gives labels that labels prints (see Labels). --blocked-by takes the ids that list and create print: T-1 on the local store, 12 on GitHub issues, separated by commas with no spaces. The relay refuses an id that no ticket has. ticket.js refuses ids after --blocked-by or --shapes written with spaces, such as --blocked-by T-18 T-16, and says how to write them: --blocked-by T-18,T-16. Without that check, T-16 would join the title. A PM's body must have the four parts What to build, Acceptance criteria, Blocked by and Out of scope, each at the start of its own line (see Filing). The relay refuses it otherwise and names the parts that are missing. Other sessions and you file any body. --shapes T-7,T-9 makes it a design ticket for those tickets, which must all be in Triage. |
kinds | Any session | Prints the kinds a ticket can have, one to a line. |
labels | Any session | Prints the labels tickets have, one to a line. |
create "Title" --body-file body.md | Any session | The same, with the body read from a file, as written. --body-file - also reads stdin. --body also takes the text itself, but inside the shell's double quotes, backticks and $( ) run as commands and a quote ends the body, so a body goes in a quoted heredoc or a file. Give the body only once. CLAUDE.md and the PM's and workers' briefs file this way. |
list | Any session | Lists the tickets in Board order, each with its id, status, priority and title, then its kind and labels if it has them, and why nothing starts it by itself if it is held back. |
chat, chat T-1 | Any session | Without a name, lists the chat channels that are not archived, says how many are, and prints the newest 30 posts in #office. With one, prints that chat channel's newest 30 posts, each with who sent it as the relay knows it. See A post types nothing into a session. |
post T-1 "text" | Any session | Posts in a chat channel, but not in #office. |
verdict merge, verdict fix | A reviewer | Gives the review's verdict for the commit its checkout is at, before it posts. See Autopilot. |
fix T-12 | A Lead you let merge | Decides that a finding the merge review marked non-blocking must be fixed, as Fix it on Needs you does. It takes a ticket id, a task id or the PR link. See The push hold. |
floor | The Lead | Prints the Floor, one line per session. See What the Lead sees. |
ready <PR link> <head commit> --body - <<'EOF' | The Lead | Marks a PR ready to merge: one note headed Ready to merge and the ready to merge label. The body has three lines that start Reviews:, Findings: and Hand checks still open:. With nothing after ready, it prints what to check and what to write. See Ready to merge. |
move T-1 ready | A Lead you let move the board | ready or rejected from Triage, rejected from Ready, triage from Rejected. |
move T-1 done https://github.com/owner/repo/pull/12 | A Lead you let move the board | From Triage or Ready, for work that merged without a task. It refuses a PR that is already another task's, now or before, or another ticket's, and says whose. It also refuses a PR that gh pr view says has not merged, one in a repo that is not a GitHub remote of the ticket's repo, and one gh cannot read. |
tasks | A Lead you let move the board | Every task's id, including those with no ticket. |
task 63e175 in_review | A Lead you let move the board | building, in_review, changes_requested, waiting_on_you or done. While Autopilot is on, only done, once its PR has merged (The Lead under Autopilot). |
start T-1 | A Lead you let start tickets | From Ready, one at a time, in Board order, while few enough are building. |
review https://github.com/owner/repo/pull/12 | A Lead you let start reviews, or any Lead while Autopilot is on | Asks the relay for a reviewer of a task's PR, as Get a review does. See The Lead starts a review. |
priority T-5 high | A PM or Lead you let set the order | high, normal or low for a Triage or Ready ticket. It goes last in that priority. See The PM sets the order and The Lead sets priority. |
order T-5 --before T-4 | A PM or Lead you let set the order | Puts a Triage or Ready ticket just above (--before) or below (--after) another one with the same priority. |
edit T-5 --title "New title" --priority high --body - <<'EOF' | The PM or the Lead | Changes a Triage or Ready ticket's title, body or priority, any of them. The body comes as in create: --body - for stdin or --body-file. A new priority needs the switch priority needs. A new title or body on a Ready ticket the person approved takes the approval back, and the command says so. See Editing a ticket. |
replace T-10 --by T-18,T-19 --why 'Split into two' | The PM or the Lead | Proposes to replace a Triage or Ready ticket with the tickets named. Once the person approves, it is rejected as replaced. The same goes for merge T-24 --into T-8, close T-5, and blockers T-19 --blocked-by T-18,T-3, which proposes the whole new list (--blocked-by none for none). Each takes --why. See Proposals. |
measures | The COO | Prints the measures as JSON. See What the relay measures. |
report < report.md | The COO | Saves the report piped in. The Floor shows it. |
access | The security officer | Prints what access the sessions run with as JSON, by name only. See What the relay reports on access. |
access-report < report.md | The security officer | Saves the report piped in, unless it holds a key. The Floor shows it. |
stop Theo | A Lead you let move the board, with Let the Lead stop sessions on | Stops a session the Floor calls safe to stop, by the name the Floor shows or a task id such as 63e175, if it is one of the two kinds the Lead stops. It prints who it stopped, with the session id. |
Games
The room can act out a game from another repo for one round, from the Games panel or these routes. The room does not change, only the roles of the sessions in it. Set GAMES_REPO to a folder of games. A game is a folder in it with a game.json: {"name", "version", "api": 1, "entry", "players": {"min", "max"}, "needs"}, and if it likes "about", what a round is in plain words, and "metrics", {"name": "what it means"} for the numbers in its score. This relay can meet the needs privateBriefs, ask and files. No code in relay/, office/ or shared/ names a game, and relay/test/games.test.js checks that when GAMES_REPO is set.
A round runs the game's entry with node, in the game's folder, as its own process, without the relay's key. They talk in JSON lines. The relay sends hello, setup (seed, settings, seats), action (id, seat, kind, args), finish and abort. The game sends hello, brief (seat, text), ready, answer (id, text), spend (usd) and done (score, reveal).
- Seats. Each seat (
S1,S2and on) is a fresh session at a free desk, in a new folder that is not a copy of a repo, with no task. Every seat folder sits under one parent,~/.office-world/seats/<round>/<seat>, and goes when its seat ends. Its brief is typed as its first prompt and kept nowhere else: not in a file, the relay's log, a title or any route but the seat's own steps. Those go only to your room page, which can already see the brief on the seat's screen. A seat's hooks reach the room without their words. The relay has no field for a role. Only the game knows who is what. - Playing. A seat runs
node "$OFFICE_PLAY" ask "a question", or another kind its brief names, and gets the game's answer. Its folder is empty, so the relay gives it the full path ofrelay/play.jsasOFFICE_PLAY. The game routes answer only the room page and the sessions on this computer, like every room route. - Watching. A round is
watch: "all"(the default): you can open any seat's screen. Or"none", for when you play too: a seat's screen is refused with 403 until the round ends. Either way a seat is read-only to you: typing into it gets 403. The one exception is Claude Code's question about trusting the seat's folder. Nothing is typed into a seat while that question is up, soGET /rounds/currentshows that seat withwaiting: "trust", and you may answer it. Claude Code's first choice there is No, so Enter alone ends the seat: the answer is Down, then Enter, as the Games panel sends it. You can also trust~/.office-world/seatsonce in Claude Code, if it honors a parent folder's trust for the folders under it. That is not checked yet. - The rest of the room. While a round runs, the Lead and Autopilot start no new tickets. Work already running goes on.
- The end. Finish shows the game's score and reveal, and a second Finish while the first waits gets the same answer. Stop ends it with no score. A game that exits, sends a line that is not JSON, or does not answer for
RELAY_GAME_TIMEOUT_MS(30 seconds) ends its own round, and so does a round that reaches its spend cap. Then every seat is stopped and its folder removed. The relay keeps only each round's id, game, time, spend and score while it runs, and for each seat its folder and session id, so you can still read its steps. - Steps and spend. Claude Code keeps each session's transcript in
~/.claude/projects/<the folder, each sign a dash>/<session id>.jsonl, and it stays after the seat's folder goes.relay/seat-steps.jsreads it: the steps forGET .../steps, and the tokens of each request once, priced per model at Claude API list prices, with cache writes at 1.25 times input for 5 minutes and 2 times for 1 hour. Claude Haiku 5.5 has a higher price for a request whose prompt is over 100K tokens, and the relay counts that too. Its cache reads are counted at a tenth of input, since no list price is given for them. While a round runs, the relay reads each seat's transcript again everyRELAY_SEAT_SPEND_MS(5 seconds) when it has grown, adds what the game reports, and stops the round at its spend cap. Text in a<system-reminder>block, which Claude Code adds with your global rules and account, never comes out in a step. - A seat's boundary. A seat has a shell and runs as your own user, so on macOS the relay starts each seat's
claudeinsidesandbox-exec, with a profile made for that seat. The seat and every program it starts cannot read or writeGAMES_REPO, the games' sealed folder (GAMES_HOME, or~/.games), the relay's state folder, the other seats' folders, and in~/.claudethe transcripts (projects),todos,file-history,session-env,plansandhistory.jsonl, which holds every session's prompts. It keeps its own folder, its own transcript folder and the files named with its own session id, and it may add to the hook queue without reading it. Add folders withRELAY_SEAT_DENY. A seat's environment also has noGAMES_REPOorGAMES_HOME. The boundary does not cover the network, your other files, or the other folders in~/.claude, such asshell-snapshots. Wheresandbox-execis missing, a round gets 409no_boundary, unless you setRELAY_SEAT_ISOLATION=off.GET /rounds/currentsays which:isolation: "sandbox"or"none". - A restart. A round never outlives the relay that ran it. Each seat is saved with its round's id, so the next relay brings no seat back: the session host hangs them up, the seat folders go, and the log says so in one line for each seat, with no brief.
- A seat's hooks. A seat runs with
OFFICE_SEAT=1, so its hooks drop every field that can hold its words (prompt,title,customTitle,message,tool_input, a huddle answer and a PR link) before they send or queue an event, and write nothing toOFFICE_HOOK_LOG. A notice that the seat waits for its next prompt keeps that fact as itsnotification_type. The relay drops the same fields for any hook it gets about a seat, also while a seat that ended is still closing.
Reaching it through a tunnel
A caller on another computer or in the cloud cannot reach localhost, so put a tunnel in front of the world's own relay (see One relay per world). Then the tunnel reaches that world alone, with its key, and not the room. For example, for a world on its relay at 8788, with Cloudflare's quick tunnel:
cloudflared tunnel --url http://localhost:8788
It prints an https://...trycloudflare.com address. Use that address as the caller's base URL, and open the world at the same address with /<folder>/?channel=<channel>&key=.... A quick tunnel gets a new address each time it starts. Check your company's rules before opening a tunnel from a work machine. The relay can keep listening on 127.0.0.1, since a tunnel connects locally. The room's own routes stay closed through a tunnel, and a tunnel that rewrites Host to localhost makes every request look local, so use one that passes its own hostname through (see hooks from another computer).
Limits
- Commands go only to a page that is open and visible.
- Everything but the room's files in its state folder (tasks, tickets, sessions and the rest) is in memory. Restarting the relay clears channels, results and events.
- One key for everything. Anyone with the key can drive any channel.
- The relay has no rate limits. Keep it behind a tunnel you control, and stop it when you are done.