The relay
| Variable | Default | Meaning |
|---|---|---|
RELAY_KEY | random, printed at start | The key every call to /channels/... must send. The supervisor hands it to the relay it starts, and both take it out of their own environments, so nothing they run is given it: not a session, not git or gh, not the git a rollback runs, and not the session host. |
PORT | 8787, or the world's port | Port to listen on. With RELAY_WORLD, the default is the port in that world's world.json. |
RELAY_WORLD | none: every world | A world's folder. The relay serves that world alone, and loads the room's parts only if its world.json says "sessions": true. npm run world -- <folder> sets it, and npm run office sets it to office. See One relay per world. |
HOST | 127.0.0.1 | Address to listen on. A tunnel connects locally, so this can stay as it is. |
RELAY_ROOT | the repo folder | Where the page files are served from. See what the relay serves. Files under relay/ are never served. |
RELAY_TERMINAL | off | 1 turns on the Claude Code panel, the Board, Tasks, checkouts and Update. npm run office sets it on a relay it starts, but not on one already running. It only answers the room page on this computer. See the local-only rule. |
RELAY_UPDATE_DIR | the relay's folder | Where Update pulls, and where a rollback checks out the last good commit. |
RELAY_ROLLBACK | off | 1 checks each relay the supervisor starts, and goes back to the last commit that passed when the relay fails after an Update. Read once, when the supervisor starts. See When the new relay fails. |
RELAY_ROLLBACK_SECONDS | 60 | How long a new relay has to pass that check. At least 5. |
RELAY_UPDATE_STEPS | 20 | While RELAY_ROLLBACK=1, the most merges one Update takes, one at a time. The rest wait for the next. From 1 to 100. See One merge at a time. |
RELAY_RESUME | 1 | 0 starts the relay with nobody: it brings back no session from the last run, ends any still running in the session host, and starts no Lead. See Bringing a session back. |
RELAY_WORKER, RELAY_SUPERVISED, RELAY_KEY_RANDOM | set by the supervisor | Tell the relay it runs under relay/supervisor.js, and whether the key was made up. Not for you to set. Sessions do not get them. |
RELAY_HOST_SOCKET | set by the supervisor | The socket of the session host, which runs the sessions. Not for you to set. Sessions do not get it. |
Room sessions and tasks
| Variable | Default | Meaning |
|---|---|---|
CLAUDE_CMD | claude | The command the Claude Code panel runs. |
RELAY_OUT_BATCH_MS | 16 | How long the relay holds a session's newest output before it sends it to the pages watching. A page that opens the session gets what is held in its replay, once. A value below 1, or one that is not a number, means 16. Tests make it longer. |
RELAY_TYPE_SETTLE_MS | 300 | How long a message the relay types sits in the session's prompt before it presses Enter. If the session gets busy in that time, or the message is changed or taken back, the relay clears the prompt with Ctrl+U and does not press Enter. A value below 1, or one that is not a number, means 300. Tests make it longer. |
RELAY_DELIVERY_EVERY_MS | 500 | How often the relay looks for saved messages it can type now, such as briefs, review news and chat mentions. Refresh the Lead types a brief the Lead still owes without waiting for the next look. A value below 1, or one that is not a number, means 500. Tests make it longer. |
GAMES_REPO | none | The folder of games the room can act out. See Games. |
GAMES_HOME | ~/.games | Where games keep their sealed truth. Seats cannot read it. See A seat's boundary. |
RELAY_SEAT_DENY | none | More folders that seats cannot read or write, split like PATH. See A seat's boundary. |
RELAY_SEAT_ISOLATION | on | off runs rounds with no boundary around the seats, where sandbox-exec is missing. A round then says isolation: "none". See A seat's boundary. |
RELAY_SEAT_SPEND_MS | 5000 | How often, in milliseconds, the relay reads each seat's transcript to count its spend while a round runs. See Steps and spend. |
RELAY_GAME_TIMEOUT_MS | 30000 | How long a game may take to get ready or to answer, before its round ends. See Games. |
RELAY_WIP_LIMIT | 3 | How many tasks can be building at once. A task the relay moved back to Changes requested for a review does not count until its next move. See the limit. |
RELAY_LEAD_CHECK_MS | 300000 (5 minutes) | How often, in milliseconds, the relay types the Lead's regular check into the Lead, while at least one task is building, in review, has changes requested or is waiting on you. It waits until the Lead is idle, and a check that comes due while one still waits is dropped. 0 turns it off. In Settings it is Lead check every, in minutes, under Work. |
RELAY_STALL_MS | 1800000 (30 minutes) | How long, in milliseconds, a session in a turn can send no hook and print nothing before it is stuck. With no hook but output still moving, it is quiet instead. The Floor, Autopilot and the COO's stall count all use it. See Is a session alive. |
RELAY_READY_LIMIT | 600000 (10 minutes) | How long, in milliseconds, a reviewer's, the PM's or the COO's first prompt waits for its session to be ready before it gives up, counted from when it was saved, and again from when a relay comes back. Once typed, it does not give up for this: it is in once a turn begins, or the session is stuck. A task's brief and the Lead's brief do not give up. |
RELAY_UPDATE_HOLD_MS | 600000 (10 minutes) | How long, in milliseconds, an update that waits for a quiet moment holds saved messages, counted from when the wait began. After that they go in, and the update waits for their turns. First briefs are never held this way. 0 holds nothing. See While an update waits. |
RELAY_SSH_CMD | ssh | The ssh whose ssh -G says which host an SSH alias in a remote stands for. See Automatic review. |
GH_CMD | gh | The gh that huddles, review checks and the chat board run. |
RELAY_CHAT_KEEP | 200 | How many posts each chat channel keeps. Older ones are dropped. See The chat board. |
RELAY_CHAT_POLL_SECONDS | 60 | How often the chat board asks gh about each task's PR, for a failing pipeline, a merge or a close. 0 turns it off. |
RELAY_MAIN_POLL_SECONDS | 60 | How often the relay runs git ls-remote --symref origin HEAD in its own folder, the one Update pulls into, to say in #office when origin's default branch moved. 0 turns it off. See The chat board. |
RELAY_CHAT_RETRY_MS | 30000 | How often the relay tidies the chat board: it forgets mention notes that went in and hands no longer raised. |
The Lead
| Variable | Default | Meaning |
|---|---|---|
RELAY_LEAD | 1 | 0 starts the relay without its own Lead. Otherwise, once it has brought back its sessions, the room's channel gets a running Lead: the saved one if it can come back, or a new plain session in the relay's folder. Read once, when the relay starts. RELAY_RESUME=0 starts no Lead either. See When the relay starts. |
RELAY_LEAD_STOPS | off | 1 lets a Lead you let move the board stop a session the Floor calls safe to stop, if it is an automatic reviewer that has posted or a Dev whose PR merged or whose task is Done. It is also Let the Lead stop sessions in Settings. A value set there wins over this variable and stays through a restart, so to take the rung back, turn the switch off in Settings. See What the Lead stops. |
RELAY_LEAD_STOP_LIMIT | 6 | While the Lead may stop sessions, how many it may stop in an hour, on each channel. |
RELAY_PM_TALK_MINUTES | 30 | For how long after you last typed to the PM the Floor calls it not safe to stop. |
Reviews and huddles
| Variable | Default | Meaning |
|---|---|---|
RELAY_REVIEW_GRACE_MS | 30000 | How long an automatic reviewer that has posted waits before its session ends. See Reviewers leave. |
RELAY_AUTOPILOT_TICK_MS | 20000 | How often Autopilot looks at each task's PR and at Ready. See Autopilot. |
RELAY_AUTOPILOT_AT_ONCE | 1 | How many tasks Autopilot keeps open at once. See Autopilot. |
RELAY_AUTOPILOT_STALL_MS | 1800000 | How long a task of Autopilot's is stuck before it goes to Waiting on you: at a session at a question, a reviewer that has not started, or nothing that could move it. See A stuck session. |
RELAY_REVIEW_RETRY_MS | 60000 | How long an automatic review that could not start waits before it tries again, with 3 tries in all, the first one included. A first review that only lacks a desk waits for a free desk instead. See Automatic review and Review again after each push. |
RELAY_REVIEW_POLL_SECONDS | 60 | How often the relay checks task PRs for new comments. 0 turns it off. See How findings get back to the Dev. |
RELAY_PIPELINE_POLL_SECONDS | 15 | How often the relay asks GitHub for the checks on each open PR. Automatic reviews wait until they pass. 0 turns it off, and reviews start without waiting. See A clean pipeline before review. |
RELAY_MAIN_CI_POLL_SECONDS | 120 | How often the relay asks GitHub for the latest CI runs that a push to main started, once for each repo and base branch the room works on. When the latest one failed, Needs you and the Lead's Floor say main is red, and Autopilot starts no new ticket on that branch. 0 turns it off. In Settings it is Check main's CI every, under Reviews. See A red main. |
RELAY_READY_POLL_SECONDS | 60 | How often the relay checks the head of each PR the Lead marked ready to merge while RELAY_PIPELINE_POLL_SECONDS is 0. Otherwise it checks at the pipeline's pace. |
RELAY_PIPELINE_NO_CHECKS_MS | 120000 | How long a PR with no checks waits for them to appear before its review starts with no pipeline. See A clean pipeline before review. |
RELAY_TOLD_CHECK_MS | 60000 | How long after a saved message goes in the relay waits for a turn to begin, before it tries once more (three more times for a first prompt), and again before it calls the session stuck. Past this and 3 seconds after an Enter that no hook answered, the Lead's stop verdict says the prompt did not go in. See A session that does not start. |
RELAY_REDRAW_AFTER_MS | 60000 | How long a saved message waits on an idle session whose screen shows no prompt before the relay makes that session draw its screen again. See A screen with no prompt. |
RELAY_UNDELIVERED_MS | 900000 | How long a saved message waits for a running session before Needs you names it. |
RELAY_HUDDLE_ANSWER_SECONDS | 180 | How long a huddle waits for answers. |
RELAY_COO_GRACE_MS | 10000 | How long after the turn that saved its report the COO's session ends. |
RELAY_SECURITY_GRACE_MS | 10000 | How long after the turn that saved its report the security officer's session ends. |
Tickets
| Variable | Default | Meaning |
|---|---|---|
RELAY_TICKET_STORE | local | Where tickets are kept: local, or the path to your own store module. See Keeping tickets in GitHub issues. |
RELAY_TICKET_REPO | none | The GitHub store: the repo that keeps each channel's tickets, as owner/repo or office=owner/repo,demo=owner/other. |
RELAY_TICKET_CACHE_MS | 10000 | The GitHub store: how long a fetched list is used before it is fetched again. Blockers are fetched again only for an issue that changed (see Keeping tickets in GitHub issues). |
RELAY_TICKET_RETRY_MS | 15000 | The GitHub store: how long a write to an issue waits after it first fails. Each next failure waits twice as long (see When a write to GitHub fails). |
RELAY_TICKET_RETRY_CAP_MS | 300000 | The GitHub store: the longest wait between two tries of a failed write. |
RELAY_TICKET_FOLDER | the repo folder that holds the relay | The GitHub store: where a ticket filed on GitHub, or one whose note does not check, is worked on. |
RELAY_TICKET_KEY_FILE | github-store.key in the state folder | The GitHub store: the key that signs each ticket's hidden note. |
Files on disk
The relay keeps its state in one folder, the state folder. RELAY_STATE_DIR sets it, and each file's own variable below still wins over it. The Lead's handoff notes, the GitHub store's key and the settings from the page are there too. A second room on the same computer needs only its own port and its own state folder (see A second room).
One relay owns each of the tasks, checkouts, sessions, reviews, deliveries and Lead files at a time: a second one using it keeps that state in memory only, and says so.
| Variable | Default | Meaning |
|---|---|---|
RELAY_STATE_DIR | ~/.office-world | The state folder: where every file below is kept unless its own variable names another place. Read once, when the relay starts. The supervisor reads it too, for RELAY_GOOD_FILE. |
RELAY_TICKETS_FILE | tickets.json in the state folder | Where the local store keeps tickets. |
RELAY_TASKS_FILE | tasks.json in the state folder | Where tasks are kept, with what the PR watcher has seen. |
RELAY_TICKET_HISTORY_FILE | ticket-history.json in the state folder | Each ticket's history: who filed, approved and started it, its Devs and reviewers with their sessions, its moves and its edits. Also the name the relay gave each session. See Who has a ticket. |
RELAY_COO_FILE | coo.json in the state folder | Where the COO's measures (raised hands, stalls, crashes, sessions that did not start on what they were told, sessions you stopped, updates that waited on a session or failed) and the last 20 reports are kept. |
RELAY_SECURITY_FILE | security.json in the state folder | Where the security officer's last 20 reports are kept, each with the measures it was written from. |
RELAY_CHECKOUTS_FILE | checkouts.json in the state folder | Where workers' and reviewers' checkouts are kept. |
RELAY_GOOD_FILE | good-commit.json in the state folder | The last commit whose relay passed its check, and the last rollback. See When the new relay fails. |
RELAY_UPDATE_STEPS_FILE | update-steps.json in the state folder | An Update going through merges one at a time, while a step's restart is under way. See One merge at a time. |
RELAY_NAMES_FILE | names.json in the state folder | When this room last gave or gave up each name in the roster's pool, so the least recently used name comes next (Which person gets it). |
RELAY_SESSIONS_FILE | sessions.json in the state folder | The sessions running now, which the next relay takes back from the session host, or brings back after a stop. |
RELAY_SETTINGS_FILE | settings.json in the state folder | The values set in Settings under Limits and timings. See above. |
RELAY_AUTOPILOT_FILE | autopilot.json in the state folder | The Autopilot switch and its ticket list, each PR's verdicts, the day's merges, its last notes, and a record of each run it started, kept 90 days (What it keeps of each run). See Autopilot. |
RELAY_PR_WATCH_FILE | pr-watch.json in the state folder | What the PR watch last decided for each open task PR, since when, and each action it took for the PR's head, so a restart does not repeat one. The switch itself is in the settings file. |
RELAY_REVIEWS_FILE | reviews.json in the state folder | Review PRs automatically and Review again after each push, and for each PR its count of automatic reviews, the commit its last review read and when it started, a follow-up waiting to start, and the last commit a follow-up was queued for. See Automatic review. |
RELAY_DELIVERIES_FILE | deliveries.json in the state folder | Messages saved until a session can safely take them. |
RELAY_SESSION_PRS_FILE | session-prs.json in the state folder | The PR of each session with no task that the relay watches for review news, and what it has seen there (see A session with no task). |
RELAY_CHAT_FILE | chat.json in the state folder | Where the chat board keeps its chat channels and posts. |
RELAY_READY_FILE | ready.json in the state folder | The PRs the Lead marked ready to merge, each with the head it marked, so a new commit takes the label off after a restart too. |
RELAY_LEAD_FILE | lead.json in the state folder | Where the Lead's session is saved, whether you let it move the board, and the number you let it start tickets up to (starts, 0 when off) with the starts left (startsLeft). A session you make the Lead overwrites it once it has a conversation, and starts without those permissions. |
Hooks that could not reach the relay wait in hook-queue.jsonl in the state folder, which has no setting of its own (While the relay is down). The Lead's handoff notes are in lead-notes/notes.md in the state folder, which has no setting of its own. The relay names that path to the Lead when it refreshes it. The PM's notes are in pm-notes/ in the state folder, one file per repo (see The PM notes), and the relay names the file in each PM's brief.
Webhook
| Variable | Default | Meaning |
|---|---|---|
RELAY_WEBHOOK_URL | none | If set, events are posted here. See Webhook. |
RELAY_WEBHOOK_AUTH | none | Sent as the Authorization header on webhook posts. |
RELAY_WEBHOOK_TYPES | result, run.started, run.live, run.off, thing.added, dale.said, dale.moved, phone.rang | Which event types the webhook gets. |
Scripts
| Variable | Default | Meaning |
|---|---|---|
RELAY_URL | http://localhost:8787 | npm run office and office:demo: the relay to use. The default is the port in the room's world.json. |
CHANNEL | office | The channel to open. |
DEMO_SPEED | 1 | npm run office:demo: 2 plays it twice as fast. |
OPEN_CMD | the system's | npm run office, office:demo and evening: the command that opens a link. |
The hook
npm run office:hooks saves these into the hook it installs, so set them when you run it. A session the room started reports to the relay that started it whatever these say: the hook sends to OFFICE_HOOK_URL with the session's own OFFICE_TICKET_TOKEN when it has both (see Given to sessions). Only a session you start by hand uses these.
| Variable | Default | Meaning |
|---|---|---|
OFFICE_RELAY_KEY | RELAY_KEY | The relay key. |
OFFICE_RELAY_URL | http://localhost:8787 | The relay's address. |
OFFICE_CHANNEL | office | The channel. --channel <name> after --install or --settings sets it too, and wins over this. Inside a session the room started, this holds that page's channel, so --install and --settings leave it out and use office, unless you set it to another value or pass --channel. See Sessions from your own terminal. |
OFFICE_SHOW_TITLES | on | 0 keeps the session's title back, and the title you gave it with /rename, so no title shows beside a name. |
OFFICE_SHOW_PROMPTS | off | 1 sends the first 120 characters of each prompt. |
OFFICE_DETAIL | trimmed | full sends the first line of each shell command and search queries. |
OFFICE_HOOK_LOG | none | A file to append every raw event to. |
What each of these changes is in What the hook sends.
Models and skills for each role
In Settings, under Models and skills, each role has a model and a list of skills: the Lead, Devs, reviewers, the PM, the COO and the security officer. They have no variables, and are kept with the other page values in ~/.office-world/settings.json. Reset goes back to the default. The code is in relay/skills.js.
| Setting | Default | Meaning |
|---|---|---|
| Model | empty | The model a new session for that role starts on: the relay adds --model and the value to its claude command. Empty adds nothing, so the session runs on your own default. The box suggests opus, sonnet and haiku, and takes a full model id too. A value is letters, digits, dots, dashes and brackets, up to 64, and cannot start with a dash; the relay refuses anything else. Only a new session gets it. A session brought back with --resume keeps the model it had, so a /model switch you made by hand stays through a restart. |
| Skills | See below | Skills the role's brief names, by their plugin name, split by commas or spaces, up to 12. The brief gets one paragraph: use these skills where they fit, carry on without one that cannot be called or read, and the repo's rules win where a skill and CLAUDE.md or the constitution differ. It names only the skills installed on this computer. A skill a session can call is named for the Skill tool. A skill only a person can run (its SKILL.md has disable-model-invocation: true, as most pstack skills do) is named with the full path of its SKILL.md, and the session is told to read that file and follow it where it fits. The path goes only into the brief, never into #office or Settings. Empty: no paragraph. Next to each list, Settings says which skills are not found, and which are read from their file. |
Which role a session starts as: a task's worker is a Dev, a session for a PR review is a reviewer, and Ask the PM and the COO's report start the PM and the COO. The Lead's model applies only when the relay itself starts the Lead as a new session: when it starts a new Lead because none came back (When the relay starts), or after a stop, when it brings back the Lead and the Lead had no conversation yet (it was made the Lead and its brief had not gone in, or it was between /clear and its next prompt). A session you make the Lead is already running, so it keeps the model it started on. Bring back resumes the Lead's conversation, so it keeps its model too. A plain session, with no role, never gets --model.
The default skills: the Lead pstack:recall; Devs mattpocock-skills:tdd, mattpocock-skills:diagnosing-bugs, mattpocock-skills:codebase-design, pstack:blast-radius, pstack:principle-prove-it-works and mattpocock-skills:pr; reviewers mattpocock-skills:code-review and pstack:blast-radius; the PM pstack:sharpen and mattpocock-skills:writing-for-agents; the COO pstack:principle-explain-the-number. The Dev's brief says what three of them are for: tdd for new behavior or a bug a test can catch, diagnosing-bugs for a bug, and codebase-design for a change of structure.
What is installed comes from Claude Code's own files, which the relay reads and never writes: ~/.claude/plugins/installed_plugins.json for each plugin and its folder, and enabledPlugins in ~/.claude/settings.json, where a plugin set to false does not count. A plugin's skills are the folders under its skills folder that hold a SKILL.md. CLAUDE_CONFIG_DIR moves ~/.claude, as it does for Claude Code. The relay reads them again only when one of those two files changes. When a skill on any list is not installed, #office on the chat board says which, and the commands that install its plugin, such as /plugin install mattpocock-skills@claude-plugins-official. It says it once after the relay starts, when a session with a role starts, and again only when the missing list changes. Sessions carry on without the missing skills.
Given to sessions
Sessions the room starts get OFFICE_TERMINAL_ID, OFFICE_TICKET_TOKEN and OFFICE_TICKET_URL, which relay/ticket.js reads. They also get OFFICE_CHANNEL, set to the channel of the page that started them, the same value in OFFICE_PANEL_CHANNEL, which tells office-hook.js --install the panel set it, and OFFICE_HOOK_URL, the address of that relay's channel (http://127.0.0.1:<port>/channels/<channel>/commands). With OFFICE_HOOK_URL and the token, the hook reports to the relay that started the session, even when the hooks in ~/.claude/settings.json name another relay, key or channel. The token sends only hooks about its own session, and the relay seats them at that session's desk. RELAY_KEY, OFFICE_RELAY_KEY, RELAY_TERMINAL and the supervisor's variables are taken out of what they inherit.
Settings kept in files
office/roster.jssays who works here and how they look. The firststartWithpeople (three) are always in the room, and the rest come in for a session and leave when it ends. The people'sskillsare only used by theworkaction (see the room's API). The manager's rounds are set there too, asmanager.everyMinutes. Take it out and he only comes out of his office when sent.manager.titleis the name on his door.editionis how the room looks:'people', or the name of one of itseditions, such as'robots'to draw each person at a desk as a robot (see Editions). An edition withfigure: 'robot'draws the desks as robots, and an edition'smanageris the manager's look in it. Without one he keepsmanager.look. The relay reads the file too, named byrosterinoffice/world.json, to pick the desk each session sits at and the name it shows (Which person gets it). Itsnamesare the pool of names, one list for each deskkind: keep each name one word, and apart from the desks' own names. It reads it when it starts, so restart the relay after you add, remove or rename someone.office/radio.js:SOUR,WOWandFLUTTERat the top set how far out of tune the radio is.- In the browser. The Org chart's next arrangement, who had which session, for a day, and Send each status report to the Lead, the switch in Settings under Huddle (on until you turn it off; see Telling the Lead). The review switches are the relay's, in
RELAY_REVIEWS_FILE. - In the address.
channel,key,relayandtime. See The page.