modboard 0.0.0-stage → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,550 @@
1
- # Temporary Holding Version
1
+ <h1 align="center">modboard</h1>
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ <p align="center">
4
+ <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"/>
5
+ <img src="https://img.shields.io/github/v/release/Magithar/modboard?include_prereleases&label=release" alt="Release"/>
6
+ <a href="https://www.npmjs.com/package/modboard"><img src="https://img.shields.io/npm/dt/modboard" alt="npm downloads"/></a>
7
+ <img src="https://img.shields.io/badge/Claude_Code-2.1.295%2B-d97757.svg" alt="Claude Code 2.1.295 or newer"/>
8
+ </p>
9
+
10
+ <p align="center">
11
+ A task board several coding agents share at once. Two Claude Code sessions, a Codex session and a person can all claim tasks from it, see who holds what, and hand unfinished work to each other without losing context. One claim wins, a crashed agent's work comes back on its own, and nothing is marked done without saying how it was checked.<br/><br/>
12
+ Works with <a href="#claude-code">Claude Code</a>, <a href="#codex-opencode-or-any-agent-with-a-shell">Codex</a>, <a href="#codex-opencode-or-any-agent-with-a-shell">OpenCode</a>, and <a href="#codex-opencode-or-any-agent-with-a-shell">anything with a shell</a>, a person included.
13
+ </p>
14
+
15
+ ---
16
+
17
+ <p align="center">
18
+ <a href="#see-it-in-action">Demo</a> • <a href="#install">Install</a> • <a href="#usage">Usage</a> • <a href="#how-it-fits-together">How it fits together</a> • <a href="#what-you-see">What you see</a> • <a href="#make-your-own-block">Make your own block</a> • <a href="#what-has-been-tested">Tested</a> • <a href="#project-structure">Project structure</a> • <a href="#known-limitations">Limitations</a> • <a href="#contributing">Contributing</a>
19
+ </p>
20
+
21
+ ---
22
+
23
+ ## See it in action
24
+
25
+ ![Three live Claude Code sessions share one board: frontend and backend race for T-001, frontend hands T-003 off partway, backend picks it up, and the viewer's /board pane follows along](docs/board-live.gif)
26
+
27
+ Three real Claude Code sessions, recorded live at real speed. Only idle
28
+ stretches are cut: the wait before the sessions start, and two short pauses
29
+ while they wrote their final summaries.
30
+ `frontend` and `backend` are each told to work the board, and `viewer` has
31
+ `/board` open. Both go for T-001. `frontend` wins, and `backend` is refused
32
+ and takes T-002. `frontend` writes part of T-003, then hands it off. The band
33
+ above its prompt says "T-003 was stopped partway, pick it up". `backend` reads
34
+ the handoff, finishes T-003, and the pane ends on "3 done".
35
+
36
+ What each part of the screen means: [what you see](#what-you-see).
37
+
38
+ ---
39
+
40
+ ## Install
41
+
42
+ | Agent | How |
43
+ |-------|-----|
44
+ | Claude Code | `claude --plugin-dir /path/to/modboard` ([steps](#claude-code)) |
45
+ | Codex, OpenCode, a shell | put `board` on your PATH and the protocol in `AGENTS.md` ([steps](#codex-opencode-or-any-agent-with-a-shell)) |
46
+ | A person | the same `board` CLI |
47
+
48
+ ### The CLI
49
+
50
+ Every agent goes through it, Claude Code included:
51
+
52
+ ```bash
53
+ git clone https://github.com/Magithar/modboard.git
54
+ cd modboard && npm link # puts `board` on your PATH
55
+ ```
56
+
57
+ Or from npm: `npm install -g modboard` puts `board` on your PATH, or
58
+ `npm install --save-dev modboard` inside a project, then `npx board ...`.
59
+
60
+ ### Claude Code
61
+
62
+ ```bash
63
+ BOARD_AGENT=frontend claude --plugin-dir /path/to/modboard
64
+ ```
65
+
66
+ `BOARD_AGENT` is optional. It sets the name this session uses on the board.
67
+ The session gets the board's tools, a line above the prompt and the `/board`
68
+ pane.
69
+
70
+ > **Early access.** The Claude Code mod uses Claude Code's function-hooks API,
71
+ > which is early access and can change between releases. It needs Claude Code
72
+ > **2.1.295 or newer**. The CLI has no such dependency.
73
+
74
+ ### Codex, OpenCode, or any agent with a shell
75
+
76
+ Give each session its own name, and put this protocol in its instructions
77
+ (`AGENTS.md`):
78
+
79
+ ```bash
80
+ export BOARD_AGENT=codex
81
+ ```
82
+
83
+ > Claim a task before working on it. Note progress. If you stop without
84
+ > finishing, release it with a handoff. Never touch a task another agent holds.
85
+
86
+ ---
87
+
88
+ ## Usage
89
+
90
+ ```bash
91
+ export BOARD_AGENT=codex # who you are; unique per session
92
+ board list # ○ todo ◐ claimed ● done
93
+ board show T-001 # description, notes, handoffs
94
+ board claim T-001 # exit 6 if another agent holds it
95
+ board note T-001 "what changed" # also renews your lease
96
+ board heartbeat # renew all your leases
97
+ board release T-001 --handoff "done X, left Y, see Z"
98
+ board done T-001 --note "ran X, saw Y" # required: how you verified it
99
+ board release-all # free everything you hold
100
+ board add "title" --desc "..." --accept "how to tell it is done"
101
+ board agents # live agents
102
+ board view # every task and live agent, as JSON
103
+ board doctor # ledger vs state
104
+ ```
105
+
106
+ Each command answers in a line or two for a person (`claimed T-001 … it's
107
+ yours until 14:05`); `--json` prints the data instead, for scripts. `view`
108
+ and `events` are for programs and always print JSON. Exit codes: 2 usage, 3 board busy, 4 no such
109
+ task, 5 not yours, 6 held by another agent, 7 name in use.
110
+
111
+ **Claude Code** gets these tools: `board_list`, `board_show`, `board_add`,
112
+ `board_claim`, `board_note`, `board_release` and `board_done`. Tool activity
113
+ renews the session's leases.
114
+
115
+ The CLI and the tools keep the board's precise terms (claim, release,
116
+ handoff, lease) because agents act on them. The display uses plain words
117
+ instead, so you can read it without learning those terms.
118
+
119
+ ---
120
+
121
+ ## How it fits together
122
+
123
+ ![How modboard fits together: who works on the board, the CLI down to storage, what you see, and a task's life](docs/system.png)
124
+
125
+ One zero-dependency Node CLI owns all state. The Claude Code mod is an
126
+ adapter over that CLI. It adds what only Claude Code's host can provide: the
127
+ session's identity, a heartbeat on every tool call, and a live pane. Any
128
+ other agent uses the same CLI directly.
129
+
130
+ - **Storage is a block.** The engine never touches files. It reads a snapshot
131
+ from a Store and commits conditional writes ("only if this task is still at
132
+ the version I read"). Any backend that can do that atomically can hold a
133
+ board. See [Make your own block](#a-storage-block-an-adapter).
134
+ - **Where the board lives:** `.modboard/` next to the git *common* dir, so
135
+ every worktree of a repo shares one board. Set `BOARD_DIR` to override it.
136
+ Add `.modboard/` to `.gitignore`, because it is runtime state. A board made
137
+ before the rename, in `.agent-board/`, keeps working where it is.
138
+ - **Claims:** one lock per board (an atomic `mkdir`). The state file is
139
+ replaced with an atomic rename. Exactly one claimant wins, and only the
140
+ owner can note, release or finish a task.
141
+ - **Leases:** a claim lasts 15 minutes (`BOARD_LEASE_MS`). `heartbeat` or
142
+ `note` renews it. An expired claim goes back to todo, and the ledger records
143
+ it, so an agent that crashed doesn't hold a task forever. A Claude session
144
+ pings the board every minute while it is open, so if one is killed outright
145
+ its claims go back after 3 minutes of silence (`BOARD_PRESENCE_MS`), not 15.
146
+ An agent that never ran `board register` (a plain shell) keeps the lease
147
+ alone.
148
+ - **Names:** start a session with `BOARD_AGENT=frontend` to name it. If
149
+ another live session already holds the name, the new one becomes
150
+ `frontend-2` and gets a toast explaining why. Without a name, a session is
151
+ `claude:<session id>`. An open session keeps its name with a presence
152
+ heartbeat; a name is freed when its session ends or goes silent for
153
+ 3 minutes.
154
+ - **Handoffs:** `release --handoff "..."` leaves a note that the next agent
155
+ reads with `show` before it continues. When a Claude session ends (exit,
156
+ `/clear`, resume, logout), the mod releases everything that session holds,
157
+ with an automatic handoff. That matters because a restarted session comes
158
+ back with a new identity.
159
+ - **Done means verified:** `done` needs a `--note` saying how the task was
160
+ checked, against its `--accept` criteria if it has any.
161
+ - **Ledger:** every change is appended to `ledger.jsonl`, including lost
162
+ claims (`claim-rejected`, with the holder). `board doctor` checks that the
163
+ ledger and the state agree.
164
+
165
+ ---
166
+
167
+ ## What you see
168
+
169
+ The display shows only what needs you. Everything else waits until you ask.
170
+
171
+ **One line above the prompt**, always visible while there's work on the board:
172
+
173
+ ```
174
+ 2 tasks waiting · 1 in progress T-005 was stopped partway, pick it up 5-hour limit ▓▓▓▓▓▓░░░░ 64% model Sonnet 5.5 effort medium
175
+ ```
176
+
177
+ The line never wraps, and stays clear of Claude Code's own `[-]` control at
178
+ its right end. In a narrow window its parts shorten first, then the
179
+ last ones drop off. The first block (the summary) keeps its full form longest,
180
+ and the alert outlasts the counts:
181
+
182
+ ```
183
+ 124 cols 2 tasks waiting 5-hour limit ▓▓▓▓▓▓░░░░ 64% model Sonnet 5.5 effort low
184
+ 64 cols 2 tasks waiting 5h ▓▓▓░░ 64% Sonnet 5.5 low
185
+ 38 cols 2 tasks waiting 5h ▓▓▓░░ 64%
186
+ 20 cols 2 tasks waiting
187
+ ```
188
+
189
+ The alert names the one thing that needs you: a task someone stopped partway
190
+ that nobody has picked up, or an agent that stopped responding (its claim is
191
+ about to run out). Usage appears only once a limit passes 50%. It's green
192
+ with room left, yellow from 70% and red from 90%. With nothing waiting or in
193
+ progress, the line disappears.
194
+
195
+ **`/board`** opens the full pane:
196
+
197
+ ```
198
+ In progress
199
+ ◐ T-004 Add a test script you're on it
200
+ ◐ T-007 Write the README backend is on it
201
+ ◐ T-006 Add a LICENSE file codex stopped responding
202
+
203
+ Needs picking up
204
+ ○ T-005 Ghost task frontend stopped partway · see its note
205
+
206
+ Not started
207
+ ○ T-008 Add dark mode
208
+
209
+ 3 done
210
+
211
+ Usage
212
+ 5-hour limit ▓▓▓▓▓▓░░░░ 64% resets 12:00
213
+ weekly limit ▓▓░░░░░░░░ 20% resets in 3d
214
+ ```
215
+
216
+ Both are stacks of display blocks, chosen in the plugin's settings (`/config`)
217
+ as comma-separated lists, in order:
218
+
219
+ | Block | Band | Pane | Shows |
220
+ |---|---|---|---|
221
+ | `summary` | ✓ | | what's waiting and in progress, and the one thing that needs you |
222
+ | `tasks` | | ✓ | in progress, then work stopped partway, then not started, then a count of done |
223
+ | `usage` | ✓ | ✓ | plan usage per window: in the band past 50%, in the pane with resets |
224
+ | `model` | ✓ | ✓ | the session's model; click it to switch to the next one |
225
+ | `effort` | ✓ | ✓ | the effort level; click it to step to the next one, wrapping from the highest to the lowest |
226
+ | `clock` | ✓ | ✓ | the time |
227
+ | `context` | ✓ | ✓ | context fill and the session's cost |
228
+ | `agents` | | ✓ | who is live on the board |
229
+
230
+ The defaults are `band: summary,usage,model,effort` and `pane: tasks,usage`.
231
+
232
+ Each row says who has a task as a sentence (`backend is on it`, `frontend
233
+ stopped partway`) rather than a bare name, which could mean whoever made,
234
+ holds or dropped it.
235
+
236
+ Click `model` or `effort` to switch: each click runs Claude Code's own
237
+ `/model` or `/effort`, the same as typing the command. (In the `/board` pane
238
+ they also answer to `m` and `e`.) Note that `/effort` saves the level as your
239
+ default for new sessions, except `max`, which lasts for this session only. The `models` setting lists what
240
+ the model block steps through (default `opus,sonnet,haiku`), and `efforts`
241
+ lists the effort levels (default `low,medium,high,xhigh,max`). A model or
242
+ effort changed by hand shows on the next request. Until the session's first
243
+ request, the effort block shows the level it will start on:
244
+ `CLAUDE_CODE_EFFORT_LEVEL` if set, else the model's own `effortLevel` under
245
+ `modelSettings`, else the general `effortLevel` setting.
246
+
247
+ **Your own blocks.** Show a command's output with no code, or write a block
248
+ of your own: see [Make your own block](#make-your-own-block).
249
+
250
+ ---
251
+
252
+ ## Make your own block
253
+
254
+ modboard is built from blocks, and you can add your own. There are two
255
+ kinds:
256
+
257
+ | Kind | What it does | How many | Where you choose it |
258
+ |---|---|---|---|
259
+ | **Storage block** (an adapter) | holds the board: a folder, a database, a server | one per board | `.modboard/config.json` |
260
+ | **Display block** | draws part of the board inside a Claude session | many, in order | the plugin's `band` and `pane` settings |
261
+
262
+ ![How blocks work: the three ways to make your own, how a storage block (an adapter) is found, what the engine asks of it, where display blocks come from and how the band fits them on one line](docs/blocks.png)
263
+
264
+ The diagram's source is plain text, [`docs/blocks.txt`](docs/blocks.txt).
265
+
266
+ ### A storage block (an adapter)
267
+
268
+ Write one when the board should live somewhere other than a local folder,
269
+ for example so agents on different machines can share it. The engine keeps
270
+ every rule (claims, leases, handoffs). A block only stores records and
271
+ refuses writes that are out of date, so it never needs to know what a task
272
+ is.
273
+
274
+ **How an adapter works.** Every record carries a version, and every write
275
+ says which version it expects. Say agents A and B both claim T-001 at the
276
+ same moment:
277
+
278
+ 1. Both read the board with `snapshot()`. T-001 is at version 3, and nobody
279
+ holds it.
280
+ 2. Both decide the claim is fine, and both send `commit`: "claim T-001, only
281
+ if it is still at version 3".
282
+ 3. A's commit lands first. The adapter sees version 3, writes the claim, and
283
+ T-001 moves to version 4.
284
+ 4. B's commit finds version 4, not 3, so the adapter writes nothing and
285
+ answers `{ ok: false, conflict: 'T-001' }`.
286
+ 5. The engine reads again for B, sees that A holds T-001, and refuses B:
287
+ "T-001 is already claimed by A" (exit 6). The ledger records B's attempt
288
+ as `claim-rejected`.
289
+
290
+ Three things follow from this:
291
+
292
+ - **The engine decides; the adapter keeps versions honest.** Claims, leases,
293
+ handoffs and names are all rules in the engine. An adapter for a new
294
+ backend never has to reimplement them.
295
+ - **The check and the write must be one step.** A transaction, a conditional
296
+ write or a lock. If an adapter checks the version and then writes in two
297
+ separate steps, A and B can both pass the check, and two agents end up
298
+ holding one task. The contract tests below race ten claims to catch this.
299
+ - **The ledger makes it checkable.** Each commit appends its events with the
300
+ writes. If a crash ever leaves the two out of step, `verify()` says so, and
301
+ `board doctor` reports it.
302
+
303
+ **1. Write the module.** One file that exports `createStore(config, { dir })`.
304
+ `config` is everything in `.modboard/config.json`, so your block's own
305
+ settings (a URL, a table name) go there too. `dir` is the `.modboard/`
306
+ folder. It returns five methods, all of which may be async:
307
+
308
+ ```js
309
+ // my-block.mjs
310
+ export function createStore(config, { dir }) {
311
+ return {
312
+ // The store's clock, in ms. Leases are timed by it, so every machine
313
+ // agrees. A database should answer with its own time.
314
+ now: () => Date.now(),
315
+
316
+ // Every record, each with the version it stands at:
317
+ // { tasks: { 'T-001': { ...task, version: 3 } },
318
+ // agents: { frontend: { ...agent, version: 1 } } }
319
+ snapshot: async () => { /* read everything */ },
320
+
321
+ // writes: [{ kind: 'task' | 'agent', key, value, expect }]
322
+ // events: ledger entries to append
323
+ // Apply every write and append every event, or nothing at all, and only
324
+ // if each record still stands at `expect` (0 means it must not exist).
325
+ // An applied record's version becomes expect + 1. A null value deletes.
326
+ // Answer { ok: true }, or { ok: false, conflict: key } to have the
327
+ // engine read again and retry.
328
+ commit: async ({ writes, events }) => { /* one transaction */ },
329
+
330
+ // Ledger events with seq > since, in order. Give each appended event the
331
+ // next seq and an `at` time.
332
+ events: async (since = 0) => { /* ... */ },
333
+
334
+ // Does the ledger agree with the state? This is what `board doctor` reports.
335
+ verify: async () => ({ ok: true, problems: [] }),
336
+ }
337
+ }
338
+ ```
339
+
340
+ `commit` is the only hard part: it must be all-or-none, and checking the
341
+ versions and writing must happen as one step (a database transaction, a
342
+ conditional write, a lock). [`examples/store-memory.mjs`](examples/store-memory.mjs)
343
+ is a complete, working block in about 20 lines to copy from, and
344
+ [`lib/store-file.mjs`](lib/store-file.mjs) is the built-in one.
345
+
346
+ **2. Test it against the contract.** The engine relies on a few rules and
347
+ nothing else: one winner when many agents claim one task, distinct ids when
348
+ they add at once, stale writes refused, one live session per name. They ship
349
+ as a test suite:
350
+
351
+ ```js
352
+ // my-block.test.mjs, run with: node --test
353
+ import { storeContract } from 'modboard/lib/contract.mjs'
354
+ import { createStore } from './my-block.mjs'
355
+
356
+ storeContract('my block', () => createStore({ /* test settings */ }, { dir: '/tmp/board-test' }))
357
+ ```
358
+
359
+ Each run should start from an empty board, so give each `createStore` call a
360
+ fresh table or folder.
361
+
362
+ **3. Point a board at it.** In `.modboard/config.json`, name it in one of
363
+ three ways. Everything besides `store` is passed to your block:
364
+
365
+ ```json
366
+ { "store": "file" } the built-in default
367
+ { "store": "./stores/my-block.mjs", "url": "..." } a block file, relative to .modboard/
368
+ { "store": "modboard-my-block", "url": "..." } a block published as a package
369
+ ```
370
+
371
+ Then check it: `board add "first task"`, `board view`, and `board doctor`.
372
+ The CLI refuses a block that won't load or is missing a method, and says
373
+ which (exit 2).
374
+
375
+ **4. Share it (optional).** Publish it as a package whose entry exports
376
+ `createStore` (through `exports` or `main`), with `modboard` as a
377
+ dev dependency for the contract tests. Anyone can then
378
+ `npm install modboard-my-block` in their project and name it in
379
+ `config.json`. A package is found the way Node finds any package: in the
380
+ `node_modules` of the project that holds the board, or a folder above it.
381
+
382
+ ### A display block from a command (no code)
383
+
384
+ The quickest way to show something of your own. The `blocks` setting (in
385
+ `/config`) maps a block name to a shell command. Every 30 seconds the command
386
+ runs, and the block shows the first line it prints, cut to 60 characters:
387
+
388
+ ```json
389
+ {"ci": "gh run list -L1 --json conclusion -q '.[0].conclusion'", "branch": "git branch --show-current"}
390
+ ```
391
+
392
+ Then name them in `band` or `pane` like a built-in block
393
+ (`band: summary,ci,usage`). In the band a command block shows as
394
+ `ci success`, or just `success` when the line is short.
395
+
396
+ - Names are lowercase letters, digits and dashes, up to 16 characters, and
397
+ can't reuse a built-in block's name. A bad entry is skipped, with a toast
398
+ saying why.
399
+ - A command that fails (non-zero exit) or prints nothing shows nothing.
400
+ - The setting lives in your user config, not in the project, so opening
401
+ someone else's repo can never make your session run its commands.
402
+
403
+ ### A display block in code
404
+
405
+ For a block that reads the board itself, or reacts to a click. Each built-in
406
+ block is its own file in [`hooks/blocks/`](hooks/blocks/), and yours is a file
407
+ of the same shape:
408
+
409
+ ```tsx
410
+ // hooks/blocks/mine.tsx: how many tasks are mine
411
+ import { words, type Block } from './types'
412
+
413
+ export const mine: Block = {
414
+ name: 'mine',
415
+ // The band: forms widest first. The band takes the widest that fits,
416
+ // and leaves the block out when even the last one doesn't.
417
+ band: ({ ui: { Text }, tasks, who }) => {
418
+ const n = tasks.filter(t => t.claim?.owner === who).length
419
+ if (!n) return null // nothing to say: the block takes no room
420
+ return [words(Text, `${n} mine`), words(Text, `${n}`)]
421
+ },
422
+ // The pane: one part of /board, or null.
423
+ pane: ({ ui: { Text }, tasks, who }) => (
424
+ <Text>{tasks.filter(t => t.claim?.owner === who).length} tasks are mine</Text>
425
+ ),
426
+ }
427
+ ```
428
+
429
+ Every block gets the same context (see [`types.tsx`](hooks/blocks/types.tsx)):
430
+ the tasks, the live agents, who this session is, plan usage, the model and
431
+ effort, the time, the width, your command blocks' output, and `act` for
432
+ switching the model or effort when the block is clicked. A block may draw in
433
+ the band, the pane or both.
434
+
435
+ Then list it in [`index.ts`](hooks/blocks/index.ts) (an import, and its name
436
+ in `BLOCKS`), name it in the `band` or `pane` setting, and run
437
+ `claude plugin test .`. Claude Code mods can't load code at runtime, so a
438
+ code block lives in your copy of the mod: fork this repo, or send it as a
439
+ pull request if others would want it.
440
+
441
+ ---
442
+
443
+ ## What has been tested
444
+
445
+ These tests ran on 2026-10-12 with two live Claude Code sessions (Sonnet 5.5,
446
+ v2.1.296), one shell acting as Codex, and no extra instructions to the agents
447
+ beyond the tool descriptions:
448
+
449
+ | Test | Result |
450
+ |---|---|
451
+ | Both sessions claim the same task at once | one wins; the other reports the holder and does no work |
452
+ | Both told "do the next task on the board" | they collided on one task; the loser moved to another by itself; each claimed before writing files |
453
+ | One session does part 1 and releases with a handoff | the other read the handoff and resumed from part 2 without redoing part 1 |
454
+ | `codex` claims a task from the shell | Claude was refused, said so, and left it alone |
455
+ | An agent's lease runs out | the task returns to todo, and the ledger records `expire` |
456
+
457
+ Automated tests: `npm test` runs the CLI tests (a 20-way claim race,
458
+ ownership, handoff, lease expiry, heartbeat, rejected-claim logging, verified
459
+ done, release-all) and the store contract against the file block and an
460
+ in-memory reference block (concurrent claims and adds, stale writes, names).
461
+ It also checks that the CLI loads a block named in `config.json` and refuses
462
+ a broken one. `claude plugin test .` runs the mod tests (the pane's sections
463
+ and alerts, the band and when it stays quiet, names and their fallback, the
464
+ tools, the verification note, release on session end, usage, and choosing
465
+ blocks).
466
+
467
+ ---
468
+
469
+ ## What modboard is not
470
+
471
+ - Not a project manager: no due dates, assignees or boards per team
472
+ - Not an agent runner: it never starts, stops or prompts an agent
473
+ - Not a sync service: one board lives in one place, the storage block decides where
474
+
475
+ modboard is a **claim ledger**: who holds what, what was left for the next
476
+ agent, and how each finished task was checked.
477
+
478
+ ---
479
+
480
+ ## Project structure
481
+
482
+ ```
483
+ modboard/
484
+ ├── bin/
485
+ │ └── board.mjs # the one CLI every agent uses
486
+ ├── lib/
487
+ │ ├── engine.mjs # the rules: claims, leases, handoffs, names, the ledger
488
+ │ ├── load-store.mjs # finds the storage block that config.json names
489
+ │ ├── store-file.mjs # the built-in storage block: a folder
490
+ │ └── contract.mjs # the tests every storage block must pass
491
+ ├── examples/
492
+ │ └── store-memory.mjs # a complete storage block in about 20 lines
493
+ ├── hooks/
494
+ │ ├── hooks.json
495
+ │ ├── register.tsx # the Claude Code mod: tools, heartbeat, band, pane
496
+ │ └── blocks/ # one file per display block, listed in index.ts
497
+ ├── types/index.d.ts
498
+ ├── .claude-plugin/
499
+ │ └── plugin.json # the mod's manifest and settings
500
+ ├── test/ # CLI and store contract tests (npm test)
501
+ ├── tests/ # mod tests (claude plugin test .)
502
+ ├── docs/
503
+ │ ├── system.txt .png # how it fits together
504
+ │ ├── blocks.txt .png # how blocks work
505
+ │ ├── board-live.gif # a live recording of three Claude sessions
506
+ │ └── render.mjs # rebuilds every image from its .txt
507
+ ├── CHANGELOG.md # what changed in each version
508
+ └── CONTRIBUTING.md # how to contribute
509
+ ```
510
+
511
+ Each diagram's source is plain text. After editing a `.txt`,
512
+ `node docs/render.mjs` rebuilds its page and image.
513
+
514
+ ---
515
+
516
+ ## Known limitations
517
+
518
+ - **It doesn't work across machines yet.** The storage socket is in place,
519
+ but the only block built is local files. A database or server block comes
520
+ when a real cross-device need does.
521
+ - **Usage is per session.** The usage block shows the session's own plan
522
+ usage, which Claude Code reports, not the other agents'.
523
+ - **A crash skips the release on session end.** If a Claude process is killed
524
+ outright, its claims are freed once its session has been silent for
525
+ 3 minutes. A plain CLI agent that never registered waits out its lease
526
+ (15 minutes).
527
+ - **A verification note is the agent's own claim.** The board requires one
528
+ but doesn't run the check itself.
529
+
530
+ ---
531
+
532
+ ## Contributing
533
+
534
+ ```bash
535
+ npm test # CLI and store contract tests
536
+ claude plugin test . # the mod's tests
537
+ claude plugin validate . # the mod's manifest and hooks
538
+ ```
539
+
540
+ Changing what the board shows? Run both test suites. Adding a storage block
541
+ or a display block? Start at [Make your own block](#make-your-own-block).
542
+ [CONTRIBUTING.md](CONTRIBUTING.md) has the full checklist, where each kind of
543
+ change goes, and the style the project keeps. [CHANGELOG.md](CHANGELOG.md)
544
+ lists what changed in each version.
545
+
546
+ ---
547
+
548
+ ## License
549
+
550
+ MIT