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:"claude"})
                                            ▼
      every pane can call zswarm ──▶ ┌─────────┐
      so agents drive each other     │ zswarm  │
                                     │ cli/mcp │
                                     └────┬────┘
                       paste + Enter ┌────┴────┐ read screen / pushed state
                                     ▼         ▼
 ══ this machine ═══════════════╗ ══ ssh user@worker-01 ════════════════════╗ ══ ssh user@build-01 ═════════╗
   zellij "crew" (orchestrators)║   zellij "workers" (workers/subworkers)   ║   zellij "ci" (runner/deploy) ║
                                ║                                           ║                               ║
   ┌────────────┐               ║   ┌────────────┐  send   ┌────────────┐   ║   ┌────────────┐              ║
   │ codex      │───────────────╫──▶│ cursor     │────────▶│ opencode   │───╫──▶│ test-runner│              ║
   │ orchestrat.│  plan/send    ║   │ worker     │◀────────│ subworker  │   ║   │ ci runner  │              ║
   │ planner    │               ║   │ wt:feat-a  │ signal  │ wt:tests   │   ║   │ wt:tests   │              ║
   └─────┬──────┘               ║   └─────┬──────┘         └─────┬──────┘   ║   └──────┬─────┘              ║
  signal │ send                 ║         │ send                 │ send     ║          │ pass / done        ║
   ┌─────▼──────┐               ║   ┌─────▼──────┐  send   ┌─────▼──────┐   ║   ┌──────▼─────┐              ║
   │ claude     │───────────────╫──▶│ agy        │────────▶│ opencode   │   ║   │ pi         │              ║
   │ orchestrat.│  review/send  ║   │ subworker  │◀────────│ subworker  │   ║   │ deploy     │              ║
   │ lead       │               ║   │ wt:docs    │ signal  │ wt:api     │   ║   │ 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 Zellij session for zero-polling state updates:

zswarm bus --install

Keep the floating pane open. --force closes orphan bus panes and reloads; do not use it as a retry.

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.

Each harness registers the server and the skill (skills/zswarm) itself; the repo ships no plugin manifests. With npm i -g zswarm, the skill is installed at $(npm root -g)/zswarm/skills/zswarm (or from a clone: skills/zswarm):

• Claude Code: claude mcp add --scope user zswarm -- "$(command -v zswarm-mcp)", then copy $(npm root -g)/zswarm/skills/zswarm (or skills/zswarm from a checkout) to ~/.claude/skills/zswarm.
• Codex: add to ~/.codex/config.toml

  [mcp_servers.zswarm]
  command = "/absolute/path/to/zswarm-mcp"
  env_vars = ["ZELLIJ_PANE_ID", "ZELLIJ_SESSION_NAME", "ZSWARM_SESSION", "ZSWARM_SELF_PANE", "ZSWARM_FROM", "ZSWARM_SERVE", "ZSWARM_SERVE_TOKEN", "ZSWARM_SSH"]
  

  (Codex passes only the variables listed in env_vars; add any other ZSWARM_* you use), then copy $(npm root -g)/zswarm/skills/zswarm (or skills/zswarm from a checkout) to ~/.codex/skills/zswarm.
• Cursor: add the JSON above to ~/.cursor/mcp.json, and copy $(npm root -g)/zswarm/skills/zswarm (or skills/zswarm from a checkout) to ~/.cursor/skills/zswarm.
• Other hosts: any stdio MCP client runs zswarm-mcp; a host that must exec node directly can use node bin/launch-mcp.mjs from a checkout (requires a build first: pnpm run build, or npm i -g zswarm).

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 | running | unknown

# 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 add --for either to stop on idle too)

# 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

# 6. Agent host commands (see docs/hosts.md)
zswarm host install --ssh root@build-host       # Node.js, zswarm, Zellij on a Linux/macOS host
zswarm crew up crew --layout crew.kdl           # Keep a session running from its layout
zswarm serve --install --session crew           # Serve as a systemd/launchd service (token in ~/.zswarm/serve/)
zswarm relay --serve 'ssh://crew1@build-host?servePort=9419' --to worker-a --body-file task.md --done 'TASK-DONE' --reply-to me
zswarm relay --wait <id>                        # Pull path: block until that relay has its message
zswarm slot -- cargo test                       # Run inside one of the host's build slots
zswarm host doctor --ssh crew1@build-host --serve 'ssh://crew1@build-host?servePort=9419' --session crew

📋 Operations Reference

🛡️ 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

⚙️ Environment Variables

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 for occasional commands or, for the default Tailscale crew, zswarm serve --install on the logged-in desktop plus OpenSSH over Tailscale from the controller.

# 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

# Linux/macOS host: keep a session and its serve running as services (docs/hosts.md)
zswarm crew up crew --layout crew.kdl
zswarm serve --install --listen 127.0.0.1:9419 --session crew

# Tailscale crew (native Windows desktop + controller). Full recipe: docs/tailscale.md
# Host (logged-in desktop, token already in this process) — default loopback:
zswarm serve --install --listen 127.0.0.1:9419 --session crew --timeout-ms 30000
# Optional: bind a verified local Tailscale IP instead (see docs/tailscale.md):
# zswarm serve --install --listen "$(tailscale ip -4):9419" --session crew --timeout-ms 30000
# Controller (same private token; ssh:// authority port is SSH, servePort is remote loopback):
zswarm --serve 'ssh://user@crew-host?servePort=9419' doctor --session crew --timeout-ms 10000
zswarm --serve 'ssh://user@crew-host?servePort=9419' status --session crew
# Direct endpoint when the host bound its Tailscale IP:
# zswarm --serve '<host-tailscale-ip>:9419' status --session crew
# Private TCP Tailscale Serve frontend (backend stays 127.0.0.1:9419):
# zswarm --serve 'tcp://crew-host:19419' doctor --session crew --timeout-ms 10000

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": "ssh://host?servePort=9419",
        "ZSWARM_SERVE_TOKEN": "secret"
      }
    }
  }
}

Note: The server picks its own session (pinned via zswarm serve --session <session> or the host environment); client-side ZSWARM_SESSION is not forwarded to serve. Explicit session arguments on individual tool calls still select that session on the server.

📦 Monorepo Structure

For spawn lifecycle fields, file/stdin handoffs, guarded menu input, tab summaries, and routing diagnostics, see Reliable crew operations.

For the Windows + Tailscale crew recipe (serve --install, OpenSSH over Tailscale, optional verified Tailscale-IP bind, private TCP Tailscale Serve, token, doctor/status), see Tailscale crew.

For layered inspect-only diagnostics (zswarm doctor), see Doctor.

For agent hosts (zswarm host install|doctor to set a Linux/macOS machine up, zswarm crew up to keep a session running from a layout, serve --install as a systemd or launchd service, zswarm relay to hand a remote pane work and be told when it is done, zswarm slot to share build capacity), see Agent hosts.

For repeated status calls, see polling performance and serve/tunnel setup.

📜 License

MIT