modboard 0.0.0-stage → 0.5.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 +50 -0
- package/LICENSE +21 -0
- package/README.md +545 -2
- package/bin/board.mjs +157 -0
- package/examples/store-memory.mjs +34 -0
- package/hooks/blocks/agents.tsx +8 -0
- package/hooks/blocks/attention.ts +14 -0
- package/hooks/blocks/clock.tsx +10 -0
- package/hooks/blocks/command.tsx +58 -0
- package/hooks/blocks/context.tsx +18 -0
- package/hooks/blocks/effort.tsx +30 -0
- package/hooks/blocks/index.ts +18 -0
- package/hooks/blocks/model.tsx +37 -0
- package/hooks/blocks/summary.tsx +46 -0
- package/hooks/blocks/tasks.tsx +77 -0
- package/hooks/blocks/types.tsx +38 -0
- package/hooks/blocks/usage.tsx +68 -0
- package/hooks/hooks.json +1 -0
- package/hooks/register.tsx +356 -0
- package/lib/contract.mjs +61 -0
- package/lib/engine.mjs +217 -0
- package/lib/load-store.mjs +66 -0
- package/lib/store-file.mjs +118 -0
- package/package.json +22 -4
- package/tsconfig.json +3 -0
- package/types/index.d.ts +23 -0
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "modboard",
|
|
3
|
+
"version": "0.5.0",
|
|
4
|
+
"description": "A task board several agents share: Claude tools, a live pane and lease heartbeats over an agent-neutral CLI",
|
|
5
|
+
"author": {
|
|
6
|
+
"name": "Magithar",
|
|
7
|
+
"url": "https://github.com/Magithar"
|
|
8
|
+
},
|
|
9
|
+
"repository": "https://github.com/Magithar/modboard",
|
|
10
|
+
"license": "MIT",
|
|
11
|
+
"keywords": [
|
|
12
|
+
"multi-agent",
|
|
13
|
+
"task-board",
|
|
14
|
+
"coordination",
|
|
15
|
+
"codex"
|
|
16
|
+
],
|
|
17
|
+
"types": "./types/index.d.ts",
|
|
18
|
+
"userConfig": {
|
|
19
|
+
"band": {
|
|
20
|
+
"type": "string",
|
|
21
|
+
"title": "Band blocks",
|
|
22
|
+
"description": "Blocks on the one line above the prompt, in order, comma-separated: summary, usage, model, effort, clock, context, or your own from Your own blocks.",
|
|
23
|
+
"default": "summary,usage,model,effort"
|
|
24
|
+
},
|
|
25
|
+
"pane": {
|
|
26
|
+
"type": "string",
|
|
27
|
+
"title": "Pane blocks",
|
|
28
|
+
"description": "Blocks in the /board pane, in order, comma-separated: tasks, usage, model, effort, clock, context, agents, or your own from Your own blocks.",
|
|
29
|
+
"default": "tasks,usage"
|
|
30
|
+
},
|
|
31
|
+
"blocks": {
|
|
32
|
+
"type": "string",
|
|
33
|
+
"title": "Your own blocks",
|
|
34
|
+
"description": "Blocks that show a shell command's first line of output, refreshed every 30 seconds, as JSON: {\"ci\": \"gh run list -L1 --json conclusion -q '.[0].conclusion'\"}. Then name them in Band blocks or Pane blocks.",
|
|
35
|
+
"default": ""
|
|
36
|
+
},
|
|
37
|
+
"models": {
|
|
38
|
+
"type": "string",
|
|
39
|
+
"title": "Models to switch between",
|
|
40
|
+
"description": "The models the model block steps through, in order, as /model takes them.",
|
|
41
|
+
"default": "opus,sonnet,haiku"
|
|
42
|
+
},
|
|
43
|
+
"efforts": {
|
|
44
|
+
"type": "string",
|
|
45
|
+
"title": "Effort levels to switch between",
|
|
46
|
+
"description": "The levels the effort block steps through, in order, as /effort takes them.",
|
|
47
|
+
"default": "low,medium,high,xhigh,max"
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
}
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Magithar
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,546 @@
|
|
|
1
|
-
|
|
1
|
+
<h1 align="center">modboard</h1>
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
<p align="center">
|
|
4
|
+
<img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"/>
|
|
5
|
+
<img src="https://img.shields.io/github/package-json/v/Magithar/modboard?label=version" alt="Version"/>
|
|
6
|
+
<img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg" alt="Node 18 or newer"/>
|
|
7
|
+
<img src="https://img.shields.io/badge/dependencies-0-brightgreen.svg" alt="No dependencies"/>
|
|
8
|
+
<img src="https://img.shields.io/badge/Claude_Code-2.1.295%2B-d97757.svg" alt="Claude Code 2.1.295 or newer"/>
|
|
9
|
+
</p>
|
|
10
|
+
|
|
11
|
+
<p align="center">
|
|
12
|
+
A task board several coding agents share at once. Two Claude Code sessions, a Codex session and a person can all claim tasks from it, see who holds what, and hand unfinished work to each other without losing context. One claim wins, a crashed agent's work comes back on its own, and nothing is marked done without saying how it was checked.<br/><br/>
|
|
13
|
+
Works with <a href="#claude-code">Claude Code</a>, <a href="#codex-opencode-or-any-agent-with-a-shell">Codex</a>, <a href="#codex-opencode-or-any-agent-with-a-shell">OpenCode</a>, and <a href="#codex-opencode-or-any-agent-with-a-shell">anything with a shell</a>, a person included.
|
|
14
|
+
</p>
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
<p align="center">
|
|
19
|
+
<a href="#see-it-in-action">Demo</a> • <a href="#install">Install</a> • <a href="#usage">Usage</a> • <a href="#how-it-fits-together">How it fits together</a> • <a href="#what-you-see">What you see</a> • <a href="#make-your-own-block">Make your own block</a> • <a href="#what-has-been-tested">Tested</a> • <a href="#project-structure">Project structure</a> • <a href="#known-limitations">Limitations</a> • <a href="#contributing">Contributing</a>
|
|
20
|
+
</p>
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## See it in action
|
|
25
|
+
|
|
26
|
+

|
|
27
|
+
|
|
28
|
+
Three real Claude Code sessions, recorded live at real speed. Two idle
|
|
29
|
+
stretches are cut: the wait before the sessions start, and four seconds while
|
|
30
|
+
one session wrapped up.
|
|
31
|
+
`frontend` and `backend` are each told to work the board, and `viewer` has
|
|
32
|
+
`/board` open. Both go for T-001. `frontend` wins, and `backend` is refused
|
|
33
|
+
and takes T-002. `frontend` writes part of T-003, then hands it off. The band
|
|
34
|
+
above its prompt says "T-003 was stopped partway, pick it up". `backend` reads
|
|
35
|
+
the handoff, finishes T-003, and the pane ends on "3 done".
|
|
36
|
+
|
|
37
|
+
What each part of the screen means: [what you see](#what-you-see).
|
|
38
|
+
|
|
39
|
+
---
|
|
40
|
+
|
|
41
|
+
## Install
|
|
42
|
+
|
|
43
|
+
| Agent | How |
|
|
44
|
+
|-------|-----|
|
|
45
|
+
| Claude Code | `claude --plugin-dir /path/to/modboard` ([steps](#claude-code)) |
|
|
46
|
+
| Codex, OpenCode, a shell | put `board` on your PATH and the protocol in `AGENTS.md` ([steps](#codex-opencode-or-any-agent-with-a-shell)) |
|
|
47
|
+
| A person | the same `board` CLI |
|
|
48
|
+
|
|
49
|
+
### The CLI
|
|
50
|
+
|
|
51
|
+
Every agent goes through it, Claude Code included:
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
git clone https://github.com/Magithar/modboard.git
|
|
55
|
+
cd modboard && npm link # puts `board` on your PATH
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Or from npm: `npm install -g modboard` puts `board` on your PATH, or
|
|
59
|
+
`npm install --save-dev modboard` inside a project, then `npx board ...`.
|
|
60
|
+
|
|
61
|
+
### Claude Code
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
BOARD_AGENT=frontend claude --plugin-dir /path/to/modboard
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
`BOARD_AGENT` is optional. It sets the name this session uses on the board.
|
|
68
|
+
The session gets the board's tools, a line above the prompt and the `/board`
|
|
69
|
+
pane.
|
|
70
|
+
|
|
71
|
+
> **Early access.** The Claude Code mod uses Claude Code's function-hooks API,
|
|
72
|
+
> which is early access and can change between releases. It needs Claude Code
|
|
73
|
+
> **2.1.295 or newer**. The CLI has no such dependency.
|
|
74
|
+
|
|
75
|
+
### Codex, OpenCode, or any agent with a shell
|
|
76
|
+
|
|
77
|
+
Give each session its own name, and put this protocol in its instructions
|
|
78
|
+
(`AGENTS.md`):
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
export BOARD_AGENT=codex
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
> Claim a task before working on it. Note progress. If you stop without
|
|
85
|
+
> finishing, release it with a handoff. Never touch a task another agent holds.
|
|
86
|
+
|
|
87
|
+
---
|
|
88
|
+
|
|
89
|
+
## Usage
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
export BOARD_AGENT=codex # who you are; unique per session
|
|
93
|
+
board list # ○ todo ◐ claimed ● done
|
|
94
|
+
board show T-001 # description, notes, handoffs
|
|
95
|
+
board claim T-001 # exit 6 if another agent holds it
|
|
96
|
+
board note T-001 "what changed" # also renews your lease
|
|
97
|
+
board heartbeat # renew all your leases
|
|
98
|
+
board release T-001 --handoff "done X, left Y, see Z"
|
|
99
|
+
board done T-001 --note "ran X, saw Y" # required: how you verified it
|
|
100
|
+
board release-all # free everything you hold
|
|
101
|
+
board add "title" --desc "..." --accept "how to tell it is done"
|
|
102
|
+
board agents # live agents
|
|
103
|
+
board view # every task and live agent, as JSON
|
|
104
|
+
board doctor # ledger vs state
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
Each command answers in a line or two for a person (`claimed T-001 … it's
|
|
108
|
+
yours until 14:05`); `--json` prints the data instead, for scripts. `view`
|
|
109
|
+
and `events` are for programs and always print JSON. Exit codes: 2 usage, 3 board busy, 4 no such
|
|
110
|
+
task, 5 not yours, 6 held by another agent, 7 name in use.
|
|
111
|
+
|
|
112
|
+
**Claude Code** gets these tools: `board_list`, `board_show`, `board_add`,
|
|
113
|
+
`board_claim`, `board_note`, `board_release` and `board_done`. Tool activity
|
|
114
|
+
renews the session's leases.
|
|
115
|
+
|
|
116
|
+
The CLI and the tools keep the board's precise terms (claim, release,
|
|
117
|
+
handoff, lease) because agents act on them. The display uses plain words
|
|
118
|
+
instead, so you can read it without learning those terms.
|
|
119
|
+
|
|
120
|
+
---
|
|
121
|
+
|
|
122
|
+
## How it fits together
|
|
123
|
+
|
|
124
|
+

|
|
125
|
+
|
|
126
|
+
One zero-dependency Node CLI owns all state. The Claude Code mod is an
|
|
127
|
+
adapter over that CLI. It adds what only Claude Code's host can provide: the
|
|
128
|
+
session's identity, a heartbeat on every tool call, and a live pane. Any
|
|
129
|
+
other agent uses the same CLI directly.
|
|
130
|
+
|
|
131
|
+
- **Storage is a block.** The engine never touches files. It reads a snapshot
|
|
132
|
+
from a Store and commits conditional writes ("only if this task is still at
|
|
133
|
+
the version I read"). Any backend that can do that atomically can hold a
|
|
134
|
+
board. See [Make your own block](#a-storage-block-an-adapter).
|
|
135
|
+
- **Where the board lives:** `.modboard/` next to the git *common* dir, so
|
|
136
|
+
every worktree of a repo shares one board. Set `BOARD_DIR` to override it.
|
|
137
|
+
Add `.modboard/` to `.gitignore`, because it is runtime state. A board made
|
|
138
|
+
before the rename, in `.agent-board/`, keeps working where it is.
|
|
139
|
+
- **Claims:** one lock per board (an atomic `mkdir`). The state file is
|
|
140
|
+
replaced with an atomic rename. Exactly one claimant wins, and only the
|
|
141
|
+
owner can note, release or finish a task.
|
|
142
|
+
- **Leases:** a claim lasts 15 minutes (`BOARD_LEASE_MS`). `heartbeat` or
|
|
143
|
+
`note` renews it. An expired claim goes back to todo, and the ledger records
|
|
144
|
+
it, so an agent that crashed doesn't hold a task forever. A Claude session
|
|
145
|
+
pings the board every minute while it is open, so if one is killed outright
|
|
146
|
+
its claims go back after 3 minutes of silence (`BOARD_PRESENCE_MS`), not 15.
|
|
147
|
+
An agent that never ran `board register` (a plain shell) keeps the lease
|
|
148
|
+
alone.
|
|
149
|
+
- **Names:** start a session with `BOARD_AGENT=frontend` to name it. If
|
|
150
|
+
another live session already holds the name, the new one becomes
|
|
151
|
+
`frontend-2` and gets a toast explaining why. Without a name, a session is
|
|
152
|
+
`claude:<session id>`. An open session keeps its name with a presence
|
|
153
|
+
heartbeat; a name is freed when its session ends or goes silent for
|
|
154
|
+
3 minutes.
|
|
155
|
+
- **Handoffs:** `release --handoff "..."` leaves a note that the next agent
|
|
156
|
+
reads with `show` before it continues. When a Claude session ends (exit,
|
|
157
|
+
`/clear`, resume, logout), the mod releases everything that session holds,
|
|
158
|
+
with an automatic handoff. That matters because a restarted session comes
|
|
159
|
+
back with a new identity.
|
|
160
|
+
- **Done means verified:** `done` needs a `--note` saying how the task was
|
|
161
|
+
checked, against its `--accept` criteria if it has any.
|
|
162
|
+
- **Ledger:** every change is appended to `ledger.jsonl`, including lost
|
|
163
|
+
claims (`claim-rejected`, with the holder). `board doctor` checks that the
|
|
164
|
+
ledger and the state agree.
|
|
165
|
+
|
|
166
|
+
---
|
|
167
|
+
|
|
168
|
+
## What you see
|
|
169
|
+
|
|
170
|
+
The display shows only what needs you. Everything else waits until you ask.
|
|
171
|
+
|
|
172
|
+
**One line above the prompt**, always visible while there's work on the board:
|
|
173
|
+
|
|
174
|
+
```
|
|
175
|
+
2 tasks waiting · 1 in progress T-005 was stopped partway, pick it up 5-hour limit ▓▓▓▓▓▓░░░░ 64% model Sonnet 5.5 effort medium
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
The line never wraps, and stays clear of Claude Code's own `[-]` control at
|
|
179
|
+
its right end. In a narrow window its parts shorten first, then the
|
|
180
|
+
last ones drop off. The first block (the summary) keeps its full form longest,
|
|
181
|
+
and the alert outlasts the counts:
|
|
182
|
+
|
|
183
|
+
```
|
|
184
|
+
124 cols 2 tasks waiting 5-hour limit ▓▓▓▓▓▓░░░░ 64% model Sonnet 5.5 effort low
|
|
185
|
+
64 cols 2 tasks waiting 5h ▓▓▓░░ 64% Sonnet 5.5 low
|
|
186
|
+
38 cols 2 tasks waiting 5h ▓▓▓░░ 64%
|
|
187
|
+
20 cols 2 tasks waiting
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
The alert names the one thing that needs you: a task someone stopped partway
|
|
191
|
+
that nobody has picked up, or an agent that stopped responding (its claim is
|
|
192
|
+
about to run out). Usage appears only once a limit passes 50%. It's green
|
|
193
|
+
with room left, yellow from 70% and red from 90%. With nothing waiting or in
|
|
194
|
+
progress, the line disappears.
|
|
195
|
+
|
|
196
|
+
**`/board`** opens the full pane:
|
|
197
|
+
|
|
198
|
+
```
|
|
199
|
+
In progress
|
|
200
|
+
◐ T-004 Add a test script you're on it
|
|
201
|
+
◐ T-007 Write the README backend is on it
|
|
202
|
+
◐ T-006 Add a LICENSE file codex stopped responding
|
|
203
|
+
|
|
204
|
+
Needs picking up
|
|
205
|
+
○ T-005 Ghost task frontend stopped partway · see its note
|
|
206
|
+
|
|
207
|
+
Not started
|
|
208
|
+
○ T-008 Add dark mode
|
|
209
|
+
|
|
210
|
+
3 done
|
|
211
|
+
|
|
212
|
+
Usage
|
|
213
|
+
5-hour limit ▓▓▓▓▓▓░░░░ 64% resets 12:00
|
|
214
|
+
weekly limit ▓▓░░░░░░░░ 20% resets in 3d
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
Both are stacks of display blocks, chosen in the plugin's settings (`/config`)
|
|
218
|
+
as comma-separated lists, in order:
|
|
219
|
+
|
|
220
|
+
| Block | Band | Pane | Shows |
|
|
221
|
+
|---|---|---|---|
|
|
222
|
+
| `summary` | ✓ | | what's waiting and in progress, and the one thing that needs you |
|
|
223
|
+
| `tasks` | | ✓ | in progress, then work stopped partway, then not started, then a count of done |
|
|
224
|
+
| `usage` | ✓ | ✓ | plan usage per window: in the band past 50%, in the pane with resets |
|
|
225
|
+
| `model` | ✓ | ✓ | the session's model; click it to switch to the next one |
|
|
226
|
+
| `effort` | ✓ | ✓ | the effort level; click it to step to the next one, wrapping from the highest to the lowest |
|
|
227
|
+
| `clock` | ✓ | ✓ | the time |
|
|
228
|
+
| `context` | ✓ | ✓ | context fill and the session's cost |
|
|
229
|
+
| `agents` | | ✓ | who is live on the board |
|
|
230
|
+
|
|
231
|
+
The defaults are `band: summary,usage,model,effort` and `pane: tasks,usage`.
|
|
232
|
+
|
|
233
|
+
Each row says who has a task as a sentence (`backend is on it`, `frontend
|
|
234
|
+
stopped partway`) rather than a bare name, which could mean whoever made,
|
|
235
|
+
holds or dropped it.
|
|
236
|
+
|
|
237
|
+
Click `model` or `effort` to switch: each click runs Claude Code's own
|
|
238
|
+
`/model` or `/effort`, the same as typing the command. (In the `/board` pane
|
|
239
|
+
they also answer to `m` and `e`.) Note that `/effort` saves the level as your
|
|
240
|
+
default for new sessions, except `max`, which lasts for this session only. The `models` setting lists what
|
|
241
|
+
the model block steps through (default `opus,sonnet,haiku`), and `efforts`
|
|
242
|
+
lists the effort levels (default `low,medium,high,xhigh,max`). A model or
|
|
243
|
+
effort changed by hand shows on the next request. Until the session's first
|
|
244
|
+
request, the effort block shows the level it will start on:
|
|
245
|
+
`CLAUDE_CODE_EFFORT_LEVEL` if set, else the model's own `effortLevel` under
|
|
246
|
+
`modelSettings`, else the general `effortLevel` setting.
|
|
247
|
+
|
|
248
|
+
**Your own blocks.** Show a command's output with no code, or write a block
|
|
249
|
+
of your own: see [Make your own block](#make-your-own-block).
|
|
250
|
+
|
|
251
|
+
---
|
|
252
|
+
|
|
253
|
+
## Make your own block
|
|
254
|
+
|
|
255
|
+
modboard is built from blocks, and you can add your own. There are two
|
|
256
|
+
kinds:
|
|
257
|
+
|
|
258
|
+
| Kind | What it does | How many | Where you choose it |
|
|
259
|
+
|---|---|---|---|
|
|
260
|
+
| **Storage block** (an adapter) | holds the board: a folder, a database, a server | one per board | `.modboard/config.json` |
|
|
261
|
+
| **Display block** | draws part of the board inside a Claude session | many, in order | the plugin's `band` and `pane` settings |
|
|
262
|
+
|
|
263
|
+

|
|
264
|
+
|
|
265
|
+
The diagram's source is plain text, [`docs/blocks.txt`](docs/blocks.txt).
|
|
266
|
+
|
|
267
|
+
### A storage block (an adapter)
|
|
268
|
+
|
|
269
|
+
Write one when the board should live somewhere other than a local folder,
|
|
270
|
+
for example so agents on different machines can share it. The engine keeps
|
|
271
|
+
every rule (claims, leases, handoffs). A block only stores records and
|
|
272
|
+
refuses writes that are out of date, so it never needs to know what a task
|
|
273
|
+
is.
|
|
274
|
+
|
|
275
|
+
**How an adapter works.** Every record carries a version, and every write
|
|
276
|
+
says which version it expects. Say agents A and B both claim T-001 at the
|
|
277
|
+
same moment:
|
|
278
|
+
|
|
279
|
+
1. Both read the board with `snapshot()`. T-001 is at version 3, and nobody
|
|
280
|
+
holds it.
|
|
281
|
+
2. Both decide the claim is fine, and both send `commit`: "claim T-001, only
|
|
282
|
+
if it is still at version 3".
|
|
283
|
+
3. A's commit lands first. The adapter sees version 3, writes the claim, and
|
|
284
|
+
T-001 moves to version 4.
|
|
285
|
+
4. B's commit finds version 4, not 3, so the adapter writes nothing and
|
|
286
|
+
answers `{ ok: false, conflict: 'T-001' }`.
|
|
287
|
+
5. The engine reads again for B, sees that A holds T-001, and refuses B:
|
|
288
|
+
"T-001 is already claimed by A" (exit 6). The ledger records B's attempt
|
|
289
|
+
as `claim-rejected`.
|
|
290
|
+
|
|
291
|
+
Three things follow from this:
|
|
292
|
+
|
|
293
|
+
- **The engine decides; the adapter keeps versions honest.** Claims, leases,
|
|
294
|
+
handoffs and names are all rules in the engine. An adapter for a new
|
|
295
|
+
backend never has to reimplement them.
|
|
296
|
+
- **The check and the write must be one step.** A transaction, a conditional
|
|
297
|
+
write or a lock. If an adapter checks the version and then writes in two
|
|
298
|
+
separate steps, A and B can both pass the check, and two agents end up
|
|
299
|
+
holding one task. The contract tests below race ten claims to catch this.
|
|
300
|
+
- **The ledger makes it checkable.** Each commit appends its events with the
|
|
301
|
+
writes. If a crash ever leaves the two out of step, `verify()` says so, and
|
|
302
|
+
`board doctor` reports it.
|
|
303
|
+
|
|
304
|
+
**1. Write the module.** One file that exports `createStore(config, { dir })`.
|
|
305
|
+
`config` is everything in `.modboard/config.json`, so your block's own
|
|
306
|
+
settings (a URL, a table name) go there too. `dir` is the `.modboard/`
|
|
307
|
+
folder. It returns five methods, all of which may be async:
|
|
308
|
+
|
|
309
|
+
```js
|
|
310
|
+
// my-block.mjs
|
|
311
|
+
export function createStore(config, { dir }) {
|
|
312
|
+
return {
|
|
313
|
+
// The store's clock, in ms. Leases are timed by it, so every machine
|
|
314
|
+
// agrees. A database should answer with its own time.
|
|
315
|
+
now: () => Date.now(),
|
|
316
|
+
|
|
317
|
+
// Every record, each with the version it stands at:
|
|
318
|
+
// { tasks: { 'T-001': { ...task, version: 3 } },
|
|
319
|
+
// agents: { frontend: { ...agent, version: 1 } } }
|
|
320
|
+
snapshot: async () => { /* read everything */ },
|
|
321
|
+
|
|
322
|
+
// writes: [{ kind: 'task' | 'agent', key, value, expect }]
|
|
323
|
+
// events: ledger entries to append
|
|
324
|
+
// Apply every write and append every event, or nothing at all, and only
|
|
325
|
+
// if each record still stands at `expect` (0 means it must not exist).
|
|
326
|
+
// An applied record's version becomes expect + 1. A null value deletes.
|
|
327
|
+
// Answer { ok: true }, or { ok: false, conflict: key } to have the
|
|
328
|
+
// engine read again and retry.
|
|
329
|
+
commit: async ({ writes, events }) => { /* one transaction */ },
|
|
330
|
+
|
|
331
|
+
// Ledger events with seq > since, in order. Give each appended event the
|
|
332
|
+
// next seq and an `at` time.
|
|
333
|
+
events: async (since = 0) => { /* ... */ },
|
|
334
|
+
|
|
335
|
+
// Does the ledger agree with the state? This is what `board doctor` reports.
|
|
336
|
+
verify: async () => ({ ok: true, problems: [] }),
|
|
337
|
+
}
|
|
338
|
+
}
|
|
339
|
+
```
|
|
340
|
+
|
|
341
|
+
`commit` is the only hard part: it must be all-or-none, and checking the
|
|
342
|
+
versions and writing must happen as one step (a database transaction, a
|
|
343
|
+
conditional write, a lock). [`examples/store-memory.mjs`](examples/store-memory.mjs)
|
|
344
|
+
is a complete, working block in about 20 lines to copy from, and
|
|
345
|
+
[`lib/store-file.mjs`](lib/store-file.mjs) is the built-in one.
|
|
346
|
+
|
|
347
|
+
**2. Test it against the contract.** The engine relies on a few rules and
|
|
348
|
+
nothing else: one winner when many agents claim one task, distinct ids when
|
|
349
|
+
they add at once, stale writes refused, one live session per name. They ship
|
|
350
|
+
as a test suite:
|
|
351
|
+
|
|
352
|
+
```js
|
|
353
|
+
// my-block.test.mjs, run with: node --test
|
|
354
|
+
import { storeContract } from 'modboard/lib/contract.mjs'
|
|
355
|
+
import { createStore } from './my-block.mjs'
|
|
356
|
+
|
|
357
|
+
storeContract('my block', () => createStore({ /* test settings */ }, { dir: '/tmp/board-test' }))
|
|
358
|
+
```
|
|
359
|
+
|
|
360
|
+
Each run should start from an empty board, so give each `createStore` call a
|
|
361
|
+
fresh table or folder.
|
|
362
|
+
|
|
363
|
+
**3. Point a board at it.** In `.modboard/config.json`, name it in one of
|
|
364
|
+
three ways. Everything besides `store` is passed to your block:
|
|
365
|
+
|
|
366
|
+
```json
|
|
367
|
+
{ "store": "file" } the built-in default
|
|
368
|
+
{ "store": "./stores/my-block.mjs", "url": "..." } a block file, relative to .modboard/
|
|
369
|
+
{ "store": "modboard-my-block", "url": "..." } a block published as a package
|
|
370
|
+
```
|
|
371
|
+
|
|
372
|
+
Then check it: `board add "first task"`, `board view`, and `board doctor`.
|
|
373
|
+
The CLI refuses a block that won't load or is missing a method, and says
|
|
374
|
+
which (exit 2).
|
|
375
|
+
|
|
376
|
+
**4. Share it (optional).** Publish it as a package whose entry exports
|
|
377
|
+
`createStore` (through `exports` or `main`), with `modboard` as a
|
|
378
|
+
dev dependency for the contract tests. Anyone can then
|
|
379
|
+
`npm install modboard-my-block` in their project and name it in
|
|
380
|
+
`config.json`. A package is found the way Node finds any package: in the
|
|
381
|
+
`node_modules` of the project that holds the board, or a folder above it.
|
|
382
|
+
|
|
383
|
+
### A display block from a command (no code)
|
|
384
|
+
|
|
385
|
+
The quickest way to show something of your own. The `blocks` setting (in
|
|
386
|
+
`/config`) maps a block name to a shell command. Every 30 seconds the command
|
|
387
|
+
runs, and the block shows the first line it prints, cut to 60 characters:
|
|
388
|
+
|
|
389
|
+
```json
|
|
390
|
+
{"ci": "gh run list -L1 --json conclusion -q '.[0].conclusion'", "branch": "git branch --show-current"}
|
|
391
|
+
```
|
|
392
|
+
|
|
393
|
+
Then name them in `band` or `pane` like a built-in block
|
|
394
|
+
(`band: summary,ci,usage`). In the band a command block shows as
|
|
395
|
+
`ci success`, or just `success` when the line is short.
|
|
396
|
+
|
|
397
|
+
- Names are lowercase letters, digits and dashes, up to 16 characters, and
|
|
398
|
+
can't reuse a built-in block's name. A bad entry is skipped, with a toast
|
|
399
|
+
saying why.
|
|
400
|
+
- A command that fails (non-zero exit) or prints nothing shows nothing.
|
|
401
|
+
- The setting lives in your user config, not in the project, so opening
|
|
402
|
+
someone else's repo can never make your session run its commands.
|
|
403
|
+
|
|
404
|
+
### A display block in code
|
|
405
|
+
|
|
406
|
+
For a block that reads the board itself, or reacts to a click. Each built-in
|
|
407
|
+
block is its own file in [`hooks/blocks/`](hooks/blocks/), and yours is a file
|
|
408
|
+
of the same shape:
|
|
409
|
+
|
|
410
|
+
```tsx
|
|
411
|
+
// hooks/blocks/mine.tsx: how many tasks are mine
|
|
412
|
+
import { words, type Block } from './types'
|
|
413
|
+
|
|
414
|
+
export const mine: Block = {
|
|
415
|
+
name: 'mine',
|
|
416
|
+
// The band: forms widest first. The band takes the widest that fits,
|
|
417
|
+
// and leaves the block out when even the last one doesn't.
|
|
418
|
+
band: ({ ui: { Text }, tasks, who }) => {
|
|
419
|
+
const n = tasks.filter(t => t.claim?.owner === who).length
|
|
420
|
+
if (!n) return null // nothing to say: the block takes no room
|
|
421
|
+
return [words(Text, `${n} mine`), words(Text, `${n}`)]
|
|
422
|
+
},
|
|
423
|
+
// The pane: one part of /board, or null.
|
|
424
|
+
pane: ({ ui: { Text }, tasks, who }) => (
|
|
425
|
+
<Text>{tasks.filter(t => t.claim?.owner === who).length} tasks are mine</Text>
|
|
426
|
+
),
|
|
427
|
+
}
|
|
428
|
+
```
|
|
429
|
+
|
|
430
|
+
Every block gets the same context (see [`types.tsx`](hooks/blocks/types.tsx)):
|
|
431
|
+
the tasks, the live agents, who this session is, plan usage, the model and
|
|
432
|
+
effort, the time, the width, your command blocks' output, and `act` for
|
|
433
|
+
switching the model or effort when the block is clicked. A block may draw in
|
|
434
|
+
the band, the pane or both.
|
|
435
|
+
|
|
436
|
+
Then list it in [`index.ts`](hooks/blocks/index.ts) (an import, and its name
|
|
437
|
+
in `BLOCKS`), name it in the `band` or `pane` setting, and run
|
|
438
|
+
`claude plugin test .`. Claude Code mods can't load code at runtime, so a
|
|
439
|
+
code block lives in your copy of the mod: fork this repo, or send it as a
|
|
440
|
+
pull request if others would want it.
|
|
441
|
+
|
|
442
|
+
---
|
|
443
|
+
|
|
444
|
+
## What has been tested
|
|
445
|
+
|
|
446
|
+
These tests ran on 2026-10-12 with two live Claude Code sessions (Sonnet 5.5,
|
|
447
|
+
v2.1.296), one shell acting as Codex, and no extra instructions to the agents
|
|
448
|
+
beyond the tool descriptions:
|
|
449
|
+
|
|
450
|
+
| Test | Result |
|
|
451
|
+
|---|---|
|
|
452
|
+
| Both sessions claim the same task at once | one wins; the other reports the holder and does no work |
|
|
453
|
+
| Both told "do the next task on the board" | they collided on one task; the loser moved to another by itself; each claimed before writing files |
|
|
454
|
+
| One session does part 1 and releases with a handoff | the other read the handoff and resumed from part 2 without redoing part 1 |
|
|
455
|
+
| `codex` claims a task from the shell | Claude was refused, said so, and left it alone |
|
|
456
|
+
| An agent's lease runs out | the task returns to todo, and the ledger records `expire` |
|
|
457
|
+
|
|
458
|
+
Automated tests: `npm test` runs the CLI tests (a 20-way claim race,
|
|
459
|
+
ownership, handoff, lease expiry, heartbeat, rejected-claim logging, verified
|
|
460
|
+
done, release-all) and the store contract against the file block and an
|
|
461
|
+
in-memory reference block (concurrent claims and adds, stale writes, names).
|
|
462
|
+
It also checks that the CLI loads a block named in `config.json` and refuses
|
|
463
|
+
a broken one. `claude plugin test .` runs the mod tests (the pane's sections
|
|
464
|
+
and alerts, the band and when it stays quiet, names and their fallback, the
|
|
465
|
+
tools, the verification note, release on session end, usage, and choosing
|
|
466
|
+
blocks).
|
|
467
|
+
|
|
468
|
+
---
|
|
469
|
+
|
|
470
|
+
## What modboard is not
|
|
471
|
+
|
|
472
|
+
- Not a project manager: no due dates, assignees or boards per team
|
|
473
|
+
- Not an agent runner: it never starts, stops or prompts an agent
|
|
474
|
+
- Not a sync service: one board lives in one place, the storage block decides where
|
|
475
|
+
|
|
476
|
+
modboard is a **claim ledger**: who holds what, what was left for the next
|
|
477
|
+
agent, and how each finished task was checked.
|
|
478
|
+
|
|
479
|
+
---
|
|
480
|
+
|
|
481
|
+
## Project structure
|
|
482
|
+
|
|
483
|
+
```
|
|
484
|
+
modboard/
|
|
485
|
+
├── bin/
|
|
486
|
+
│ └── board.mjs # the one CLI every agent uses
|
|
487
|
+
├── lib/
|
|
488
|
+
│ ├── engine.mjs # the rules: claims, leases, handoffs, names, the ledger
|
|
489
|
+
│ ├── load-store.mjs # finds the storage block that config.json names
|
|
490
|
+
│ ├── store-file.mjs # the built-in storage block: a folder
|
|
491
|
+
│ └── contract.mjs # the tests every storage block must pass
|
|
492
|
+
├── examples/
|
|
493
|
+
│ └── store-memory.mjs # a complete storage block in about 20 lines
|
|
494
|
+
├── hooks/
|
|
495
|
+
│ ├── hooks.json
|
|
496
|
+
│ ├── register.tsx # the Claude Code mod: tools, heartbeat, band, pane
|
|
497
|
+
│ └── blocks/ # one file per display block, listed in index.ts
|
|
498
|
+
├── types/index.d.ts
|
|
499
|
+
├── .claude-plugin/
|
|
500
|
+
│ └── plugin.json # the mod's manifest and settings
|
|
501
|
+
├── test/ # CLI and store contract tests (npm test)
|
|
502
|
+
├── tests/ # mod tests (claude plugin test .)
|
|
503
|
+
└── docs/
|
|
504
|
+
├── system.txt .png # how it fits together
|
|
505
|
+
├── blocks.txt .png # how blocks work
|
|
506
|
+
├── board-live.gif # a live recording of three Claude sessions
|
|
507
|
+
└── render.mjs # rebuilds every image from its .txt
|
|
508
|
+
```
|
|
509
|
+
|
|
510
|
+
Each diagram's source is plain text. After editing a `.txt`,
|
|
511
|
+
`node docs/render.mjs` rebuilds its page and image.
|
|
512
|
+
|
|
513
|
+
---
|
|
514
|
+
|
|
515
|
+
## Known limitations
|
|
516
|
+
|
|
517
|
+
- **It doesn't work across machines yet.** The storage socket is in place,
|
|
518
|
+
but the only block built is local files. A database or server block comes
|
|
519
|
+
when a real cross-device need does.
|
|
520
|
+
- **Usage is per session.** The usage block shows the session's own plan
|
|
521
|
+
usage, which Claude Code reports, not the other agents'.
|
|
522
|
+
- **A crash skips the release on session end.** If a Claude process is killed
|
|
523
|
+
outright, its claims are freed once its session has been silent for
|
|
524
|
+
3 minutes. A plain CLI agent that never registered waits out its lease
|
|
525
|
+
(15 minutes).
|
|
526
|
+
- **A verification note is the agent's own claim.** The board requires one
|
|
527
|
+
but doesn't run the check itself.
|
|
528
|
+
|
|
529
|
+
---
|
|
530
|
+
|
|
531
|
+
## Contributing
|
|
532
|
+
|
|
533
|
+
```bash
|
|
534
|
+
npm test # CLI and store contract tests
|
|
535
|
+
claude plugin test . # the mod's tests
|
|
536
|
+
claude plugin validate . # the mod's manifest and hooks
|
|
537
|
+
```
|
|
538
|
+
|
|
539
|
+
Changing what the board shows? Run both test suites. Adding a storage block
|
|
540
|
+
or a display block? Start at [Make your own block](#make-your-own-block).
|
|
541
|
+
|
|
542
|
+
---
|
|
543
|
+
|
|
544
|
+
## License
|
|
545
|
+
|
|
546
|
+
MIT
|