> ## Documentation Index
> Fetch the complete documentation index at: https://docs.building58.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# How a Building58 room works

> The room page, the relay and the Claude Code sessions: what each part does, how hooks report each session's state, and when the relay may type into a session.

A Building58 room has three parts on your computer: the room page in your browser, a relay, and the Claude Code sessions the relay runs. GitHub is the outside world. This page explains what each part does and how they talk to each other.

## The parts

| Part | What it does |
| - | - |
| The room page | The 3D loft, the Claude Code panel, the Board, the Floor and the org chart. The page never runs anything itself. It asks the relay. |
| The relay | A Node server on `localhost:8787` with no dependencies. It runs every session, hears every hook, keeps the room's state in files on disk, and serves the page. |
| Sessions | Plain Claude Code, at most 9 in a room. Each gets a brief typed as its first prompt, a token for the room's ticket command, and its own copy of the repo. |
| GitHub | Code leaves your computer only as branches and pull requests. The relay reads pull requests, comments and CI with `gh`. |

## Hooks up, typing down

Two flows keep the room alive.

**Up: hooks.** Claude Code hooks tell the relay what each session is doing. The hook trims each event before it leaves: the first two words of a command, short file paths, and no prompt text unless you turn that on. It runs in the background, except for `SessionEnd`, which runs before the session ends with a 5 second limit. It gives up on the relay after one second and always exits 0, so it never slows Claude Code down.

**Down: typing.** The relay types briefs, review news and other messages into sessions. Text and Enter answer whatever is on the screen, so a message typed on a guess could approve a command nobody read. The relay types only when hooks say the turn has ended, no menu or question shows, and nobody has text in the session's prompt. It checks again right before Enter. Silence never counts as idle.

## What you see in the room

Each hook event moves the person who holds that session.

| Hook event | In the room |
| - | - |
| `SessionStart` | A person takes the session and goes to their desk. |
| `UserPromptSubmit` | They start work. |
| `PreToolUse` | A line on their monitor. A skill becomes their label until the session has a title. |
| `PostToolUseFailure` | A red line on their monitor. |
| `Notification` | For a permission prompt or a question, they raise a hand and the board shows Waiting on you. |
| `Stop` | They finish the turn and are ready for a prompt. |
| `SessionEnd` | They finish and are free for another session. |

## Is a session alive

One part of the relay answers this for the whole room, from everything it sees of a session together:

* **Working:** in a turn, and a hook came recently.
* **Quiet:** in a turn with no hook for the stall time, but its screen still moves.
* **Stuck:** in a turn with no hook and no output for the stall time, 30 minutes unless you change it.
* **Job:** out of a turn, but a command it started, such as a test run in the background, still runs.
* **Gone:** its process ended, or it was stopped.

Only a hook counts as progress. Output only keeps a silent session from being called stuck.

For every route and setting, see [How the room works](https://building58.ai/docs/manual/how-it-works.html) in the technical manual.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.