@gorlitzer-labs/seldon 0.1.24 → 0.9.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +191 -4
- package/bin/seldon.js +784 -62
- package/lib/actions.mjs +56 -0
- package/lib/agents.mjs +167 -0
- package/lib/holds-store.mjs +65 -0
- package/lib/holds.mjs +68 -0
- package/lib/home.mjs +64 -0
- package/lib/lanes.mjs +250 -0
- package/lib/machines.mjs +82 -0
- package/lib/notify.mjs +10 -0
- package/lib/projects.mjs +114 -0
- package/lib/reports.mjs +116 -0
- package/modules.mjs +6 -6
- package/package.json +2 -1
package/README.md
CHANGED
|
@@ -9,15 +9,19 @@
|
|
|
9
9
|
╚══════╝╚══════╝╚══════╝╚═════╝ ╚═════╝ ╚═╝ ╚═══╝
|
|
10
10
|
```
|
|
11
11
|
|
|
12
|
-
**
|
|
13
|
-
|
|
14
|
-
|
|
12
|
+
**One screen for every coding agent** — Claude Code, Codex, opencode — on every project and
|
|
13
|
+
machine: what is working, what needs you, what is next on the plan.
|
|
14
|
+
|
|
15
|
+
`seldon` is the panel. `seldon install` adds the optional add-ons (rooms, voice, secrets, the
|
|
16
|
+
plan), each via its native method (npm for the Node tools, a shell installer for bifrost, a
|
|
17
|
+
venv for demerzel).
|
|
15
18
|
|
|
16
19
|
## Install
|
|
17
20
|
|
|
18
21
|
```bash
|
|
19
22
|
pnpm add -g @gorlitzer-labs/seldon # or: bun add -g … · npm i -g …
|
|
20
|
-
seldon #
|
|
23
|
+
seldon # the panel
|
|
24
|
+
seldon install # the add-on checklist — ↑↓ move · space pick · a all · enter
|
|
21
25
|
```
|
|
22
26
|
|
|
23
27
|
Or name the modules directly:
|
|
@@ -28,6 +32,189 @@ seldon doctor # check external deps (tmux, sops, age, tailsca
|
|
|
28
32
|
seldon list # everything available
|
|
29
33
|
```
|
|
30
34
|
|
|
35
|
+
## The panel — `seldon`
|
|
36
|
+
|
|
37
|
+
```text
|
|
38
|
+
SELDON 1 need you · 2 working · 1 idle ● watcher ○ voice
|
|
39
|
+
|
|
40
|
+
❯ stranded plan 5 · 2 done
|
|
41
|
+
⚑ fix-save-crash claude needs you: permission prompt 2m
|
|
42
|
+
● smoke-harness codex working 40m
|
|
43
|
+
weather plan 2 · 0 done
|
|
44
|
+
● add-cache claude working 12m
|
|
45
|
+
○ docs-pass claude idle 1h
|
|
46
|
+
|
|
47
|
+
↑↓ move · ⏎ open · x stop · R resume · n new lane · p plan · r refresh · q quit
|
|
48
|
+
U start stack · D stop stack · i install
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Every coding agent on this machine — Claude Code, Codex, opencode — grouped by project (a
|
|
52
|
+
worktree counts for its main repo), most urgent first, refreshed every two seconds. `⏎` on an
|
|
53
|
+
agent opens it; `⏎` on a project runs `go`. Claude agents report their own state via
|
|
54
|
+
`claude agents --json`; Codex and opencode do after `seldon setup` (until then they read
|
|
55
|
+
*running*). Without a terminal
|
|
56
|
+
(a script, a hook, an agent's shell) the same rows are printed as plain text.
|
|
57
|
+
|
|
58
|
+
| key | does |
|
|
59
|
+
|---|---|
|
|
60
|
+
| `n` | new lane: type the task, pick `1` claude · `2` codex · `3` opencode (⏎ = claude) |
|
|
61
|
+
| `p` | the project's plan (`docs/QUEUE.md`); `⏎` on an item starts a lane on it, `a` adds one |
|
|
62
|
+
| `⏎` | on an agent: open it · on a project: `seldon go` |
|
|
63
|
+
| `x` `x` | stop the agent (asks twice) |
|
|
64
|
+
| `R` | resume what a reboot stopped; on a project, all of its stopped lanes |
|
|
65
|
+
|
|
66
|
+
Every lane gets its own branch and worktree. Claude lanes run as `claude --bg -w <slug>`, so
|
|
67
|
+
they live under Claude's own supervisor and show in `claude agents` too. Codex and opencode
|
|
68
|
+
lanes run in tmux (`seldon_<slug>`), in a worktree under `~/.seldon/worktrees/`, and are
|
|
69
|
+
recorded in `~/.seldon/lanes.json`. A plan item shows the lane working on it.
|
|
70
|
+
|
|
71
|
+
## Lanes from the command line
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
seldon lanes [--json] # every agent here
|
|
75
|
+
seldon lane start [dir] --task "fix the save crash" [--agent codex]
|
|
76
|
+
seldon lane stop|resume|open <name or key>
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
## Codex and opencode: let them report their state
|
|
80
|
+
|
|
81
|
+
Claude Code lists its own sessions. Codex and opencode do not, so out of the box their lanes
|
|
82
|
+
read *running*. One command teaches them to say what they are doing:
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
seldon setup # both, if installed · seldon setup codex | opencode · --remove
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
- **Codex:** adds command hooks to `~/.codex/hooks.json` (yours are kept). Codex runs a hook
|
|
89
|
+
only after you trust it, so open `codex` once, run `/hooks` and trust the seldon ones.
|
|
90
|
+
- **opencode:** installs a small plugin at `~/.config/opencode/plugins/seldon.js` that forwards
|
|
91
|
+
only the state events (busy / idle / permission asked / error).
|
|
92
|
+
|
|
93
|
+
Both call `seldon report <harness>`, which keeps one tiny state file per session in
|
|
94
|
+
`~/.seldon/state/`. The panel matches it to the lane by worktree, so a Codex lane waiting on an
|
|
95
|
+
approval shows **needs you: permission: Bash**, and the watcher tells you.
|
|
96
|
+
|
|
97
|
+
## The watcher — `seldon watch`
|
|
98
|
+
|
|
99
|
+
`seldon up` starts it; `seldon down` stops it. Every 5 seconds it reads the same lanes the
|
|
100
|
+
panel shows and sends a desktop notification **once** when an agent starts waiting on you,
|
|
101
|
+
fails, or finishes a piece of work. It is plain code: no tokens, and it never types into an
|
|
102
|
+
agent or posts into a room. `seldon watch` runs it in the foreground (`--interval 2s`,
|
|
103
|
+
`--once`).
|
|
104
|
+
|
|
105
|
+
## After a reboot
|
|
106
|
+
|
|
107
|
+
Claude lanes come back with Claude's own supervisor. A Codex or opencode lane whose tmux
|
|
108
|
+
session is gone (and that you did not stop with `x x`) shows as **stopped**; `R` on it brings
|
|
109
|
+
it back, and `R` on a project brings back all of its stopped lanes:
|
|
110
|
+
|
|
111
|
+
- Claude: `claude respawn` — the same conversation.
|
|
112
|
+
- Codex: `codex resume --last` in the lane's own worktree — the same conversation (Codex scopes
|
|
113
|
+
`--last` to the directory, and every lane has its own).
|
|
114
|
+
- opencode: a new conversation on the same task in the same worktree; the work on disk is kept.
|
|
115
|
+
(Its "continue" is per project and could pick up a sibling lane's conversation.)
|
|
116
|
+
|
|
117
|
+
## Other machines
|
|
118
|
+
|
|
119
|
+
The panel shows the agents on your other computers too, under `project @machine`, and every
|
|
120
|
+
key works on them: open, stop, resume, new lane, plan.
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
seldon machines add mini you@mini.tailnet.ts.net # once (needs seldon there + ssh keys)
|
|
124
|
+
seldon machines # each one, and whether it answers
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
- **The list:** machines are bifrost's realms (`~/.config/bifrost/realms/`), so bifrost,
|
|
128
|
+
factory and seldon share one list.
|
|
129
|
+
- **How it reaches them:** the panel runs `ssh <machine> seldon lanes --json` in the background
|
|
130
|
+
every 10 seconds, so a sleeping machine never freezes it, and it acts with
|
|
131
|
+
`ssh <machine> seldon lane <verb> <key>`.
|
|
132
|
+
- **From a phone:** `ssh` to any one machine and run `seldon`. Below 70 columns it switches to
|
|
133
|
+
one line per lane.
|
|
134
|
+
|
|
135
|
+
## Holds — taking turns on shared things
|
|
136
|
+
|
|
137
|
+
Agents on different projects share one machine: one boots the Android emulator, another
|
|
138
|
+
opens Unreal, and they trip over each other. A **hold** is turn-taking for that:
|
|
139
|
+
|
|
140
|
+
```bash
|
|
141
|
+
seldon hold emulator # yours, or wait your turn (90s, then exit 2: "held by stranded/fix-save")
|
|
142
|
+
seldon release emulator # done
|
|
143
|
+
seldon hold unreal -- ./build.sh # hold, run, release
|
|
144
|
+
seldon holds # who holds what
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
- **Ownership:** a hold belongs to the agent process that took it (the `claude` / `codex` /
|
|
148
|
+
`opencode` above the shell).
|
|
149
|
+
- **Expiry:** it ends when the agent exits, or after `--for` (30m default; ask again to renew),
|
|
150
|
+
so a crashed agent never blocks anyone.
|
|
151
|
+
- **Release:** only the holder can release it. `--force` exists for a hold that is truly stuck.
|
|
152
|
+
- **The panel:** shows current holds at the top.
|
|
153
|
+
|
|
154
|
+
Tell your agents once, in `~/.claude/CLAUDE.md` / `AGENTS.md`:
|
|
155
|
+
|
|
156
|
+
```markdown
|
|
157
|
+
## Shared machine resources
|
|
158
|
+
Before using the Android emulator, Unreal Editor or the GPU, run `seldon hold emulator`
|
|
159
|
+
(or `unreal`, `gpu`). Exit 2 means another agent has it: do other work and try again later.
|
|
160
|
+
Run `seldon release <name>` as soon as you are done.
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
## If something's off
|
|
164
|
+
|
|
165
|
+
| you see | do this |
|
|
166
|
+
|---|---|
|
|
167
|
+
| `seldon: command not found` in a new or SSH shell | the package manager's bin folder isn't on PATH there. it's `$(npm prefix -g)/bin` for npm, `$PNPM_HOME` for pnpm. Add that folder to PATH in `~/.zshrc` |
|
|
168
|
+
| `factory: command not found`, but `seldon` works | nothing to fix — `seldon go` and the panel prepend their own install folder, so the siblings resolve even in a non-interactive shell |
|
|
169
|
+
| you joined a room and you are alone in it | opening a room never staffs it. `seldon go` does both; or `factory staff <project>` |
|
|
170
|
+
| an old version answers, or two copies | `seldon install <tool>`. It leaves exactly one copy and says which one it removed |
|
|
171
|
+
| `seldon uninstall` says *still installed under …* | that exact path is left; delete it, then run the uninstall again |
|
|
172
|
+
| pnpm: *global bin directory … is not in PATH* | two pnpm versions on one machine. `seldon install` / `uninstall` handle it; avoid running `pnpm rm -g` by hand |
|
|
173
|
+
| Cursor / an app can't start `apiary mcp` | apps don't get your shell's PATH. Use absolute paths ([how](modules/apiary/README.md#mcp-server-apiary-mcp)) |
|
|
174
|
+
| an MCP agent's `catch_up` always says *nothing new* | apiary older than 1.13.9. Run `seldon install apiary` |
|
|
175
|
+
|
|
176
|
+
## With rooms: `seldon go` (apiary + factory add-ons)
|
|
177
|
+
|
|
178
|
+
The one verb. Run it inside a repo and it fills in whatever is missing, in order, then hands
|
|
179
|
+
you a seat in the room:
|
|
180
|
+
|
|
181
|
+
```bash
|
|
182
|
+
seldon go # this repo
|
|
183
|
+
seldon go stranded # by project name, from anywhere
|
|
184
|
+
seldon go --agent codex # a Codex agent rather than Claude
|
|
185
|
+
seldon go --no-staff # open the room, start nobody
|
|
186
|
+
seldon go --no-attach # do everything, leave the terminal alone
|
|
187
|
+
seldon go --attach # attach even with no terminal detected (inside tmux, a script)
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
```text
|
|
191
|
+
stranded /Users/you/Desktop/stranded
|
|
192
|
+
✓ adopted (foundation docs in place)
|
|
193
|
+
✓ hive up http://127.0.0.1:7920
|
|
194
|
+
✓ supervisor running
|
|
195
|
+
→ nobody is working here — staffing
|
|
196
|
+
queue 5 · 2 done · 2 lanes
|
|
197
|
+
next: (P1) automate the playtest checklist in the smoke harness…
|
|
198
|
+
→ attaching to the stranded room
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
`✓` is a step it skipped because it was already true, `→` one it did. The five steps are:
|
|
202
|
+
**adopted?** → **room up?** → **supervisor?** → **anyone working?** → **attach**. Each is
|
|
203
|
+
idempotent, so `go` is safe on a cold boot, twice in a row, or mid-session.
|
|
204
|
+
|
|
205
|
+
It owns no state of its own: it asks `factory state` what is missing and delegates every
|
|
206
|
+
action to `factory adopt`, `factory staff` and `apiary room resume`. The reason it exists is
|
|
207
|
+
that those four commands live in three tools and **none of them answered the whole question**
|
|
208
|
+
— so an adopted repo whose room had stopped looked exactly like a broken install.
|
|
209
|
+
|
|
210
|
+
Two things it fixes that bit repeatedly:
|
|
211
|
+
|
|
212
|
+
- **Opening a room does not staff it.** `factory adopt` leaves an *empty* room, so you joined
|
|
213
|
+
and sat there alone. `go` staffs before it attaches, and the panel flags "work queued,
|
|
214
|
+
nobody working" as needing you.
|
|
215
|
+
- **Siblings resolve.** `go` and the panel prepend seldon's own install folder to `PATH`, so
|
|
216
|
+
`factory: command not found` stops happening in non-interactive shells.
|
|
217
|
+
|
|
31
218
|
## Start the stack
|
|
32
219
|
|
|
33
220
|
One command brings up the always-on services and prints where to go:
|