modboard 0.5.1 → 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,4 +1,6 @@
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"/>
@@ -8,159 +10,161 @@
8
10
  </p>
9
11
 
10
12
  <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
+ <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.
13
15
  </p>
14
16
 
15
- ---
16
-
17
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>
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>
19
26
  </p>
20
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
+
21
46
  ---
22
47
 
23
48
  ## See it in action
24
49
 
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)
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)
26
51
 
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".
52
+ Three real Claude Code sessions, recorded live at real speed. Only the wait
53
+ before the two workers start is cut.
35
54
 
36
- 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`.
37
64
 
38
- ---
65
+ The demo project has no task file, so **To do** doesn't appear here; see
66
+ [Your task.md](#your-taskmd).
39
67
 
40
- ## Install
68
+ ---
41
69
 
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 |
70
+ ## Quick start
47
71
 
48
- ### 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.
49
76
 
50
- Every agent goes through it, Claude Code included:
77
+ **1. Install the `board` CLI.** Every agent uses it, Claude Code included.
51
78
 
52
79
  ```bash
53
- git clone https://github.com/Magithar/modboard.git
54
- cd modboard && npm link # puts `board` on your PATH
80
+ npm install -g modboard
55
81
  ```
56
82
 
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 ...`.
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 …`.
59
86
 
60
- ### Claude Code
87
+ **2. Connect your agents.**
61
88
 
62
- ```bash
63
- BOARD_AGENT=frontend claude --plugin-dir /path/to/modboard
64
- ```
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:
65
97
 
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.
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`.
69
104
 
105
+ > [!IMPORTANT]
70
106
  > **Early access.** The Claude Code mod uses Claude Code's function-hooks API,
71
107
  > which is early access and can change between releases. It needs Claude Code
72
108
  > **2.1.295 or newer**. The CLI has no such dependency.
73
109
 
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`):
110
+ **3. Add a task and open the board.**
78
111
 
79
112
  ```bash
80
- export BOARD_AGENT=codex
113
+ board add "Add a login page" --accept "signing in works"
81
114
  ```
82
115
 
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.
116
+ Then type `/board` in Claude Code.
85
117
 
86
118
  ---
87
119
 
88
- ## Usage
120
+ ## Everyday use
89
121
 
90
122
  ```bash
91
- export BOARD_AGENT=codex # who you are; unique per session
92
123
  board list # ○ todo ◐ claimed ● done
93
124
  board show T-001 # description, notes, handoffs
94
125
  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
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
100
129
  board add "title" --desc "..." --accept "how to tell it is done"
101
- 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
102
145
  board view # every task and live agent, as JSON
103
- board doctor # ledger vs state
146
+ board doctor # check the ledger against the state
147
+ board taskfile # the project's task.md, read only
104
148
  ```
105
149
 
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.
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 |
110
158
 
111
159
  **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.
160
+ `board_claim`, `board_note`, `board_release` and `board_done`. Any tool call
161
+ renews the session's claims.
114
162
 
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.
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.
118
166
 
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.
167
+ </details>
164
168
 
165
169
  ---
166
170
 
@@ -168,185 +172,400 @@ other agent uses the same CLI directly.
168
172
 
169
173
  The display shows only what needs you. Everything else waits until you ask.
170
174
 
171
- **One line above the prompt**, always visible while there's work on the board:
175
+ ### The band
172
176
 
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
- ```
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` |
176
187
 
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:
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/>
181
195
 
182
196
  ```
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
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]
187
202
  ```
188
203
 
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.
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.
194
208
 
195
- **`/board`** opens the full pane:
209
+ </details>
196
210
 
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
211
+ ### The `/board` pane
202
212
 
203
- Needs picking up
204
- ○ 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>
205
288
 
206
- Not started
207
- ○ T-008 Add dark mode
289
+ ---
208
290
 
209
- 3 done
291
+ ## Settings
210
292
 
211
- Usage
212
- 5-hour limit ▓▓▓▓▓▓░░░░ 64% resets 12:00
213
- weekly limit ▓▓░░░░░░░░ 20% resets in 3d
214
- ```
293
+ Open the plugin's settings with `/config`.
215
294
 
216
- Both are stacks of display blocks, chosen in the plugin's settings (`/config`)
217
- 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
+ ```
218
303
 
219
304
  | 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 |
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 |
226
314
  | `clock` | ✓ | ✓ | the time |
227
- | `context` | ✓ | ✓ | context fill and the session's cost |
315
+ | `context` | ✓ | ✓ | context fill and the session's cost, as text |
228
316
  | `agents` | | ✓ | who is live on the board |
229
317
 
230
- 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
231
322
 
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.
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.
235
325
 
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.
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 |
246
330
 
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).
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.
249
397
 
250
398
  ---
251
399
 
252
400
  ## Make your own block
253
401
 
254
- modboard is built from blocks, and you can add your own. There are two
255
- kinds:
402
+ modBOARD is built from blocks, and you can add your own. Pick the row that
403
+ matches what you want:
256
404
 
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 |
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 |
261
410
 
262
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)
263
412
 
264
413
  The diagram's source is plain text, [`docs/blocks.txt`](docs/blocks.txt).
265
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
+
266
508
  ### A storage block (an adapter)
267
509
 
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.
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.
273
512
 
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:
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.**
277
516
 
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:
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.
307
530
 
308
531
  ```js
309
532
  // my-block.mjs
310
533
  export function createStore(config, { dir }) {
311
534
  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.
535
+ // A database should answer with its own time, so every machine agrees.
314
536
  now: () => Date.now(),
315
537
 
316
- // Every record, each with the version it stands at:
317
- // { tasks: { 'T-001': { ...task, version: 3 } },
318
- // agents: { frontend: { ...agent, version: 1 } } }
538
+ // { tasks: { 'T-001': { ...task, version: 3 } },
539
+ // agents: { 'claude 1': { ...agent, version: 1 } } }
319
540
  snapshot: async () => { /* read everything */ },
320
541
 
321
542
  // 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.
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.
328
547
  commit: async ({ writes, events }) => { /* one transaction */ },
329
548
 
330
- // Ledger events with seq > since, in order. Give each appended event the
331
- // next seq and an `at` time.
549
+ // Give each appended event the next `seq` and an `at` time.
332
550
  events: async (since = 0) => { /* ... */ },
333
551
 
334
- // Does the ledger agree with the state? This is what `board doctor` reports.
335
552
  verify: async () => ({ ok: true, problems: [] }),
336
553
  }
337
554
  }
338
555
  ```
339
556
 
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.
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.
345
565
 
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:
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:
350
569
 
351
570
  ```js
352
571
  // my-block.test.mjs, run with: node --test
@@ -356,95 +575,63 @@ import { createStore } from './my-block.mjs'
356
575
  storeContract('my block', () => createStore({ /* test settings */ }, { dir: '/tmp/board-test' }))
357
576
  ```
358
577
 
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:
578
+ Give each `createStore` call a fresh table or folder, so each run starts empty.
364
579
 
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
- ```
580
+ **3. Point a board at it** in `.modboard/config.json`. Everything besides
581
+ `store` is passed to your block:
370
582
 
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).
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 |
374
588
 
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.
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).
381
592
 
382
- ### 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.
383
598
 
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:
599
+ <details>
600
+ <summary><b>Why the version check matters: two agents claim one task</b></summary>
387
601
 
388
- ```json
389
- {"ci": "gh run list -L1 --json conclusion -q '.[0].conclusion'", "branch": "git branch --show-current"}
390
- ```
602
+ <br/>
391
603
 
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.
604
+ Say agents A and B both claim T-001 at the same moment:
395
605
 
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:
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`.
408
616
 
409
- ```tsx
410
- // hooks/blocks/mine.tsx: how many tasks are mine
411
- 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.
412
620
 
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
- ```
621
+ </details>
428
622
 
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.
623
+ ---
434
624
 
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.
625
+ ## Testing
440
626
 
441
- ---
627
+ <details>
628
+ <summary><b>Tested live with two Claude Code sessions and a shell</b></summary>
442
629
 
443
- ## What has been tested
630
+ <br/>
444
631
 
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:
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:
448
635
 
449
636
  | Test | Result |
450
637
  |---|---|
@@ -452,96 +639,102 @@ beyond the tool descriptions:
452
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 |
453
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 |
454
641
  | `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).
642
+ | An agent's lease runs out | the task goes back to waiting, and the ledger records `expire` |
466
643
 
467
- ---
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/>
468
654
 
469
- ## What modboard is not
655
+ **`npm test`** runs the CLI tests and the store contract:
470
656
 
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
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
474
663
 
475
- modboard is a **claim ledger**: who holds what, what was left for the next
476
- 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.
477
684
 
478
685
  ---
479
686
 
480
- ## 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/>
481
703
 
482
704
  ```
483
705
  modboard/
484
- ├── bin/
485
- │ └── board.mjs # the one CLI every agent uses
706
+ ├── bin/board.mjs # the one CLI every agent uses
486
707
  ├── lib/
487
708
  │ ├── engine.mjs # the rules: claims, leases, handoffs, names, the ledger
488
709
  │ ├── load-store.mjs # finds the storage block that config.json names
489
710
  │ ├── store-file.mjs # the built-in storage block: a folder
711
+ │ ├── taskfile.mjs # reads a project's task file and its priorities
490
712
  │ └── contract.mjs # the tests every storage block must pass
491
713
  ├── examples/
492
714
  │ └── store-memory.mjs # a complete storage block in about 20 lines
493
715
  ├── hooks/
494
- │ ├── hooks.json
495
716
  │ ├── register.tsx # the Claude Code mod: tools, heartbeat, band, pane
496
717
  │ └── blocks/ # one file per display block, listed in index.ts
497
- ├── types/index.d.ts
498
718
  ├── .claude-plugin/
499
719
  │ └── plugin.json # the mod's manifest and settings
500
720
  ├── test/ # CLI and store contract tests (npm test)
501
721
  ├── 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
722
  ├── 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
723
+ ├── ROADMAP.md # what's planned next
724
+ ├── CONTRIBUTING.md # how to contribute
725
+ └── docs/
726
+ ├── TUTORIAL.md # from install to two agents sharing a board
727
+ ├── system.txt .png # how it fits together
728
+ ├── blocks.txt .png # how blocks work
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
538
735
  ```
539
736
 
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.
737
+ </details>
545
738
 
546
739
  ---
547
740