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

2. Connect the orchestrator to the running server:

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

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

4. 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