zswarm 0.4.0 → 0.4.2
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/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "zswarm",
|
|
3
|
-
"version": "0.4.
|
|
3
|
+
"version": "0.4.2",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Coordinate CLI agent crews in Zellij panes",
|
|
6
6
|
"engines": {
|
|
@@ -23,8 +23,8 @@
|
|
|
23
23
|
"skills"
|
|
24
24
|
],
|
|
25
25
|
"dependencies": {
|
|
26
|
-
"@zswarm/cli": "0.4.
|
|
27
|
-
"@zswarm/mcp": "0.3.
|
|
26
|
+
"@zswarm/cli": "0.4.2",
|
|
27
|
+
"@zswarm/mcp": "0.3.2"
|
|
28
28
|
},
|
|
29
29
|
"publishConfig": {
|
|
30
30
|
"access": "public"
|
package/skills/zswarm/SKILL.md
CHANGED
|
@@ -1,75 +1,76 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: zswarm
|
|
3
|
-
description: >-
|
|
4
|
-
Coordinate CLI crews in Zellij panes via zSwarm MCP (list, send, dump, tail,
|
|
5
|
-
wait, status, keys, interrupt, spawn, close, broadcast, signal, signals,
|
|
6
|
-
await, log, worktrees, unworktree, rename, focus, tabs, layout, stack, diff,
|
|
7
|
-
checkpoint, bus, serve). Use when messaging another Codex, Claude Code, Cursor
|
|
8
|
-
CLI, pi, OpenCode, or agy session in a Zellij pane, waiting for one to finish,
|
|
9
|
-
broadcasting to a crew, signalling barriers,
|
|
10
|
-
interrupting, opening a new crew pane, isolating peers in git worktrees,
|
|
11
|
-
reviewing peer diffs/checkpoints, renaming/focusing panes, or dumping short
|
|
12
|
-
scrollback. Same host as Zellij, or ZSWARM_SSH / ZSWARM_SERVE for a remote
|
|
13
|
-
crew — not IDE side-panel chat.
|
|
14
|
-
---
|
|
15
|
-
|
|
16
|
-
# zSwarm
|
|
17
|
-
|
|
18
|
-
Talk to **CLI** sessions in Zellij panes (Codex, Claude Code, Cursor CLI, pi, OpenCode, agy, shells).
|
|
19
|
-
Delivery is `zellij action paste` + Enter. Not IDE side-panel chat.
|
|
20
|
-
|
|
21
|
-
## Happy path
|
|
22
|
-
|
|
23
|
-
```text
|
|
24
|
-
zswarm({ op: "list" })
|
|
25
|
-
zswarm({ op: "send", to: "reviewer", body: "please review the plan" })
|
|
26
|
-
zswarm({ op: "wait", to: "reviewer", for: "idle" })
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
`session` when more than one Zellij session is live, or set `ZSWARM_SESSION`.
|
|
30
|
-
Resolution: arg → `ZSWARM_SESSION` → `ZELLIJ_SESSION_NAME` → the sole live session.
|
|
31
|
-
MCP hosts inherit neither PATH nor Zellij env — absolute interpreter + `ZSWARM_SESSION`.
|
|
32
|
-
CLI backup: `zswarm <op>` (`@zswarm/cli`).
|
|
33
|
-
|
|
34
|
-
## Read when needed
|
|
35
|
-
|
|
36
|
-
- Ops, submit/expect, bus: [references/ops.md](references/ops.md)
|
|
37
|
-
- Remote SSH (Linux / macOS / Windows) / serve: [references/remote.md](references/remote.md)
|
|
38
|
-
- Barriers, worktrees, review, wait: [references/workflows.md](references/workflows.md)
|
|
39
|
-
- Harness notes: [references/harness.md](references/harness.md)
|
|
40
|
-
|
|
41
|
-
## Prefix
|
|
42
|
-
|
|
43
|
-
Unless `raw: true`:
|
|
44
|
-
|
|
45
|
-
```text
|
|
46
|
-
[zswarm from=<sender>
|
|
47
|
-
<body>
|
|
48
|
-
```
|
|
49
|
-
|
|
50
|
-
`<sender>` is `from` if you pass it, else `ZSWARM_FROM`, else the sending
|
|
51
|
-
pane's title when `ZELLIJ_PANE_ID` / `ZSWARM_SELF_PANE` is visible, else
|
|
52
|
-
`swarm`. zswarm appends the sender's session/pane and host
|
|
53
|
-
hides it) when known, and `via
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
Zellij.
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
1
|
+
---
|
|
2
|
+
name: zswarm
|
|
3
|
+
description: >-
|
|
4
|
+
Coordinate CLI crews in Zellij panes via zSwarm MCP (list, send, dump, tail,
|
|
5
|
+
wait, status, keys, interrupt, spawn, close, broadcast, signal, signals,
|
|
6
|
+
await, log, worktrees, unworktree, rename, focus, tabs, layout, stack, diff,
|
|
7
|
+
checkpoint, bus, serve). Use when messaging another Codex, Claude Code, Cursor
|
|
8
|
+
CLI, pi, OpenCode, or agy session in a Zellij pane, waiting for one to finish,
|
|
9
|
+
broadcasting to a crew, signalling barriers,
|
|
10
|
+
interrupting, opening a new crew pane, isolating peers in git worktrees,
|
|
11
|
+
reviewing peer diffs/checkpoints, renaming/focusing panes, or dumping short
|
|
12
|
+
scrollback. Same host as Zellij, or ZSWARM_SSH / ZSWARM_SERVE for a remote
|
|
13
|
+
crew — not IDE side-panel chat.
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
# zSwarm
|
|
17
|
+
|
|
18
|
+
Talk to **CLI** sessions in Zellij panes (Codex, Claude Code, Cursor CLI, pi, OpenCode, agy, shells).
|
|
19
|
+
Delivery is `zellij action paste` + Enter. Not IDE side-panel chat.
|
|
20
|
+
|
|
21
|
+
## Happy path
|
|
22
|
+
|
|
23
|
+
```text
|
|
24
|
+
zswarm({ op: "list" })
|
|
25
|
+
zswarm({ op: "send", to: "reviewer", body: "please review the plan" })
|
|
26
|
+
zswarm({ op: "wait", to: "reviewer", for: "idle" })
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
`session` when more than one Zellij session is live, or set `ZSWARM_SESSION`.
|
|
30
|
+
Resolution: arg → `ZSWARM_SESSION` → `ZELLIJ_SESSION_NAME` → the sole live session.
|
|
31
|
+
MCP hosts inherit neither PATH nor Zellij env — absolute interpreter + `ZSWARM_SESSION`.
|
|
32
|
+
CLI backup: `zswarm <op>` (`@zswarm/cli`).
|
|
33
|
+
|
|
34
|
+
## Read when needed
|
|
35
|
+
|
|
36
|
+
- Ops, submit/expect, bus: [references/ops.md](references/ops.md)
|
|
37
|
+
- Remote SSH (Linux / macOS / Windows) / serve: [references/remote.md](references/remote.md)
|
|
38
|
+
- Barriers, worktrees, review, wait: [references/workflows.md](references/workflows.md)
|
|
39
|
+
- Harness notes: [references/harness.md](references/harness.md)
|
|
40
|
+
|
|
41
|
+
## Prefix
|
|
42
|
+
|
|
43
|
+
Unless `raw: true`:
|
|
44
|
+
|
|
45
|
+
```text
|
|
46
|
+
[zswarm from=<sender> src=<session>/<pane> host=<host> via=serve]
|
|
47
|
+
<body>
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
`<sender>` is `from` if you pass it, else `ZSWARM_FROM`, else the sending
|
|
51
|
+
pane's title when `ZELLIJ_PANE_ID` / `ZSWARM_SELF_PANE` is visible, else
|
|
52
|
+
`swarm`. zswarm appends `src=` (the sender's session/pane) and `host=`
|
|
53
|
+
(`ZSWARM_HOST`, `-` hides it) when known, and `via=serve` when the message
|
|
54
|
+
arrived over serve. `from=` is always the bare label.
|
|
55
|
+
MCP hosts that drop Zellij env need those vars listed (or set
|
|
56
|
+
`from` / `ZSWARM_FROM`).
|
|
57
|
+
|
|
58
|
+
## Rules
|
|
59
|
+
|
|
60
|
+
1. Target **pane ids or names** from `list` — do not invent transports.
|
|
61
|
+
2. Keep the session + pane ID returned by `spawn`. Use names once `alias.observed` is true; retry observation before creating a duplicate.
|
|
62
|
+
3. Prefer `send` + `wait` over polling. Prefer `tail` over repeated `dump`.
|
|
63
|
+
4. Check `submitted` on `send`: `false` is still in the composer, `"unverified"` is inconclusive (the screen changed while the body is not visible — never a resend), and `"not-delivered"` means nothing landed (safe to resend). `--confirm` never pastes the body twice.
|
|
64
|
+
5. Prefer `diff` / `checkpoint` over reading a worktree by hand.
|
|
65
|
+
6. Zellij terminal panes only — not IDE side-panel chats.
|
|
66
|
+
7. Same host as Zellij, or `ZSWARM_SSH` / `ZSWARM_SERVE`. Linux/macOS SSH is
|
|
67
|
+
the same user + `$TMPDIR`. Windows pane attach: `ZSWARM_SSH_MODE=interactive`
|
|
68
|
+
or `zswarm serve` next to Zellij. `file:` wasm stays on the box that owns
|
|
69
|
+
Zellij. Details: [references/remote.md](references/remote.md).
|
|
70
|
+
8. Writes refuse own pane (`self_target`) and exited panes (`pane_exited`).
|
|
71
|
+
Override with `allowSelf` / `force` only when you mean it.
|
|
72
|
+
9. Policy env vars can block writes (`policy_denied` names the env var).
|
|
73
|
+
10. `spawn` is executable + argv — no shell, so no pipes or `&&`.
|
|
74
|
+
11. Prefer `worktree` on `spawn` when peers should not share one dirty tree.
|
|
75
|
+
Tear down with `unworktree` after the pane is closed.
|
|
76
|
+
12. Crew barriers: `broadcast` + `signal` + `await`, not ad-hoc dumps.
|
|
@@ -5,7 +5,7 @@ MCP: `zswarm({ op, ... })`. CLI: `zswarm <op>`. Same surface.
|
|
|
5
5
|
| op | Purpose |
|
|
6
6
|
|----|---------|
|
|
7
7
|
| `list` | Terminal panes (id, title, command, tab); `verbose` adds cwd/flags |
|
|
8
|
-
| `send` | Paste body + Enter (`to` = id / title / command). `from` labels `[zswarm from=…]` (default: `ZSWARM_FROM`, else the sending pane's title, else `swarm`); zswarm also appends
|
|
8
|
+
| `send` | Paste body + Enter (`to` = id / title / command). `from` labels `[zswarm from=…]` (default: `ZSWARM_FROM`, else the sending pane's title, else `swarm`); zswarm also appends `src=<session>/<pane>`, `host=<host>` (`ZSWARM_HOST`, `-` hides it) and `via=serve` when known; `from=` stays the bare label. `submit`: `auto` (default; Codex panes default to `double-enter`) / `double-enter` / `none`. `submitted`: `true` (accepted and running) \| `"queued"` (accepted behind a running turn) \| `false` (still in the composer, not submitted) \| `"unverified"` (inconclusive) \| `"not-delivered"` (the pane was unchanged apart from the composer; op fails `not_delivered`, resend is safe). Settle (`--settle-ms`, default 300) and pane-observe (`--observe-ms`, default 1000) budgets scale up to 5x on a slow Zellij, explicit flags win. `--confirm` re-pastes only on `not-delivered` (Enter when still in the composer, an extra dump on `unverified`) and never pastes twice. `expect` refuses unless the screen already shows that substring `ifIdle: true` (`--if-idle`) refuses a live-leased pane (`pane_leased`) or a harness that shows it is working (`pane_busy`; OpenCode's progress bar, Claude Code's `esc to interrupt`) instead of sending. |
|
|
9
9
|
| `dump` | Full-screen read; capped at 8000 chars (tail) — expensive vs `tail` |
|
|
10
10
|
| `tail` | Incremental read since last cursor; `reset: true` returns the whole screen |
|
|
11
11
|
| `wait` | Block until quiet or `match`; returns `reason` + a 2000-char tail. Bus holds one pipe for the wait |
|