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/.claude-plugin/plugin.json +5 -5
- package/CHANGELOG.md +99 -0
- package/README.md +559 -366
- package/ROADMAP.md +48 -0
- package/bin/board.mjs +54 -17
- package/hooks/blocks/board.tsx +23 -0
- package/hooks/blocks/clock.tsx +1 -1
- package/hooks/blocks/compact.tsx +49 -0
- package/hooks/blocks/context.tsx +1 -0
- package/hooks/blocks/effort.tsx +9 -10
- package/hooks/blocks/index.ts +4 -1
- package/hooks/blocks/meter.tsx +29 -0
- package/hooks/blocks/model.tsx +9 -10
- package/hooks/blocks/summary.tsx +46 -29
- package/hooks/blocks/taskfile.tsx +130 -0
- package/hooks/blocks/tasks.tsx +117 -26
- package/hooks/blocks/types.tsx +15 -3
- package/hooks/blocks/usage.tsx +21 -30
- package/hooks/register.tsx +218 -28
- package/lib/contract.mjs +12 -0
- package/lib/engine.mjs +22 -1
- package/lib/taskfile.mjs +151 -0
- package/package.json +2 -2
- package/types/index.d.ts +8 -1
package/README.md
CHANGED
|
@@ -1,4 +1,6 @@
|
|
|
1
|
-
<h1 align="center">
|
|
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
|
-
|
|
12
|
-
Works with
|
|
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>
|
|
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
|
-

|
|
26
51
|
|
|
27
|
-
Three real Claude Code sessions, recorded live at real speed. Only
|
|
28
|
-
|
|
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
|
-
|
|
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
|
-
|
|
68
|
+
---
|
|
41
69
|
|
|
42
|
-
|
|
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
|
-
|
|
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
|
|
77
|
+
**1. Install the `board` CLI.** Every agent uses it, Claude Code included.
|
|
51
78
|
|
|
52
79
|
```bash
|
|
53
|
-
|
|
54
|
-
cd modboard && npm link # puts `board` on your PATH
|
|
80
|
+
npm install -g modboard
|
|
55
81
|
```
|
|
56
82
|
|
|
57
|
-
Or from
|
|
58
|
-
`npm
|
|
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
|
-
|
|
87
|
+
**2. Connect your agents.**
|
|
61
88
|
|
|
62
|
-
|
|
63
|
-
|
|
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
|
-
|
|
67
|
-
|
|
68
|
-
|
|
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
|
-
|
|
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
|
-
|
|
113
|
+
board add "Add a login page" --accept "signing in works"
|
|
81
114
|
```
|
|
82
115
|
|
|
83
|
-
|
|
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
|
-
##
|
|
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
|
|
96
|
-
board
|
|
97
|
-
board
|
|
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
|
-
|
|
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
|
|
146
|
+
board doctor # check the ledger against the state
|
|
147
|
+
board taskfile # the project's task.md, read only
|
|
104
148
|
```
|
|
105
149
|
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
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`.
|
|
113
|
-
renews the session's
|
|
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
|
|
116
|
-
|
|
117
|
-
|
|
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
|
-

|
|
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
|
-
|
|
175
|
+
### The band
|
|
172
176
|
|
|
173
|
-
|
|
174
|
-
|
|
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
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
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
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
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
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
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
|
-
|
|
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
|
-
|
|
204
|
-
|
|
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
|
-
|
|
207
|
-
○ T-008 Add dark mode
|
|
289
|
+
---
|
|
208
290
|
|
|
209
|
-
|
|
291
|
+
## Settings
|
|
210
292
|
|
|
211
|
-
|
|
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
|
-
|
|
217
|
-
|
|
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
|
|
222
|
-
| `
|
|
223
|
-
| `
|
|
224
|
-
| `
|
|
225
|
-
| `
|
|
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
|
-
|
|
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
|
-
|
|
233
|
-
|
|
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
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
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
|
-
|
|
248
|
-
|
|
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
|
+

|
|
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
|
-
|
|
255
|
-
|
|
402
|
+
modBOARD is built from blocks, and you can add your own. Pick the row that
|
|
403
|
+
matches what you want:
|
|
256
404
|
|
|
257
|
-
|
|
|
258
|
-
|
|
259
|
-
|
|
|
260
|
-
|
|
|
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
|

|
|
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
|
-
|
|
269
|
-
for example so agents on different machines can share it.
|
|
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
|
-
|
|
275
|
-
|
|
276
|
-
|
|
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.
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
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
|
-
//
|
|
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
|
-
//
|
|
317
|
-
//
|
|
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
|
-
//
|
|
323
|
-
//
|
|
324
|
-
//
|
|
325
|
-
//
|
|
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
|
-
//
|
|
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
|
-
|
|
341
|
-
|
|
342
|
-
conditional write, a lock
|
|
343
|
-
|
|
344
|
-
|
|
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
|
|
347
|
-
|
|
348
|
-
|
|
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
|
-
|
|
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
|
-
|
|
366
|
-
|
|
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
|
-
|
|
372
|
-
|
|
373
|
-
|
|
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.
|
|
376
|
-
|
|
377
|
-
|
|
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
|
-
|
|
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
|
-
|
|
385
|
-
|
|
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
|
-
|
|
389
|
-
{"ci": "gh run list -L1 --json conclusion -q '.[0].conclusion'", "branch": "git branch --show-current"}
|
|
390
|
-
```
|
|
602
|
+
<br/>
|
|
391
603
|
|
|
392
|
-
|
|
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
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
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
|
-
|
|
410
|
-
|
|
411
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
630
|
+
<br/>
|
|
444
631
|
|
|
445
|
-
These
|
|
446
|
-
v2.1.296), one shell acting as Codex, and no
|
|
447
|
-
|
|
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
|
|
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
|
-
|
|
655
|
+
**`npm test`** runs the CLI tests and the store contract:
|
|
470
656
|
|
|
471
|
-
-
|
|
472
|
-
-
|
|
473
|
-
-
|
|
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
|
-
|
|
476
|
-
|
|
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
|
-
##
|
|
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
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
|
|
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
|
-
|
|
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
|
|