modboard 0.5.0 → 0.6.0

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,167 +1,170 @@
1
- <h1 align="center">modboard</h1>
1
+ <h1 align="center">
2
+ <img src="docs/logo.png" alt="modBOARD" width="460"/>
3
+ </h1>
2
4
 
3
5
  <p align="center">
4
6
  <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"/>
5
- <img src="https://img.shields.io/github/package-json/v/Magithar/modboard?label=version" alt="Version"/>
6
- <img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg" alt="Node 18 or newer"/>
7
- <img src="https://img.shields.io/badge/dependencies-0-brightgreen.svg" alt="No dependencies"/>
7
+ <img src="https://img.shields.io/github/v/release/Magithar/modboard?include_prereleases&label=release" alt="Release"/>
8
+ <a href="https://www.npmjs.com/package/modboard"><img src="https://img.shields.io/npm/dt/modboard" alt="npm downloads"/></a>
8
9
  <img src="https://img.shields.io/badge/Claude_Code-2.1.295%2B-d97757.svg" alt="Claude Code 2.1.295 or newer"/>
9
10
  </p>
10
11
 
11
12
  <p align="center">
12
- 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/>
13
- 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
+ <b>One task board every coding agent shares, built from blocks you can add to.</b><br/>
14
+ Works with Claude Code, Codex, OpenCode, anything with a shell, and people.
14
15
  </p>
15
16
 
16
- ---
17
-
18
17
  <p align="center">
19
- <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>
18
+ <a href="#see-it-in-action">Demo</a> ·
19
+ <a href="#quick-start">Quick start</a> ·
20
+ <a href="#everyday-use">Everyday use</a> ·
21
+ <a href="#what-you-see">What you see</a> ·
22
+ <a href="#settings">Settings</a> ·
23
+ <a href="#how-it-works">How it works</a> ·
24
+ <a href="#make-your-own-block">Make your own block</a> ·
25
+ <a href="docs/TUTORIAL.md">Tutorial</a>
20
26
  </p>
21
27
 
28
+ <br/>
29
+
30
+ ## What it does
31
+
32
+ modBOARD is one universal board for every agent you run. Two Claude Code
33
+ sessions, a Codex session and a person can all take tasks from it, see who holds what, and
34
+ hand unfinished work to each other without losing context. It's built from
35
+ blocks, so you can add your own and show whatever you need on it.
36
+
37
+ | | |
38
+ |---|---|
39
+ | **One claim wins** | Two agents never end up on the same task. |
40
+ | **Crashed work comes back** | A task held by an agent that died returns to the board on its own. |
41
+ | **Handoffs keep context** | An agent that stops partway leaves a note; the next one reads it and carries on. |
42
+ | **Done means verified** | Nothing is marked done without saying how it was checked. |
43
+ | **Your task.md, beside the board** | The pane lists what's left in your project's own task file, by priority. |
44
+ | **Add your own blocks** | Show anything on the board, like CI status, the git branch or any command's output, with no code. Or keep the board in a database. [How](#make-your-own-block) |
45
+
22
46
  ---
23
47
 
24
48
  ## See it in action
25
49
 
26
- ![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)
50
+ ![Three live Claude Code sessions share one board: claude 2 and claude 3 race for T-001, claude 2 hands T-003 off partway, claude 3 picks it up, and claude 1's /board pane follows along](docs/board-live.gif)
27
51
 
28
- Three real Claude Code sessions, recorded live at real speed. Two idle
29
- stretches are cut: the wait before the sessions start, and four seconds while
30
- one session wrapped up.
31
- `frontend` and `backend` are each told to work the board, and `viewer` has
32
- `/board` open. Both go for T-001. `frontend` wins, and `backend` is refused
33
- and takes T-002. `frontend` writes part of T-003, then hands it off. The band
34
- above its prompt says "T-003 was stopped partway, pick it up". `backend` reads
35
- the handoff, finishes T-003, and the pane ends on "3 done".
52
+ Three real Claude Code sessions, recorded live at real speed. Only the wait
53
+ before the two workers start is cut.
36
54
 
37
- What each part of the screen means: [what you see](#what-you-see).
55
+ 1. The board names each session as it joins. `claude 1` has `/board` open;
56
+ `claude 2` and `claude 3` are each told to work the board.
57
+ 2. Both go for T-001. `claude 2` wins, and `claude 3` is refused and takes
58
+ T-002.
59
+ 3. `claude 2` writes part of T-003, then hands it off. The line above every
60
+ prompt (the band) shows `T-003` in a yellow box, and the pane lists it under Unfinished with the
61
+ handoff as points.
62
+ 4. `claude 3` reads the handoff, finishes T-003, and the pane ends on
63
+ `Done · 3`.
38
64
 
39
- ---
65
+ The demo project has no task file, so **To do** doesn't appear here; see
66
+ [Your task.md](#your-taskmd).
40
67
 
41
- ## Install
68
+ ---
42
69
 
43
- | Agent | How |
44
- |-------|-----|
45
- | Claude Code | `claude --plugin-dir /path/to/modboard` ([steps](#claude-code)) |
46
- | Codex, OpenCode, a shell | put `board` on your PATH and the protocol in `AGENTS.md` ([steps](#codex-opencode-or-any-agent-with-a-shell)) |
47
- | A person | the same `board` CLI |
70
+ ## Quick start
48
71
 
49
- ### The CLI
72
+ > [!TIP]
73
+ > New here? The [tutorial](docs/TUTORIAL.md) walks you from install to two
74
+ > agents sharing a board, your task.md on it, and every button, in about
75
+ > fifteen minutes.
50
76
 
51
- Every agent goes through it, Claude Code included:
77
+ **1. Install the `board` CLI.** Every agent uses it, Claude Code included.
52
78
 
53
79
  ```bash
54
- git clone https://github.com/Magithar/modboard.git
55
- cd modboard && npm link # puts `board` on your PATH
80
+ npm install -g modboard
56
81
  ```
57
82
 
58
- Or from npm: `npm install -g modboard` puts `board` on your PATH, or
59
- `npm install --save-dev modboard` inside a project, then `npx board ...`.
83
+ Or from source: clone `https://github.com/Magithar/modboard.git` and run
84
+ `npm link` inside it. To use it in one project only, run
85
+ `npm install --save-dev modboard` there, then `npx board …`.
60
86
 
61
- ### Claude Code
87
+ **2. Connect your agents.**
62
88
 
63
- ```bash
64
- BOARD_AGENT=frontend claude --plugin-dir /path/to/modboard
65
- ```
89
+ | Agent | What to do | Its name on the board |
90
+ |---|---|---|
91
+ | **Claude Code** | `claude --plugin-dir /path/to/modboard` | `claude 1`, `claude 2`, … |
92
+ | **Codex** | put the protocol below in `AGENTS.md` | `codex 1`, `codex 2`, … |
93
+ | **OpenCode, a shell** | `export BOARD_AGENT=opencode`, and put the protocol in `AGENTS.md` | the name you set |
94
+ | **A person** | use the same `board` commands | the name you set |
95
+
96
+ The protocol, for any agent's instructions:
66
97
 
67
- `BOARD_AGENT` is optional. It sets the name this session uses on the board.
68
- The session gets the board's tools, a line above the prompt and the `/board`
69
- pane.
98
+ > Claim a task before working on it. Note progress. If you stop without
99
+ > finishing, release it with a handoff. Never touch a task another agent holds.
100
+
101
+ Claude Code gets the board's tools, a line above the prompt and the `/board`
102
+ pane. Names are automatic: the board numbers sessions as they join. To pick
103
+ one yourself, start Claude Code with `BOARD_AGENT=frontend`.
70
104
 
105
+ > [!IMPORTANT]
71
106
  > **Early access.** The Claude Code mod uses Claude Code's function-hooks API,
72
107
  > which is early access and can change between releases. It needs Claude Code
73
108
  > **2.1.295 or newer**. The CLI has no such dependency.
74
109
 
75
- ### Codex, OpenCode, or any agent with a shell
76
-
77
- Give each session its own name, and put this protocol in its instructions
78
- (`AGENTS.md`):
110
+ **3. Add a task and open the board.**
79
111
 
80
112
  ```bash
81
- export BOARD_AGENT=codex
113
+ board add "Add a login page" --accept "signing in works"
82
114
  ```
83
115
 
84
- > Claim a task before working on it. Note progress. If you stop without
85
- > finishing, release it with a handoff. Never touch a task another agent holds.
116
+ Then type `/board` in Claude Code.
86
117
 
87
118
  ---
88
119
 
89
- ## Usage
120
+ ## Everyday use
90
121
 
91
122
  ```bash
92
- export BOARD_AGENT=codex # who you are; unique per session
93
123
  board list # ○ todo ◐ claimed ● done
94
124
  board show T-001 # description, notes, handoffs
95
125
  board claim T-001 # exit 6 if another agent holds it
96
- board note T-001 "what changed" # also renews your lease
97
- board heartbeat # renew all your leases
98
- board release T-001 --handoff "done X, left Y, see Z"
99
- board done T-001 --note "ran X, saw Y" # required: how you verified it
100
- board release-all # free everything you hold
126
+ board note T-001 "what changed" # also renews your claim
127
+ board release T-001 --handoff "done X; left Y; see Z"
128
+ board done T-001 --note "ran X, saw Y" # required: how you checked it
101
129
  board add "title" --desc "..." --accept "how to tell it is done"
102
- board agents # live agents
130
+ ```
131
+
132
+ Each command answers in a line or two (`claimed T-001 … it's yours until
133
+ 14:05`). Add `--json` for the data instead.
134
+
135
+ <details>
136
+ <summary><b>More commands, exit codes and the Claude Code tools</b></summary>
137
+
138
+ <br/>
139
+
140
+ ```bash
141
+ board heartbeat # renew all your claims
142
+ board release-all # free everything you hold
143
+ board whoami # the name the board gave you
144
+ board agents # who is live
103
145
  board view # every task and live agent, as JSON
104
- board doctor # ledger vs state
146
+ board doctor # check the ledger against the state
147
+ board taskfile # the project's task.md, read only
105
148
  ```
106
149
 
107
- Each command answers in a line or two for a person (`claimed T-001 … it's
108
- yours until 14:05`); `--json` prints the data instead, for scripts. `view`
109
- and `events` are for programs and always print JSON. Exit codes: 2 usage, 3 board busy, 4 no such
110
- task, 5 not yours, 6 held by another agent, 7 name in use.
150
+ | Exit code | Meaning |
151
+ |---|---|
152
+ | 2 | usage |
153
+ | 3 | board busy |
154
+ | 4 | no such task |
155
+ | 5 | not yours |
156
+ | 6 | held by another agent |
157
+ | 7 | name in use |
111
158
 
112
159
  **Claude Code** gets these tools: `board_list`, `board_show`, `board_add`,
113
- `board_claim`, `board_note`, `board_release` and `board_done`. Tool activity
114
- renews the session's leases.
160
+ `board_claim`, `board_note`, `board_release` and `board_done`. Any tool call
161
+ renews the session's claims.
115
162
 
116
- The CLI and the tools keep the board's precise terms (claim, release,
117
- handoff, lease) because agents act on them. The display uses plain words
118
- instead, so you can read it without learning those terms.
163
+ The CLI and the tools use the board's precise terms (claim, release, handoff,
164
+ lease), because agents act on them. The display uses plain words, so you can
165
+ read it without learning those terms.
119
166
 
120
- ---
121
-
122
- ## How it fits together
123
-
124
- ![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)
125
-
126
- One zero-dependency Node CLI owns all state. The Claude Code mod is an
127
- adapter over that CLI. It adds what only Claude Code's host can provide: the
128
- session's identity, a heartbeat on every tool call, and a live pane. Any
129
- other agent uses the same CLI directly.
130
-
131
- - **Storage is a block.** The engine never touches files. It reads a snapshot
132
- from a Store and commits conditional writes ("only if this task is still at
133
- the version I read"). Any backend that can do that atomically can hold a
134
- board. See [Make your own block](#a-storage-block-an-adapter).
135
- - **Where the board lives:** `.modboard/` next to the git *common* dir, so
136
- every worktree of a repo shares one board. Set `BOARD_DIR` to override it.
137
- Add `.modboard/` to `.gitignore`, because it is runtime state. A board made
138
- before the rename, in `.agent-board/`, keeps working where it is.
139
- - **Claims:** one lock per board (an atomic `mkdir`). The state file is
140
- replaced with an atomic rename. Exactly one claimant wins, and only the
141
- owner can note, release or finish a task.
142
- - **Leases:** a claim lasts 15 minutes (`BOARD_LEASE_MS`). `heartbeat` or
143
- `note` renews it. An expired claim goes back to todo, and the ledger records
144
- it, so an agent that crashed doesn't hold a task forever. A Claude session
145
- pings the board every minute while it is open, so if one is killed outright
146
- its claims go back after 3 minutes of silence (`BOARD_PRESENCE_MS`), not 15.
147
- An agent that never ran `board register` (a plain shell) keeps the lease
148
- alone.
149
- - **Names:** start a session with `BOARD_AGENT=frontend` to name it. If
150
- another live session already holds the name, the new one becomes
151
- `frontend-2` and gets a toast explaining why. Without a name, a session is
152
- `claude:<session id>`. An open session keeps its name with a presence
153
- heartbeat; a name is freed when its session ends or goes silent for
154
- 3 minutes.
155
- - **Handoffs:** `release --handoff "..."` leaves a note that the next agent
156
- reads with `show` before it continues. When a Claude session ends (exit,
157
- `/clear`, resume, logout), the mod releases everything that session holds,
158
- with an automatic handoff. That matters because a restarted session comes
159
- back with a new identity.
160
- - **Done means verified:** `done` needs a `--note` saying how the task was
161
- checked, against its `--accept` criteria if it has any.
162
- - **Ledger:** every change is appended to `ledger.jsonl`, including lost
163
- claims (`claim-rejected`, with the holder). `board doctor` checks that the
164
- ledger and the state agree.
167
+ </details>
165
168
 
166
169
  ---
167
170
 
@@ -169,185 +172,400 @@ other agent uses the same CLI directly.
169
172
 
170
173
  The display shows only what needs you. Everything else waits until you ask.
171
174
 
172
- **One line above the prompt**, always visible while there's work on the board:
175
+ ### The band
173
176
 
174
- ```
175
- 2 tasks waiting · 1 in progress T-005 was stopped partway, pick it up 5-hour limit ▓▓▓▓▓▓░░░░ 64% model Sonnet 5.5 effort medium
176
- ```
177
+ One line above the prompt, while there's work on the board:
178
+
179
+ ![The line above the prompt: 2 waiting · 1 active in green, T-005 in a yellow box, Sonnet 5.5, low, and modBOARD in green at the right end beside Claude Code's [-]](docs/band.png)
180
+
181
+ | Part | What it means | Click it to |
182
+ |---|---|---|
183
+ | `2 waiting · 1 active` | tasks not started, and tasks being worked on (in green) | |
184
+ | `T-005` in a yellow box | someone stopped it partway and left a handoff; up to three boxes, then `+N` | open `/board` at Unfinished; click again to fold it |
185
+ | `Sonnet 5.5` · `low` | the model and effort | switch to the next one |
186
+ | `modBOARD` | the board | open or close `/board` |
177
187
 
178
- The line never wraps, and stays clear of Claude Code's own `[-]` control at
179
- its right end. In a narrow window its parts shorten first, then the
180
- last ones drop off. The first block (the summary) keeps its full form longest,
181
- and the alert outlasts the counts:
188
+ With nothing waiting or in progress, the line disappears. It never wraps: in a
189
+ narrow window the last parts drop off first.
190
+
191
+ <details>
192
+ <summary><b>How the band fits a narrow window</b></summary>
193
+
194
+ <br/>
182
195
 
183
196
  ```
184
- 124 cols 2 tasks waiting 5-hour limit ▓▓▓▓▓▓░░░░ 64% model Sonnet 5.5 effort low
185
- 64 cols 2 tasks waiting 5h ▓▓▓░░ 64% Sonnet 5.5 low
186
- 38 cols 2 tasks waiting 5h ▓▓▓░░ 64%
187
- 20 cols 2 tasks waiting
197
+ 66 cols 2 waiting · 1 active [T-005] Sonnet 5.5 low modBOARD
198
+ 60 cols 2 waiting · 1 active [T-005] Sonnet 5.5 modBOARD
199
+ 48 cols 2 waiting · 1 active [T-005] modBOARD
200
+ 36 cols 2 waiting · 1 active [T-005]
201
+ 20 cols [T-005]
188
202
  ```
189
203
 
190
- The alert names the one thing that needs you: a task someone stopped partway
191
- that nobody has picked up, or an agent that stopped responding (its claim is
192
- about to run out). Usage appears only once a limit passes 50%. It's green
193
- with room left, yellow from 70% and red from 90%. With nothing waiting or in
194
- progress, the line disappears.
204
+ The boxes outlast the counts, because they're the one thing that needs you. A
205
+ claim gone idle stays off the line, since its lease frees it on its own; the
206
+ pane marks it `idle`. The line stays clear of Claude Code's own `[-]` at its
207
+ right end.
195
208
 
196
- **`/board`** opens the full pane:
209
+ </details>
197
210
 
198
- ```
199
- In progress
200
- ◐ T-004 Add a test script you're on it
201
- ◐ T-007 Write the README backend is on it
202
- ◐ T-006 Add a LICENSE file codex stopped responding
211
+ ### The `/board` pane
203
212
 
204
- Needs picking up
205
- ○ T-005 Ghost task frontend stopped partway · see its note
213
+ <p align="center">
214
+ <img src="docs/pane-board.png" width="640" alt="The /board pane as it opens: In progress with an idle codex 1 row in yellow, Unfinished with each handoff as points, Not started and Done folded, To do, and the Limits bars"/>
215
+ <br/><em>As it opens</em>
216
+ </p>
217
+
218
+ <table>
219
+ <tr>
220
+ <td width="50%"><img src="docs/pane-done.png" alt="Done opened, listing who finished each task, and To do opened at P0, showing the task file's most urgent items"/></td>
221
+ <td width="50%"><img src="docs/pane-all.png" alt="Not started opened, To do turned to all with each item's priority, and Limits folded to its figures"/></td>
222
+ </tr>
223
+ <tr>
224
+ <td align="center">Done and To do opened</td>
225
+ <td align="center">Not started, every priority, Limits folded</td>
226
+ </tr>
227
+ </table>
228
+
229
+ | Section | What it shows |
230
+ |---|---|
231
+ | **In progress** | who is on what. `codex 1 · idle` in yellow: no note or heartbeat for most of its claim's time |
232
+ | **Unfinished** | work stopped partway, with the handoff as points |
233
+ | **Not started** | everything waiting |
234
+ | **Done** | what's finished, and who finished it |
235
+ | **To do** | what's left in [your task.md](#your-taskmd) |
236
+ | **Limits** | the context window (with a `compact` button) and the 5-hour limit |
237
+
238
+ - **Every heading is a button.** Click to open or close it. In progress and
239
+ Unfinished start open, because they need you.
240
+ - **Colour only when something needs you**: yellow for unfinished or idle work
241
+ and for a limit past 70%; red for a limit past 90%.
242
+ - If the board stops answering, a red `board not updating: …` line says so at
243
+ the top until it answers again.
244
+
245
+ ### Your task.md
246
+
247
+ If your project has a `task.md`, `tasks.md` or `todo.md` (upper or lower case) at its
248
+ root or in `docs/`, the pane shows what's left in it under **To do**.
249
+
250
+ <table>
251
+ <tr>
252
+ <td valign="top"><img src="docs/taskfile-p0.png" alt="To do open at P0: 9 open, from TASKS.md, and the three P0 items, each after a grey dot" width="380"/></td>
253
+ <td valign="top"><img src="docs/taskfile-all.png" alt="To do turned to all: each open item with its priority, P0 first, then P1, P2, and items without one marked with a dash" width="380"/></td>
254
+ </tr>
255
+ <tr>
256
+ <td align="center"><code>P0</code>: the most urgent tier</td>
257
+ <td align="center"><code>all</code>: every item, by priority</td>
258
+ </tr>
259
+ </table>
260
+
261
+ - **Click `To do`** to open it. Each click reads the file again.
262
+ - **Click the priority** (`P0`) to step through the tiers the file has, then
263
+ `all`, then round again.
264
+ - **Priorities** are read from a heading (`## P0 — launch`, `## Sync (P1)`),
265
+ an item (`- [ ] P2 Benchmarks`, which wins over its heading), or a table with
266
+ a Priority column.
267
+ - **Only what's left shows.** Checked-off items, struck-through items
268
+ (`~~old~~`) and done table rows stay out of the list.
269
+ - **It's read-only.** The board never writes the file, and its items can't be
270
+ claimed. To work one through the board, `board add` it.
271
+
272
+ <details>
273
+ <summary><b>More on how the list is built</b></summary>
274
+
275
+ <br/>
276
+
277
+ - Within a priority, the file's own order is kept. Items with no priority come
278
+ last under `all`, marked with a dash. A tier the file doesn't have is
279
+ skipped.
280
+ - Without any priorities, the list keeps the file's order under its headings,
281
+ and there's no priority button.
282
+ - A table row counts as done when its Status says done, complete or ✅.
283
+ - Once a file checks anything off, its plain bullets count as notes, not
284
+ tasks.
285
+ - `board taskfile` prints the whole list; `--json` gives it as data.
286
+
287
+ </details>
206
288
 
207
- Not started
208
- ○ T-008 Add dark mode
289
+ ---
209
290
 
210
- 3 done
291
+ ## Settings
211
292
 
212
- Usage
213
- 5-hour limit ▓▓▓▓▓▓░░░░ 64% resets 12:00
214
- weekly limit ▓▓░░░░░░░░ 20% resets in 3d
215
- ```
293
+ Open the plugin's settings with `/config`.
216
294
 
217
- Both are stacks of display blocks, chosen in the plugin's settings (`/config`)
218
- as comma-separated lists, in order:
295
+ ### What shows where
296
+
297
+ The band and the pane are each a list of display blocks, in order:
298
+
299
+ ```
300
+ band: summary,model,effort,board (the default)
301
+ pane: tasks,taskfile,compact,usage (the default)
302
+ ```
219
303
 
220
304
  | Block | Band | Pane | Shows |
221
- |---|---|---|---|
222
- | `summary` | ✓ | | what's waiting and in progress, and the one thing that needs you |
223
- | `tasks` | | ✓ | in progress, then work stopped partway, then not started, then a count of done |
224
- | `usage` | ✓ | ✓ | plan usage per window: in the band past 50%, in the pane with resets |
225
- | `model` | ✓ | ✓ | the session's model; click it to switch to the next one |
226
- | `effort` | ✓ | ✓ | the effort level; click it to step to the next one, wrapping from the highest to the lowest |
305
+ |---|:-:|:-:|---|
306
+ | `summary` | ✓ | | what's waiting and active, and the unfinished boxes |
307
+ | `board` | ✓ | | the `modBOARD` button |
308
+ | `tasks` | | ✓ | In progress, Unfinished, Not started and Done |
309
+ | `taskfile` | | ✓ | your task.md under To do |
310
+ | `compact` | ✓ | ✓ | the context window as a bar, and a button that compacts the conversation |
311
+ | `usage` | ✓ | ✓ | the 5-hour limit as a bar (in the band, only once it passes 50%) |
312
+ | `model` | ✓ | ✓ | the model; click to switch |
313
+ | `effort` | ✓ | ✓ | the effort level; click to step through |
227
314
  | `clock` | ✓ | ✓ | the time |
228
- | `context` | ✓ | ✓ | context fill and the session's cost |
315
+ | `context` | ✓ | ✓ | context fill and the session's cost, as text |
229
316
  | `agents` | | ✓ | who is live on the board |
230
317
 
231
- The defaults are `band: summary,usage,model,effort` and `pane: tasks,usage`.
318
+ In a narrow window, the band's last blocks drop first, so put what matters
319
+ most first.
320
+
321
+ ### Model and effort
232
322
 
233
- Each row says who has a task as a sentence (`backend is on it`, `frontend
234
- stopped partway`) rather than a bare name, which could mean whoever made,
235
- holds or dropped it.
323
+ Clicking the model or effort runs Claude Code's own `/model` or `/effort`, the
324
+ same as typing it. In the pane, the keys `m` and `e` do the same.
236
325
 
237
- Click `model` or `effort` to switch: each click runs Claude Code's own
238
- `/model` or `/effort`, the same as typing the command. (In the `/board` pane
239
- they also answer to `m` and `e`.) Note that `/effort` saves the level as your
240
- default for new sessions, except `max`, which lasts for this session only. The `models` setting lists what
241
- the model block steps through (default `opus,sonnet,haiku`), and `efforts`
242
- lists the effort levels (default `low,medium,high,xhigh,max`). A model or
243
- effort changed by hand shows on the next request. Until the session's first
244
- request, the effort block shows the level it will start on:
245
- `CLAUDE_CODE_EFFORT_LEVEL` if set, else the model's own `effortLevel` under
246
- `modelSettings`, else the general `effortLevel` setting.
326
+ | Setting | Default | What it is |
327
+ |---|---|---|
328
+ | `models` | `opus,sonnet,haiku` | what the model button steps through |
329
+ | `efforts` | `low,medium,high,xhigh,max` | what the effort button steps through |
247
330
 
248
- **Your own blocks.** Show a command's output with no code, or write a block
249
- of your own: see [Make your own block](#make-your-own-block).
331
+ `/effort` saves the level as your default for new sessions, except `max`,
332
+ which lasts for this session only. Before the first request, the effort block shows
333
+ the level the session will start on: `CLAUDE_CODE_EFFORT_LEVEL` if set, else
334
+ the model's own `effortLevel` under `modelSettings`, else the general
335
+ `effortLevel`.
336
+
337
+ ### Environment
338
+
339
+ | Variable | Default | What it does |
340
+ |---|---|---|
341
+ | `BOARD_AGENT` | a number, given by the board | the name to use on the board |
342
+ | `BOARD_DIR` | `.modboard/`, beside the repo's git folder | where the board lives |
343
+ | `BOARD_LEASE_MS` | 15 minutes | how long a claim lasts without a note or heartbeat |
344
+ | `BOARD_PRESENCE_MS` | 3 minutes | how long a Claude session can be silent before its claims go back |
345
+
346
+ ---
347
+
348
+ ## How it works
349
+
350
+ ![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)
351
+
352
+ One small Node CLI, `board`, owns the board; it has no dependencies. The Claude
353
+ Code mod sits on top of it and adds what only Claude Code can provide: the session's
354
+ name, a heartbeat on every tool call, and the display. Every other agent uses
355
+ the CLI directly.
356
+
357
+ | | How it works |
358
+ |---|---|
359
+ | **Where the board lives** | `.modboard/`, beside the repo's git folder, so every worktree shares one board. Add it to `.gitignore`. |
360
+ | **One claim wins** | Each change takes a lock and replaces the board in one step, so exactly one claimant wins. Only the holder can note, release or finish a task. |
361
+ | **Claims expire** | A claim lasts 15 minutes; a note or heartbeat renews it. An expired claim goes back to waiting. |
362
+ | **Crashes recover fast** | An open Claude session pings the board every minute. If it's killed, its claims go back after 3 minutes of silence. |
363
+ | **Names** | The board numbers sessions as they join: `claude 1`, `codex 1`. A session keeps its name while it's open; a new one takes the lowest free number. |
364
+ | **Handoffs** | `release --handoff` leaves a note the next agent reads first. A Claude session that ends releases what it holds, with a handoff of its own. |
365
+ | **Done means verified** | `done` needs a `--note` on how the task was checked, against its `--accept` criteria if it has any. |
366
+ | **A ledger** | Every change, lost claims included, is appended to `ledger.jsonl`. `board doctor` checks it against the board. |
367
+
368
+ <details>
369
+ <summary><b>More detail</b></summary>
370
+
371
+ <br/>
372
+
373
+ - **Storage is a block.** The engine never touches files itself. It reads a
374
+ snapshot from a store and commits conditional writes ("only if this task is
375
+ still at the version I read"). Any backend that can do that in one step can
376
+ hold a board: see [a storage block](#a-storage-block-an-adapter).
377
+ - **The lock** is an atomic `mkdir`, and the board file is replaced with an
378
+ atomic rename.
379
+ - **Names you choose:** if another live session already holds the name you
380
+ ask for, the new one becomes `frontend-2` and a toast says why.
381
+ - **Codex** sends no presence ping, so its name and claims last only as long
382
+ as its leases. An agent that never registered (a plain shell) is the same.
383
+ - **A board made before the rename**, in `.agent-board/`, keeps working where
384
+ it is.
385
+
386
+ </details>
387
+
388
+ ### What modBOARD is not
389
+
390
+ - **Not a project manager:** no due dates, assignees or per-team boards.
391
+ - **Not an agent runner:** it never starts, stops or prompts an agent.
392
+ - **Not a sync service:** one board lives in one place; the storage block
393
+ decides where.
394
+
395
+ It's a **claim ledger**: who holds what, what was left for the next agent, and
396
+ how each finished task was checked.
250
397
 
251
398
  ---
252
399
 
253
400
  ## Make your own block
254
401
 
255
- modboard is built from blocks, and you can add your own. There are two
256
- kinds:
402
+ modBOARD is built from blocks, and you can add your own. Pick the row that
403
+ matches what you want:
257
404
 
258
- | Kind | What it does | How many | Where you choose it |
259
- |---|---|---|---|
260
- | **Storage block** (an adapter) | holds the board: a folder, a database, a server | one per board | `.modboard/config.json` |
261
- | **Display block** | draws part of the board inside a Claude session | many, in order | the plugin's `band` and `pane` settings |
405
+ | I want to… | Make | You write |
406
+ |---|---|---|
407
+ | show a command's output (CI status, git branch…) | [a command block](#a-display-block-from-a-command-no-code) | two settings, no code |
408
+ | show something from the board, or react to a click | [a display block in code](#a-display-block-in-code) | one `.tsx` file |
409
+ | keep the board somewhere else (a database, a server) | [a storage block](#a-storage-block-an-adapter) | one `.mjs` file |
262
410
 
263
411
  ![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)
264
412
 
265
413
  The diagram's source is plain text, [`docs/blocks.txt`](docs/blocks.txt).
266
414
 
415
+ ### A display block from a command (no code)
416
+
417
+ The quickest way. Two steps, both in the plugin's settings (`/config`):
418
+
419
+ **1. Name a command** in the `blocks` setting:
420
+
421
+ ```json
422
+ {
423
+ "ci": "gh run list -L1 --json conclusion -q '.[0].conclusion'",
424
+ "branch": "git branch --show-current"
425
+ }
426
+ ```
427
+
428
+ **2. Add the name** to `band` or `pane`, like a built-in block:
429
+
430
+ ```
431
+ band: summary,ci,model,effort,board
432
+ ```
433
+
434
+ That's it. Every 30 seconds the command runs, and the block shows the first
435
+ line it prints, cut to 60 characters. In the band it reads `ci success`, or
436
+ just `success` when the line is short.
437
+
438
+ Good to know:
439
+
440
+ - Names are lowercase letters, digits and dashes, up to 16 characters, and
441
+ can't reuse a built-in block's name. A bad entry is skipped, with a toast
442
+ saying why.
443
+ - A command that fails (non-zero exit) or prints nothing shows nothing.
444
+ - The setting lives in your user config, not in the project, so opening
445
+ someone else's repo can never make your session run its commands.
446
+
447
+ ### A display block in code
448
+
449
+ For a block that reads the board itself, or reacts to a click. Claude Code mods
450
+ can't load code at runtime, so this lives in your copy of the mod: fork this
451
+ repo (or send a pull request if others would want it).
452
+
453
+ **1. Write the block** as a file in [`hooks/blocks/`](hooks/blocks/). This one
454
+ shows how many tasks are yours:
455
+
456
+ ```tsx
457
+ // hooks/blocks/mine.tsx
458
+ import { words, type Block } from './types'
459
+
460
+ export const mine: Block = {
461
+ name: 'mine',
462
+
463
+ // In the band: a list of forms, widest first. The band uses the widest
464
+ // that fits, and drops the block when none do. null = show nothing.
465
+ band: ({ ui: { Text }, tasks, who }) => {
466
+ const n = tasks.filter(t => t.claim?.owner === who).length
467
+ if (!n) return null
468
+ return [words(Text, `${n} mine`), words(Text, `${n}`)]
469
+ },
470
+
471
+ // In the /board pane: one part of it, or null.
472
+ pane: ({ ui: { Text }, tasks, who }) => (
473
+ <Text>{tasks.filter(t => t.claim?.owner === who).length} tasks are mine</Text>
474
+ ),
475
+ }
476
+ ```
477
+
478
+ A block can have `band`, `pane`, or both.
479
+
480
+ **2. Register it** in [`hooks/blocks/index.ts`](hooks/blocks/index.ts):
481
+
482
+ ```ts
483
+ import { mine } from './mine'
484
+
485
+ export const BLOCKS: Block[] = [summary, board, /* … */, mine]
486
+ ```
487
+
488
+ **3. Turn it on** by adding `mine` to the `band` or `pane` setting.
489
+
490
+ **4. Test it** with `claude plugin test .`.
491
+
492
+ What a block gets (the full shape is in [`types.tsx`](hooks/blocks/types.tsx)):
493
+
494
+ - the tasks, the live agents, and who this session is
495
+ - plan usage and context fill, the model and effort, the time, the width
496
+ - your command blocks' output, and the project's task file
497
+ - `act`, for what a click can do: switch the model or effort, run `/compact`,
498
+ open a group, the task file or the pane
499
+
500
+ Two rules keep the display calm:
501
+
502
+ - **Colour only when something needs you** (theme `warning` and `error`).
503
+ - **No word or mark that the heading or the order already says.**
504
+
505
+ For anything that fills up, reuse the bar in `meter.tsx`, as the context and
506
+ 5-hour limit blocks do.
507
+
267
508
  ### A storage block (an adapter)
268
509
 
269
- Write one when the board should live somewhere other than a local folder,
270
- for example so agents on different machines can share it. The engine keeps
271
- every rule (claims, leases, handoffs). A block only stores records and
272
- refuses writes that are out of date, so it never needs to know what a task
273
- is.
510
+ Only needed when the board should live somewhere other than a local folder,
511
+ for example so agents on different machines can share it.
274
512
 
275
- **How an adapter works.** Every record carries a version, and every write
276
- says which version it expects. Say agents A and B both claim T-001 at the
277
- same moment:
513
+ You don't reimplement claims, leases or handoffs: the engine keeps every rule.
514
+ Your block just **stores records, each with a version number, and refuses a
515
+ write when the version has moved on.**
278
516
 
279
- 1. Both read the board with `snapshot()`. T-001 is at version 3, and nobody
280
- holds it.
281
- 2. Both decide the claim is fine, and both send `commit`: "claim T-001, only
282
- if it is still at version 3".
283
- 3. A's commit lands first. The adapter sees version 3, writes the claim, and
284
- T-001 moves to version 4.
285
- 4. B's commit finds version 4, not 3, so the adapter writes nothing and
286
- answers `{ ok: false, conflict: 'T-001' }`.
287
- 5. The engine reads again for B, sees that A holds T-001, and refuses B:
288
- "T-001 is already claimed by A" (exit 6). The ledger records B's attempt
289
- as `claim-rejected`.
290
-
291
- Three things follow from this:
292
-
293
- - **The engine decides; the adapter keeps versions honest.** Claims, leases,
294
- handoffs and names are all rules in the engine. An adapter for a new
295
- backend never has to reimplement them.
296
- - **The check and the write must be one step.** A transaction, a conditional
297
- write or a lock. If an adapter checks the version and then writes in two
298
- separate steps, A and B can both pass the check, and two agents end up
299
- holding one task. The contract tests below race ten claims to catch this.
300
- - **The ledger makes it checkable.** Each commit appends its events with the
301
- writes. If a crash ever leaves the two out of step, `verify()` says so, and
302
- `board doctor` reports it.
303
-
304
- **1. Write the module.** One file that exports `createStore(config, { dir })`.
305
- `config` is everything in `.modboard/config.json`, so your block's own
306
- settings (a URL, a table name) go there too. `dir` is the `.modboard/`
307
- folder. It returns five methods, all of which may be async:
517
+ **1. Write the module.** One file exporting `createStore(config, { dir })`,
518
+ which returns five methods (any of them may be async):
519
+
520
+ | Method | What it does |
521
+ |---|---|
522
+ | `now()` | the store's clock in ms; leases are timed by it |
523
+ | `snapshot()` | every task and agent, each with its version |
524
+ | `commit({ writes, events })` | apply all the writes and log the events, or none, and only if each record is still at the version the write expects |
525
+ | `events(since)` | the ledger events after `since`, in order |
526
+ | `verify()` | does the ledger agree with the state? (`board doctor` shows this) |
527
+
528
+ `config` is everything in `.modboard/config.json`, so your own settings (a URL,
529
+ a table name) go there. `dir` is the `.modboard/` folder.
308
530
 
309
531
  ```js
310
532
  // my-block.mjs
311
533
  export function createStore(config, { dir }) {
312
534
  return {
313
- // The store's clock, in ms. Leases are timed by it, so every machine
314
- // agrees. A database should answer with its own time.
535
+ // A database should answer with its own time, so every machine agrees.
315
536
  now: () => Date.now(),
316
537
 
317
- // Every record, each with the version it stands at:
318
- // { tasks: { 'T-001': { ...task, version: 3 } },
319
- // agents: { frontend: { ...agent, version: 1 } } }
538
+ // { tasks: { 'T-001': { ...task, version: 3 } },
539
+ // agents: { 'claude 1': { ...agent, version: 1 } } }
320
540
  snapshot: async () => { /* read everything */ },
321
541
 
322
542
  // writes: [{ kind: 'task' | 'agent', key, value, expect }]
323
- // events: ledger entries to append
324
- // Apply every write and append every event, or nothing at all, and only
325
- // if each record still stands at `expect` (0 means it must not exist).
326
- // An applied record's version becomes expect + 1. A null value deletes.
327
- // Answer { ok: true }, or { ok: false, conflict: key } to have the
328
- // engine read again and retry.
543
+ // expect 0 = the record must not exist yet; value null = delete it.
544
+ // An applied record's version becomes expect + 1.
545
+ // Answer { ok: true }, or { ok: false, conflict: key } and the engine
546
+ // reads again and retries.
329
547
  commit: async ({ writes, events }) => { /* one transaction */ },
330
548
 
331
- // Ledger events with seq > since, in order. Give each appended event the
332
- // next seq and an `at` time.
549
+ // Give each appended event the next `seq` and an `at` time.
333
550
  events: async (since = 0) => { /* ... */ },
334
551
 
335
- // Does the ledger agree with the state? This is what `board doctor` reports.
336
552
  verify: async () => ({ ok: true, problems: [] }),
337
553
  }
338
554
  }
339
555
  ```
340
556
 
341
- `commit` is the only hard part: it must be all-or-none, and checking the
342
- versions and writing must happen as one step (a database transaction, a
343
- conditional write, a lock). [`examples/store-memory.mjs`](examples/store-memory.mjs)
344
- is a complete, working block in about 20 lines to copy from, and
345
- [`lib/store-file.mjs`](lib/store-file.mjs) is the built-in one.
557
+ > [!IMPORTANT]
558
+ > `commit` is the only hard part. Checking the versions and writing must be
559
+ > **one step**: a database transaction, a conditional write, or a lock. If you
560
+ > check, then write, two agents can both pass the check and both hold one task.
561
+
562
+ Copy from [`examples/store-memory.mjs`](examples/store-memory.mjs), a short,
563
+ complete block, or [`lib/store-file.mjs`](lib/store-file.mjs), the built-in
564
+ one.
346
565
 
347
- **2. Test it against the contract.** The engine relies on a few rules and
348
- nothing else: one winner when many agents claim one task, distinct ids when
349
- they add at once, stale writes refused, one live session per name. They ship
350
- as a test suite:
566
+ **2. Test it against the contract.** The suite races claims, adds tasks at
567
+ once, sends stale writes and reuses names, and fails if your block lets any of them
568
+ through:
351
569
 
352
570
  ```js
353
571
  // my-block.test.mjs, run with: node --test
@@ -357,95 +575,63 @@ import { createStore } from './my-block.mjs'
357
575
  storeContract('my block', () => createStore({ /* test settings */ }, { dir: '/tmp/board-test' }))
358
576
  ```
359
577
 
360
- Each run should start from an empty board, so give each `createStore` call a
361
- fresh table or folder.
362
-
363
- **3. Point a board at it.** In `.modboard/config.json`, name it in one of
364
- three ways. Everything besides `store` is passed to your block:
578
+ Give each `createStore` call a fresh table or folder, so each run starts empty.
365
579
 
366
- ```json
367
- { "store": "file" } the built-in default
368
- { "store": "./stores/my-block.mjs", "url": "..." } a block file, relative to .modboard/
369
- { "store": "modboard-my-block", "url": "..." } a block published as a package
370
- ```
580
+ **3. Point a board at it** in `.modboard/config.json`. Everything besides
581
+ `store` is passed to your block:
371
582
 
372
- Then check it: `board add "first task"`, `board view`, and `board doctor`.
373
- The CLI refuses a block that won't load or is missing a method, and says
374
- which (exit 2).
583
+ | `config.json` | Uses |
584
+ |---|---|
585
+ | `{ "store": "file" }` | the built-in default |
586
+ | `{ "store": "./stores/my-block.mjs", "url": "..." }` | a block file, relative to `.modboard/` |
587
+ | `{ "store": "modboard-my-block", "url": "..." }` | a block published as a package |
375
588
 
376
- **4. Share it (optional).** Publish it as a package whose entry exports
377
- `createStore` (through `exports` or `main`), with `modboard` as a
378
- dev dependency for the contract tests. Anyone can then
379
- `npm install modboard-my-block` in their project and name it in
380
- `config.json`. A package is found the way Node finds any package: in the
381
- `node_modules` of the project that holds the board, or a folder above it.
589
+ **4. Check it:** `board add "first task"`, `board view`, `board doctor`. The CLI
590
+ refuses a block that won't load or is missing a method, and says which
591
+ (exit 2).
382
592
 
383
- ### A display block from a command (no code)
593
+ **5. Share it (optional).** Publish a package whose entry exports `createStore`
594
+ (through `exports` or `main`), with `modboard` as a dev dependency for the
595
+ contract tests. Others `npm install modboard-my-block` and name it in
596
+ `config.json`. It's found the way Node finds any package: in `node_modules` of
597
+ the project that holds the board, or a folder above it.
384
598
 
385
- The quickest way to show something of your own. The `blocks` setting (in
386
- `/config`) maps a block name to a shell command. Every 30 seconds the command
387
- runs, and the block shows the first line it prints, cut to 60 characters:
599
+ <details>
600
+ <summary><b>Why the version check matters: two agents claim one task</b></summary>
388
601
 
389
- ```json
390
- {"ci": "gh run list -L1 --json conclusion -q '.[0].conclusion'", "branch": "git branch --show-current"}
391
- ```
602
+ <br/>
392
603
 
393
- Then name them in `band` or `pane` like a built-in block
394
- (`band: summary,ci,usage`). In the band a command block shows as
395
- `ci success`, or just `success` when the line is short.
604
+ Say agents A and B both claim T-001 at the same moment:
396
605
 
397
- - Names are lowercase letters, digits and dashes, up to 16 characters, and
398
- can't reuse a built-in block's name. A bad entry is skipped, with a toast
399
- saying why.
400
- - A command that fails (non-zero exit) or prints nothing shows nothing.
401
- - The setting lives in your user config, not in the project, so opening
402
- someone else's repo can never make your session run its commands.
403
-
404
- ### A display block in code
405
-
406
- For a block that reads the board itself, or reacts to a click. Each built-in
407
- block is its own file in [`hooks/blocks/`](hooks/blocks/), and yours is a file
408
- of the same shape:
606
+ 1. Both read the board with `snapshot()`. T-001 is at version 3, and nobody
607
+ holds it.
608
+ 2. Both send `commit`: "claim T-001, only if it is still at version 3".
609
+ 3. A's commit lands first. The block sees version 3, writes the claim, and
610
+ T-001 moves to version 4.
611
+ 4. B's commit finds version 4, not 3, so the block writes nothing and answers
612
+ `{ ok: false, conflict: 'T-001' }`.
613
+ 5. The engine reads again for B, sees that A holds T-001, and refuses B:
614
+ "T-001 is already claimed by A" (exit 6). The ledger records B's attempt as
615
+ `claim-rejected`.
409
616
 
410
- ```tsx
411
- // hooks/blocks/mine.tsx: how many tasks are mine
412
- import { words, type Block } from './types'
617
+ So the engine decides who wins, and the block only keeps the versions honest.
618
+ Each commit also appends its ledger events with its writes; if a crash ever
619
+ leaves the two out of step, `verify()` says so and `board doctor` reports it.
413
620
 
414
- export const mine: Block = {
415
- name: 'mine',
416
- // The band: forms widest first. The band takes the widest that fits,
417
- // and leaves the block out when even the last one doesn't.
418
- band: ({ ui: { Text }, tasks, who }) => {
419
- const n = tasks.filter(t => t.claim?.owner === who).length
420
- if (!n) return null // nothing to say: the block takes no room
421
- return [words(Text, `${n} mine`), words(Text, `${n}`)]
422
- },
423
- // The pane: one part of /board, or null.
424
- pane: ({ ui: { Text }, tasks, who }) => (
425
- <Text>{tasks.filter(t => t.claim?.owner === who).length} tasks are mine</Text>
426
- ),
427
- }
428
- ```
621
+ </details>
429
622
 
430
- Every block gets the same context (see [`types.tsx`](hooks/blocks/types.tsx)):
431
- the tasks, the live agents, who this session is, plan usage, the model and
432
- effort, the time, the width, your command blocks' output, and `act` for
433
- switching the model or effort when the block is clicked. A block may draw in
434
- the band, the pane or both.
623
+ ---
435
624
 
436
- Then list it in [`index.ts`](hooks/blocks/index.ts) (an import, and its name
437
- in `BLOCKS`), name it in the `band` or `pane` setting, and run
438
- `claude plugin test .`. Claude Code mods can't load code at runtime, so a
439
- code block lives in your copy of the mod: fork this repo, or send it as a
440
- pull request if others would want it.
625
+ ## Testing
441
626
 
442
- ---
627
+ <details>
628
+ <summary><b>Tested live with two Claude Code sessions and a shell</b></summary>
443
629
 
444
- ## What has been tested
630
+ <br/>
445
631
 
446
- These tests ran on 2026-10-12 with two live Claude Code sessions (Sonnet 5.5,
447
- v2.1.296), one shell acting as Codex, and no extra instructions to the agents
448
- beyond the tool descriptions:
632
+ These ran on 2026-10-12 with two live Claude Code sessions (Sonnet 5.5,
633
+ v2.1.296), one shell acting as Codex, and no instructions to the agents beyond
634
+ the tool descriptions:
449
635
 
450
636
  | Test | Result |
451
637
  |---|---|
@@ -453,91 +639,102 @@ beyond the tool descriptions:
453
639
  | 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 |
454
640
  | One session does part 1 and releases with a handoff | the other read the handoff and resumed from part 2 without redoing part 1 |
455
641
  | `codex` claims a task from the shell | Claude was refused, said so, and left it alone |
456
- | An agent's lease runs out | the task returns to todo, and the ledger records `expire` |
457
-
458
- Automated tests: `npm test` runs the CLI tests (a 20-way claim race,
459
- ownership, handoff, lease expiry, heartbeat, rejected-claim logging, verified
460
- done, release-all) and the store contract against the file block and an
461
- in-memory reference block (concurrent claims and adds, stale writes, names).
462
- It also checks that the CLI loads a block named in `config.json` and refuses
463
- a broken one. `claude plugin test .` runs the mod tests (the pane's sections
464
- and alerts, the band and when it stays quiet, names and their fallback, the
465
- tools, the verification note, release on session end, usage, and choosing
466
- blocks).
642
+ | An agent's lease runs out | the task goes back to waiting, and the ledger records `expire` |
467
643
 
468
- ---
644
+ The task file, priorities, compact button and automatic names came later.
645
+ They've run in live sessions while being built (the demo above shows the
646
+ automatic names), but haven't been through this full set.
647
+
648
+ </details>
649
+
650
+ <details>
651
+ <summary><b>Automated tests</b></summary>
652
+
653
+ <br/>
469
654
 
470
- ## What modboard is not
655
+ **`npm test`** runs the CLI tests and the store contract:
471
656
 
472
- - Not a project manager: no due dates, assignees or boards per team
473
- - Not an agent runner: it never starts, stops or prompts an agent
474
- - Not a sync service: one board lives in one place, the storage block decides where
657
+ - a 20-way claim race, ownership, handoffs, lease expiry, heartbeats,
658
+ rejected-claim logging, verified done, release-all, automatic names
659
+ - the store contract against the file block and an in-memory block
660
+ (concurrent claims and adds, stale writes, names)
661
+ - that the CLI loads a block named in `config.json` and refuses a broken one
662
+ - that `board taskfile` reads each way a task file keeps items and priorities
475
663
 
476
- modboard is a **claim ledger**: who holds what, what was left for the next
477
- agent, and how each finished task was checked.
664
+ **`claude plugin test .`** runs the mod's tests: the band and how it fits a
665
+ line, the pane's groups and what folds, handoff points, the task file and its
666
+ priority button, the Limits heading, the error line, names, the tools, release
667
+ on session end, and choosing blocks.
668
+
669
+ </details>
670
+
671
+ ### Known limitations
672
+
673
+ - **One machine for now.** The storage socket is in place, but the only block
674
+ built keeps the board in local files.
675
+ - **Usage is per session.** The usage bar shows this session's own plan usage,
676
+ not the other agents'.
677
+ - **A killed CLI agent's claims wait out their lease.** A killed Claude session frees its
678
+ claims after 3 minutes of silence; a plain CLI agent that never registered
679
+ waits out the full 15.
680
+ - **A verification note is the agent's word.** The board requires one but
681
+ doesn't run the check itself.
682
+ - **The task file is read-only.** Add an item with `board add` to work it
683
+ through the board.
478
684
 
479
685
  ---
480
686
 
481
- ## Project structure
687
+ ## Contributing
688
+
689
+ ```bash
690
+ npm test # CLI and store contract tests
691
+ claude plugin test . # the mod's tests
692
+ claude plugin validate . # the mod's manifest and hooks
693
+ ```
694
+
695
+ [CONTRIBUTING.md](CONTRIBUTING.md) has the checklist, where each kind of change
696
+ goes, and the style the project keeps. [CHANGELOG.md](CHANGELOG.md) lists what
697
+ changed in each version, and [ROADMAP.md](ROADMAP.md) what's planned next.
698
+
699
+ <details>
700
+ <summary><b>Project structure</b></summary>
701
+
702
+ <br/>
482
703
 
483
704
  ```
484
705
  modboard/
485
- ├── bin/
486
- │ └── board.mjs # the one CLI every agent uses
706
+ ├── bin/board.mjs # the one CLI every agent uses
487
707
  ├── lib/
488
708
  │ ├── engine.mjs # the rules: claims, leases, handoffs, names, the ledger
489
709
  │ ├── load-store.mjs # finds the storage block that config.json names
490
710
  │ ├── store-file.mjs # the built-in storage block: a folder
711
+ │ ├── taskfile.mjs # reads a project's task file and its priorities
491
712
  │ └── contract.mjs # the tests every storage block must pass
492
713
  ├── examples/
493
714
  │ └── store-memory.mjs # a complete storage block in about 20 lines
494
715
  ├── hooks/
495
- │ ├── hooks.json
496
716
  │ ├── register.tsx # the Claude Code mod: tools, heartbeat, band, pane
497
717
  │ └── blocks/ # one file per display block, listed in index.ts
498
- ├── types/index.d.ts
499
718
  ├── .claude-plugin/
500
719
  │ └── plugin.json # the mod's manifest and settings
501
720
  ├── test/ # CLI and store contract tests (npm test)
502
721
  ├── tests/ # mod tests (claude plugin test .)
722
+ ├── CHANGELOG.md # what changed in each version
723
+ ├── ROADMAP.md # what's planned next
724
+ ├── CONTRIBUTING.md # how to contribute
503
725
  └── docs/
726
+ ├── TUTORIAL.md # from install to two agents sharing a board
504
727
  ├── system.txt .png # how it fits together
505
728
  ├── blocks.txt .png # how blocks work
506
- ├── board-live.gif # a live recording of three Claude sessions
507
- └── render.mjs # rebuilds every image from its .txt
508
- ```
509
-
510
- Each diagram's source is plain text. After editing a `.txt`,
511
- `node docs/render.mjs` rebuilds its page and image.
512
-
513
- ---
514
-
515
- ## Known limitations
516
-
517
- - **It doesn't work across machines yet.** The storage socket is in place,
518
- but the only block built is local files. A database or server block comes
519
- when a real cross-device need does.
520
- - **Usage is per session.** The usage block shows the session's own plan
521
- usage, which Claude Code reports, not the other agents'.
522
- - **A crash skips the release on session end.** If a Claude process is killed
523
- outright, its claims are freed once its session has been silent for
524
- 3 minutes. A plain CLI agent that never registered waits out its lease
525
- (15 minutes).
526
- - **A verification note is the agent's own claim.** The board requires one
527
- but doesn't run the check itself.
528
-
529
- ---
530
-
531
- ## Contributing
532
-
533
- ```bash
534
- npm test # CLI and store contract tests
535
- claude plugin test . # the mod's tests
536
- claude plugin validate . # the mod's manifest and hooks
729
+ ├── render.mjs # rebuilds each diagram from its .txt
730
+ ├── band.mjs .png # the band image
731
+ ├── board-live.gif # the live demo
732
+ ├── pane-*.png # screenshots of the /board pane
733
+ ├── taskfile-*.png # the To do list, at P0 and at all
734
+ └── logo.png # the modBOARD logo
537
735
  ```
538
736
 
539
- Changing what the board shows? Run both test suites. Adding a storage block
540
- or a display block? Start at [Make your own block](#make-your-own-block).
737
+ </details>
541
738
 
542
739
  ---
543
740