zSwarm

Coordinate CLI AI crews across Zellij terminal panes. Control agents, pass prompts between panes, manage git worktrees, inspect outputs, and sync crew tasks via CLI or Model Context Protocol (MCP).

                       you ──▶ any agent ──┐
                                           │ zswarm({op:"send", to:"reviewer"})
                                           ▼
      every pane can call zswarm ──▶ ┌─────────┐
      so agents drive each other     │ zswarm  │
                                     │ cli/mcp │
                                     └────┬────┘
                       paste + Enter ┌────┴────┐ read screen / pushed state
                                     ▼         ▼
 ══ this machine ══════════════════════════════╗ ══ ssh user@build-01 ═════════╗
   zellij "crew"                               ║   zellij "ci"                 ║
                                               ║                               ║
   ┌────────────┐  send   ┌────────────┐       ║   ┌────────────┐              ║
   │ codex      │────────▶│ claude     │───────╫──▶│ opencode   │              ║
   │ builder    │◀────────│ reviewer   │  send ║   │ test-runner│              ║
   │ wt:feat-a  │ signal  │ wt:rev-a   │       ║   │ wt:feat-a  │              ║
   └────────────┘         └────────────┘       ║   └──────┬─────┘              ║
   ┌────────────┐         ┌────────────┐       ║   ┌──────▼─────┐              ║
   │ cursor     │         │ agy        │       ║   │ pi         │              ║
   │ refactor   │         │ docs       │       ║   │ deploy     │              ║
   │ wt:feat-b  │         │ wt:docs    │       ║   │ cwd:/srv   │              ║
   └────────────┘         └────────────┘       ║   └────────────┘              ║
 ═══════════════════════════════════════════════╝ ══════════════════════════════╝
     one pane = one agent + one role + optionally its own worktree
     any pane can drive any other, on this machine or across the ssh boundary

---

⚡ Quick Start

Requirements

• Zellij ≥ 0.42 on PATH (or set ZSWARM_BIN / ZSWARM_PATH)
• Node.js ≥ 20

Installation

npm i -g zswarm
zswarm list

Enable the optional Zellij event-bus plugin once per machine for zero-polling state updates:

zswarm bus --install

MCP Server Setup

Configure zswarm-mcp (stdio MCP server bundled with the package) in your MCP host:

{
  "mcpServers": {
    "zswarm": {
      "command": "/absolute/path/to/zswarm-mcp",
      "env": {
        "ZSWARM_SESSION": "my-zellij-session"
      }
    }
  }
}

Note: Use the absolute path to zswarm-mcp and specify ZSWARM_SESSION to prevent ambiguous session errors when multiple Zellij sessions run.

---

Usage & Quick Syntax

Every operation is supported both via CLI (zswarm <op> [flags]) and MCP (zswarm({ op: "<op>", ... })).

Essential Examples

# 1. Inspect Panes & Status
zswarm list                                     # List active panes
zswarm status                                   # Check status: busy | waiting | idle | exited

# 2. Spawn Panes & Worktrees
zswarm spawn --command "claude" --name reviewer # Spawn agent pane
zswarm spawn --command "codex" --worktree feature-auth --name auth-dev   # Isolated git worktree pane

# 3. Pass Prompts & Input
zswarm send --to reviewer --body "Review changes in src/" --submit auto
zswarm keys --to reviewer --key "Ctrl c"        # Send special keys / interrupts

# 4. Read Outputs & Wait
zswarm dump --to reviewer --max 4000            # Read recent screen tail
zswarm tail --to reviewer                       # Incremental read since last check
zswarm wait --to reviewer --match "DONE"        # Block until pattern matched or pane idle

# 5. Coordinate Crew & Sync Signals
zswarm broadcast --all --group builder --body "Run test suite"  # group matches pane title or command
zswarm signal --channel tests --payload ok      # Send signal to durable channel
zswarm await --channel tests --count 3          # Wait for 3 worker signals

---

📋 Operations Reference

Operation	Purpose	Key Parameters / Flags
list / sessions	List panes or live Zellij sessions	verbose
status	Panes classified by state (idle, busy, waiting, exited)	to, sampleMs, since-last
spawn	Launch command in new pane, tab, or git worktree	command, name, cwd, worktree, tab, newTab
send	Send text / prompt into a pane	to, body, submit (auto|double-enter|none), expect
dump	Read screen content (screen tail)	to, max (default 8000)
tail	Incremental screen read since last cursor	to, reset
wait	Block until quiet, pattern match, or idle	to, match, for (idle), idleMs, timeoutMs
broadcast	Send one prompt to multiple panes	to, tab, all, group, body
keys / interrupt	Send key combos (Ctrl c, Esc) or raw chars	to, keys, chars, enter, hard
close	Close a pane	to, force
signal / signals / await	Durable message channels & barrier sync	channel, payload, count
worktrees / unworktree	List or remove managed git worktrees	cwd, branch, path, force
diff / checkpoint	Inspect peer worktree patch or autocommit WIP	branch, path, stat, message
rename / focus	Retitle pane/tab or focus pane	to, tab, name
tabs / layout / stack	Inspect tabs, layout KDL, or stack panes	to, max
bus / log	Event bus plugin management & delivery log	install, clear, failed, limit

---

🛡️ Safety & Policy Guards

• Self-Target Guard: Operations refuse to modify zSwarm's own pane (allowSelf: true to override).
• Execution & Exited Guards: Prevents writing to exited panes (force: true to override).
• Prompt Safety (expect): send --expect <text> ensures target pane screen contains <text> before writing (prevents accidental shell execution).
• Submission Verification (submit): auto verifies text submission into TUI composers and retries Enter if unsubmitted.

Environment Security Controls

Env Variable	Effect
ZSWARM_READONLY=1	Disable all write ops (send, spawn, close, etc.)
ZSWARM_ALLOW_PANES / ZSWARM_DENY_PANES	Comma-separated list/patterns of allowed/denied pane titles
ZSWARM_ALLOW_SPAWN=0	Disable spawning new panes
ZSWARM_ALLOW_CLOSE=0	Disable closing panes
ZSWARM_ALLOW_WORKTREE_REMOVE=0	Disable removing git worktrees

---

⚙️ Environment Variables

Variable	Description
ZSWARM_BIN / ZSWARM_PATH	Path to zellij executable
ZSWARM_SESSION	Default Zellij session name
ZELLIJ_SESSION_NAME	Active Zellij session (set automatically inside Zellij panes)
ZELLIJ_PANE_ID / ZSWARM_SELF_PANE	Sending pane id (Zellij sets the first inside a pane). Used to refuse self-target and to default from to that pane's title
ZSWARM_FROM	Sender label when from is omitted (overrides the pane title)
ZSWARM_WORKTREE_ROOT	Directory for linked worktrees (default: <repo>-worktrees)
ZSWARM_STATE_DIR	State storage directory for logs, signals, and cursors (default: ~/.zswarm)
ZSWARM_SSH	user@host — Route Zellij commands across SSH
ZSWARM_REMOTE_BIN	Remote zellij binary (zellij.exe on Windows)
ZSWARM_TMP	Remote IPC temp directory, or auto to parse live zellij --server paths
ZSWARM_SSH_MODE	interactive — Windows only: run each CLI call in the desktop session (scheduled task, same idea as schtasks /IT)
ZSWARM_REMOTE_SHELL	cmd or sh — override remote quoting (inferred from .exe / Windows tmp / interactive)
ZSWARM_SERVE	127.0.0.1:9419 — Forward ops to zswarm serve (SSH tunnel to loopback; non-loopback listen is refused)
ZSWARM_SERVE_TOKEN	Shared secret for zswarm serve. Required even on loopback (another local OS user can connect to 127.0.0.1); send the same value on the client

Remote crews

Linux/macOS SSH works when it is the same user and $TMPDIR. Windows OpenSSH is session 0; live Zellij is usually the interactive desktop session. ZSWARM_TMP=auto points at that TEMP (enough to list sessions). Pane attach on Windows uses named pipes in the desktop session, so use ZSWARM_SSH_MODE=interactive or run zswarm serve next to Zellij.

# Linux/macOS, same user:
ZSWARM_SSH=user@host zswarm list

# Point SSH at the interactive TEMP (auto reads zellij --server …)
ZSWARM_SSH=user@host ZSWARM_TMP=auto zswarm sessions

# Windows: run the CLI inside the desktop session. Discovers TEMP unless ZSWARM_TMP is set.
ZSWARM_SSH=user@host ZSWARM_SSH_MODE=interactive zswarm list

# Any OS: run zswarm next to Zellij; another machine talks over a tunnel to 127.0.0.1
# On the host, in the session that owns Zellij (loopback only; a token is not a bind substitute):
ZSWARM_SERVE_TOKEN=secret zswarm serve --listen 127.0.0.1:9419
# Windows, once (bakes ZSWARM_SERVE_TOKEN into the logon task env): zswarm serve --install
# On the client:
ssh -fN -L 9419:127.0.0.1:9419 user@host
ZSWARM_SERVE=127.0.0.1:9419 ZSWARM_SERVE_TOKEN=secret zswarm list

file: plugin URLs stay on the machine that owns Zellij. A client with ZSWARM_SERVE never sends a local wasm path across the tunnel.

{
  "mcpServers": {
    "zswarm": {
      "command": "/absolute/path/to/zswarm-mcp",
      "env": {
        "ZSWARM_SERVE": "127.0.0.1:9419",
        "ZSWARM_SERVE_TOKEN": "secret",
        "ZSWARM_SESSION": "crew"
      }
    }
  }
}

---

📦 Monorepo Structure

Package	Purpose
zswarm	Main meta-package (npm i -g zswarm)
@zswarm/core	Core Zellij client and shared dispatch engine
@zswarm/cli	zswarm command line interface
@zswarm/mcp	Stdio MCP server (zswarm-mcp)
@zswarm/wasm	Precompiled Rust event-bus WASM plugin
@zswarm/pi	Extension bridge for harnesses without native MCP support

---

📜 License

MIT