zswarm 0.3.1 → 0.4.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.
Files changed (3) hide show
  1. package/package.json +3 -3
  2. package/skills/zswarm/SKILL.md +76 -73
  3. package/skills/zswarm/references/ops.md +1 -1
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "zswarm",
3
- "version": "0.3.1",
3
+ "version": "0.4.1",
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.3.1",
27
- "@zswarm/mcp": "0.2.1"
26
+ "@zswarm/cli": "0.4.1",
27
+ "@zswarm/mcp": "0.3.1"
28
28
  },
29
29
  "publishConfig": {
30
30
  "access": "public"
package/skills/zswarm/SKILL.md CHANGED
@@ -1,73 +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`. MCP hosts that drop Zellij env need those vars listed (or set
53
- `from` / `ZSWARM_FROM`).
54
-
55
- ## Rules
56
-
57
- 1. Target **pane ids or names** from `list` — do not invent transports.
58
- 2. Keep the session + pane ID returned by `spawn`. Use names once `alias.observed` is true; retry observation before creating a duplicate.
59
- 3. Prefer `send` + `wait` over polling. Prefer `tail` over repeated `dump`.
60
- 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.
61
- 5. Prefer `diff` / `checkpoint` over reading a worktree by hand.
62
- 6. Zellij terminal panes only — not IDE side-panel chats.
63
- 7. Same host as Zellij, or `ZSWARM_SSH` / `ZSWARM_SERVE`. Linux/macOS SSH is
64
- the same user + `$TMPDIR`. Windows pane attach: `ZSWARM_SSH_MODE=interactive`
65
- or `zswarm serve` next to Zellij. `file:` wasm stays on the box that owns
66
- Zellij. Details: [references/remote.md](references/remote.md).
67
- 8. Writes refuse own pane (`self_target`) and exited panes (`pane_exited`).
68
- Override with `allowSelf` / `force` only when you mean it.
69
- 9. Policy env vars can block writes (`policy_denied` names the env var).
70
- 10. `spawn` is executable + argv — no shell, so no pipes or `&&`.
71
- 11. Prefer `worktree` on `spawn` when peers should not share one dirty tree.
72
- Tear down with `unworktree` after the pane is closed.
73
- 12. Crew barriers: `broadcast` + `signal` + `await`, not ad-hoc dumps.
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.
package/skills/zswarm/references/ops.md CHANGED
@@ -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`). `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. |
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 |