The map
Four places, with you at the top. The relay is the hub: it runs every Claude Code session as a child process, hears every hook, serves the page, and is the only part that talks to the page. GitHub is reached through gh and git, with your own login.
The page never runs anything
It asks the relay. Even Refresh the Lead is a request: the relay does the typing, because only it knows whether a prompt is safe to type into.
The relay drives every session
Sessions run in the session host, which the supervisor starts. The supervisor restarts the relay after Update, and the new relay takes each session back, still running. Stop the relay and they stop, and the next start brings each back with claude --resume. See Bringing a session back.
Sessions are plain Claude Code
They get a brief typed as their first prompt, a token for ticket.js, and their own checkout. The relay's key is taken out of what they inherit.
GitHub is the outside world
Code leaves the computer only as branches and PRs. The relay reads PRs, comments and CI with gh, and writes issues only if the GitHub ticket store is on.
A ticket's life
One ticket, from idea to running code. Each step sits in the lane of whoever does it. Dashed steps are the ones a person still does, or that need a switch you turn on. The Board's side of this, column by column, is in The life of a ticket.
What each step leans on
| Step | Who | What makes it happen |
|---|---|---|
| 2. PM files | PM session | POST /tickets/ask starts the PM, which files with relay/ticket.js. New tickets land in Triage. |
| 3. Ready | You, or the Lead | The Board, or ticket.js move with the Lead's token, only while you allow Let the Lead move the board. |
| 4 to 5. Start | You, or the Lead | POST /tickets/{id}/start: a git worktree in .worktrees/, a task/… branch, a worker session, and its brief, typed only once the session is ready. At most 3 tasks build at once (RELAY_WIP_LIMIT). The Lead starts only while you allow Let the Lead start tickets, within its limits. |
| 6 to 8. PR and first review | Dev, relay | After gh pr create, the hook sends the PR link. The relay records it on the task, and starts a reviewer in its own checkout of the PR head, while Review PRs automatically is ticked. The page need not be open. |
| 9. Reviewer leaves | Relay | The hook reports a gh pr comment or gh pr review that worked, and the relay ends that reviewer about 30 seconds after its turn. |
| 10. Dev is told | Relay | relay/pr-comments.js checks each task's PR about once a minute. News goes to the Dev as links, never as the comment's words, and only when the Dev is idle. The task moves back to Changes requested. |
| 12. Follow-up review | Relay | When a reviewed PR's latest commit on GitHub is not the one its last review read, with or without the push's hook, once the Dev's turn ends and no review of that PR is running. At most 3 automatic reviews per PR, counted by the relay. Off until you tick Review again after each push. |
| 13. Merge | You, or the Lead | The Lead may merge only under the merge rung: a review of the current head, blocking and fix-now findings fixed, CI green, GitHub says clean, no decision left that is yours, and never a change to CLAUDE.md, the constitution or the lint rules (eslint.config.js, eslint-local.js). |
| 14. Update | Relay | git fetch for the relay's folder. Page-only changes fast-forward the folder and reload the page. Relay changes wait until no session is in a turn, then the folder fast-forwards and the supervisor restarts the relay, and every session runs on through it. See Update. |
Hooks up, typing down
Two flows keep the room alive. Up: Claude Code tells the relay what each session is doing, through hooks. Down: the relay types into sessions, but only when it is safe. Silence never counts as idle: only a hook says a turn has ended.
Where the hooks come from
Either installed once in ~/.claude/settings.json with npm run office:hooks, pointing at one relay and channel, or, without those, given by the relay to each session it starts with claude --settings. See Sessions from your own terminal.
Why "safe to type" matters
Text and Enter answer whatever is on screen. Typed on a guess, a message could approve a command nobody read, or be joined to what you were typing.
What the page does on its own
Nothing that moves work. The relay starts every automatic review, so they start with the tab closed. The page sends what you press and shows what the relay says.
What the hook sends
relay/office-hook.js trims each event before it leaves the machine:
| Field | What is sent |
|---|---|
| Session | The first 12 characters of the session id, and the name of the project folder. |
| Title | The session's title, at most 60 characters. Claude Code writes it from your prompts, so it says a little about them. If you named the session with /rename, that name is the title, and it is also sent on its own as customTitle. When the newest /rename record in the transcript has no name, customTitle is sent empty. OFFICE_SHOW_TITLES=0 keeps both back: set it when you run --install, which saves it into the hook. |
| Skills and subagents | The skill name, the subagent type and its short description. |
| Files | The path relative to the project, at most 48 characters. |
| Shell commands | The first two words of the first command, for example npm test or gh issue. No arguments. |
| Web | The host name of a fetched URL. |
| Notifications | The message, such as "Claude needs your permission to use Bash". |
| Pull requests | After gh pr create, the PR's address and the session's folder. After a gh pr comment or gh pr review that worked, the PR's number and repo, whether it was a comment, a review, an approval or changes requested, and the comment's link. None of the command's other words. |
| Pushes | After a git push that may have sent commits, only that it ran. A quiet or piped push counts too. A push that sends no commits to a branch does not: see Review again after each push for which ones. |
| Huddle answers | Only the one line that starts with the huddle question's marker, from what Claude Code passes when a turn ends. See Ask idle workers too. |
| Prompts | Nothing, unless you set OFFICE_SHOW_PROMPTS=1. Then the first 120 characters, which go on the monitor, and are the label until the session has a title. |
OFFICE_DETAIL=full sends the first line of each shell command and search queries. OFFICE_HOOK_LOG=/some/file also appends every raw event to that file, which is useful to see what Claude Code sends. Raw events can hold whole prompts and file contents.
How events become work
Each session gets a person (see which person), and each hook event moves them:
| Hook event | In the room |
|---|---|
SessionStart | A person takes the session and goes to their desk. |
UserPromptSubmit | They start work. |
PreToolUse for Skill | The skill goes on their monitor, and becomes their label until the session has a title. |
PreToolUse for Agent (or Task) | A line on their monitor. |
PreToolUse for any other tool | A line on their monitor. A subagent's lines start with ↳. |
PostToolUse | Clears a raised hand. After gh pr create, links the PR on the session's task and can start an automatic review. After an automatic reviewer posts to its PR, its session ends once its turn does (see Reviewers leave). After a git push to a Dev's PR, can start another review. |
PostToolUseFailure | A red line on their monitor. |
Notification | For a permission prompt or a question dialog (AskUserQuestion sends the same permission_prompt), they raise a hand and the board shows "Waiting on you". The relay puts a session at a question only for these kinds of notification_type: permission_prompt and elicitation_dialog. When the event has no notification_type, the relay reads the message, and anything but "waiting for your input" or "idle" puts it at a question. Any other kind, such as auth_success, which can come in mid-turn, leaves the session as it was, so an update still waits for its turn. While they wait they stay in their chair: on their phone, swivelling, leaning back, looking around, with the hand coming back up every so often. |
Stop | They finish and are ready for a prompt. |
SessionEnd | They finish and are free for another session. |
Hooks from another computer are ignored. The relay changes no state, title or message for a hook event unless it came from this computer, because that state decides when anything is typed into a session, the Lead's brief included. Hooks run on this computer and post to localhost, so nothing real is lost. The page still shows such an event. A tunnel that rewrites Host to localhost makes every request look local, so use one that passes its own hostname through.
Typing into sessions
The relay types briefs, saved messages, review news, huddle questions and the steps of Refresh the Lead. Before each one it asks notSafeToType, drawn in the figure above, and checks again right before Enter.
Saved messages (relay/delivery.js, kept in RELAY_DELIVERIES_FILE) are typed only when:
- hooks say the turn has ended,
- nothing has printed for a moment,
- no menu or trust question shows in the last of the output,
- a
❯shows somewhere in the last 16 KB of it, - nobody has left text in the prompt,
- and a hook says a turn began after the last message the relay typed into that session, or 15 seconds have passed since it went in (
RELAY_TOLD_HOLD_MS).
The last rule is there because a hook can come seconds after Enter, and a second message typed before it can sit unsent in the prompt while the turn counts for it. If no turn begins in that time, the next message goes in, and the check below still looks at whether the session started.
A screen with no prompt. An idle Claude Code does not draw its prompt again on its own. After a relay restart, the relay takes each running session back with the output the session host kept, and that can be only status-line updates, with no ❯ in it. Then no saved message would go in. So when a saved message waits on a session that hooks say is idle, and its screen has shown no prompt for a minute (RELAY_REDRAW_AFTER_MS), the relay makes the session draw its whole screen again. It makes the terminal one column wider, then puts the width back at the next output, as dragging the panel's edge would. The size the relay keeps for the session does not change. It does this at most once every 5 minutes for one session. If the prompt still does not show, Needs you names the message after 15 minutes.
Text of 800 bytes or more, such as a brief, goes in as one paste. Typed as plain keys, Claude Code reads a long text about 1024 bytes at a time and keeps only the last piece. Bytes count, not characters, since a letter outside plain English can take two bytes or more. This holds for every message, a session's first brief included. The Lead's brief names ticket.js by its full path, so it is longer when the checkout's folder path is long, and it still arrives whole, however long that path is.
A key you press holds typing until Enter, Ctrl+C or Ctrl+U, even if you deleted what you typed, unless a menu was up when you pressed it. The check runs right before typing. Silence never counts as idle. Saved messages survive a relay restart, and reach a session brought back with the same id once a hook has been heard from it. While an update restarts the relay, nothing is typed, and while it waits for a quiet moment, saved messages are held for a while.
A first brief. A task's brief and the Lead's brief are saved messages too. Nothing else is typed into that session before its brief. The Lead's brief counts as in once it is typed, since a Lead with no hooks reaching the relay is still briefed. A task's brief is in only once a hook says a turn began after it was typed: typed alone does not count, so the task says brief not in yet until then, and the brief stays saved until then. If the worker ends first, the brief waits for that session id: a session brought back with the same id gets it again, and Bring back on a task whose brief is not in starts the worker over and gives it the brief. A relay restart keeps it: a worker that ran on through the restart is watched again from when the brief was typed, and is not typed into twice. Like a first prompt below, a task's brief and the Lead's brief are held by an update only while the relay restarts, not while the update waits for a quiet moment. Refresh the Lead types a brief the Lead still owes at once, with the same checks.
A first prompt. A reviewer's (from Get a review too), the PM's and the COO's first prompts are first briefs too, and each is in only once a hook says a turn began after it, as for a task's brief. Until then it is saved, both as a saved message and with its session. As for a task's brief, an update holds it only while the relay restarts, not while the update waits for a quiet moment (see While an update waits). Two things differ. If its session is not ready for it within RELAY_READY_LIMIT, counted again from when a relay comes back, or the session ends while the relay runs, the relay gives up on it and writes why in its log. And the relay tries it three more times, not once, before it calls the session stuck (below), since Claude Code can drop the Enter that follows a long paste and leave the prompt in its box. A session that ran on through a relay restart is watched again from when its prompt was typed. A session nobody spoke to comes back after a stop with a new session id and a new desk, and its prompt goes with it, typed again there.
A session that does not start. After a saved message goes in, such as review news, a Lead comment or a chat mention, the relay checks that a hook says a turn began within a minute (RELAY_TOLD_CHECK_MS). If none did, it tries once more (three more times for a first prompt), when it is safe to type: Enter if the message still shows since its last Enter, or the prompt cleared with Ctrl+U and the message typed again if it does not. It does not try while a menu or question is on the screen, since Enter would answer it. If no turn begins a minute after its last try, the session is stuck. The relay stops trying and leaves it to you. It never types a message again into a session that began a turn after it.
- The Floor says
stuck: told 27 min ago, did not start, counted from when it was first told, and the next step says why, where the relay can tell from the screen: a menu is open, it is asking whether to trust its folder, someone has text in its prompt, its screen shows no prompt, or the message is still in its prompt, not sent. Otherwise it says the relay cannot tell why.ticket.js floorshows the same, so the Lead sees it. - #office, and the ticket's chat channel, say once that it is stuck and why. For a first prompt they say so, and for a reviewer they name its PR:
Ravi on T-12 did not start on its first prompt, the review of PR #154, so it is stuck: the note is still in its prompt, not sent. The relay stopped trying after 3 more tries. Open its session and press Enter if the prompt is still in its box, or answer what is on its screen. Stopping it drops the prompt.The Floor's next step says the same. A reviewer, the PM or the COO has no task to Bring back, and stopping one drops its prompt, so open its session instead. - Nothing else is typed into a stuck session. Other messages for it wait.
What to do. Open its session on the Floor. Answer the menu or question, or press Enter if the message is still in its prompt. Once a hook says a turn began, it is not stuck, and the messages that waited go in. If the session does not answer, stop it and press Bring back on its task: the message is kept for that session id, so the session brought back gets it once it is idle. A reviewer, the PM or the COO stuck on its first prompt has no task to bring back, and stopping it drops the prompt, so open its session and press Enter there instead. Stuck is kept only in the relay's memory, so a relay restart forgets it (T-53).
Is a session alive. One module, relay/liveness.js, answers this for every session, from all the relay sees of it together: what its hooks last said, when it last printed, and whether its process ended. The Floor, ticket.js floor, Autopilot's stall check, the COO's stall count and huddles all ask it, and none of them reads hooks for this on its own. Its answer is one of these:
- working: in a turn, and a hook came within the stall time.
- quiet: in a turn, no hook for the stall time, but it printed something within that time. The Floor says
quiet: no hook for 34 min, its screen still moves. - stuck: in a turn, with no hook and no output for the stall time. The Floor says
stuck: no hook and no output for 31 min, counted from the later of its last hook and its last output, and its next step waits on you. A session that did not start on a message is stuck too, as above. - gone: its process ended, or it was stopped. It leaves the Floor.
- Out of a turn, it is waiting on you or idle, as its hooks say. A session waiting on you is never stuck, however long: the question is yours.
- job: out of a turn, but a command it started still runs, such as
npm testsent to the background. It is busy, not idle: Autopilot does not count its task as stalled, Update waits for it, and it is not safe to stop, since a stop would end the command. The Floor saysjob: its turn ended 4 min ago, and a command it started still runs, and its desk line saysrunning a job. Once the command ends, it is idle.
How the relay sees a job. Hooks cannot say when a command in the background ends, so the relay reads the process tree instead. Every 5 seconds the session host runs ps once and looks at the children of each session's claude process. A child is a job when it is a shell run with -c that sources Claude Code's shell snapshot (~/.claude/shell-snapshots/), which is how the Bash tool runs every command, or any shell run with -c that has run for a minute. Every other child is a helper and does not count: caffeinate, which Claude Code starts while it works, MCP servers, and hook and status line commands, which end within seconds. The host tells the relay only when a session's jobs change. A session host started before this change does not look, so its sessions are never job until you stop the relay and start it again once.
The stall time is A session is stuck after in Settings, under Work (30 minutes, RELAY_STALL_MS). Only a hook counts as progress. Claude Code's spinner and its timer keep printing while it thinks and while a long command runs, so output says only that the process is alive and drawing. Output never makes a session working. It only keeps a session whose hooks went silent from being called stuck. A quiet session may be thinking, running a long command, or sending hooks that no longer reach the relay, and the relay cannot tell which, so nothing acts on quiet by itself. A quiet session whose output stops too becomes stuck once the stall time has passed since its last output. After a relay restart, the stall time counts again from when the new relay took the session back.
What you see on the page
While a session works, its developer types at their desk with its tool calls on their monitor (edit src/cart.ts, $ npm test). When it needs your permission, they raise a hand and the tab title counts them. When its turn ends, they stretch and go back to the coffee machine, the couch, the window, the bar table or the ping pong table until you give it the next prompt. So the room replaces your terminal tabs. What each sight means for you is in How to tell what is waiting on you.
- Floor: everyone in the room. The Lead comes first, and its row stays at the top of the list while the rest scrolls under it. Then come the others, in the order needs you, working, ready for a prompt, free. Each row says what the person is on, with the ticket first: a Dev shows
T-17 · Review comments reach the Devand a reviewer showsreviewing T-17 · Review comments reach the Dev, followed by the PR if there is room. A reviewer showsReview PR #7until a task has recorded that PR, and for good if no task ever does. The PM's row startsPM:. A session with no ticket, such as Add worker, shows its own title. Click the number to open that ticket on the Board. Click anywhere else on the row to show their session and follow them with the camera. Click again to stop following. Under that, each session the room started has its desk lines. - Needs you: at the top of the Floor, under the Huddle bar, a count and one line for each thing you need to do now. Click a line to open it. See Needs you.
- Scene: each name tag shows what that person is working on, and so do the Org chart and their monitor: the Floor's words without the PR, cut to 60 characters. A note on the wall board starts with its ticket's number. Clicking a person or their tag does the same as the Floor list. The first three people are always there. The rest come in for a session and leave when it ends. When two name tags would cover each other, the higher one moves up above the other, and the tag nearest the bottom of the scene stays on its person. If that pushes a tag off the top of the scene, the tags stack down from the top instead. While the page is hidden, the people still go on with what they were doing, about once a second, so they are in the right place when it shows again.
- Moving the view: drag to turn the scene, and scroll or pinch to zoom. The pad at the bottom right of the scene does the same, in the room and any world that attaches it, for anyone who finds dragging hard. The side arrows take the camera around to the left or right, the up and down arrows raise and lower it, + and − zoom, and the house goes back to the first view. Hold a button to keep going. With a pad button or the scene in focus, the arrow keys, + and - do a step, and Home or 0 goes back. The button between − and + hides the pad and leaves one button that shows it again. This browser keeps the choice, for every world, and with the pad hidden the keys still work with the scene in focus. The pad keeps each world's own limits on how far the camera turns and zooms. In the room it stops the opening glide and following a person, as a drag does. Without WebGL there is no scene, so there is no pad.
- The manager's office: the Manager's office button at the bottom left of the scene puts the view behind the manager at his desk, over his head and out through the glass at the room. Drag, the side arrows or the arrow keys swing it around him, about 70 degrees each way and a little up and down: to the sofa and floor lamp on the left, the files on the right. The view is wider there, and the name tags of people out on the floor are hidden. It stays behind his chair, in front of the pin board, so it never goes through a wall, and + and − zoom only a little. Back to the room, the house, or following a person brings back the room's view. In the room, the view turns around a point on the floor, which a right drag can also slide into the office through the opening. Without WebGL there is no button.
- Activity: its own panel under the scene and the Floor, above the Board, folded like the Board. It lists who started and finished what, prompts, turns and permission waits, newest first, with the count of events on its title line.
- Chat: under the Board, the chat channels and their posts. See The chat board.
- Tasks: each task's state, worker, branch and PR. Click a task to see its worker.
- The manager: someone in a suit works in a glass office off the back wall, behind the glass door under the clock. The room opens with him at work at his desk, and he goes back to it after each round. Between rounds he keeps busy in there: he works at his desk, leans back to think, takes calls at his desk or on the sofa, stands at the glass looking out at the floor, goes through the files, and reads the pin board. The office's floor lamp, desk lamp and ceiling light follow the room's Light: nearly off by day, warm in the evening, and warmer and brighter at night. He never leaves, so they never go out. Only he and the Lead walk into the office. With nothing to do, the Lead sometimes goes in, sits in a guest chair for a moment, and comes back out. The door opens for either of them as they come up to it, and the name on it is
manager.titleinoffice/roster.js. - The manager's rounds: every 6 to 15 minutes, he opens his door, comes out, looks around, and stands behind a few people. Behind most of them he says a line of tech buzzwords, such as "Can we make it more agentic?". He has 100 lines, in
office/manager-lines.js, and says each once in a shuffled order before any comes round again. Anyone without real work hurries to a desk and types until he is back through his door. Sessions that are working or waiting carry on as they were, and the Floor list and tags keep telling the truth. So a person who looks busy may not be. - Editions: an edition is a way the room can look.
editioninoffice/roster.jsnames the one every page shows:'people', or one of the roster'seditions. Add&edition=and a name to a page's address, such as&edition=robots, to show that edition on that page only.&edition=peopleshows people. A name the roster does not have shows the roster'sedition. Only the scene changes: the names, the Floor, the org chart's badge photos and the sessions stay as they are. The trailer shows the roster'sedition, sonpm run trailerrecords it.The robot edition (
robots, withfigure: 'robot') draws each person at a desk as a robot. The manager stays a person, in a 1950s look in muted colours: a gray suit, a white shirt, a narrow dark tie with a clip, a pocket square, browline glasses and a fedora (the edition'smanager). At a party he wears the party hat on top of his fedora. An edition'smanageris his look in that edition, and an edition with none keeps his own. A robot is built on the same joints as a person (office/figures.js), so it walks, sits, types, carries a mug, takes a call on the couch, plays ping pong and wears a party hat the same way. Its lights are its desk'scolorin the roster. Itsdesignsgive each desk one of five designs, by the desk'sid, and each shows the desk's colour in its own place:- Tin Toy (
tin): a 1950s wind-up robot with a red body, ribbed arms, porthole eyes in the colour and a key that turns on its back. - Terminal (
tty): a beige computer with a CRT for a head. Its screen shows lines of code while it works, wide eyes and a question mark while it waits on you, relaxed eyes on the couch and at a party, and a face with a prompt at other times. The text is in the colour. - Visor (
visor): a white humanoid with dark joints and a light band across its visor in the colour. - Ilium Works (
ilium): a factory unit with hazard paint, pistons, a beacon and one camera eye in the colour, after the works in Player Piano. Its chest plate is in the colour. - Pebble (
pebble): a soft, round helper painted in the colour, with a screen for a face. Its eyes focus while it works, grow while it waits on you, and smile on the couch and at a party.
A desk with no design, or one the page does not know, is the Tin Toy. Under reduced motion the key does not turn, the lights do not pulse and the screens hold still, but a face still changes with what the robot is doing.
- Tin Toy (
- Holidays: the room decorates itself for the next holiday, from this browser's date, with no network call. A holiday's decorations go up 14 days before it and stay until the day after it. New Year's runs from Dec 26 to Jan 1, so it follows Christmas, and Christmas ends on Dec 25. On other days there are none. Easter is worked out for each year (the Gregorian computus) and Thanksgiving is the fourth Thursday of November.
- New Year's: streamers on the walls, a Happy New Year banner with the coming year above the windows, and confetti that falls for ten minutes from midnight on Jan 1.
- Easter: pastel eggs on the window sills, the counter and in a basket by the board, and two bunnies.
- The Fourth of July: red, white and blue bunting on the walls, and small flags.
- Halloween: jack-o'-lanterns that glow, cobwebs and two bats.
- Thanksgiving: a cornucopia on the counter, pumpkins, and autumn leaves on the desks.
- Christmas: a tree with lights and a star in the corner by the bike, wrapped presents, and string lights on the walls.
?holiday=halloweenin the address does the same as picking it, and?holiday=offturns them off for that page only. Under reduced motion nothing moves: the bats hang still, the lights stay lit and the confetti lies on the floor. - Light: the scene's light, from the clock (day, evening or night), or pick one.
?time=nightin the address does the same. It changes only the 3D room, never the page's colours. - The baked look:
?look=bakedin the address. Blender has baked the room's light for each time of day: the light that bounces off the floor and the brick, and the soft dark where things meet. The bake covers the parts that never move and are at least 30 cm across, such as the walls, the floor, the desks and the couch. The page swaps those parts for a baked copy. It follows the Light, like the live look: day, evening or night, from the clock or picked. The sun, the moon and the lamps still light everything live, and the sun casts the shadows. People, chair seats, mugs, the ping pong things, screens, signs, glass and anything small stay as they are. The evening sun is lower than in the live look, so it lays the window frames across the floor. At night the lamps do most of the lighting. While the bake loads, the room stays lit live. Before the swap, the page sends the bake's textures to the graphics card and compiles the shaders the swap needs, a few each frame, so the people keep moving. The swap then compiles none. If the bake does not load, the room is lit live and the browser console says why. A part the bake does not know stays lit live. The baked look also draws through three effects, each set for the time of day: bloom, so the bulbs, the neon sign and the windows glow, strongest at night; a haze that grows with distance from the camera, amber in the evening, pale at day and blue at night; and a colour grade that warms the picture (cools it at night), adds a little contrast and darkens the corners.&fx=offin the address leaves the effects out and keeps the bake.office/baked/README.mdsays how to bake again. - Page Light, Dark and Auto: the switch under All worlds, top right, and on the Board tab, sets the colours of everything around the scene: the Floor, Activity, the Claude Code panel's header, the Board, Chat, Tasks, forms and buttons. Auto is where it starts: the page follows your computer's setting, and changes when your computer does. Light or Dark holds whatever your computer is set to, and is kept in this browser. Auto forgets that choice, so the page follows your computer again. The choice carries to the All worlds page, each world's page, this manual and
office/help.htmlwhen the relay serves them from the same address as the room, and tabs that are open follow it. A manual opened from disk or from another port follows your computer. If the browser blocks storage, the choice lasts until the page closes. Three things stay as they are in both modes: the scene and its name tags, which sit on the 3D room; the terminal, which stays dark so Claude Code's colours read and a running session is never redrawn; and the Org chart, a cream sheet. The page switch and the scene's Light do not change each other. - Org chart: you at the top and everyone in the room under you, live, with a badge photo. Click someone to follow them and open their session if it runs here. Under you is the Officers row, in every arrangement: a card each for the Lead, the PM, the COO and security. Each card says what that officer does and what it costs, whether the officer is in now (a session runs in that role) and who sits there, or out. It holds that officer's buttons. Go to follows them and opens their session, and the Lead's card has it for Paul even when no Lead runs. Ask the PM needs an idea: with one typed in the Board's ticket form it does what the form's own Ask the PM does, and with none it opens the Board and takes you to the title box with a hint. The COO's and the security card have Ask the COO or Ask security, and the last report (see The COO). The report shows on the Floor, so these buttons close the chart. An officer shows only in the Officers row, never also in a group below, so the groups hold everyone else: by job is Specialists and Hot desks. The chart holds still while the pointer is over it. In each group, people who need you come first, then working, ready for a prompt and free, as on the Floor, and otherwise in roster order. Reorg rearranges them by job, by project or by what they are doing, and someone has a word to say about it. The next arrangement is remembered in this browser. Open headcount takes you to Add worker. The star goes to whoever has finished the most turns since the page opened or the last reset, and Finish all does not count.
- Finish all: tidies the picture by ending everyone's current work in the scene. It does not stop any session, free a desk or lower a raised hand.
- Throw a party: everyone in the room, the manager too, puts on a party hat in one of six colours, and a cake with five lit candles stands on the coffee table in the lounge. Everyone with no real work walks over and sits on the couch or stands round the table. Someone who is working or waiting on you stays at their desk, in a hat. The party is only a view: no session is stopped, paused or sent text, and the name tags, the Floor list and the boards show the real state the whole time. After a minute of room time, or when you press End the party, the candles go out, the hats come off a moment later, and the guests go back to their desks. Someone who finishes work during the party joins it, and someone who gets work leaves for their desk. The manager does not walk in on a party. If the manager is in when it starts, people put hats on but stay at their desks until the manager leaves. A huddle still works during a party. Ping pong stops when one starts, and nobody starts a game on their own during one, though the
idleaction can still send two people to the table. Someone already on the couch or in the armchair stays there for the party. Under reduced motion the hats and the cake show, but nobody moves and the candles do not flicker. - Radio: six original 1940s-style records in turn, out of tune on purpose and warped like an old pressing.
- The controls under the scene: one panel in three groups. People has Run a demo, Finish all, Throw a party and Org chart. Scene has Light, Holiday, Decorations and Name tags. Sound has Radio. A switch shows a dot, filled while it is on.
What each desk says. Under the name, each Floor row for a session the room started says:
- For a Dev with a task, a status icon with a short label beside it, so it reads without knowing the icons. It says where the Dev's PR stands, and the first of these that holds wins: ✅
mergedordone, ✋waiting on you(its task is in Waiting on you), 🔨building(no PR yet), 🔍being reviewed bythe reviewer's name (orbeing reviewedbefore the page has named them), ❌CI failed, ⏳CI running, 🔧fix requested(its task is in Changes requested, or the latest verdict says fix), 👍review says merge, and otherwise 🕒waiting for a review. A verdict counts only while CI is on the commit it read, so after a push the icon sayswaiting for a reviewagain, even while the card is still in Changes requested. The icon changes at the page's next look, as the relay learns of each step. The Lead, the PM, a reviewer and a session you added have none. - Who reviews whom. A reviewer's row sits right under the row of the Dev whose PR it reviews, indented with a line on its left, and says
reviewing PR #31 forthe Dev's name. That Dev's row saysreviewed byand the reviewer's name, or each name when more than one reviews it. A reviewer whose PR has no Dev on the Floor stays a row of its own and saysreviewing PR #31. The relay pairs them by PR (pairReviewersinrelay/desk.js) and sends the pair with each desk inGET /floor. - What it is doing now:
working,idle 12 min,waiting on youwith the reason, such as a permission prompt,quiet: no hook for 34 min, output still moving,running a job: a command it started still runs,stuck: no hook or output for 31 min, orstuck: told 5 min ago, did not startfor a session that did not start on a message the relay typed (A session that does not start). See Is a session alive. A stuck desk's next step waits on you and says why. - Its ticket's column on the Board, such as
In review, by the same rule as the Board, so a ticket that Needs you names saysWaiting on you. A reviewer shows the column of the ticket whose PR it reviews. The ticket's number above it opens its card on the Board. - Its PR, as a link to GitHub, with the CI state the relay last heard (
CI green,CI running,CI failed,no CI) and the review state (no review yet,review running,review says merge,review asks for fixes,review waits on CI,review waits for a desk,review tries again,automatic reviews used up,automatic review could not start, or for a reviewerreview posted). - One line for the next step and who owns it, such as
Next: Autopilot merges when CI is green,Next: The reviewer reviews PR #31 (reviewer),Next: Waiting on you: constitution changeorNext: Done, safe to stop. A step that startsWaiting on youis in amber. A review that waits on CI, the first one or one after a push, saysreview waits on CI. A Done Dev that cannot be stopped says why, such asDone, not safe to stop yet: it is working. A task in Waiting on you gives the reason Autopilot handed it over, or the note on the move that put it there. A task Autopilot handed to you gives that reason in any column, until you move its card, since the relay can move the card for a new review comment. Safe to stopwith the reason and a Stop button, only when both the stop verdict and the two kinds the Lead stops allow it: an automatic reviewer that has posted, or a Dev whose PR merged or whose task is Done with all its work pushed. The Lead, the PM, a session you added and a Dev still at work never show it.
When any desk is safe to stop, Stop all safe appears in the bar at the top of the Floor with how many. It and each Stop send POST /floor/stop, and the relay asks the same verdict again at that moment, so a desk that started working since the page drew it is not stopped. You stop them, so Let the Lead stop sessions and the Lead's hourly limit do not apply. A stopped Dev keeps its checkout and branch, its task's history says you stopped it from the Floor, and Bring back returns it. The page asks GET /floor every 3 seconds. The relay builds each desk (relay/desk.js) from what it already keeps: tasks, the pipeline it polls, automatic reviews and Autopilot's last look. Drawing a desk asks GitHub nothing, so the CI and review words are as old as the relay's last poll.
Where a label comes from. A worker on a ticket shows T-17 · its title, and a reviewer of that ticket's PR shows reviewing T-17 · its title. The relay works this out (workOf in relay/tasks.js) and sends it as work with each session in GET /terminals, so a reload loses nothing. A worker on a task with no ticket shows the task's title for as long as the task lasts. Otherwise it is the session's title: the one Claude Code writes soon after the first prompt, or your own if you run /rename building worker labels in that session. It appears on their name tag, the Floor list, the board and their monitor at their next event. Claude Code does not document where it keeps titles, so if that changes, the label falls back to the skill or the project folder.
A title you give a session. Run /rename my title in a session the room runs, and my title shows right after that person's name, as Paul · my title: on their name tag in the scene, on their row in the Floor list, and in the Claude Code panel's header when their session is open. This works for every session the room runs: one you added, a task's Dev, a reviewer, the PM, the COO and the Lead. Only a title you set counts. The one Claude Code writes by itself does not show here. The hook sends it as customTitle, and the relay keeps it with the session in sessions.json, so it is still there after the relay restarts, and sends it as customTitle with each session in GET /terminals. More than 30 characters is cut with …, and the whole title shows when you hover over it. It is shown as text, never as HTML. When the label after the name would only say the same title again, it shows the project folder instead. A new conversation in that terminal, after /clear or /resume, starts with no title until its own transcript has one. The page reads it every 2 seconds. A session from your own terminal, which the room does not run, does not show one. The person's name stays as it was everywhere a name is matched, such as an @ mention in Chat, a huddle, node relay/ticket.js stop Paul and the Floor's names.
The room looks like a loft in New York: exposed brick, steel factory windows with water towers outside, cast iron columns, ductwork, Edison bulbs, a coffee bar and a couch. People are built from spheres, cylinders and boxes on a rig of joints (pelvis, spine, neck, shoulders, elbows, hips, knees), posed by joint angles in POSE. They walk on a 15 cm grid with A*, and each plan is a list of steps: stand, walk, face, sit, act.
Guards at each boundary
What stops the room from doing what it should not.
| Boundary | Guard | Enforced by |
|---|---|---|
| Browser to relay | The terminal, Board, Tasks, checkouts and Update answer only the room page on this computer: loopback, a localhost Host, the relay's own Origin, and the key. | Code (localOnly) |
| Session to relay | A session's token lists and files tickets. The Lead's also reads the Floor. A Lead you allowed can also move the board, stop sessions and start tickets, each within its limits. Nothing else. See tokens. | Code, with tests |
| Hook to relay | Events from another computer change no state. The hook sends trimmed fields, and prompts only if you turn that on. | Code |
| Relay to session | Typing waits for notSafeToType. Worker and huddle text reaches the Lead quoted as untrusted. | Code, and the brief |
| Session to GitHub | Sessions run with your gh login. Briefs say never merge (except the Lead's merge rung). Nothing stops gh pr merge but the brief. | The brief only |
| Commits | The pre-commit secret check, which stops a commit that adds a key or password. The same hook then runs lint on the JavaScript files the commit changes, as they are in the working tree, and stops the commit when lint fails. In a worktree with no node_modules of its own, it finds ESLint in the checkout above it. With no ESLint installed, the commit goes through with a note. CI runs the same check on the lines and files a pull request adds since its base, so a commit made with --no-verify, or on a computer without the hook, still fails the pipeline check. Taking the secret out in a later commit makes the check pass, but the key stays in the branch's history, so replace it. A separate Secret scan check, on each pull request, in the weekly run and on a run you start by hand, reads every line of every tracked file in the checkout the same way, skipping binary files, so a secret already on main is found too. It also fails on a tracked .env, .env.local, .envrc or .envrc.local, but not on a .example, .sample or .template copy such as .envrc.example. GitHub does not require it unless you add it to branch protection. secret-check: allow on a line marks a false alarm in all of these, and none of them prints the value it found. CI also runs lint, the tests, and the browser tests of the room page, and GitHub requires the pipeline check on main. Lint also fails on a new comment in relay/, office/ or shared/, outside relay/test/. The comments already there are counted in eslint-suppressions.json, and the counts only go down: npm test fails when a count is higher than at the merge base with main. See README.md. | Checks |
| Notes and memory | The Lead's handoff notes and the PM notes grant nothing. A line that reads like a permission is confirmed with you. | The brief only |
The trust ladder
How much the room is trusted to do alone. The rungs come from article 5 of docs/constitution.md: each is off until you turn it on.
| Step toward running alone | State | Ticket |
|---|---|---|
| First review of every new PR | on | built |
| Review findings reach the Dev | on | T-17 |
| Follow-up review after each push, by the relay | switch, starts off | T-54 |
| The Lead moves the board | your switch | built |
| The Lead merges a reviewed, green PR | on, by your word | T-48; a switch is T-50 |
| The Lead knows the Floor, and who can be stopped | on | T-62 |
| The Lead stops posted reviewers and Devs whose work merged | switch, starts off | T-55, T-92, RELAY_LEAD_STOPS |
| Update goes back to the last good commit when the new relay fails | switch, starts off | T-80, RELAY_ROLLBACK |
| Update goes through merges one at a time, and checks each | switch, starts off | T-81, RELAY_ROLLBACK |
| The Lead starts tickets, a few at a time | your switch, with limits | T-37 |
| The Lead starts a review of a task's PR, through the relay | switch, starts off | T-98 |
Rungs that are not built yet are in article 5 and on the Board, not here.
Two rooms
A second room in a second tab, for a new project, with its tickets as GitHub issues. Run a second relay with its own port and its own state folder (RELAY_STATE_DIR), and, for issues, its own ticket store. A second room has the command.
Why a second relay, not a second channel
A channel is a separate room on the same relay, but the ticket store is set once per relay. Turning on GitHub issues for one channel would turn it on for all of them.
Why a new repo
Tasks work in their ticket's repo, so the new room's branches and PRs never touch 3d. The relay's own code stays in 3d.
Costs
Up to 18 sessions on one computer, and the relay writing the new repo's issues through your gh login.
The code
Where each part lives. It uses three.js r128 from cdnjs and its OrbitControls from jsDelivr (three@0.128.0), and xterm.js for the panel.
| Path | What it is |
|---|---|
index.html | A page that links to the room. |
shared/nav.js | The pad for moving the view in each world. Each world attaches it to its camera controls. |
shared/relay.js | Connects a world page to the relay when it is opened with ?channel=. Uses only window.run. |
docs/manual/ | This manual. |
office/index.html | The page and its styles. |
office/help.html | Points to this manual, for old links. |
office/roster.js | The people and their looks. Edit this one. See Settings kept in files. |
office/office.js | The room, the people, how they walk and sit, their plans, the hook mapping and window.run. |
office/seats.js | What a session's job does to its title. |
office/figures.js | The skeleton every person and robot is built on, the robot designs, and which edition the page shows and how it draws each desk. See Editions. |
office/poses.js | The people's poses, and the way an arm moves at a desk so a hand never passes through it. |
office/holidays.js | Which holiday the room decorates for, from the date. office/office.js builds the decorations. |
office/panel.js | The floor board, the activity feed and the controls. Uses only window.run. |
office/update.js | The Update button in the room bar, talking to relay/update.js. |
office/officers.js | The Ask the COO and Ask security buttons and their last-report buttons, on the org chart's officer cards, and the report on the Floor. The relay's side is relay/coo.js and relay/security.js. |
office/chat.js | The chat board on the page, talking to relay/chat.js. |
office/desks.js | Asks the relay what each desk says, for office/panel.js to draw, and sends each Stop and Stop all safe. |
office/needs-you.js | The Needs you panel on the Floor. The relay's side is relay/needs-you.js, with the rules in relay/needs-you-plan.js. |
office/huddle.js | The Huddle buttons and the report on the Floor. The relay's side is relay/huddles.js, and relay/delivery.js saves messages until a session can safely take them. |
office/orgchart.js | The org chart, with its Officers row and Ask the PM there. Uses window.run, the office:pick event and the Add worker folder field. |
office/radio-songs.js | The radio's six records, as notes. |
office/radio.js | The radio's instruments, its worn speaker and its buttons. |
office/demo-session.js | The pretend sessions, as hook events. Used by the page and by relay/office.js. |
office/tickets.js | The Board, talking to relay/tickets.js, on the room page and in its own tab. |
office/board-model.js | The Board's columns, filter and Done list. To give a new task state a column, add it there. |
office/board.html | The Board in its own tab. See The Board in its own tab. |
office/board.css, office/tokens.css | The Board's styles, and the page's Light and Dark colours, shared by both pages. |
office/ticket-history.js | Draws who has a ticket now and who worked on it, for the Board or any other view of a ticket. |
office/fold.js | Folds the room page's Activity, Board, Chat, Tasks and Games to their title, and keeps the ones you opened. |
office/tasks.js | The Tasks panel, talking to relay/tasks.js. |
office/games.js | The Games panel, talking to relay/games.js. See The Games panel. |
office/reviews.js | Which review Get a review and the automatic reviews start, their briefs, and when a push brings another review. |
office/terminal.js | The Claude Code panel: xterm.js, talking to relay/terminal.js, one session on screen at a time. Its Get a review starts a review by hand. It also fills the room bar: the Settings button, its chips and the office-wide notes. |
relay/server.js | The relay. It also serves the pages. See The relay API. |
relay/supervisor.js | Starts the session host and the relay, and starts the relay again after an update. |
relay/session-host.js, relay/host-link.js | The session host, which runs the sessions' processes so a relay restart leaves them running, and the relay's side of its socket. |
relay/office.js | Behind npm run office: starts the relay if needed, opens the page, and with --demo plays pretend sessions. |
relay/office-hook.js | The Claude Code hook that sends session events to the room. |
relay/terminal.js, relay/pty-bridge.py | Start claude in a pseudo-terminal in the session host for the panel, on this computer only. |
relay/sessions.js | Brings back, when the relay starts, every session that was running when it stopped. |
relay/seats.js | Which person each session is: the seating rules as one function. |
relay/update.js | Update: fetches, waits for a quiet moment, then fast-forwards the folder and restarts the relay, which the supervisor starts again. |
relay/tickets.js | The rules about tickets. Starting one makes a task. |
relay/ticket-history.js | Each ticket's history and who has it now, and the name the relay gave each session. |
relay/ticket-stores/ | Where tickets are kept: local.js by default, or github.js. |
relay/ticket.js | The command sessions use to list and file tickets and to read and post on the chat board, and the Lead to read the floor and how tired it is, move tasks and tickets, start tickets, start reviews and stop sessions. |
relay/tasks.js | Keeps the tasks on disk and gives each a checkout and a worker. |
relay/checkouts.js | Gives Add worker and automatic PR reviews their own checkouts, and takes them away. |
relay/reviews.js | Starts the automatic reviews: the first one, and a follow-up after each push. Keeps their switches and each PR's count. |
relay/pr-comments.js | Watches each task's PR and tells the Dev about new comments. |
relay/needs-you.js, relay/needs-you-plan.js | The one list of what needs you, for the Needs you panel. |
relay/old-relays.js, relay/old-relays-plan.js | Finds other relays on the room's state folder at start, stops an old copy of this relay, and names the others in Needs you (Old relays). |
relay/floor.js, relay/stop-verdict.js, relay/desk.js | What the Floor says about each session, whether each can be stopped, what each desk says, and the stops by the Lead and from the Floor. |
relay/pm-brief.js | The PM's brief, as plain text from the idea and its settings. |
relay/pm-brief-eval.js | Reruns the PM-brief eval in edd-platform after the brief changes, and keeps the change only if the eval did not get worse (The PM-brief eval). |
relay/pm-notes.js | Where each repo's PM notes are, and what the PM's brief says about them. |
relay/lead-brief.js, relay/lead-refresh.js | The Lead's brief, and the steps of Refresh the Lead: handoff notes, /clear, and the notes read back. The relay runs them. |
relay/lead-tired.js, relay/status-line.js | How tired the Lead is: the levels, and the status line of each session the room starts, which prints the level and tells the relay. |
relay/coo.js | The COO: the measures it reads, its session, and its saved reports. |
relay/security.js | The security officer: its session, its saved reports, and the check that a report holds no key. |
relay/access.js | What access the sessions run with, by name only: the security officer's measures. |
relay/session-env.js | The environment each session gets, and the same as names only. |
relay/huddles.js, relay/delivery.js | Huddles, and messages saved until a session can safely take them. |
relay/chat.js, relay/chat-summary.js | The chat board: chat channels, posts, the relay's news, the one note a mention types in, and the summary a ticket's chat channel leaves on its ticket when you delete it. |
relay/test/ | The tests that npm test runs, including the checks on this manual. |
relay/test/browser/ | The tests that npm run test:browser runs: the room page in a headless Chromium, against a real relay with a fake claude. |