Skip to main content

zrb-board

A turn-based board for a human and a coding agent: markdown files that render in a browser, with notes pinned to the paragraph they disagree with.

The design — why markdown is the truth, what a block is, why ink is normalised to its block and why the nudge is a trigger — is in docs/architecture.md.

The agent does not watch the page. It reads /api/docs/<name>/state.md, a plain-text view of the document with every note placed inline, and writes back with a revision-checked PUT. Turns are the clock; the browser is a window.

Install

pip install zrb-board
zrb-board          # http://127.0.0.1:8765

The wheel carries the page — the CSS, the pen and the vendored Mermaid bundle — so an installed board draws diagrams with no network at render time.

Run it from a checkout

cd ~/zrb-board
python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"   # once
.venv/bin/zrb-board                                          # http://127.0.0.1:8765

Your documents are not in this checkout. They live in ~/.zrb/board, the same shape as zrb-avatar's ~/.zrb/avatar:

~/.zrb/board/docs/0001-what-…md      the markdown is the truth
~/.zrb/board/.board/0001-….annotations.json    notes, anchored to quotes
~/.zrb/board/.board/inbox.md         what "Mark for next message" appended

Every setting is an environment variable, $ZRB_BOARD_<NAME> — with the ZRB read from _ZRB_ENV_PREFIX, so a white-labeled zrb needs no code change:

Variable Default What it does
ZRB_BOARD_HOME ~/.zrb/board the folder holding docs/ and .board/
ZRB_BOARD_DOCS <home>/docs the documents folder alone
ZRB_BOARD_META <home>/.board the notes folder alone
ZRB_BOARD_HOST 127.0.0.1 the address to bind
ZRB_BOARD_PORT 8765 the port
ZRB_BOARD_NUDGE unset — off 1 lets an unread mark start a chat turn on its own
ZRB_BOARD_NUDGE_EVERY 15 seconds between the trigger's looks at the inbox
ZRB_BOARD_NUDGE_SETTLE 30 seconds of no new marks before a turn starts

The last three are read by the chat's trigger, not by the server: setting them changes nothing about the board that is serving.

It binds loopback only and has no authentication — it is a desk, not a service.

8765 is quad digits, easy to say and to type, and nothing is registered to it. It only has to stay clear of zrb's web port, 21213, which a board URL is often pasted next to. It is a default rather than a decision: ZRB_BOARD_PORT moves it.

Run it in the background

zrb-board -d        # starts a detached copy, writes ~/.zrb/board/board.pid, exits
zrb-board status    # running or not, which pid, and whether it answers
zrb-board stop      # SIGTERM that pid, and remove the file

-d spawns a second copy of the program with no terminal attached and points its output at ~/.zrb/board/board.log; nothing is left holding it, so closing the terminal does not close the board. On POSIX the child gets a session of its own (start_new_session); on Windows it gets no console (DETACHED_PROCESS) and a process group of its own. Those are the same promise by two names, and it is the only platform difference in here.

What it does not do, on purpose: restart after a crash, or start when the machine boots. Both need a supervisor, and every system ships one — systemd --user on Linux, Task Scheduler on Windows, launchd on macOS. A unit file is four lines:

# ~/.config/systemd/user/zrb-board.service
[Unit]
Description=zrb-board
[Service]
ExecStart=%h/.local/bin/zrb-board
Restart=on-failure
[Install]
WantedBy=default.target
systemctl --user daemon-reload && systemctl --user enable --now zrb-board

The board

~/.zrb/board/docs/0001-what-does-the-board-do-that-chat-doesnt.md   the truth
~/.zrb/board/.board/0001-….annotations.json                          the notes beside it
  • One file per question. Create one by writing the file; the index picks it up.
  • Each contribution is prefixed **Go:** or **Tara:** and nobody edits the other's paragraph, only answers below it — so a softened sentence shows in git diff and a third party can still read the argument.
  • Closed questions move to closed/ rather than being deleted, so the shelf keeps its dates.

Anchors, not coordinates

Every annotation stores the block id, the exact quote, and offsets inside the block. On each render it is resolved in three steps: the named block still holds the quote → the quote is found in another block → nothing matches and the note appears under "the text moved — these lost their anchor". It is never placed somewhere that merely looks close.

The block id is a hash of the block's visible text, so editing a paragraph changes its id; that is what the quote fallback is for.

Strokes are stored the same way: normalised coordinates inside their block (0.0–1.0, x and y), never page pixels. A circle drawn around a sentence follows that sentence through an edit above it, a resize, or a font change. The stored form is ours; Excalidraw's scene format is absolute-coordinate, so an .excalidraw export is a projection made at export time, not the truth.

Drawing and editing

draw turns the page into a surface: drag to ink, erase removes one stroke at a time — a click within 10px of a stroke, not a click on the ink itself. Ink is kept per author, so a drawing of yours and one of mine can sit on the same paragraph without either replacing the other. Erasing the last stroke deletes that author's note on the block rather than leaving a hollow one.

edit markdown puts the raw file in a textarea; save (or Cmd/Ctrl-S) writes it back with the revision you read.

Diagrams

A ```mermaid fence is drawn in place by a vendored mermaid.min.js — no network at render time. A diagram that fails to parse stays a code block with the error on hover, because a blank is worse than its source.

The pen and the diagram are different tools on purpose: ink is geometry pinned to a block and nobody can edit it, while a diagram is text that both authors can change. Reach for the pen when words run out; reach for the fence when the shape itself is the argument.

API

Route Purpose
GET /api/docs the board index
GET /api/docs/{name} html, blocks, and annotations resolved to blocks
GET /api/docs/{name}/state.md the text view the agent reads
POST /api/docs {name, markdown} — 201 with the rev, 409 when the name is taken
PUT /api/docs/{name} {markdown, rev} — 409 with the current text on a stale rev
DELETE /api/docs/{name} the document and its notes together — 409 while a note is open
POST /api/docs/{name}/notes {quote, note, author, near} — locate the quote and store the note in one request; near picks the occurrence when the words stand twice
POST /api/docs/{name}/annotations {block, quote, note, author, start, end}
POST /api/docs/{name}/annotations/{id}/resolve close a note
PUT /api/docs/{name}/ink/{block} {quote, strokes} — replace the strokes drawn on one block
GET/POST /api/inbox the "Mark for next message" marker
POST /api/inbox/retire {upto} — retire the marks up to a stamp, or every mark

The agent's tools

src/board/tools.py is the other side of that table: seven tools an LLM agent calls, in the same tree as the routes they call, so a route that changes here changes its caller in the same diff. Nothing in the server imports them — board.app runs without zrb.

Tool What it does
BoardState the marks waiting, then every document with its revision and its open notes (ink and notes counted apart)
BoardRead one document as text: the view — rev, then each note beside the passage it is about — or, with source=True, the document's own markdown byte for byte, which is the text BoardWrite takes
BoardWrite the whole markdown back, stating the revision that was read; a stale revision writes nothing and returns the current text to merge into
BoardCreate a new document under a name nothing uses; a name that is taken is a 409, never an overwrite
BoardNote a note on a quoted passage — the quote is sent to the board, which renders it where it stands (a table row under its header, a link as its words) and returns the block and the words that block holds; a near hint says which occurrence when the same words stand twice, and the answer says when it had to choose
BoardResolveNote close a note by the id BoardRead shows; ink is refused, because there is nothing to close
BoardRetireMarks retire the marks the work is done for, up to a stamp or all of them — reading the inbox is not answering it

They are registered with zrb by src/board/zrb_init.py, which a shell points at:

export ZRB_INIT_SCRIPTS="$ZRB_INIT_SCRIPTS:$(zrb-board init-path)"

BOARD_URL overrides the address; without it the tools call the host and port the server binds (ZRB_BOARD_HOST, ZRB_BOARD_PORT). BOARD_AUTHOR signs a note, agent unless it is set. The tools read the marker folder as a whole and fold it by document, because nothing ever clears it.

The button is a note, and a nudge you switch on

"Mark for next message" appends one line to .board/inbox.md in the board's home folder — the line names the document, and carries the passage you had selected. The agent reads it the next time it is spoken to, and the convention is that the word board in a message means: read the inbox, then read the state of the open documents.

The board can also start that turn itself. src/board/zrb_init.py registers a chat trigger beside the seven tools (zrb/llm/ui/trigger.py), so with ZRB_BOARD_NUDGE=1 an unread mark becomes a turn with nobody typing: the agent reads the document, answers the passage in the margin beside it with BoardNote, and retires the mark it answered. A mark made with nothing selected has no quotation to anchor a note to, so that answer comes back in the chat, and the trigger says so rather than inventing a quotation.

Four things the trigger is careful about:

  • off by default — a program that starts turns on your behalf should be one you switched on; ZRB_BOARD_NUDGE_EVERY sets how often it looks, 15 seconds otherwise
  • not while you are still marking — nothing is claimed until no new mark has arrived for ZRB_BOARD_NUDGE_SETTLE seconds, thirty by default. A mark is a selection you may be about to replace, or the first of three; the queue waits for the run to finish instead of answering its first item while the next passage is being dragged
  • one turn per mark — each mark is claimed in .board/nudge.json immediately before its own turn, so a restart cannot answer it twice and a chat that stops between turns loses nothing. The claim names the mark by a hash of its own line, never by its timestamp: two marks made in the same second are still two marks, and retiring one leaves the other. A claim is a lease and not a tombstone — it carries the time it was made and expires after ten minutes, so a chat killed between claiming a mark and running its turn costs a repeat rather than a mark. The claim is taken under a file lock, so two chats on one board cannot both answer the same mark
  • the server need not be up — the inbox is read as a file, so a mark left while the board is stopped still becomes a turn

What this section used to say

It said the button could only ever be "a live-context line carrying the unread count", and that making it notify was deliberately not built. That describes the mechanism docs/architecture.md §7 rejects: a line in the prompt is passive, so the mark still waits for someone to speak. The description was wrong before the code was.

Tests

.venv/bin/python -m pytest -q      # storage, anchors, digest, routes
npm test                           # pen coordinate maths (node --test)

Both suites run in CI on four Pythons and on macOS. A pull request opened from a branch of this repository also gets a review posted on it — zrb reads the diff with the model key, from a workflow that pull_request_target resolves out of main, so a branch cannot edit the reviewer that looks at it. A pull request from a fork is not reviewed: the workflow's guard asks for a head repository it cannot be. test_ci.py is what keeps those workflows pinned to commits and to named runner images.

Metadata

Release files for zrb-board 0.2.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for zrb-board 0.2.5
File Size Uploaded Provenance Actions
zrb_board-0.2.5.tar.gz 1.1 MB With provenance Details for zrb_board-0.2.5.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for zrb-board 0.2.5
File Interpreter ABI Platform Actions
zrb_board-0.2.5-py3-none-any.whl Python 3 none any Details for zrb_board-0.2.5-py3-none-any.whl

Total release size: 2.1 MB

Release files / zrb_board-0.2.5.tar.gz

Download URL zrb_board-0.2.5.tar.gz
Size 1.1 MB
Tags Source
SHA-256 checksum
How to use checksums
cb2ab9d2413505bb76487fffe63cf8456c1dea3322734a5705e23272ccdf8df6
BLAKE2b-256 checksum
How to use checksums
b8f2ca01966771a6df82d2fc7a4df9141f089f3caaf36b68733437a4660a1ef7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / zrb_board-0.2.5-py3-none-any.whl

Download URL zrb_board-0.2.5-py3-none-any.whl
Size 1.1 MB
Tags Python 3
SHA-256 checksum
How to use checksums
b5e4fa769c66cd06ffc6f246b1b2c6ed1901d8937515534a2c28a855c5ad4b59
BLAKE2b-256 checksum
How to use checksums
131faddbef1776cc98a2cfb6f6d724eee281f34cfa9b2ba9cb08704a6b00db1e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for zrb-board 0.2.5

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for zrb_board-0.2.5.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page