Zwerm

Zwerm

A minimal and opinionated agent swarm framework.

Dispatches coding agents into git worktrees, reviews their work when they're done, and handles the back-and-forth until it's ready to merge. One Claude Code session acts as the orchestrator while other agents do the work in parallel.

Prerequisites

• tmux (agents run in tmux windows)
• uv (Python package manager)
• Python 3.13+
• codex installed and authorised

Install

Install the server:

uv tool install git+https://github.com/mikery/zwerm

Install the Claude Code plugin:

claude plugin marketplace add mikery/zwerm
claude plugin install zwerm

Quick start

1. Start the server (from your project directory):

zwerm

1. Connect the orchestrator to the running server:

claude mcp add --transport http zwerm "http://127.0.0.1:${ZWERM_PORT:-8000}/mcp"

1. Run /setup to scaffold config and prompt templates.

2. Use /orchestrate to dispatch a task:

orchestrate: add a health check endpoint that returns build version and uptime

The orchestrator dispatches an agent to a worktree, waits for it to finish, runs review agents, and reports a verdict. You keep working.

More examples:

orchestrate: refactor the database layer to use connection pooling

orchestrate: add input validation and error messages to the signup form

orchestrate: audit src/payments/ for security vulnerabilities

Dispatch multiple tasks concurrently — each gets its own agent, worktree, and review cycle:

orchestrate these three tasks: 1) add rate limiting to the API 2) write integration tests for the auth flow 3) migrate the config from JSON to TOML

/orchestrate linear issues ENG-42 and 123

Architecture

Orchestrator (Claude Code)
    │
    ├── /mcp          ← full tool set (16 tools)
    │
    └── /worker/mcp   ← filtered tool set (5 tools, injected at dispatch)
          │
          ├── Agent 1  [tmux window, git worktree]
          ├── Agent 2  [tmux window, git worktree]
          └── ...

Workers connect to /worker/mcp automatically — they only see the tools they need (ping, ack_task, report_complete, report_blocked, wait_for_feedback).

Background processes

The server runs background tasks for operational robustness:

• Stale session monitor — polls every 60s, marks sessions as EXITED when their tmux window disappears (catches zombie sessions from crashes or manual kills)
• Graceful shutdown — on SIGTERM, wakes all blocking waiters (wait_for_completion, consume_feedback) so they return immediately with status "shutdown", then cancels all background tasks

Configuration

Run /setup to scaffold .claude/zwerm/config.toml and prompt templates. Or create the config manually — the server searches for config in this order:

1. .claude/zwerm/config.toml
2. .zwerm.toml

Environment variables (ZWERM_HOST, ZWERM_PORT, ZWERM_DEFAULT_AGENT, etc.) override file settings. Set ZWERM_PORT in .envrc for per-project port isolation.

Agent profiles

Define profiles in your config to control which CLI, flags, and prompt templates each agent uses:

[profiles.codex]
command = ["codex", "--full-auto"]
resume_command = ["codex", "resume", "--last", "--full-auto"]
prompt_templates = ["prompts/default.md", "prompts/codex.md"]

Review agents

Configure agents that review completed work before merging:

review_agents = ["superpowers:code-reviewer", "feature-dev:code-reviewer"]

Review agents run in parallel against the agent's worktree, then the orchestrator synthesizes their verdicts.

Auto-rebase

When an agent reports complete, the server automatically rebases the worktree branch onto the base branch (the branch that was checked out when the worktree was created). This reduces merge conflicts when the agent's work is ready to merge.

auto_rebase = true  # default

If the rebase conflicts, the server aborts it and reports rebase_status: "conflict" in the completion result. The orchestrate skill sends the agent feedback to resolve conflicts manually.

Disable with auto_rebase = false or ZWERM_AUTO_REBASE=false.

Resource bounds

[resource_bounds]
max_concurrent_sessions = 100     # simultaneous agents
max_feedback_queue_depth = 100    # messages per session
max_log_file_bytes = 104857600    # 100 MB per session log
max_session_lifetime = 0          # seconds, 0 = unlimited

All settings

Setting	Env override	Default	Description
default_agent	ZWERM_DEFAULT_AGENT	"codex"	Profile used when none specified
target_tmux_session	ZWERM_TARGET_TMUX_SESSION	null	Tmux session for agent windows (default: dedicated zwerm-... session)
auto_rebase	ZWERM_AUTO_REBASE	true	Rebase worktree branch on completion
host	ZWERM_HOST	"127.0.0.1"	Server bind address
port	ZWERM_PORT	8000	Server bind port

Tools

Orchestrator tools

Tool	Description
dispatch_agent	Create worktree + tmux window, launch agent
list_sessions	All active sessions with status and elapsed time
get_session	Detailed session info
wait_for_completion	Block until agent reports complete/blocked/exit (returns branch_stats and rebase_status)
read_output	Cursor-based output from session log
send_input	Send text to agent's tmux pane
post_feedback	Queue feedback for agent, optional ack confirmation
clear_feedback	Clear queued feedback
cleanup_session	Kill tmux window, optionally remove worktree + branch
get_config	Expose resolved config
server_status	Uptime and session counts

Worker tools (served at /worker/mcp)

Tool	Description
ping	Verify connectivity
ack_task	Acknowledge task receipt
report_complete	Mark complete, long-poll for feedback
report_blocked	Mark blocked, long-poll for guidance
wait_for_feedback	Explicit feedback polling

Completion response

When wait_for_completion returns with status "complete", the response includes:

{
  "session_id": "agent/fix-auth",
  "status": "complete",
  "completion_summary": "Fixed the auth bug...",
  "branch_stats": {
    "commit_count": 3,
    "files_changed": 5,
    "insertions": 120,
    "deletions": 45
  },
  "rebase_status": "ok",
  "acked": true
}

The orchestrate skill uses branch_stats and rebase_status for pre-review checks:

• commit_count == 0 — skips review, asks user to re-dispatch or dismiss
• rebase_status == "conflict" — sends the agent feedback to resolve conflicts before review proceeds

Workflow

Parallel dispatch

Two agents dispatched concurrently, each in its own worktree. The orchestrator continues working while both run.

sequenceDiagram
    actor User
    participant Orch as Orchestrator
    participant Zwerm as Zwerm Server
    participant A1 as Agent 1
    participant A2 as Agent 2

    User->>Orch: orchestrate two tasks
    par Dispatch
        Orch->>Zwerm: dispatch_agent(branch-1)
        Zwerm->>A1: launch in worktree
    and
        Orch->>Zwerm: dispatch_agent(branch-2)
        Zwerm->>A2: launch in worktree
    end
    Note over Orch: continues working

    A1->>Zwerm: ack_task
    A2->>Zwerm: ack_task
    A1->>Zwerm: report_complete
    A2->>Zwerm: report_complete
    Zwerm-->>Orch: both complete
    Orch->>Orch: review + merge

Blocked agent

An agent gets stuck and reports blocked. The orchestrator posts guidance, the agent resumes and finishes.

sequenceDiagram
    participant Orch as Orchestrator
    participant Zwerm as Zwerm Server
    participant Agent

    Orch->>Zwerm: dispatch_agent
    Zwerm->>Agent: launch in worktree
    Agent->>Zwerm: ack_task
    Agent->>Zwerm: report_blocked(reason)
    Zwerm-->>Orch: status: blocked
    Orch->>Zwerm: post_feedback(guidance)
    Zwerm-->>Agent: guidance delivered
    Note over Agent: resumes work
    Agent->>Zwerm: report_complete
    Zwerm-->>Orch: status: complete
    Orch->>Orch: review + merge

Review feedback loop

Agent completes, but review agents find issues. After two rounds of review, the work is merged.

sequenceDiagram
    participant Orch as Orchestrator
    participant Zwerm as Zwerm Server
    participant Agent
    participant R1 as Reviewer 1
    participant R2 as Reviewer 2

    Agent->>Zwerm: report_complete
    Zwerm-->>Orch: status: complete

    rect rgb(240, 240, 255)
    Note over Orch,R2: Round 1
    par Review
        Orch->>R1: review branch diff + worktree
    and
        Orch->>R2: review branch diff + worktree
    end
    R1-->>Orch: needs-work
    R2-->>Orch: approved
    end

    Orch->>Zwerm: post_feedback(issues)
    Zwerm-->>Agent: feedback delivered
    Agent->>Zwerm: report_complete
    Zwerm-->>Orch: status: complete

    rect rgb(240, 255, 240)
    Note over Orch,R2: Round 2
    par Review
        Orch->>R1: review branch diff + worktree
    and
        Orch->>R2: review branch diff + worktree
    end
    R1-->>Orch: approved
    R2-->>Orch: approved
    end

    Orch->>Orch: merge branch into main
    Orch->>Zwerm: cleanup_session

Development

uv sync
uv run pytest -v

Project structure

src/zwerm/
    __main__.py     # CLI entrypoint, lifespan management
    server.py       # FastMCP tool definitions
    service.py      # Business logic, stale monitor, shutdown
    store.py        # In-memory session state, condition-based waits
    runtime.py      # Tmux process management
    worktree.py     # Git worktree lifecycle, branch stats, rebase
    config.py       # TOML + env config loading
    models.py       # SessionRecord, RuntimeRef dataclasses
    errors.py       # Exception hierarchy
    agents.py       # Agent command building

plugin/
    .claude-plugin/plugin.json
    skills/orchestrate/SKILL.md     # Full orchestration workflow
    commands/setup.md               # /setup scaffolding
    scripts/branch-diff.sh          # Diff helper for review agents
    assets/templates/               # Config + prompt templates