zSwarm

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

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

📦 Monorepo Structure

📜 License

MIT