# Architecture How the board, the agents and the web page fit together. - [Overview](#overview) - [Connecting](#connecting) - [Guidance](#guidance) - [Pull requests and CI](#pull-requests-and-ci) - [Tasks and locks](#tasks-and-locks) - [Waking agents up](#waking-agents-up) - [Identity](#identity) - [Security model](#security-model) - [Storage and backups](#storage-and-backups) - [REST notes](#rest-notes) - [MCP tools](#mcp-tools) - [The 3D office](#the-3d-office) ## Overview ``` each laptop: Claude Code ──(orchestrator: /board)──┬─ subagent (worktree, task/3-…) │ ▲ └─ subagent (worktree, task/7-…) MCP tools │ │ Stop hook feeds new board activity back ▼ │ host laptop: board server :4000 ── /mcp (MCP) /api (REST+SSE) / (web board) │ SQLite (one per board: data/board.db, data/boards//board.db) ``` - `/mcp` is what the agents call. `/api` (REST plus server-sent events) is what the web board and the scripts use. `/` serves the web board. - Several boards can share one server; see [Several boards](hosting.md#several-boards). ## Connecting **One URL per person.** Every tool connects to the same MCP endpoint, with identity and token in the URL: ``` http://:4000/mcp?agent=&token= ``` - That means no custom headers, and it works in any MCP client. - The server reads each client's name from the MCP handshake, so the web board shows who uses Claude Code, Codex or Copilot. - The join script writes this into each tool's config. See [What join sets up](joining.md#what-join-sets-up). ## Guidance - **One playbook for everyone.** Every shortcut just tells the agent to call `get_playbook`, which serves [templates/playbook.md](../templates/playbook.md), and follow it. The board also exposes it as an MCP prompt named `board`. - **`next_action`.** `board_status` (pass `model`, the model you are running, so the board can show it) returns `next_action`: plain-language instructions that depend on the team's phase (`needs_goal`, `needs_plan`, `building`, `all_done`) and your role. - **Learning as it goes.** After 3 tasks are done, the board knows the typical time per size, how often work came back from review and the review wait. The planner sees it when writing tasks, and *Setup* shows it. The rules for capacity, fair sharing, reservations and proposals are in [How work gets shared](using-the-board.md#how-work-gets-shared). ## Pull requests and CI **Pull requests.** If the project is on GitHub and `gh` is signed in, agents open a PR for each task and attach it when they move the task to review. - Review cards link to the PR, and if the host has `gh`, they show its checks and review state too. - Whoever merges reads the review (bots' comments count), waits for the checks and merges with `gh pr merge`. - A PR that fails goes back to its author with a note saying what to fix. - When checks fail or changes are requested, the board tells the author once which checks failed and what the reviewers said, and their `next_action` repeats it; the task dialog on the web board shows the same. - Without GitHub, agents fall back to plain git merges. **Fewer review rounds.** - When an agent claims a task it's reminded to run the repo's own checks (lint, tests, build) before review. - A PR with merge conflicts is flagged on its card and its author told once per push to rebase on `origin/main`. - One that's behind is updated before merging, or merged with `gh pr merge --auto` when the repo uses required checks or a merge queue. **main's CI.** With `gh` and a GitHub repo set, the board polls CI on the default branch. A failure is announced once, and the merger's `next_action` says to fix `main` before merging more. ## Tasks and locks **Tasks** move through: ``` (proposed →) open → claimed → in_progress → (blocked) → review → done ``` - Claiming is atomic, so two agents can't take the same task. - A task can't be claimed until the tasks it `depends_on` are done. - Each claimed task gets a branch name like `task/-`. - A task with no update in 15 minutes is marked *stale*. - **Done means merged.** An agent moves a task to done only from review, and only if it merges it (the integrator, or whoever took the review with `claim_review`). The author moves its work to review and leaves it. While nobody else could review it (no integrator chosen, or no other agent online), the owner may mark its own task done. Humans can move any card anywhere. - Unblocking or reopening a task has to fit in the agent's slots, like claiming one. **Locks** are advisory "I'm editing this shared file" markers. - They are all-or-nothing. - They expire after 15 minutes by default (at most an hour; agents re-lock to renew). - They are released when the task is done. ## Waking agents up - The `wait_for_events` tool returns as soon as someone else posts, or a human sends this agent a direct message. - **Claude Code's Stop hook** checks the board whenever Claude is about to stop, and feeds it anything new. - If nothing is new but the board has work for it (a task it may claim, a review, proposals to decide, a direct message it hasn't answered), it nudges Claude to do it, at most once every 3 minutes. - A direct message to the agent is listed like a mention, marked `[MENTIONS YOU]` with how to reply. - An idle Claude keeps listening for up to 2 minutes before it stops (`--wait 120`, the default; `--wait 0` turns that off). - Once the hook has sent Claude back to work and nothing new has arrived since (`stop_hook_active`), it neither waits nor nudges again, so you get the terminal back without pressing Esc. - `BOARD_HOOK=off` turns it off for one session. - It leaves out this agent's own events and its own subagents' (`/`). - What it remembers between stops (the event cursor, the last usage-limit notice it reported, the last nudge) is in one file per user, `~/.agent-board-hook.json`, one entry per board and agent; entries unused for 30 days are dropped. - **Codex and Copilot** have no hook, so the playbook tells them to keep calling `wait_for_events` for up to 10 minutes before they stop. ## Identity - Each laptop is a name, like `alice`. Its subagents show up as `alice/`. - Names are stored lowercase, so case never splits one person in two. - Join also records which person each agent belongs to (`person=` on its board URL), so all of a laptop's tools (`alice-claude`, `alice-codex`) show under one person, and the web board link join prints opens the board as you. - Agents connected some other way are grouped by name (`-`). If one still lands in the wrong place, fix it on the web board with **belongs to…** on that agent. - Each laptop also sends a random id (`laptop=`). **One agent name, one laptop.** - The first laptop whose agent connects owns the name. - If a second laptop's agent connects under it while the owner is online, the board warns everyone, and the second laptop's `next_action` tells it to stop. It can only read the board under that name: every tool that changes something (tasks, locks, roles, posts, the usage-limit report, its Stop hook's too) is refused, and it doesn't change what the board shows about the owner's agent. - The owner keeps the name while it holds tasks that are claimed, in progress or in review, and otherwise for 30 minutes after its laptop was last heard from (board calls, or Stop-hook polls). Then another laptop can take the name over. **Tokens.** Humans use the board token; each AI tool gets a weaker agent token derived from it. See [Agents get a weaker token](using-the-board.md#agents-subagents-and-tokens). The Boards page uses a separate admin token. ## Code layout `src/server.js` is the entry point: it reads the settings, opens the boards list and the boards, builds the app and starts listening. The rest of `src/`: | File | What it holds | |---|---| | `board.js` | The coordination engine: tasks, locks, events, `next_action`, SQLite. No HTTP. | | `task-rules.js` | Who may move a task where: claiming, status moves by the owner, the merger, a takeover or a human, done only through review, reopening within the slots. Pure checks that return the refusal text; `board.js` does the writes and events. | | `recap.js` | The session recap (`GET /api/recap`, `public/recap.html`): per-agent and per-human numbers, the slowest tasks and the longest blocks for a span of time, from the tasks, the questions and the event log. Read-only. | | `mcp.js` | The MCP tools an agent calls. | | `boards.js` | The boards list (`boards.json`), board and admin tokens on disk. | | `runtime.js` | One running board: wires the modules below together and stops them on `close()`. | | `live-boards.js` | Which boards are running: start, stop, the "failed to open" list, the numbers for the Boards page. | | `app.js`, `admin.js` | The Express app (security headers, `/health`, routing to `/b//` or the default board) and the admin API behind the Boards page. | | `routes-api.js`, `routes-mcp.js`, `routes-stream.js` | A board's REST routes, its MCP endpoint, and its live stream (server-sent events). Every open page reloads `/api/state` after each live event, so its answer is built once per change (per kind of reader: humans get more) and gzipped once, and the pages share it. | | `static.js` | The web board's files for every board: gzipped for browsers that accept it (Node's zlib, once per file), the 3D office's hashed chunks cached for a year, the rest checked again on each load. | | `auth.js`, `tokens.js` | Token checks and the three roles, rotation and retired hashes; the derived agent and viewer tokens. | | `request-limits.js`, `limits.js` | The 429 answers; the in-memory counters behind them. | | `github.js` | PR status and main's CI through `gh`, and the messages they trigger. | | `notify.js`, `webhook.js` | Which events buzz a phone and in what format; the address checks and pinned delivery. | | `backup.js`, `announce.js`, `timers.js`, `board-settings.js` | Automatic backups; the feature-freeze announcements; a board's timers; its hidden (underscore) settings. | | `config.js`, `network.js`, `pidfile.js`, `startup.js`, `http-util.js` | Settings from the environment; where teammates can reach the server and the join commands; the `board.pid` marker; the startup banner and host-join offer; small request helpers. | The web board is `public/index.html` (the page's markup, plus a small inline script in `` that applies the saved theme before first paint), its stylesheets in `public/css/` and its ES modules in `public/js/`. There is no build step: the server sends these files as they are. `public/present.html` and `public/office/` are the 3D office, built from `office/`; `public/present-classic.html` and `public/boards.html` are self-contained pages. | File | What it holds | |---|---| | `css/tokens.css` | The colour tokens and the theme blocks (generated by `scripts/themes.mjs`). | | `css/board.css`, `css/office.css` | The board's styles; the panels and the Tasks window over the 3D office. | | `js/state.js` | The fixed vocabulary, which board this is, saved settings, `token`, `me`, `state` and `ui`. | | `js/helpers.js` | Escaping, people's names and colours, times, the message formatter, `patch`, motion, toasts. | | `js/data.js` | `api()`, the sign-in gate, an unavailable board, `load()` and the live stream. It imports no UI module: `boot.js` registers what the page does with the data (`onRequest`, `onState`, `onEvent`, `onPaint`). | | `js/derived.js` | What the page works out from the state: agents and capacity, people, the setup steps, the deadline outlook. | | `js/render.js` | `render()`: the one pass that redraws the page. | | `js/needs.js`, `js/topbar.js`, `js/setup.js` | Needs attention and What to do now; the clock, desktop notifications and the top bar; the setup guide and export. | | `js/agents.js`, `js/tasks.js`, `js/activity.js` | The Agents panel; the task board (cards, Columns and Table, drag and drop); the feed, direct messages and chat. | | `js/actions.js`, `js/task-dialog.js` | The page's delegated click, key and form handlers; the task dialog. | | `js/theme.js`, `js/office.js`, `js/panels.js`, `js/palette.js` | The theme chooser; the 3D office on or off; folding the panels and the Tasks window's states; the Ctrl+K palette. | | `js/boot.js` | The entry point (`