zswarm 0.2.0 → 0.2.2

package/README.md

@@ -1,14 +1,17 @@
 # zswarm
 
-Meta-package for a global install. Puts `zswarm` (CLI) and `zswarm-mcp` (MCP server) on your PATH.
+Meta-package for a global install. Puts `zswarm` (CLI) and `zswarm-mcp` (MCP server) on your PATH, and bundles `skills/zswarm` for AI agent harnesses.
 
 ```bash
 npm i -g zswarm
 zswarm list
 ```
 
-Ops, env, MCP setup, and the event bus: the [repo README](../../README.md).
+The bundled skill can be copied from `$(npm root -g)/zswarm/skills/zswarm` into your harness skill directory (e.g. `~/.claude/skills/zswarm`, `~/.codex/skills/zswarm`, or `~/.cursor/skills/zswarm`).
+
+Ops, env, MCP setup, and the event bus: the [repo README](https://github.com/brandonkramer/zswarm#readme).
 
 ## License
 
 MIT
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zswarm",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "type": "module",
   "description": "Coordinate CLI agent crews in Zellij panes",
   "engines": {
@@ -19,14 +19,17 @@
   },
   "files": [
     "bin",
-    "README.md"
+    "README.md",
+    "skills"
   ],
   "dependencies": {
-    "@zswarm/cli": "0.2.0",
-    "@zswarm/mcp": "0.1.10"
+    "@zswarm/cli": "0.2.2",
+    "@zswarm/mcp": "0.1.12"
   },
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {}
+  "scripts": {
+    "build": "node -e \"const fs=require('node:fs'); fs.cpSync('../../skills', 'skills', {recursive:true})\""
+  }
 }

package/skills/zswarm/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: zswarm
+description: >-
+  Coordinate CLI crews in Zellij panes via zSwarm MCP (list, send, dump, tail,
+  wait, status, keys, interrupt, spawn, close, broadcast, signal, signals,
+  await, log, worktrees, unworktree, rename, focus, tabs, layout, stack, diff,
+  checkpoint, bus, serve). Use when messaging another Codex, Claude Code, Cursor
+  CLI, pi, OpenCode, or agy session in a Zellij pane, waiting for one to finish,
+  broadcasting to a crew, signalling barriers,
+  interrupting, opening a new crew pane, isolating peers in git worktrees,
+  reviewing peer diffs/checkpoints, renaming/focusing panes, or dumping short
+  scrollback. Same host as Zellij, or ZSWARM_SSH / ZSWARM_SERVE for a remote
+  crew — not IDE side-panel chat.
+---
+
+# zSwarm
+
+Talk to **CLI** sessions in Zellij panes (Codex, Claude Code, Cursor CLI, pi, OpenCode, agy, shells).
+Delivery is `zellij action paste` + Enter. Not IDE side-panel chat.
+
+## Happy path
+
+```text
+zswarm({ op: "list" })
+zswarm({ op: "send", to: "reviewer", body: "please review the plan" })
+zswarm({ op: "wait", to: "reviewer", for: "idle" })
+```
+
+`session` when more than one Zellij session is live, or set `ZSWARM_SESSION`.
+Resolution: arg → `ZSWARM_SESSION` → `ZELLIJ_SESSION_NAME` → the sole live session.
+MCP hosts inherit neither PATH nor Zellij env — absolute interpreter + `ZSWARM_SESSION`.
+CLI backup: `zswarm <op>` (`@zswarm/cli`).
+
+## Read when needed
+
+- Ops, submit/expect, bus: [references/ops.md](references/ops.md)
+- Remote SSH (Linux / macOS / Windows) / serve: [references/remote.md](references/remote.md)
+- Barriers, worktrees, review, wait: [references/workflows.md](references/workflows.md)
+- Harness notes: [references/harness.md](references/harness.md)
+
+## Prefix
+
+Unless `raw: true`:
+
+```text
+[zswarm from=<sender>]
+<body>
+```
+
+`<sender>` is `from` if you pass it, else `ZSWARM_FROM`, else the sending
+pane's title when `ZELLIJ_PANE_ID` / `ZSWARM_SELF_PANE` is visible, else
+`swarm`. MCP hosts that drop Zellij env need those vars listed (or set
+`from` / `ZSWARM_FROM`).
+
+## Rules
+
+1. Target **pane ids or names** from `list` — do not invent transports.
+2. Keep the session + pane ID returned by `spawn`. Use names once `alias.observed` is true; retry observation before creating a duplicate.
+3. Prefer `send` + `wait` over polling. Prefer `tail` over repeated `dump`.
+4. Check `submitted` on `send`; `false` means the peer never got it.
+5. Prefer `diff` / `checkpoint` over reading a worktree by hand.
+6. Zellij terminal panes only — not IDE side-panel chats.
+7. Same host as Zellij, or `ZSWARM_SSH` / `ZSWARM_SERVE`. Linux/macOS SSH is
+   the same user + `$TMPDIR`. Windows pane attach: `ZSWARM_SSH_MODE=interactive`
+   or `zswarm serve` next to Zellij. `file:` wasm stays on the box that owns
+   Zellij. Details: [references/remote.md](references/remote.md).
+8. Writes refuse own pane (`self_target`) and exited panes (`pane_exited`).
+   Override with `allowSelf` / `force` only when you mean it.
+9. Policy env vars can block writes (`policy_denied` names the env var).
+10. `spawn` is executable + argv — no shell, so no pipes or `&&`.
+11. Prefer `worktree` on `spawn` when peers should not share one dirty tree.
+    Tear down with `unworktree` after the pane is closed.
+12. Crew barriers: `broadcast` + `signal` + `await`, not ad-hoc dumps.

package/skills/zswarm/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "zSwarm"
+  short_description: "Coordinate CLI crews in Zellij panes"
+  default_prompt: "Use $zswarm to list panes, send to a peer, and wait until idle. Remote crew: read references/remote.md."

package/skills/zswarm/references/harness.md

@@ -0,0 +1,21 @@
+# Harness notes
+
+Verified live against **codex**, **cursor**, **pi**, **opencode**, and **gemini** (`agy`).
+
+- **Read** (`dump`, `tail`, `status`, `wait --for idle`) works on all five.
+- **Send** lands on all five (`codex` auto-detects `submit=double-enter`, others `auto`). The `expect` guard works on all five.
+- **Replies can take > 60s.** Budget timeouts; a quiet pane is rarely a failed send.
+- **`wait --match` on a redrawing TUI is viewport-and-moment dependent.** Those apps
+  own the alternate screen (no scrollback; `--full` is identical). Prefer
+  `wait --for idle` or match text the harness keeps pinned.
+- Re-test: `node scripts/harness-check.mjs <panes...>`
+
+Reaching zswarm from a harness is separate from driving one:
+
+- **4 of 5 have an MCP client** — they reach zswarm once session and interpreter
+  path are explicit in the server config.
+- **1 ships no MCP client** — use `@zswarm/cli`, or the generic MCP bridge at
+  `packages/pi/extensions/zswarm-mcp.ts` (`ZSWARM_MCP_SERVERS`).
+- **Being a target needs no integration.** All five are drivable with
+  `send` / `dump` / `tail` / `wait` / `status`.
+

package/skills/zswarm/references/ops.md

@@ -0,0 +1,90 @@
+# Ops
+
+MCP: `zswarm({ op, ... })`. CLI: `zswarm <op>`. Same surface.
+
+| op | Purpose |
+|----|---------|
+| `list` | Terminal panes (id, title, command, tab); `verbose` adds cwd/flags |
+| `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`. Result `submitted: true\|false\|"unverified"`. `expect` refuses unless the screen already shows that substring |
+| `dump` | Full-screen read; capped at 8000 chars (tail) — expensive vs `tail` |
+| `tail` | Incremental read since last cursor; `reset: true` returns the whole screen |
+| `wait` | Block until quiet or `match`; returns `reason` + a 2000-char tail. Bus holds one pipe for the wait |
+| `status` | busy / waiting / idle / exited / running / unknown, with tab names/IDs, tab summary and waiting evidence; `free[]` = idle ids. `sampleMs: 0` skips sampling. `sinceLast: true` skips the 400ms gap |
+| `keys` | `expect` is checked before any input. Key specs (`keys: ["Ctrl c"]`) or literal `chars` (+ `enter`) |
+| `interrupt` | `Esc`; `hard: true` sends `Ctrl c` |
+| `spawn` | New pane (`newTab: true` for a fresh tab) with `command`, `cwd`, `name`, `direction`, `floating`; `tab` = tab name; `worktree` isolates on a branch |
+| `close` | Close a pane |
+| `rename` | Retitle a pane (`to` + `name`) or a tab (`tab` + `name`) |
+| `focus` | Focus a pane; already-focused is a no-op success |
+| `tabs` | List tabs with pane counts |
+| `layout` | Dump the session layout as KDL |
+| `stack` | Stack a comma list of panes (needs 2+) |
+| `broadcast` | One body to many panes (`to` list, `tab`, or `all`; narrow with `group`) |
+| `signal` | Post to a channel (`channel`, optional `payload`); `clear` resets |
+| `signals` | List channels with cumulative counts |
+| `await` | Block until a channel reaches `count` posts |
+| `log` | Delivery log for send/broadcast/keys/interrupt/close |
+| `worktrees` | List repo git worktrees, annotated with panes working in them |
+| `unworktree` | Remove a worktree (`path` or `branch`; `worktree` aliases `branch`) |
+| `diff` | What a peer changed in its worktree |
+| `checkpoint` | Commit a peer worktree (`message`); clean tree is not an error |
+| `sessions` | Live Zellij session names |
+| `bus` | Event-bus status; `install: true` loads the plugin, `clear: true` forgets it |
+| `serve` | Listen for remote zswarm (`--listen`). `--install` / `--clear` installs/removes a service (Windows logon task, Linux systemd user unit, macOS launchd job). MCP cannot listen; set `ZSWARM_SERVE` on the client. See [remote.md](remote.md) |
+| `doctor` | Inspect-only route/SSH/serve/Zellij/bus diagnostics |
+
+`submit=auto` retries Enter if the paste is still sitting in a TUI composer.
+`submit=double-enter` always sends the extra Enter; `submit=none` skips the check.
+Check `submitted` — a queued composer used to report success.
+
+**Breaking:** `spawn`'s boolean `tab` is now `newTab`; `tab` is a tab **name**.
+
+## expect
+
+A pane that dropped back to a shell will **run** your message as a command.
+Name something the screen must already show:
+
+```text
+zswarm({ op: "send", to: "reviewer", body: "…", expect: "Add a follow-up" })
+```
+
+Failure is `expect_missing` and nothing is written.
+
+## Event bus
+
+`zswarm({ op: "bus", install: true })` once per Zellij session. After that
+`list` and `status` read a pushed manifest (`source: "plugin"` or `"zellij"`).
+Off until installed; any failure falls back silently — speed, not a dependency.
+Do not pass `force` to recover from a quiet bus: that used to stack WASM copies.
+Approve the existing pane's permission prompt, or `force` only when you mean to
+close every bus plugin pane and load one replacement. Keep the floating pane
+open; closing it unloads the bus.
+
+The manifest has no pane command or cwd, so a bus-served `list` omits `command`,
+and `list` with `verbose` / `status --to <command>` keep polling. `status`
+sampling and `wait` use the plugin; `dump` / `tail` stay on the CLI.
+
+## Reliable spawn and handoffs
+
+Keep the returned session + pane ID. Spawn creates once and observes for up to
+`observeMs` (default 3000), within one `timeoutMs` budget (default 30000).
+`created` is the creation acknowledgment; `observed`, `exited`, `observation`,
+`alias.observed`, and `ready` describe what was actually seen. `live` means
+observed and not exited; it does not establish application readiness. An
+observation timeout can accompany `ok: true`: retry reads before spawning again.
+New-tab correlation stays within the returned tab and ambiguous layouts remain
+unresolved. `newTab` + `name` also establishes the terminal alias when observed.
+Pane lookups retry absence for 1000ms; `observeMs: 0` disables retries.
+
+CLI: `send --body-file PATH` reads a local UTF-8 file before remote forwarding;
+`--body-file -` reads stdin. Do not combine with `--body`/`--text`/a positional
+body. Newlines are preserved. MCP uses `body`, never its protocol stdin. Paste
+still uses argv, so reference a shared file for very large handoffs.
+
+For menus: wait for a match and check `reason`, perform one
+`keys --expect TEXT --key Enter`, then wait for the resulting state. `expect`
+also applies to `chars` and `interrupt`. It is a fresh case-insensitive screen
+check, not an atomic transaction. Serialize input per pane and avoid blind
+retries. Waiting evidence is a screen heuristic, not authorization to approve.
+
+Ordinary status uses bus changes without a sample gap by default; first/missing observations are unknown unless a prompt is visible. `sampleMs` explicitly selects two-sample observation (0 = metadata only). Bus change history is shared by the plugin instance. Read-only listings use a 500ms process cache; `fresh: true` bypasses it, and `ZSWARM_CACHE_TTL_MS=0` disables reuse. Writes/spawn settling use fresh metadata. Serve retains caches across client CLI calls.

package/skills/zswarm/references/remote.md

@@ -0,0 +1,121 @@
+# Remote crews
+
+Client (MCP or CLI) talks to Zellij on another machine. `file:` wasm stays on
+the host that owns Zellij.
+
+## Linux / macOS
+
+Same user, same `$TMPDIR` — SSH is enough:
+
+```bash
+ZSWARM_SSH=user@host zswarm list
+ZSWARM_SSH=user@host zswarm send --to reviewer --body "please review"
+```
+
+If the remote Zellij uses a different socket dir than the SSH login's `$TMPDIR`:
+
+```bash
+ZSWARM_SSH=user@host ZSWARM_TMP=auto zswarm list
+# or set ZSWARM_TMP to that directory explicitly
+```
+
+`auto` reads live `zellij --server` paths (`ps` on Unix). `serve` (below) is
+optional when SSH already sees the sockets.
+
+## Windows
+
+OpenSSH is session 0; live Zellij is usually the desktop session. Named pipes
+live there, so SSH + TEMP can **list sessions** but not attach panes.
+
+```text
+ZSWARM_SSH=user@host ZSWARM_TMP=auto                 → sessions
+ZSWARM_SSH=user@host ZSWARM_SSH_MODE=interactive     → list/send
+```
+
+`interactive` is Windows-only: `schtasks /IT` in the desktop session. Discovers
+TEMP unless `ZSWARM_TMP` is set. `ZSWARM_REMOTE_BIN=zellij.exe` if `zellij` is
+not on the remote PATH. `ZSWARM_REMOTE_SHELL=cmd|sh` overrides quoting.
+
+## Serve (any OS)
+
+Run zswarm **next to Zellij**; the client talks over a tunnel. Use this when
+SSH is a different session than Zellij, or when MCP should not spawn `ssh` per
+op.
+
+**Native Windows + Tailscale:** the default recipe is
+[`zswarm serve --install`](../../../docs/tailscale.md) on the already-logged-in
+desktop (Interactive/Limited logon task, loopback + token), then
+`--serve 'ssh://user@host?servePort=9419'` from the controller (OpenSSH over
+the tailnet — not Tailscale SSH). That guide also covers an **optional**
+verified Tailscale-IP bind for direct TCP, and **private raw TCP Tailscale
+Serve** (`tailscale serve --tcp=…` over a loopback backend). Readiness, token
+storage, bus approval, and login/reboot limits are documented there.
+
+```bash
+# On the host, in the session that owns Zellij (default loopback):
+ZSWARM_SERVE_TOKEN=secret zswarm serve --listen 127.0.0.1:9419
+# Token is required on loopback too: another local OS user can connect to 127.0.0.1.
+# Optional: bind a verified local Tailscale IP (see docs/tailscale.md):
+#   zswarm serve --listen "$(tailscale ip -4):9419"
+# Windows verified logon task: zswarm serve --install --listen 127.0.0.1:9419 --session crew --timeout-ms 30000
+# (Start-ScheduledTask is asynchronous; install waits for authenticated hello + host visibility.)
+# Linux/macOS service (systemd user unit + linger / launchd job; token in ~/.zswarm/serve/):
+#   zswarm serve --install --listen 127.0.0.1:9419 --session crew
+# Keep the session itself running from a layout: zswarm crew up crew --layout crew.kdl
+
+# On the client (concise default is ssh://; token already in this process):
+zswarm --serve 'ssh://user@host?servePort=9419' status --session crew
+# Or a manual LocalForward to an existing endpoint:
+ssh -fN -L 9419:127.0.0.1:9419 user@host
+ZSWARM_SERVE=127.0.0.1:9419 ZSWARM_SERVE_TOKEN=secret zswarm list
+# Direct endpoint when the host bound its Tailscale IP:
+# zswarm --serve '<host-tailscale-ip>:9419' status --session crew
+# Private TCP Tailscale Serve (frontend port; backend remains 127.0.0.1:9419):
+# zswarm --serve 'tcp://crew-host:19419' status --session crew
+```
+
+`ZSWARM_SSH` only forwards Zellij. Git worktree ops (`worktrees`, `unworktree`,
+`diff`, `checkpoint`, `spawn --worktree`) and barrier ops (`signal`, `signals`,
+`await`) are refused over plain SSH without serve (`ssh_git_unsupported`) — use
+`serve` on the host that owns the repo and session if those ops should run there.
+
+Direct SSH cannot `bus --install` or `bus --clear` (`bus_remote_unsupported`):
+the plugin `file:` URL and the install marker belong on the Zellij host. Run
+those on that host, or through `serve` over a tunnel. A remote `bus` report
+still explains that the bus is unavailable. `--local` overrides inherited SSH
+when this machine owns Zellij.
+
+MCP: set `ZSWARM_SERVE` in the MCP server env. Pass `session` explicitly or
+configure `ZSWARM_SESSION` on the host running `serve`. Do **not** call
+`op: "serve"` with `listen` — that is CLI-only. `serve` with `install` or `clear`
+works via MCP. Other ops forward.
+A client with `ZSWARM_SERVE` never sends a local wasm path across the tunnel.
+
+## Invocation routing
+
+`--local` clears SSH, serve, and remote IPC for this call only. It preserves the
+parent environment and inherited session selection; use `--session` explicitly
+when switching hosts. `--ssh user@host` overrides the inherited destination and
+serve for this call. Passing both flags is a usage error.
+
+Normal responses carry `context`: transport, host, resolved session, and the
+origin of those settings. Serve responses also identify the server's context
+when supported, because the endpoint may be a local tunnel. Interactive CLI
+routing notices go to stderr; stdout stays JSON. Scope remote env vars to the
+remote launcher and give local crew wrappers fixed `--local --session` flags.
+Configure each MCP server's environment explicitly.
+
+Dedicated crew Zellij configs can disable startup distractions with
+`show_startup_tips false` and `show_release_notes false`. Correct TERM on the
+host that starts workers. Terminal screen reads do not prove the presence or
+absence of all Zellij overlays; inspect held exit output before recovery.
+
+For frequent status polling, prefer serve beside Zellij with an SSH tunnel. Use `--serve 127.0.0.1:9419 --session crew` (MCP: `serveAddress`) to select an already-open endpoint, or `--serve 'ssh://user@host?servePort=9419'` for a process-owned LocalForward that probes hello before ops. Keep `ZSWARM_SERVE_TOKEN` configured on both sides. Direct SSH status reports its bus limitation and a serve recommendation. `host:port` does not start a tunnel; `ssh://` starts only the local SSH child, never remote serve. Native Windows recipe: [Tailscale crew](../../../docs/tailscale.md). See also [performance guidance](../../../docs/performance.md).
+
+## Agent hosts (CLI subcommands)
+
+`zswarm host install|doctor`, `zswarm crew up|status|down`, `zswarm relay`
+(hand a remote pane work, get a message in a local pane when a done line
+appears; `zswarm relay --wait ID` is the pull path) and `zswarm slot`
+(shared build slots) set up and keep a remote crew running. See
+docs/hosts.md in the zswarm repo.

package/skills/zswarm/references/workflows.md

@@ -0,0 +1,76 @@
+# Workflows
+
+## Barriers
+
+Broadcast a task, each peer signals when done, await N:
+
+```text
+zswarm({ op: "signal", channel: "done", clear: true })
+zswarm({ op: "broadcast", body: "finish your slice, then signal done", all: true, group: "claude" })
+zswarm({ op: "await", channel: "done", count: 3, timeoutMs: 600000 })
+```
+
+`status` to see who is free; `tail` (not `dump`) to poll what a peer printed.
+State under `ZSWARM_STATE_DIR` (default `~/.zswarm`): `log.jsonl`, `signals.json`,
+`cursors.json`. `ZSWARM_LOG=0` disables the delivery log; past 4MB it is trimmed to
+its last 512KB, which is all `log` reads.
+
+`broadcast` skips plugin / exited / own pane (never errors on those);
+`force` / `allowSelf` override. Empty selection → `no_targets`.
+
+## Worktrees
+
+`spawn` with `worktree=<branch>` gives the peer its own git worktree + branch,
+setting the pane's working directory to the worktree path. `cwd` selects the base
+repository the worktree is created from (defaulting to the current working
+directory). Optional `worktreeRoot`, `baseRef`. Defaults: worktrees under
+`<repo>-worktrees` beside the repo (`ZSWARM_WORKTREE_ROOT`). Existing worktree
+at the target path is reused. Git binary: `ZSWARM_GIT_BIN`.
+
+```text
+zswarm({ op: "spawn", command: "claude", worktree: "review-auth", cwd: "/path/to/repo", name: "reviewer" })
+zswarm({ op: "worktrees", cwd: "/path/to/repo" })
+zswarm({ op: "unworktree", branch: "review-auth", cwd: "/path/to/repo" })
+```
+
+`unworktree` refuses the main worktree (`worktree_is_main`), a worktree still
+used by a pane (`worktree_busy`), or one with uncommitted changes
+(`worktree_dirty`). `force: true` overrides busy/dirty only.
+
+Note on remote SSH: Over plain SSH (`ZSWARM_SSH` without `serve`), git worktree ops
+and signal/await barrier ops are refused with `ssh_git_unsupported`. Run `zswarm serve`
+on the host that owns the session and connect via `ZSWARM_SERVE`.
+
+## Review loop
+
+Isolate a peer, name it, task it, save its work, tear down:
+
+```text
+zswarm({ op: "spawn", command: "claude", worktree: "review-auth", name: "reviewer" })
+zswarm({ op: "rename", to: "terminal_11", name: "reviewer" })
+zswarm({ op: "send", to: "reviewer", body: "review the auth changes" })
+zswarm({ op: "wait", to: "reviewer", for: "idle" })
+zswarm({ op: "diff", branch: "review-auth", cwd: "/path/to/repo" })
+zswarm({ op: "checkpoint", branch: "review-auth", cwd: "/path/to/repo", message: "review checkpoint" })
+zswarm({ op: "close", to: "reviewer" })
+zswarm({ op: "unworktree", branch: "review-auth", cwd: "/path/to/repo" })
+```
+
+Prefer `diff` / `checkpoint` over reading the worktree by hand. Clean
+`checkpoint` returns `committed: false`, `nothingToCommit: true` — not an error.
+
+## Waiting
+
+`wait` polls the pane screen instead of you re-dumping it.
+
+- `for: "idle"` (default) — screen unchanged for `idleMs` (2000).
+- `match: "…"` — substring, or `regex: true`; sets `for` to `match`.
+- `for: "either"` — whichever lands first. `timeoutMs` defaults to 60000.
+
+```text
+zswarm({ op: "send", to: "reviewer", body: "run the tests" })
+zswarm({ op: "wait", to: "reviewer", for: "either", match: "FAIL", idleMs: 4000 })
+```
+
+Prefer `tail` for cheap incremental polls; reserve `dump` for a one-shot full
+screen (or `tail` with `reset: true`).