@gorlitzer-labs/seldon 0.1.24 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -9,15 +9,19 @@
9
9
  ╚══════╝╚══════╝╚══════╝╚═════╝ ╚═════╝ ╚═╝ ╚═══╝
10
10
  ```
11
11
 
12
- **The installer for the Seldon stack** — a software factory of AI agents.
13
- Pick the tools you want from a checklist; each installs via its native method
14
- (npm for the Node tools, a shell installer for bifrost, a venv for demerzel).
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 # open the checklist — ↑↓ move · space pick · a all · enter install
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: