PowerSwarm

Fan work out to many headless coding agents — Grok, Codex or Claude Code — each in its own git worktree, and accept only what passes its kill check.

You (or the agent you work with) split a build into independent targets. PowerSwarm gives each target its own branch and worktree, starts an agent on it, and runs that target's kill check: a command, run without a shell, that has to print one exact line. A lane is green only when the check passes and the agent stayed inside its files. Nothing is merged or pushed. You review the branches and keep what you accept.

It is the open core of the swarm engine I use to build my own tools: same request format, same rules. In the run pictured above, PowerSwarm used Grok to build two pieces of itself: the viewer you are looking at and the quickstart example. Watch that run →

Install

pip install "git+https://github.com/willykeenan/powerswarm"

Python 3.9+, git, and at least one agent CLI: Grok Build (grok), Codex (codex) or Claude Code (claude). No other dependencies.

Related MCP server: JEVULON VII (JVII)

Quickstart

Three lanes finish a tiny library, textstats, one file each:

git clone https://github.com/willykeenan/powerswarm && cd powerswarm && pip install -e .
cd examples/quickstart
repo="$(mktemp -d)/textstats" && mkdir -p "$repo" && cp -R project/. "$repo/"
git -C "$repo" init -q -b main && git -C "$repo" add -A && git -C "$repo" commit -qm start
powerswarm run request.json --root "$repo"

The quickstart guide explains each step, how to watch the run and how to review each lane's branch.

How a run works

1. Validate. The request is checked before anything starts: independent scopes, shell-free kill checks that are committed in HEAD and live outside the lane's own scope, sane budgets. Every problem is reported at once.

2. Worktrees. Each target gets branch powerswarm/<run>/<target> and its own worktree, starting from HEAD. Your checkout is never touched.

3. Earned waves. The first wave runs up to 3 lanes. A wave at least 75% green doubles the width; under 25% halves it. The cap is min(requested_concurrency, half your cores, 32).

4. Attempts. A worker gets a compact brief: its aim, owned scope, definition of done and the kill check as the authoritative acceptance test. If attempt 1 fails, attempt 2 gets the evidence: the check's output, the files changed outside scope, the worktree status. Attempt 1 always leaves room for attempt 2.

5. Acceptance. Green means: the kill check exited 0, printed the exact line, and left the worktree unchanged; and every changed file is inside the lane's scope.

6. Bug sweep. A fresh worker hunts for defects in the green lane. If its change breaks the check, it is discarded and the earlier green is kept (the discarded commit stays under refs/powerswarm/).

7. Receipts. ~/.powerswarm/runs/<run>/ holds run.json, an event log, and every prompt, worker log and check output. Deadlines are hard; lanes that no longer fit are skipped, not started.

Request

{
  "objective": "Add JSON and CSV exports to the reports module",
  "targets": [
    {
      "id": "json-export",
      "aim": "Implement reports/export_json.py with export_json(rows) -> str.",
      "scope": ["reports/export_json.py", "tests/test_export_json.py"],
      "kill_check": {"argv": ["python3", "checks/lane.py", "json-export"], "expected_output": "LANE_OK json-export"}
    },
    {
      "id": "csv-export",
      "aim": "Implement reports/export_csv.py with export_csv(rows) -> str (RFC 4180 quoting).",
      "scope": ["reports/export_csv.py", "tests/test_export_csv.py"],
      "kill_check": {"argv": ["python3", "checks/lane.py", "csv-export"], "expected_output": "LANE_OK csv-export"}
    }
  ]
}

powerswarm spec prints every field and rule; powerswarm example prints a complete request.

Runtimes

--model passes a model id to the runtime.

Commands

powerswarm run REQUEST --root REPO [--runtime ...] [--detach]   start (and follow) a run
powerswarm status [RUN]                                         lanes, attempts, reasons, waves
powerswarm view [RUN] [--open]                                  live viewer on 127.0.0.1
powerswarm report [RUN]                                         markdown summary with review commands
powerswarm cancel RUN | recover RUN | clean RUN                 stop, resume after a crash, remove worktrees
powerswarm validate REQUEST [--root REPO] | spec | example | list
powerswarm mcp                                                  MCP server over stdio

Add --json before the command for machine-readable output.

From your agent

PowerSwarm is built to be conducted by an agent. Register the MCP server:

claude mcp add powerswarm -- python3 -m powerswarm mcp

# ~/.codex/config.toml
[mcp_servers.powerswarm]
command = "python3"
args = ["-m", "powerswarm", "mcp"]

Tools: powerswarm_spec, powerswarm_validate, powerswarm_run, powerswarm_status, powerswarm_cancel, powerswarm_report. The skill teaches when to use it and how to conduct a run: observe, challenge, synthesize, advance, verify. A finished swarm is the start of integration, not the end of the task.

Safety

• PowerSwarm never merges, pushes, deploys or edits your checkout. Every lane ends as a branch.

• Kill checks run without a shell. bash, sh, env and friends are refused at validation.

• Lanes cannot start PowerSwarm.

• Workers are real agents with your permissions inside their worktrees. The worktree, scope fence and kill check decide what is accepted; they do not sandbox what a worker runs. Use a VM or container for untrusted code. See SECURITY.md.

Status

0.1.0. Tested on macOS and Linux with Python 3.9 and 3.12. Windows is untested.

License

Apache-2.0. Not affiliated with xAI, OpenAI or Anthropic.