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.
- The games. Each folder in
GAMES_REPOwith agame.json, with its name, version and seat range. A game the relay cannot run says why, and is not offered. Under the form, the picked game says in its own words what a round is (itsabout). With noGAMES_REPO, the list says so. The relay readsGAMES_REPOonly when it starts. - Start a round. Pick the game, the number of seats, a seed (or none, for a random one), Watch all or Watch none, and settings as JSON if the game takes any. When the relay refuses, the panel shows its reason, such as a seat count outside the game's range or
no_boundary. One round runs at a time. - While it runs. Each seat, with its person on the Floor, its session id, what it is doing (starting, working, done or ended) and its tokens and spend, and how the seats are kept apart: in their own sandbox, or with no boundary. Under Watch all, Show its screen opens a seat in the Claude Code panel, which says the seat is read-only. When every seat has worked and is idle again, the panel says All seats are done. Press Finish.
- Steps. A seat's screen keeps only its recent output, so Steps shows everything the seat did, from Claude Code's own transcript of its session: its brief, what it said, each tool it ran and what came back, one folded row a step. Claude Code's own notes in a session, which hold your global rules and account, are left out. Under Watch all, Steps opens while the round runs. Under Watch none, it opens when the round ends. After the round, the result and Past rounds have a Steps button for each seat. The relay reads the transcript when you ask, and keeps and logs no copy. See Games.
- The trust question. A new seat asks whether to trust its folder, and Claude Code's first choice is No, exit, so Enter alone ends the seat. Trust this seat's folder sends Down, then Enter, which picks Yes. Trust all waiting seats does that for every seat still on the question. This works under Watch none too, where the seat's screen stays closed. The relay takes these keys only while the seat shows that question.
- Spend. The round shows its spend at API prices: each seat's tokens from its transcript, priced per model, plus any spend the game reports. Seats run on your own plan, so this is what the same tokens would cost on the Claude API, not your bill. A model with no price in the relay is counted in tokens only, and the round names it.
- Finish and Stop. Finish asks the game for its score and reveal, and the panel shows both: the score's
metricsandseats, and the reveal, each as rows of keys and values. A game may say what each number means (itsmetrics), and the panel shows that line under the number. The page keeps them only until you reload it or start the next round. Stop ends the round with no score. Past rounds lists the relay's last rounds with their spend and metrics, asGET /roundskeeps them, with no reveal, and a Steps button for each seat.
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.
- Never older over newer. The relay keeps the time of the last event it applied to each session, and saves it with the session. An event older than that changes nothing. So a queued Stop applies after the restart, but a queued prompt does not undo a Stop that came after it.
- Only what the relay would have taken. A queued event keeps the address it was for, and a hash of the token or key it would have sent, never the token or key itself. The relay applies one only if it was for this relay's port, and its hash is this relay's key, or the token of a session this relay runs, for that session. It drops anything else, such as an event meant for another room, and says in its log how many it applied.
- Limits. The hook adds to the queue only if the state folder is there, which it is once a room has run with it, so hooks installed with no room running keep nothing. The file holds what the hook would have sent (see What the hook sends), only you can read it, and the hook stops adding to it once it is 1 MB. The relay drops events more than an hour old. The time an event carries is when node started the hook, so two hooks that fire within a few milliseconds of each other can carry their times in the wrong order. A queued event changes the session's state, and the page gets it only if it is open then.
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:
- If your branch is only behind, the task starts from the remote's commit, since that is what the PR goes against.
- If your branch has commits the remote does not, the task keeps them, and the brief says the PR will show them.
- If the base was never pushed, or the remote cannot be reached, the task starts from your branch, and the brief says so.
- In a repo with no remote, the task starts from your branch, and the brief says nothing about it.
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.
- After a restart, such as Update's, each session is still running in the session host. The relay takes it back as it is: the same process, desk, conversation and ticket token, its output so far, and the state hooks last gave it, so a turn in progress goes on. It also keeps the time of its last hook, so a session that was idle before the restart is still idle since that hook: the Floor's minutes since its hook, the stall time, and Autopilot's "idle for N minutes" all count from it, not from the restart. The relay's log says
Took backandstill running. A hook sent in the second or two while no relay runs is lost, so a turn that ended then still shows as working until the next hook. A session still running that the relay does not take back, for example because its task is gone, ends. - After a stop, when Ctrl+C or the end of the supervisor ended the host and every session, their conversations are kept. The relay brings back each one with
claude --resume, in the same folder, with the same title, task, role, PR, and Lead and board permission. They get new desks, and keep their session ids. A resumed session keeps the model it had. One that nobody spoke to has no conversation, so it starts a new one in the same place, on its role's model if one is set (Models and skills).A task's worker that was in a turn when the relay stopped, or waiting on you in one, comes back idle:
claude --resumebrings back its conversation, not its turn. So if its task is in Building or Changes requested and has no PR, the relay types one short prompt into it,The relay restarted while you were in a turn, so that turn was cut short. Go on with your task from where you stopped.It is a saved message, so it goes in only once the worker shows its prompt mark and a hook has been heard from it. If a turn begins before then, for example because you typed into it, the prompt is dropped. The relay's log says who got it. A worker that was idle, or whose task has a PR, gets nothing, and so does one taken back still running after a restart, since its turn goes on. If the worker is still idle with no PR after that, Needs you says to prompt it, and if it did not start on the prompt, Needs you says it is stuck.
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.
- Page changes only: the folder moves to the fetched commit, the page reloads, and nothing else stops.
- Relay changes (files under
relay/, tests aside): the relay waits until hooks say no session is in a turn, then moves the folder to the fetched commit and exits, and the supervisor starts it again from the new code, on the same port with the same key. The sessions keep running in the session host through the restart, the new relay takes each one back, and the page reloads once the relay answers. While it waits, the folder is as it was, so the running relay serves the old pages and the global hooks run the oldoffice-hook.js. A merge Autopilot sees in that wait is fetched into the same update. The panel names who it is waiting for, and Call off the restart stops the wait and leaves the folder as it was. Relay files count from the commit the running relay started from, so after agit pullby hand, pressing Update offers the restart even when nothing is new. If a session starts a turn just as the restart begins, or the folder cannot fast-forward then, for example because a file was changed by hand, the restart is called off, the folder stays as it was, and the panel says so. - If the new relay fails, and
RELAY_ROLLBACK=1is on, Update goes back to the last commit that worked. See When the new relay fails. - While
RELAY_ROLLBACK=1is on, Update does not go straight to the latest commit. It goes through the merges one at a time. See One merge at a time. - If the relay does not come back within a minute, for example because the new code fails to start and the rollback is off, the panel stops saying Restarting and points you to the terminal where the relay runs. That terminal says why the supervisor stopped. The supervisor's stop ends the sessions too, and they are saved, so starting it by hand brings everyone back.
- A change to
relay/supervisor.js, the small process that restarts the relay, or torelay/session-host.jsorrelay/pty-bridge.py, which run the sessions, needs you to stop the relay and start it again once. The panel says so. After the restart, if the session host speaks an older version of its messages than the new relay, the panel says that too, until you stop and start the office (the host's version).
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 in a turn. If its turn ends in that gap, its Stop waits in the hook queue, and until the new relay applies it, the session counts as working, so nothing is typed into it.
- Enter pressed in the last few seconds: a prompt you send yourself counts as a turn before its hook arrives.
- A session you answered at a question, while it still prints. Its turn goes on, but no hook says so until its next tool or its end, so the relay still says it is at a question. Claude Code's spinner prints all through a turn, so once its screen has not moved for 5 seconds, as after Esc, it holds nothing. The panel names it as answered its question, so it is in a turn. A new question clears that answer, so the session holds nothing again until you answer the new one.
- A task's brief or a first prompt the relay has typed but not yet sent with Enter. The panel names it as the relay is typing its first prompt.
- Text left in a prompt, until you send or clear it. The new relay would not know it is there, and could type a message onto it.
- A session you have spoken to that no hook has reached, since the relay cannot tell whether it is in a turn. A session just brought back with
claude --resumeis like this until its first hook. - A session running a job: out of its turn, but with a command it started still running, such as
npm testin the background. The panel names it as running a job. - A checkout that Add worker or a PR review is still making.
- A reviewer that has posted its review and is about to leave.
- A refresh of the Lead, until it ends. The panel names it as The Lead (refreshing). It holds the restart even while the Lead is at a question, until the refresh ends or hits its 15 minute limit. While it runs, the relay still types into the Lead during the update, so its steps and the brief
/clearbrings go in. A message saved for the Lead can go in then too, as during any refresh. A refresh cannot start once an update is under way. - An open huddle, until its answer time ends (3 minutes by default). Its questions are saved messages, so they are held as below.
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 check. Within
RELAY_ROLLBACK_SECONDS(60) of each start, the relay must answer/health, serve the room page, and take back or bring back the sessions it saved. A session whose task or folder is gone does not count against it, and nor does one that already failed to come back on an earlier start, since that says nothing about the new code. One that comes back and then ends within seconds is not seen by the check. The check calls the relay at127.0.0.1, or atlocalhostor::1whenHOSTis one of them. A relay bound only to another address never passes, so leaveHOSTat its default while the switch is on. - A pass records the commit of the relay's folder as the last good one, in
~/.office-world/good-commit.json(RELAY_GOOD_FILE), outside the repo, beside the relay's other state, with the folder it came from. A record from a relay in another folder, such as another checkout, is not used. The terminal sayspassed its check. - A fail after an Update's restart, from the button or from Autopilot's pull after a merge, stops the new relay if it still runs, so it saves its sessions, then checks out the recorded commit in the relay's folder, and starts the relay on it. The terminal says what failed and
Rolled back towhich commit. The page reloads when the relay is back, and the panel says which commit failed, why, and which commit runs now. - The folder is then on that commit, not on
main, so Update pulls nothing more, and says so, until you fixmainand check it out there yourself. Autopilot's pulls are refused the same way. Once a branch is checked out there, the panel stops saying the relay rolled back. - Once in a row. If the relay on the old commit fails its check too, it does not roll back again. It keeps running if it can, and the terminal says why.
- Never over your changes. If the folder has changes to tracked files, it does not roll back, and the terminal names the files. A file git does not track stops it only if git would overwrite it. Then git refuses, the folder stays as it was, and the relay starts again on the same new code, which does not roll back again.
- Back to code from before the session host. The supervisor keeps the host and its sessions running through a rollback, unless the commit it goes back to has no
relay/session-host.js. A relay from such a commit does not use the host, and would start each saved session a second time. So after the failed relay has stopped and saved its list, the supervisor stops the host, which ends the sessions, and starts no host for that relay. That relay then brings each session back once withclaude --resume. The terminal sayshas no session hostwhen this happens. A turn in progress stops, as on any stop. - A fail on a start you make by hand, or before any commit has passed, does not roll back: there is nothing to go back from, or to.
The five questions of article 5, for this switch:
- 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. - What does it read and write? It reads
/healthwith the key, the room page, and the relay's folder with git. It writesgood-commit.json, and checks out one commit in the relay's folder. - What does it start next? The relay, once, on the old commit. That relay takes the sessions back, as any restart does.
- Where does the person come back in? The panel's note and the terminal after a rollback, and fixing
mainand checking it out, which Update waits for. - 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 steps. Update fetches, then lists the merge commits on
main's own line between the commit the folder is on and the fetched one, oldest first. Commits pushed straight tomaingo in with the next merge, and those after the last merge are a step of their own. A squash merge or a rebase merge makes no merge commit, so a run of those is one step. Each step is named by its PR, from GitHub's Merge pull request #41, or by its commit. - A merge that changes no relay file, such as one that changes only
office/, needs no restart. The folder moves to it, the relay checks that it still answers/healthand serves the room page, records it as the last good commit, and a page that follows the update reloads. Then the next step goes. Sessions this relay could not bring back at its own start do not count against the step, since it did not restart. If the check fails, the folder goes back to the step before, and the loop stops as below. - A merge that changes relay files waits for a quiet moment, as any restart does, then the folder moves to it and the relay restarts. A page that follows the update reloads once the new relay answers, so it shows that merge's page files too. The new relay waits for the supervisor's check. Once it passes, the next step goes. If it does not pass within
RELAY_ROLLBACK_SECONDSand 30 seconds more, counted from when the new relay took its sessions back, and nothing rolled back, the loop stops and says so. A merge that changesrelay/supervisor.js,relay/session-host.jsorrelay/pty-bridge.pystill needs you to stop the relay and start it once: the panel says so when the loop starts, and again when it ends, unless that merge was the one that failed and went out. - The first failed check stops the loop. The rollback goes back to the last good commit, which is the step before, so only that merge goes out. The merges before it stay in, and the merges after it wait. The panel names the PR that failed, its commit, why it failed, and which PRs are in and which wait. The folder is then off
main, so Update pulls nothing more until you fixmainand check it out there, as after any rollback. - The panel shows the loop's progress, such as Update: 2 of 5, PR 41, and what that step is doing. A page that loads within 10 minutes of the end of an update says how it ended.
- Stopping it. Stop after this merge stops the loop between steps. A step that waits for its quiet moment stops at once, with the folder on the step before it. A step that is going in or being checked finishes first. A restart under way cannot be stopped. The merges that went in stay in, and the rest wait for the next Update.
- The limit. One run takes at most
RELAY_UPDATE_STEPSmerges (20). The rest wait for the next press of Update, and the panel says how many. A merge Autopilot sees while the loop runs joins it as one more step, within the same limit. A merge it sees once a step's restart has begun waits for the next Update. - The loop lives in
update-steps.jsonin the state folder (RELAY_UPDATE_STEPS_FILE) only while a step's restart is under way. A relay that finds a loop there more than 15 minutes old, or on another commit than the step, ends it and says so. One you start by hand within that time, on the step's commit, carries it on once it passes its check.
The five questions of article 5, for this loop:
- 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. - What does it read and write? It reads
mainon origin withgit fetch, andgood-commit.json. It moves the relay's folder forward one merge withgit merge --ff-only, restarts the relay, writesgood-commit.jsonafter a step with no restart, and writesupdate-steps.jsonwhile a restart is under way. - 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.
- 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
mainand checking it out after a rollback. - 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:
| Ticket | On GitHub |
|---|---|
| Id | The issue number. |
| Title, body | The 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, Started | The labels office:triage, office:ready and office:started. The store makes them the first time it needs them. |
| Done | Closed as completed. |
| Rejected | Closed as not planned. |
| Priority | The label office:priority-high, office:priority-normal or office:priority-low. |
| Blocked by | The 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:
- A ticket filed on GitHub, or one whose note does not check, works in
RELAY_TICKET_FOLDER(by default the repo folder that holds the relay's own code), starts from that folder's branch, and shows its GitHub author as who filed it. - When the relay changes a ticket whose note does not check, it keeps that note as it is and logs it. It refuses to change what only the note holds, such as the base. So if the key is lost or changed, the right key reads the tickets again.
- Do not run a second relay, on another computer or with another key file, on the same repo. Each one would see the other's tickets as filed on GitHub, and could not change their base.
- A ticket filed on GitHub has no note, so the first time the relay changes it, the relay signs its folder into a new note.
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 store needs a gh recent enough to have
gh api --slurp, which arrived in 2024. Checkgh api --help. - The hidden note puts folder paths from this computer into the issue bodies.
- A pull request that says "Fixes #12" closes issue 12 as completed, so the Board shows it Done.
- A blocker in another repo is not shown on the ticket, so the ticket does not wait for it.
- Tickets on the local store do not carry over. Their ids, such as
T-21, are not issue numbers. - A ticket you file on GitHub has no approval, so a Lead you let start tickets leaves it for you (see The Lead starts tickets).
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 see | What it means | What 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 changes | Update 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 not | The 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 pull | The 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 all | The 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 work | Their 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. |