The relay API and routes

The relay is a small server between callers and the world pages, such as the room. This page has its calls, its errors, its events, the room's API, the room's routes, and the scripts that drive it.

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.

A command through the relay A caller posts a command to the relay, which streams it to the page. The page runs it with window.run and returns the result to the relay, which returns it to the caller. The page also sends events, which callers read from /events or get by webhook. Caller curl, a script, a hook Relay relay/server.js Page window.run POST /commands stream result result events: GET /events or the webhook

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:

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:

ParameterMeaning
channelThe channel to join: 1 to 64 letters, numbers, dashes or underscores.
keyThe relay key.
relayThe relay's address, if it is not the server the page came from.
othersA world can read parameters of its own, such as the room's below.
timeThe room only: day, evening or night, the same as picking the light.
holidayThe 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.
lookThe 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.

CallWhat it does
POST /channels/{channel}/commandsSend 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}/eventsRead 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 /healthThe 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:

FieldDefaultMeaning
actionrequiredOne 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".
atnoneRun the command at this many seconds into the run.
waittrueWait for the result. With false, the reply is 202 with an id to poll.
timeout30Seconds 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:

StatuserrorMeaning
200The world answered. Check ok.
202Accepted with wait: false. Poll /commands/{id}.
400bad_command, bad_request, bad_channelNo action, the body is not JSON, or a bad channel name.
401unauthorizedMissing or wrong key. The message says which.
403local_only, and others such as not_allowed or lead_onlyA 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.
409such as wip_limit, lead_limit, bad_moveA room route refused a move or a start, and the message says why.
404not_found, unknown_commandNo such route or command id.
413bad_requestThe body is over 256 KB.
503no_pageNo page is connected to the channel.
504timeoutThe 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).

ActionParametersWhat it does
hookevent: a hook payloadWhat the Claude Code hook sends. See How events become work.
workwho or skill, labelSends someone to work, from outside a session. With skill, a free person with that skill in the roster.
activitywho or skill, text, kindA line on their monitor. kind: edit, read, bash, web, tool or fail.
donewho, skill or all: trueFinishes work.
sessionslistThe sessions the relay runs. The panel sends this so each has a person.
taskslistThe tasks for the wall board. The Tasks panel sends this.
waitingmessageThe lead raises a hand. Send no message to clear it.
idlewho, doSends 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.
saywho, textA speech bubble.
managernoneSends the manager out of his office on a round now.
leadVisitnoneSends the Lead into the manager's office for a moment. Refused while the Lead has real work, or when both guest chairs are taken.
partyon: true or false (anything else is refused), or left out to toggle; seconds: 5 to 600, 60 if left outThrows 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.
resetnoneEnds all work and clears the board.
state, roster, readynoneA snapshot, the people, and a wait until the room is built.
speedvalue: 0 to 8How fast people move. Work state does not depend on it.
waitsecondsWaits.

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.

RouteWhat it does
GET, POST /ticketsList 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-readyMarks 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}/startStart 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 /tasksList 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, /cleanBring 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 /checkoutsList 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}/cleanRemove one. Files git ignores are asked about as for a task's Clean up.
GET, POST /reviewsThe 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 /terminalsList 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/leadMake 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}/streamA session's output.
POST /terminals/{id}/input, /resize, /stopType 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/contextOnly 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 /floorWhat 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-watchOnly 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/stopWith 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 /updateThe 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 /updateFetches 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-youOnly 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-relaysOnly 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>/stopOnly 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 /huddleThe last report, who can be asked, and whether a huddle is open. Calls neither gh nor git.
GET /cooThe last COO report's text, and the COO's session if one is running.
GET /coo/measuresThe measures, worked out now, with the load and headline the last report saw. See What the relay measures.
POST /coo/askStarts 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 /securityThe last security report's text, and the security officer's session if one is running.
GET /security/measuresWhat 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/askStarts 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 /chatThe 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 /gamesThe 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/currentThe 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/finishAsks the game for its score and reveal, and ends the round. The answer has both.
POST /rounds/current/stopEnds the round with no score.
GET /roundsPast 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}/stepsWhat 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 /playOnly 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}/deleteThe 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:

  • The PM's token can also 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.
  • The PM's and the Lead's tokens can also 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.
  • The PM's and the Lead's tokens can also 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.
  • The Lead's token can also 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.

    CommandWhoWhat it does
    create "Title" --priority high --kind bug --blocked-by T-1,T-2 --body - <<'EOF'Any sessionFiles 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.
    kindsAny sessionPrints the kinds a ticket can have, one to a line.
    labelsAny sessionPrints the labels tickets have, one to a line.
    create "Title" --body-file body.mdAny sessionThe 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.
    listAny sessionLists 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-1Any sessionWithout 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 sessionPosts in a chat channel, but not in #office.
    verdict merge, verdict fixA reviewerGives the review's verdict for the commit its checkout is at, before it posts. See Autopilot.
    fix T-12A Lead you let mergeDecides 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.
    floorThe LeadPrints the Floor, one line per session. See What the Lead sees.
    ready <PR link> <head commit> --body - <<'EOF'The LeadMarks 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 readyA Lead you let move the boardready or rejected from Triage, rejected from Ready, triage from Rejected.
    move T-1 done https://github.com/owner/repo/pull/12A Lead you let move the boardFrom 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.
    tasksA Lead you let move the boardEvery task's id, including those with no ticket.
    task 63e175 in_reviewA Lead you let move the boardbuilding, 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-1A Lead you let start ticketsFrom Ready, one at a time, in Board order, while few enough are building.
    review https://github.com/owner/repo/pull/12A Lead you let start reviews, or any Lead while Autopilot is onAsks the relay for a reviewer of a task's PR, as Get a review does. See The Lead starts a review.
    priority T-5 highA PM or Lead you let set the orderhigh, 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-4A PM or Lead you let set the orderPuts 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 LeadChanges 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 LeadProposes 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.
    measuresThe COOPrints the measures as JSON. See What the relay measures.
    report < report.mdThe COOSaves the report piped in. The Floor shows it.
    accessThe security officerPrints what access the sessions run with as JSON, by name only. See What the relay reports on access.
    access-report < report.mdThe security officerSaves the report piped in, unless it holds a key. The Floor shows it.
    stop TheoA Lead you let move the board, with Let the Lead stop sessions onStops 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).

    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