Under the hood

How the room keeps its sessions working for hours, and how you see what they do.

Building58 is a room where Claude Code sessions work as a team. Sessions have roles, such as the Lead, the PM, a Dev and a reviewer. A local server, the relay, runs up to 9 sessions at once. This page gives the rules that the relay keeps. Each part links to its code and its tests.

The words on this page

Session
One running Claude Code conversation. The room shows each session as a person.
Relay
The local server that runs every session, keeps the state and serves the room page.
Hook
An event that Claude Code sends to the relay, for example when a tool runs or a turn ends.
Turn
The work that a session does for one prompt, from the prompt to the end of its reply.
Ticket and task
A ticket is work on the Board. Starting it makes a task: a checkout, a branch and a Dev.
Checkout
A separate working copy of the repo. Git calls it a worktree.
Brief
The first prompt that the relay types into a session. It gives the session its job.
Token
What a session sends to the relay instead of the key. It reaches only the routes that its role allows.
Rung
One permission that you give to the room, such as merge. Each rung is off until you turn it on.

All the words are in the glossary.

The map

How the parts of a room connect The room page talks only to the relay. The relay and the session host run inside a supervisor. The session host runs each Claude Code session, and the sessions send hooks back to the relay. State is kept in files on disk, and hooks queue there when the relay is down. Sessions and the relay reach GitHub with gh and git. After a merge, the relay pulls main and restarts on the new code. The room page 3D room (three.js) Claude Code panel Board · Floor · Steps Games · Org chart Asks. Never runs anything itself. State on disk tickets · tasks sessions · the Lead saved messages hook-queue.jsonl good-commit.json ~/.office-world/ supervisor.js: restarts the relay on exit 75 Relay Node, no dependencies, :8787 Routes: local + tokens Delivery: safe to type Liveness Autopilot PR watcher (gh) Game rounds Update + rollback Measures + spend Session host keeps the last 256 KB of each Leadclaude PMclaude Devsclaude Reviewersclaude Each in its own worktree and branch. Game seats run in a sandbox profile. pty-bridge.py runs each one GitHub branches + PRs CI: pipeline reviews + verdicts merge only the commit reviewed HTTP stream start · type · resize hooks: 1 s, exit 0 gh push · gh pr create after a merge, pull main and restart on the new code

Blue: hooks go to the relay. While the relay is down, they wait in a file on disk. Pink: the loop that lets the room build itself. The map comes from the manual page How the room works.

Part 1

Keeping sessions running

Each session is plain Claude Code. The relay gives it a brief, a token and its own checkout. Then the relay keeps the session running through restarts, merges and the relay's own updates.

01

Sessions keep running when the relay restarts

The relay restarts each time it pulls new code. A restart must not stop a session.

  • A supervisor runs two processes: the relay and a session host. The session host runs each claude process and keeps the last 256 KB of its output.
  • To restart, the relay exits with code 75. The new relay takes each session back with no change: the same process, conversation and desk, and the same turn.
  • After a full stop, the relay starts each session again with claude --resume. The session keeps its title, task and role. If a session does not start, the relay tries again at the next start, up to three times.
  • Two relays that use one state folder can erase each other's files. So a new relay finds old relays with ps and stops an old copy of itself.

Code supervisor.js · session-host.js · old-relays.js
Tests session-host · old-relays

02

Hooks do not slow a session, and do not get lost

The relay knows what a session does only from its hooks. So a hook must not slow the session.

  • Each hook runs in the background. SessionEnd is the one exception: it runs before the session ends, with a limit of 5 seconds. A hook waits for the relay for 1 second at most, and it always exits with code 0.
  • The hook makes each event small before it sends it. The event has the first two words of a command and short file paths. It has no prompt text unless you turn that on.
  • If the relay does not answer, the hook adds the event and its time to hook-queue.jsonl. The next relay first takes its sessions back. Then it applies the queue in order.
  • A hook from another computer changes no state. The relay uses that state to decide when it can type into a session.

Code office-hook.js · hook-queue.js
Tests hook-queue · hook-checkout

03

The relay types only when it is safe

Typed text and Enter answer what is on the screen. If the relay types at the wrong time, it can approve a command that nobody read.

  • Before each message, and again before Enter, the relay checks four things. The session is not in a turn. No menu or trust question shows. The prompt has no text that a person left there. The screen stopped changing.
  • Silence does not mean that a session is idle. Only a hook can tell the relay that a turn ended.
  • A message is delivered only when a hook says that a turn started after it. If no hook comes, the relay tries again. Then it marks the session stuck and says why.
  • The relay pastes text of 800 bytes or more in one piece. Claude Code reads typed text about 1024 bytes at a time and keeps only the last piece.

Code delivery.js · typed.js
Tests first-brief · review-typing · delivery-redraw

04

Each task gets its own checkout

Sessions that share one folder write over each other's work. Code that a session wrote must not reach your secrets or the work of another session.

  • Each task, worker, reviewer and the PM gets its own checkout, on its own branch. Your folder does not change.
  • Each task gets a stub .env file. It has no real keys. It gives the task its own ports from 41000 to 41999, so tests in two checkouts do not use the same port.
  • All checkouts on the computer share one test slot for each CPU core. Four checkouts on 10 cores run 10 test files at once, not 24.
  • Seats in a game (part 10) run inside a macOS sandbox profile. A seat cannot read the games, the relay's state, or the folders and transcripts of other seats.

Code checkouts.js · stub-env.js · seat-boundary.js
Tests checkouts · stub-env · test-slots

05

Autopilot starts, reviews and merges work

Autopilot is the part of the relay that moves an approved ticket to merged code. Nobody has to press a button.

  • Every 20 seconds, Autopilot starts the next approved ticket in Board order, one at a time. At most 3 tasks build at once, and the room has 9 desks. When main is red, Autopilot starts nothing.
  • The first review starts after the checks on the pull request pass. The reviewer marks each finding as blocking, fix now or follow-up, and posts a verdict. The Dev fixes the code and pushes. Then a new review reads only the new commits.
  • Autopilot merges with --match-head-commit. It merges only if the last verdict says merge for that exact commit, and every check passed.
  • In two cases, Autopilot gives the task to a person and says why. The first is 2 review rounds that still ask for fixes. The second is a change to the room's own rules.

Code autopilot.js · autopilot-plan.js · merge-hold.js
Tests autopilot · autopilot-stuck · merge-hold

06

The relay updates itself, and can roll back

If a change breaks the relay, no session can continue. That includes the sessions that could fix it.

  • After Autopilot merges, the relay pulls main into its own folder. When no session is busy, it restarts on the new code. This is the loop that lets the room build itself.
  • With the rollback switch on, an update applies new merges one at a time, oldest first. After each restart, the relay has 60 seconds to answer, serve the room page and take its sessions back.
  • If the relay fails that check, the supervisor checks out the last commit that passed and starts the relay there. If that commit fails too, it does not roll back again. It never rolls back over changes that are not committed.
  • The relay and the session host each give the version of the messages that they use. The relay never sends the session host a message that the host does not know.

Code update-steps.js · rollback.js · host-link.js
Tests update-steps · rollback · host-version

07

The Lead's context and memory

The Lead runs for a long time. Its context fills, Claude Code compacts it, and the Lead can forget a decision.

  • The status line of each session shows how full its context window is. The Lead is fresh below 50%, getting tired from 50% to 69%, and needs a refresh from 70%.
  • To refresh the Lead, the relay has it write handoff notes. Then the Lead gets a new, small conversation and reads the notes again.
  • The relay types the Lead's brief again after /clear and after compaction.
  • The PM keeps one notes file for each repo, with at most 40 dated lines. A note is context, not permission. If a line reads like a permission, the PM checks it with you.

Code lead-tired.js · status-line.js · lead-refresh.js · pm-notes.js
Tests lead-tired

08

Tokens and rungs limit each session

Sessions run with your logins. So the limits on a session must be in code, outside the prompt, where that is possible.

  • Each session gets its own token. A Dev's token can list and file tickets, post to the chat board, and report its own hooks and context. All other routes refuse it.
  • The Lead's extra powers are rungs: move the Board, start tickets, stop sessions and merge. Each rung is off until the person turns it on. The rung to start tickets gives a number of starts, and it stops when none are left.
  • Routes that can run commands answer only the room page on the same computer, and only with the key. A request through a tunnel or from another site gets 403.
  • The relay removes its key from the environment of each session. The manual marks each guard as code or as brief only, so the gaps are written down.

Manual What a token reaches · Guards at each boundary
Tests lead-start · lint-ratchet

Part 2

Seeing what sessions do

Nine sessions in nine terminals are hard to follow. The room shows their state as a picture that you can read quickly. Then you can open any session, replay its steps and measure the run.

09

The room shows the state of each session

The relay draws each person in the room from hooks, not from a script.

  • When a session starts, a person sits down. When a tool runs, a line shows on their monitor, and the line is red if the tool fails. When Claude Code asks for permission, the person raises a hand. When a turn ends, the person gets coffee.
  • One module decides if a session is alive. The states are working, quiet (the screen changes, but no hook comes), stuck (no hook and no output for 30 minutes), running a job, and gone.
  • Every 5 seconds, the session host reads the process tree. So a test that runs in the background shows as a job, not as idle.
  • The Floor is the list of all sessions, with the state and the next step of each. The developer view opens the terminal of a session.

See it the guided walk
Code liveness.js · Tests liveness · liveness-relay

10

Rounds run like experiments

The room can play a game from another repo. Each session takes a seat, and the game scores the round.

  • A round has a game, a number of seats, a seed and settings. With the setting Watch none, the screens of all seats stay hidden until the round ends. You can never type into a seat.
  • The game talks to the relay in JSON lines, version 1. No code in the room names a game, and a test checks that.
  • The Steps panel shows what each seat did, from the seat's own transcript: its brief, each tool and what came back. Each step is one row that you can open.
  • Every 5 seconds, the relay prices the spend of each seat from its transcript, by model. The round stops when it reaches its spend limit.

Manual Games
Code games.js · seat-steps.js · Tests games · seat-steps

11

What the relay measures

The goal is a room that does not need you. So the relay measures that.

  • The relay puts each merged run, from start to merge, in one of three groups: merged alone, merged after it got stuck, or needed a person. Review rounds are normal work, not a failure.
  • Your load: each raised hand, the number of hands each day, and the median and longest wait.
  • Recovery: stalls, quiet periods, crashes, and how each one ended.
  • The COO is a session that you can ask for a one-page report, with at most 3 changes for you to approve. Its token can read the measures and tickets and post the report. The relay refuses all other requests from it.

Manual What the relay measures
Code coo.js · Tests coo

12

Evals check each change to a brief

A change to a brief can make a session worse. You do not see that until the session runs.

  • npm test compares the PM's brief to the text that its eval judged last. If you change one word, the test fails until the eval runs again.
  • The eval runs three cases live, with the old brief and with the new brief. A strict ticket rubric judges the results. If a case that passed now fails, the change is refused.
  • The eval runs on my own evaluation platform. Room B, a second room, uses that platform as a new user would.
  • My papers use the same approach. One asks if an eval run is valid. The other asks if you can trust the score of a judge.

Code pm-brief-eval.js · Tests pm-brief-eval
Papers Is This Run Valid? · Can You Trust Your Judge's Score?

13

Small interfaces

A world is a page with window.run. The room is one world. The relay passes commands from curl, a script or a hook to the page, and sends the page's events back. The relay knows no world by name: any folder with a world.json file is a world.

One relay for each world. Each relay has its own port, key and state folder. So a restart or a key in one world has no effect on another world.

Sessions use a command-line tool. ticket.js lists, files, shows and moves tickets. The token of the session decides what it can do.

API reference Relay API, with every endpoint
Manual The relay API and routes · Code server.js · world.js · ticket.js

Take the guided walk Run your own room Read the code