Running it

What the room does when you start it, connect sessions, restart it and update it. The commands to type are in office/README.md.

Starting the room

npm run office (relay/office.js) starts the relay if none is running at RELAY_URL, and opens the room on channel office with the command in OPEN_CMD. If no browser opens, open the link it prints, with your relay key in place of <your relay key>. It prints the link with that placeholder, and gives the real link only to the browser, so the key does not land in the log. When it leaves the room running, it prints how to add the hooks for sessions from your own terminal (see Your own terminal), with <your relay key> in place of the key, so the key does not land in the log. For a second room it prints no such line, and says not to add the hooks (see A second room). It counts as a second room when RELAY_URL is not port 8787 on this computer, or the state folder is not ~/.office-world. It sets RELAY_TERMINAL=1 and RELAY_WORLD=office on a relay it starts, so that relay serves the room alone, and other worlds run on relays of their own (see One relay per world). It does not change a relay already running, which it reuses as it is.

npm run relay, with no RELAY_WORLD, serves every world and prints a link for each one it finds (see Worlds):

Relay on http://127.0.0.1:8787
Key: pick-a-long-random-key
Open the office: http://localhost:8787/office/?channel=office&key=pick-a-long-random-key

node relay/server.js is a small supervisor (relay/supervisor.js) that runs the relay as its child. When Update pulls new relay code, the relay exits with code 75 and the supervisor starts it again on the same port with the same key, even a random one. Ctrl+C stops both.

The session host. While RELAY_TERMINAL=1, as npm run office sets, the supervisor also starts the session host (relay/session-host.js). The host runs each session's pty-bridge.py and the claude in it, and keeps each session's last 256 KB of output. The relay drives the sessions through the host, over a socket in a folder only you can open, named to the relay in RELAY_HOST_SOCKET. So a restart of the relay does not touch the sessions: a turn in progress goes on, and the panel shows the same output. When the supervisor stops, it stops the relay first, so the relay saves its list, then the host, which ends every session. If the host stops by itself, every session ends with it, and the relay restarts and brings them back as after a stop. The supervisor and the host load once, so a change to relay/supervisor.js, relay/session-host.js or relay/pty-bridge.py needs a stop and start by hand. The host says which version of its messages it speaks when the relay connects. A host started before the version existed says none, and counts as version 1. When the host's version is not the relay's, as after an Update that changed those messages, the relay's log and the Update panel say so, with the two versions: stop and start the office to use the new host. Until then the relay sends the host only the messages its version knows, and the log names each one it held back, once. A relay started with RELAY_WORKER=1 and no supervisor starts a host of its own, whose sessions end with it. If that host stops, that relay stops too, since nothing would start it again. The relay takes RELAY_KEY out of its own environment when it starts, so no git, gh or Claude Code it runs is given the key.

Old relays. Each relay reads its files once and writes them whole, so two relays on one state folder can erase each other's work. A relay can stay behind: for example, one paused with Ctrl+Z keeps its supervisor and its session host, and its sessions, after its own relay process is killed. So when a relay starts, it lists the other relay/server.js processes with ps (relay/old-relays.js, with the rules in relay/old-relays-plan.js). It looks only at relays on its own state folder, from their HOME and RELAY_STATE_DIR, and for its own world or none. A relative RELAY_STATE_DIR is read against that relay's folder. A relay whose settings ps does not show is left alone. A supervisor with no relay process left, for the same relay/server.js on the same HOST and port, is an old copy of this relay: it cannot answer, so the relay stops it before it brings its sessions back. A relay that still has its relay process is never stopped this way, and nor is one on another HOST, since two relays on one port with different addresses can both listen. It sends SIGTERM and then SIGCONT, so a paused copy wakes up to stop and stops its session host, and after 10 seconds it kills what still runs. Any other relay on the folder, such as one from another checkout, port or HOST, is only named: the log says so, and Needs you has a line for it with a Stop button. A second room on its own state folder (see A second room), and the test relays, which each have their own HOME, are not touched. A paused old copy does not answer hooks, since it has no relay process on a port. A session in its host goes on running, and its hooks reach the new relay on the same port, which does not know its token and refuses them. Nothing types into it, since no relay is connected to that host.

The demo. npm run office:demo plays three pretend sessions (office/demo-session.js), about two and a half minutes in all, with no Claude Code. DEMO_SPEED=2 plays it twice as fast. It starts its relay with RELAY_RESUME=0 and a sessions file of its own in a temporary folder, so it brings no session back and leaves your saved list alone. Without the relay, open office/ from any web server and press Run a demo.

A second room

A second room on the same computer is a second relay with its own port and its own state folder. Nothing else needs to change:

RELAY_URL=http://localhost:8790 RELAY_STATE_DIR=~/.office-world-b RELAY_KEY=another-key npm run office

npm run office starts the relay on the port in RELAY_URL. RELAY_STATE_DIR moves every state file to that folder: tickets, tasks, sessions, the Lead, the Lead's handoff notes and the rest (see Files on disk). Without it, both relays would use ~/.office-world, and the second would find the files owned by the first and keep its state in memory only. The session host is the relay's own, with its socket in a new folder each time it starts, so two relays never share one.

Each relay gives the sessions it starts its own address in OFFICE_HOOK_URL, with the session's token. The hook sends there first, so each room hears only its own sessions, even when the hooks in ~/.claude/settings.json were added for the other relay. Do not run npm run office:hooks for the second office: that replaces the hooks for the first. npm run office says so when it starts a second room, in place of the line that says how to add them. A session you start by hand in your own terminal still reports where those hooks say, which is the first room unless you change them.

The room's name. The sign on the back wall, the heading, the label at the top left of the scene and the page title show the room's name: company in office/roster.js, Building58 unless you change it. To tell two rooms apart side by side, add &name= to a page's address, for example http://localhost:8790/office/?channel=office&key=another-key&name=Room%20B. That page then shows Room B, and its title reads Room B · Building58. The name is cut to 40 characters, and a long one is drawn narrower so it fits on the sign. It changes only that page: the relay, the sessions and other pages keep company. Without name, or with an empty one, the page shows company.

A trailer of the room

Add &trailer to the page's address (or open /office/?trailer) and the page plays a film of about 83 seconds, like a game trailer. It is staged, not real work, and it sends nothing to the relay or to any session. Only the scene shows, full screen, with black bars, and the side panels are hidden. The film brings the whole roster into the room, sets the Light to night, and gives people pretend work, with lines on their monitors. The camera then flies a fixed list of shots: the city out of the window, the neon sign, close-ups of faces and monitors, the coffee machine, someone at the window, a ping pong game, a party with three snapshots in a white frame, the manager walking through, a time-lapse from day to night, and a slow pull-back over the whole room. The film ends on the title over black. Title cards come and go between the shots. While a shot plays, the mouse does not move the camera, and the manager comes only when the film sends him. The film shows the roster's edition, such as the robot edition with edition: 'robots' in office/roster.js, and &edition= in the address changes it for that page. Add &look=baked for the baked look. The film then waits until the baked light for each time of day has loaded, and starts after that. The shot list, the cards and the cues are in office/trailer.js. Reload the page to see it again.

A smooth video. npm run trailer records the film to trailer.mp4, 1920 by 1080 at 60 frames a second, with the baked look. It serves the repo on a local port, opens the page in Chrome with no window, and takes over the page's clock. For each frame it moves the clock on by exactly one frame, takes a picture and sends it to ffmpeg. A slow computer takes longer but drops no frames, so the video is smooth, unlike a screen recording. The room's random choices use a fixed seed, so every run makes the same film, and --seed 7 makes another. Options: --out film.mp4, --fps 30, --width 3840 --height 2160, --look live, and --stills 5,16,47, which saves only those seconds as PNG pictures, to check shots quickly. It needs ffmpeg on the PATH, and Chrome or the Chromium from npx playwright-core install chromium. The music is the trailer's own: an original tune in a mid-1980s synth-pop style: a drum machine with a big gated snare, a walking bass, a choir pad, bell-like electric piano and a lead tune, written as notes in office/trailer-music.js and drawn sample by sample, so it needs no licence. Its parts follow the film: choir and bells over the city, drums and bass from Work hard., the tune softly over the work and in full at the party, a stop for look busy., and one chord that rings over the last frame. node office/trailer-music.js music.wav writes it alone. --audio song.m4a lays your own file under the film instead, --audio-start 12 starts it 12 seconds into the file, and it fades out over the last 4 seconds. Music you bought is yours to watch, not to post: a public video needs music you may share. --silent leaves the music out. While the recorder runs, the room moves by the film's time (run.clock), not the browser's, so people walk at their normal pace however long a frame takes to draw.

The room bar

The bar under the page title holds what applies to the whole room, whichever session the panel shows. On the left, a chip each for Autopilot, the Lead, Reviews and Huddle says what is on, and opens Settings at that section. On the right are Update (see Update, after a merge), Settings, and ?, which opens Roles and how work moves.

Notes about the whole room show once, under the bar: the warning about hooks from another checkout, a reviewer that posted and gave its desk back, sessions that could not come back, checkouts with nobody in them, the Lead's brief still waiting, and the offer to bring back the Lead's last session. Each goes away once it is dealt with.

The Claude Code panel

Type a folder in the Claude Code panel and press Add worker, once per session. The folder starts as the one the session on screen started from, or the relay's own folder when there are none. The relay runs claude (or CLAUDE_CMD) on your computer, with the room hooks for that session only (claude --settings), so you do not need to install anything. Where that session works is in Add worker's copy. To bring back an old conversation, put its id in Resume.

The panel needs python3 (it runs the terminal with Python's pty module, relay/pty-bridge.py) and claude on your PATH.

Only the room page on this computer can use it. The panel can run any command on your computer, so the relay only lets the room page itself use it: the request must come from this computer, to localhost or 127.0.0.1, from the relay's own page. A tunnel, another website or another computer gets 403, even with the key. The panel is off unless the relay starts with RELAY_TERMINAL=1. The Board, Tasks, checkouts and Update follow the same rule.

Clicking someone, in the scene or on the Floor list, shows their session in the terminal beside the room and replays the last 256 KB of it. Every session keeps running while you look at another, and reloading the page reconnects to all of them. Sessions the room starts get OFFICE_TERMINAL_ID, OFFICE_CHANNEL, OFFICE_PANEL_CHANNEL, OFFICE_TICKET_TOKEN, OFFICE_TICKET_URL and OFFICE_HOOK_URL (and a seat in a round of a game also OFFICE_SEAT and OFFICE_PLAY), and RELAY_KEY is taken out of what they inherit.

The Games panel

The Games panel runs a round of a game from GAMES_REPO (see Games). It asks the relay every 2 seconds, like the Tasks panel, and shows what the relay sends. It names no game of its own.

Sessions from your own terminal

npm run office:hooks adds the room hooks to ~/.claude/settings.json, and keeps a copy of the old file as settings.json.before-office. OFFICE_RELAY_KEY=pick-a-key node relay/office-hook.js --settings prints them, to add by hand instead, and node relay/office-hook.js --uninstall takes them out. They report to channel office. To pick another channel, add --channel <name>: npm run office:hooks -- --channel my-project. OFFICE_CHANNEL works too, except the value the room gives a session it started: run inside such a session, npm run office:hooks leaves that page's channel out, so the hooks do not send every session from then on to that one page. npm run office prints the command with --channel when you open a channel other than office. A new Claude Code session then gets a developer, marked other terminal on the Floor list. You can watch but not type. The relay does not run these sessions, so the page seats them itself: each takes the first person the relay has given to nobody, the Lead's desk last. When the relay gives that person to a session of its own, the one from your terminal moves to another free person, or leaves if nobody is free. If the desks run out, the one quiet the longest makes room for a session you add here, and one that is idle for 30 minutes gives its desk back. The page keeps no seats, so after a reload a session from your terminal is seated again by its next hook, and may be someone else.

With these hooks installed, sessions started from the panel use them too, and the panel does not add its own, so no event is sent twice. The panel gives each session OFFICE_HOOK_URL, its relay's address for its page's channel, and the session's token, and the hook sends there first. So a session started from /office/?channel=my-project works at a desk in that room, on the relay that started it, whatever relay, key or channel the installed hooks name. The key the hooks were added with is used only by sessions you start by hand, so add them again if you change the relay's key. A different key is turned away with no message. They also run office-hook.js from the folder they were added from, so add them from the relay's own folder. If they come from another folder, the panel says so under Add worker (see the message).

The hook runs in the background ("async": true), gives up on the relay after one second and always exits 0, so it never slows Claude Code down. If the page is not open, it misses the events, but the relay still keeps the state of each session it runs, and a page that opens later seats those people from it. What it sends is in What the hook sends.

While the relay is down. When the relay does not answer, as during the restart after Update, the hook adds the event to hook-queue.jsonl in the room's state folder, and exits 0 as before. That is the folder in RELAY_STATE_DIR, which a session the room started gets from its relay, or ~/.office-world. So two rooms on one computer each keep their own queue. Each event carries the time the hook ran. When the relay starts, it takes its sessions back, then applies the queued events in the order they happened, then deletes the file. A hook that reaches a relay that is still taking its sessions back waits with them. A hook that gave up just as the relay started is applied when the next hook arrives, or 3 seconds after the start.

Copies of the repo, and branches

Each task and worker gets a separate working copy of the repo, which git calls a worktree and the room's messages call a checkout. They live in the repo's .worktrees folder, which is listed in its own .git/info/exclude, so nothing in the repo changes. The relay keeps the list in RELAY_CHECKOUTS_FILE for workers, reviewers and the PM, and on each task for tasks.

node_modules comes along. Right after it makes a checkout for a task, a worker, a reviewer or the PM, the relay links the checkout's node_modules to the main folder's, as ../../node_modules. So lint and tests run there with no install. It makes the link only when the main folder has a node_modules, the checkout has none, and git ignores the name node_modules there. A node_modules line in .gitignore does that. A node_modules/ line does not, since it matches only a folder, and git would show the link as a new file. Leave the link in place: git does not show it, a commit leaves it out, and Clean up does not ask about it. Removing the checkout deletes only the link, never the main folder's node_modules.

A task checkout gets a stub .env. Right after it makes a task's checkout, the relay writes a .env there with placeholder values, no real keys, and ports of its own. So tests in two checkouts do not use the same port, and a tool that looks for .env finds this file, not the main folder's real one. It takes the names from the main folder's .env and from a committed .env.example, .env.sample or .env.template in the checkout. A value comes only from that committed example, and a name that looks like a key, such as one with TOKEN, SECRET or API_KEY in it, always gets stub. No value of the main folder's .env is copied. Each name that ends in PORT gets a port of its own, in order. A name that starts with an outside service, such as DB_, POSTGRES_, REDIS_ or SMTP_, keeps its example value instead, so the app still finds that service. If no name ends in PORT, the file adds PORT with the first port. The ports are two or more in a row, one per such name, from 41000 to 41999. They are ones no other .env in the repo's .worktrees lists on its # ports line, even one a session changed, and nothing listens on, on 127.0.0.1, ::1 or every address. Two tasks started at the same moment take turns, so they get different ports. The task's brief names them. The relay writes the file only when git ignores the name .env in the checkout and the checkout has none. The last line is a seal: while the file is as the relay wrote it, Clean up does not ask about it. Once a session changes it, Clean up asks.

Where the PM reads. Ask the PM takes the branch of the folder you typed, checks it against the remote the way a task does, and makes a checkout on no branch at the commit a task would start from: the remote's latest commit when your branch is only behind, or else your local branch. The folder you typed keeps its branch, its commit and its files. The relay's log says when the PM reads your local branch and why: there is no remote, the branch is not pushed, the remote could not be reached, or the branch has commits the remote does not. A branch with no commits cannot be checked out, so then the PM works in the folder itself, and the log says that too. The checkout goes when the PM's session ends, unless the PM left files or commits in it, which then wait for Clean up. The room bar lists such a checkout as Checkout for the PM with nobody in it, with its folder. One whose session did not come back after a restart goes too.

Which branch work goes to, in this repo today

Work merges to main. A ticket a worker or the Lead files starts from main, and so does one the PM files when you ask them from a folder on main. Its brief says to open the PR against main, and to push with a plain git push, not quiet or piped. The old office and office-worker-sessions branches are far behind, so if a card shows either as its base, press Change base and type main before you start it.

Every brief names the base the task records, and says it wins over any other branch the ticket text names, unless you tell the worker otherwise in its session. The ticket text does not count as you telling it. The worker opens the PR against that base, and does not reset, rebase or switch its branch onto a different branch, though it may catch up with the base. Old ticket text that says to work from office-worker-sessions is left as it is, so the brief is what keeps the worker on main.

Which branch a ticket starts from

A ticket records its branch when filed, and the card shows it as base. For you, that is the branch of the folder you typed. The PM files against the branch of the folder you asked them from. Any other session, wherever it runs, files against the repo's default branch. That is the branch its origin remote names, if the repo has a local branch of that name. Otherwise it is a local main or master, or else the branch the main folder is on. A folder on no branch, or on a branch whose name a task cannot use, cannot file.

Until a ticket starts, in Triage or Ready, you can press Change base on its card and type another local branch (POST /tickets/{id}/base). A branch that is only on the remote is refused, so fetch and check it out first. The change is also refused while the ticket is starting, or when another open ticket has the same title on that branch. The brief then names the new branch for the PR. Once it has started, its base stays. Filing the same title from another branch makes a new ticket. Old tickets with no recorded base start from the branch the main folder has checked out, and count as the same ticket for that title on any branch.

When a task starts, it checks its base against the remote, and never changes your local branch:

A task

Its copy is <repo>/.worktrees/<name> on branch task/<name>, and only committed work comes across. Tasks outlive a relay restart, and so do their workers, who come back in the same conversation. Clean up keeps the branch, and git refuses if there is uncommitted work. If the copy holds only files git ignores, such as a changed .env or a build folder, but not the node_modules link or an unchanged stub .env, the task names them and asks before deleting them: press Delete them too, or Keep and copy out what you want first. A file that turned up after the question is asked about too.

Add worker

In a git repo, each worker gets <repo>/.worktrees/worker-<id> on a new branch worker-<id>, from what the folder has checked out, and the folder itself does not change. Tick Use this folder to work in the folder instead. Outside a git repo a worker just starts in the folder.

A worker nobody ever pressed Enter for, with no files or commits in their copy, leaves nothing behind. Any other copy stays so its session can come back, and the room bar lists it with Clean up once nobody is in it. As for a task, the page names ignored files and asks before deleting them. A branch with new commits stays, a branch the worker was on stays, and an unused worker-<id> goes.

A reviewer's copy is in Automatic review.

Bringing a session back

The relay keeps a list of the running sessions in ~/.office-world/sessions.json (RELAY_SESSIONS_FILE), with what it knows of each: its title, the title you gave it with /rename, task, role, PR, Lead and board permission, and what hooks last said. A session with no task or role loses its title when /clear or /resume starts a new conversation in its terminal, and keeps it after /compact, which keeps the same conversation. When it starts, it takes back or brings back each one on the list.

A task's worker comes back as Bring back would bring it. The Lead is not briefed again, unless its brief never went in. A session whose hooks never heard a turn, from a prompt, a tool or the end of a turn, has no conversation yet, so it starts a new one in the same folder. That covers Enter at the question about trusting the folder, a session just after /clear, and a new session with no hooks reaching the relay, even if you typed into it. A session after /compact keeps its conversation and comes back in it. A session you stopped yourself, or the Lead stopped, is not on the list and stays stopped, except the Lead. Then, if no Lead came back, the relay brings back the saved Lead, or starts a new one in its own folder (see the Lead when the relay starts). RELAY_LEAD=0 turns that off. To start with nobody, the Lead too, set RELAY_RESUME=0. A relay that starts no session leaves the saved list as it was.

A session that cannot come back, because claude --resume failed or it exited with an error within ten seconds, not from /exit, stays on the list marked failed, and so does its checkout, unless its folder is gone. One you quit yourself does not count. The room bar shows it as Could not come back with its id, and the next start tries again, up to three times. Resume on that line fills in the folder and the id, so Add worker tries now. For a task's worker the button is Bring back, which brings it back as the task, as the tasks list does. Forget takes it off the list (POST /terminals/failed).

Anything that did not come back can still be brought back by hand. Bring back does this for a task. For anything else, put the session's id in Resume and start it in the folder where it first ran, which for a worker with their own copy is that copy. Resume always stays in the folder you give it. With RELAY_LEAD=0, if the Lead's last session is not running after a restart, the panel offers to bring it back, and keeps the Lead's desk until you answer (see the Lead when the relay starts).

Update, after a merge

The relay runs the code in the folder it was started from, so a merge on GitHub changes nothing until that folder has it. Press Update in the room bar. It runs git fetch in that folder (RELAY_UPDATE_DIR) and plans from what came in. The folder itself changes only when Update moves it to the fetched commit with git merge --ff-only: at once for page changes, and just before the relay exits for relay changes. It refuses, and says why, if the folder is not on main, has changes to tracked files, or has commits its upstream does not, so it never merges or overwrites anything. relay/update.js and office/update.js do this.

What the restart waits for. The restart cuts nothing off: every session runs on in the session host, and nothing can be typed into one while no relay runs. A hook sent in the second or two with no relay is not lost: it waits in the hook queue, and the new relay applies it once it has taken the sessions back. What it can lose is what lives only in the relay's memory. So it waits for these:

A session at a question or a permission prompt that nobody has answered does not hold the restart, however long it has been there. Only the relay types into it, so it is still at its question when the new relay takes it back, and you answer it there as before.

While an update waits for a quiet moment, the relay types no saved message into any session, at first. That gives the sessions a chance to finish their turns with nothing new starting, so the update can restart the relay. Saved messages and huddle questions stay in their file. After RELAY_UPDATE_HOLD_MS (10 minutes, Hold messages for an update for in Settings), counted from when the wait began, they go in again as each session is ready, and the update then waits for their turns like any other. In a busy office, Autopilot pulls main after each merge, so a wait can last hours, and a Dev held all that time would not get the review findings or the PR watch's notes meant for it. A wait that takes in a new merge goes on counting from when it began. 0 holds nothing. While the relay restarts, nothing is typed, and what is still saved goes in after the restart.

First briefs are never held while the update waits: a task's brief, the Lead's brief, and a first prompt for a reviewer, the PM or the COO. Each is typed as soon as its session is ready, and the update then waits for its turn like any other. Only the restart itself holds it: one still waiting then, or typed with no turn begun yet, stays saved and goes in after the restart (A first brief, A first prompt).

The update itself never gives up waiting. Once saved messages go in, the wait costs the sessions nothing, and calling it off would leave the relay on old code until the next merge or press of Update. The panel shows what it waits for, and Cancel calls it off. A second press of Update while one is under way is refused.

The panel shows an update under way also when you did not press Update, such as Autopilot's pull after a merge: it looks every 10 seconds. While an update waits, Autopilot goes on, and stops only once the restart begins. When it merges a PR in that wait, it fetches main into the same update, so the restart pulls and runs the newest code. If the relay restarted between two of the panel's looks, the page reloads.

A session running a job holds the restart until its oldest job has run for RELAY_AUTOPILOT_STALL_MS (30 minutes, Give you a stuck task after in Settings). After that it holds nothing, so a command that never ends, such as a dev server, cannot hold the update for good. The restart does not end the job, since the session runs on in the session host.

When the new relay fails

A change that breaks the relay leaves every session with no relay to drive it, including the ones that could fix it. So the supervisor can check each relay it starts, and go back to the last commit that worked. It is off by default. Start the relay with RELAY_ROLLBACK=1 to turn it on, and without it to turn it off. relay/rollback.js does this, and the supervisor loads it once, so a broken relay cannot break it. Turning it on, or a new version of it, needs one stop and start by hand, like any change to the supervisor.

The five questions of article 5, for this switch:

  1. What starts it? The supervisor, each time it starts the relay, while RELAY_ROLLBACK=1. It rolls back only on a start that followed an Update's restart.
  2. What does it read and write? It reads /health with the key, the room page, and the relay's folder with git. It writes good-commit.json, and checks out one commit in the relay's folder.
  3. What does it start next? The relay, once, on the old commit. That relay takes the sessions back, as any restart does.
  4. Where does the person come back in? The panel's note and the terminal after a rollback, and fixing main and checking it out, which Update waits for.
  5. What stops two sessions from doing the same work? There is one supervisor for each relay, and it rolls back at most once in a row.

One merge at a time

When several PRs merge back to back and the new relay fails, nobody can tell which merge broke it, and going back throws away the good ones too. So while RELAY_ROLLBACK=1 is on, the same switch as the rollback, one press of Update, or one pull by Autopilot after a merge, takes main forward one merge at a time, and the loop runs by itself. relay/update.js and relay/update-steps.js do this. With the switch off, Update goes straight to the latest commit, as above.

The five questions of article 5, for this loop:

  1. What starts it? A press of Update, or Autopilot's pull after a merge, while RELAY_ROLLBACK=1. Each later step starts only when the step before passed its check.
  2. What does it read and write? It reads main on origin with git fetch, and good-commit.json. It moves the relay's folder forward one merge with git merge --ff-only, restarts the relay, writes good-commit.json after a step with no restart, and writes update-steps.json while a restart is under way.
  3. What does it start next? The relay, once per step that changes relay files. It starts no session, and every session runs on through each restart.
  4. Where does the person come back in? The panel's progress, Stop after this merge, the note that names the PR that failed and what failed, and fixing main and checking it out after a rollback.
  5. What stops two sessions from doing the same work? There is one relay and one update under way at a time: a second press is refused, and a merge seen meanwhile joins the loop. A run takes at most 20 merges, and it stops at the first failed check.

Without the button, run git pull in that folder, then reload the page, or stop and start the relay for relay changes. Sessions come back either way. GET /update and POST /update are in the routes.

Keeping tickets in GitHub issues

Tickets are kept by a store, relay/ticket-stores/local.js by default, in RELAY_TICKETS_FILE. To replace it, write a module with the same five members, described at the top of that file, and start the relay with RELAY_TICKET_STORE=/path/to/store.js. Your store has to pass relay/test/ticket-store-contract.js. The rules stay in relay/tickets.js, and checkouts and workers stay in relay/tasks.js.

relay/ticket-stores/github.js keeps tickets as GitHub issues. It is a pilot, and it is off unless you turn it on. To turn it on, log in with gh auth login, then start the relay with:

RELAY_TICKET_STORE=relay/ticket-stores/github.js RELAY_TICKET_REPO=owner/repo npm run office

RELAY_TICKET_REPO=owner/repo gives the office channel that repo. To give other channels a repo, use office=owner/repo,demo=owner/other. A channel with no repo has no tickets. Two channels cannot name the same repo, and the relay will not start if they do: a task belongs to one channel, so the other channel would offer Start again on its ticket.

The store calls GitHub with gh api, so it uses your gh login and needs no new key. This gives the relay write access to the repo's issues and labels through that login, which needs the repo scope for a private repo: it opens, edits, labels and closes issues, makes labels, and adds and removes issue dependencies.

What the Board shows maps to GitHub like this:

TicketOn GitHub
IdThe issue number.
Title, bodyThe issue's title and body. The repo, base and who filed it are in a hidden note at the end of the body, which the relay signs.
Triage, Ready, StartedThe labels office:triage, office:ready and office:started. The store makes them the first time it needs them.
DoneClosed as completed.
RejectedClosed as not planned.
PriorityThe label office:priority-high, office:priority-normal or office:priority-low.
Blocked byThe issue's dependencies.

An issue is a ticket only if it has an office: label, in any case. On GitHub, labels are added by people with triage or write access, and also by issue templates and Actions if the repo has them. The author of an issue, and anyone with write access, can edit its text, and a ticket's text becomes a worker's brief. Use a repo where you trust everyone who can do that.

A title or body edited on GitHub is cut to the limits a ticket filed in the room has: 80 and 8000 characters.

The relay signs the hidden note together with the issue number, and reads the note only when the signature holds. So a forged note, an edited one or one copied onto another issue is not read. The key is in ~/.office-world/github-store.key (RELAY_TICKET_KEY_FILE), made the first time it is needed. The key belongs to one computer:

Filing opens the issue with no label, then adds the dependencies, the labels and the note. If a step after the first fails, the relay closes the issue as not planned, so it is not a ticket and a retry does not leave two open. If that close fails too, an unlabeled open issue is left, and you can close it by hand.

Other things to know:

The Board lists the issues once, then uses that list for RELAY_TICKET_CACHE_MS. After that it shows the old list at once and fetches a new one, so a change made on GitHub shows one refresh later. What the relay changes shows at once. Each refresh reads the issue list, one request for each 100 issues. A ticket's blockers take one more request each, so the relay keeps them and reads an issue's blockers again only when the list shows that issue with a new updated time or new blocker counts. Before the relay changes a ticket, it reads that issue's blockers fresh, so it never writes from an old copy. Blockers the relay sets are kept at once, with the time GitHub gives that change.

When a write to GitHub fails. The relay writes to an issue when a ticket changes, such as when it closes the issue of a task that is Done. If GitHub refuses that write, the relay waits before it tries again: 15 seconds after the first failure (RELAY_TICKET_RETRY_MS), then twice as long after each next failure, up to 5 minutes (RELAY_TICKET_RETRY_CAP_MS). While it waits, it asks GitHub nothing for that issue, and any other write to the issue, yours too, fails at once and says when the next try is. So one write that keeps failing uses a few of your GitHub calls each minute, not one at each read of the Board. The Board still reads, and shows the ticket as it is on GitHub. The ticket's card shows one red line, and Needs you shows the same line once: Fix what stops a GitHub write: the relay could not close issue #68. GitHub says: Resource not accessible by integration (HTTP 403). It tries again in 4 minutes. Fix what GitHub names, such as the scope of your gh login. The line goes when a write to the issue goes through, when the relay reads the issue and it already shows what the write wanted, such as an issue you closed by hand, or when the relay reads the issue after the wait. A write the relay still needs, such as closing the issue of a Done task, tries again at the first read of the Board after the wait, and if it fails again, the line comes back with a longer wait. A write you made by hand, such as a new priority, is not tried again: make it again once GitHub takes it. The relay counts the tries until a write goes through, and keeps them in memory only, so a restart tries again at once. A failed filing is not kept this way: see the paragraph on filing above.

Common messages, and what to do

You seeWhat it meansWhat to do
This page's key is not the relay's key, so nothing on this page reaches the relay.The page's address has a key= that is not the key the relay was started with. Every request from the page gets 401, so the Floor, the Board and the Claude Code panel stay empty or off, and Update is hidden. The note shows under the room bar, and the Floor's relay dot says Relay: wrong key. A request with no key at all, from curl or a script, gets Send the relay key as "Authorization: Bearer <key>" or ?key=<key>. instead, and one with a wrong key gets That key is not this relay's key.Open the room with the key the relay was started with (RELAY_KEY). The link npm run office prints has <your relay key> in its place, after key=. To use another key, stop the room and start it again with that RELAY_KEY, then run npm run office:hooks again so sessions from your terminal use it too.
All 9 desks are taken. Stop a session first.Nine sessions are running, finished ones included. Nothing was started, and a ticket stays Ready. An automatic review does not need you for this: it frees a desk by itself when it may (A review frees a desk), and Needs you says when it may not.Find someone on the Floor who says Ready for a prompt and has finished. Click them, then Stop this session.
3 tasks are already being built. Finish one first, or raise the WIP limit in Settings.Three tasks are in Building or Changes requested with a running worker.If one has its PR up, move it to In review. Or stop a worker. Or raise the WIP limit in Settings, under Limits and timings.
waiting for T-1 (on a card)This ticket was filed to wait for another that is not done, so Start is off.Finish or reject T-1.
There is no branch X with any commits. Change this ticket's base on the Board…The branch this ticket starts from was deleted. The ticket is back in Ready.Press Change base on its card, type a local branch that is there, then press Start.
T-3 already has that title on X. What you typed is still here.An open ticket has this title on this branch.Use that ticket, or change the title.
Review waiting, Dev session has ended (on a task)New comments on its PR are saved for the Dev, whose session is gone.Press Bring back. The message goes in once the Dev is idle.
Cannot check the PR for comments (on a task)gh is missing, not signed in, or failing. The relay keeps trying.Run gh auth status in a terminal and fix what it says.
Start again (a button on a card)The ticket says started, but has no task. A start did not finish.Press it.
brief not in yet (on a task)The brief is a first brief: it goes in when the session is ready, and is in only once a hook says a turn began after it. It holds back while Claude Code asks whether to trust the folder. If the session ends first, the brief stays saved.Click the worker and answer the question. If the worker ended, or is stuck, stop them and press Bring back, which starts over with the brief.
Could not start a reviewer: …The rest of the message says why, often desks. It shows for about 15 seconds in the panel's header, above the terminal.For a review you started with Get a review, fix that and press it again. An automatic review tries again by itself: see Automatic review.
… has no remote at github.com, so it cannot review …No remote of this clone is at GitHub, and the relay fetches a PR only into a clone that has one. No reviewer started, and the message is in the relay's log. See Automatic review.Add a GitHub remote, or review from a clone that has one.
… shares no history with …The PR was fetched from its own repo, but it is of another project than this clone, and the room has no clone of the PR's repo of its own. No reviewer started, and the ref the fetch made is gone.Review from a clone of the PR's repo, or file a ticket that names one, so the room uses it.
… has no commits yet, so the relay cannot tell whether …No remote of this clone is the PR's repo, and with no commits there is nothing to compare the PR to. No reviewer started, and nothing was fetched.Review from a clone of the PR's repo, or commit to this one first.
Stop its worker first. / A session is still running in its checkout. Stop it first.Clean up will not pull a copy of the repo out from under a session.Stop that session first.
Git kept the checkout: …That copy holds uncommitted work.Commit it or throw it away, then clean up again.
That session did not come back. Its conversation may be gone.The Lead's saved session could not be resumed.Press Not now and start a new one.
no free desk for session … (in Activity)A session from another terminal arrived with every person taken, so it does not show.Nothing is wrong with that session. Stop one here if you want to see it.
The relay did not answer.The relay has stopped, and every session it ran stopped with it.Start it again with npm run office. It brings back every session that was running. See Bringing a session back.
The relay's folder … is on …, not main / has local changesUpdate pulls only into a folder on main with nothing changed by hand, so it never merges or overwrites anything.In that folder, check out main, or commit or put away the changes, then press Update again.
git fetch … failed / … has commits its upstream does notThe remote could not be reached, or the folder's main has commits GitHub does not.Sort out main in that folder by hand. Update never merges.
main in … has no upstream branch, so Update has nothing to pullThe folder's main does not track a branch on a remote, so Update does not know what to fetch.In that folder, run git branch -u origin/main main, then press Update again.
This only works in a session the room started.relay/ticket.js was run somewhere else, with no token.File from the Board, or from a session started here.
No Board or Tasks panel at allThe page was opened with no channel, or the relay started without the terminal switched on.Stop any relay that is running, then run npm run office and open the link it prints. If a relay is already running, that command reuses it as it is.
The room hooks in ~/.claude/settings.json run …, not this relay's copy (under the room bar)The global hooks were added from another copy of the repo, such as an old worktree. Every session runs that copy's office-hook.js, so hook fields added since then never arrive, and the features that need them fail with no message. The relay checks ~/.claude/settings.json each time the page asks, and shows nothing when no global hooks are installed. It sends the page only the paths, never the key the hooks hold. A hook written by hand with a relative path to office-hook.js is not checked, since the file it runs depends on the folder each session starts in.Run the command the warning shows, with your relay key in place of <your relay key>. It runs npm run office:hooks from the relay's own folder, which replaces the old hooks. Then start new sessions: running ones keep the hooks they started with.
Sessions run, but people never go to workTheir events are not reaching the room. Hooks added earlier keep the key from that time, and a different key is turned away with no message.Run npm run office:hooks again with the relay's current key. New sessions then report.