professorpalmer/Puppetmaster

Provider-neutral control plane for durable-state agent swarms: subprocess workers, leases, artifacts, memory, and deterministic stitching.

Puppetmaster – Durable orchestration for LLM‑based developer agents

What it is – puppetmaster (installed from PyPI as puppetmaster‑ai) is a Python‑based supervisor that lets you run multi‑step engineering tasks through the LLM‑powered tools you already use (Cursor, Claude‑Code, Codex, Gemini Antigravity, Hermes, OpenAI‑compatible APIs, etc.). It launches independent worker processes, routes each sub‑task to the most appropriate model, and persists every typed result in a local SQLite database. The stored artifacts make the whole workflow inspectable, resumable, and auditable.

Why it matters – Typical LLM “agents” keep a single growing transcript, which makes it hard to recover from failures, compare model outputs, or prove what was done. Puppetmaster breaks the work into durable, typed artifacts, giving developers a reliable state layer for code‑base audits, refactors, or any repository‑wide automation.

Core concepts

Concept	Role
Pilots (MCP)	Front‑ends that invoke Puppetmaster (Cursor Agent, Grok Bot, Claude Desktop, Pi, OMP).
Adapters / Workers	Concrete model back‑ends (cursor, claude‑code, codex, hermes, antigravity, generic agentic API).
Supervisor	Coordinates routing, starts workers, writes SQLite artifacts, and provides a stitched summary.
SQLite store	Durable log of each step (payload, evidence, content hash) that can be queried later.
Dashboard	Small web UI (`http://127.0.0.1:<port>/?job=<id>&embed=1`) for live job inspection, also usable from phones.

Quick start (shell)

# install (pipx recommended)
pipx install puppetmaster-ai
# set up adapters you have, e.g. Cursor
puppetmaster setup --platforms cursor

# run a simple “doctor” pass on the current repo
puppetmaster doctor

# launch a supervised change
puppetmaster start "Review this repo for release blockers" \
    --review --dry-run

# inspect the latest job
puppetmaster show $(puppetmaster last)

In a supported UI (Cursor, Grok Bot, etc.) you can simply type:

Use Puppetmaster to run doctor in this repo and summarize what is missing.

The UI forwards the request to the local supervisor, which spawns the appropriate workers and returns a job ID you can poll.

Key features

Multi‑model routing – choose the cheapest or most capable model per sub‑task; cost‑routing shown to cut spend ~30 % on SWE‑bench Lite.
Durable state – every worker writes a typed artifact to SQLite; jobs survive crashes and can be resumed.
Fan‑out & stitching – parallel workers can be launched, then a final model produces a concise summary.
Adapter‑agnostic – works with any CLI that follows the MCP contract (Cursor, Claude‑Code, Codex, Gemini Antigravity, Hermes, or a generic API key).
Remote MCP for Grok Bot – expose the same tool handlers over HTTP/SSE so Cursor’s Grok Bot can drive jobs from another machine.
Optional CodeGraph context – if the codegraph index is present, workers receive structural code information automatically.
Dashboard & CLI inspection – puppetmaster artifacts <job_id> or python -m puppetmaster dashboard to view raw results.
Safety hooks – built‑in request‑level verification (puppetmaster setup --verify-first-run …) and a security model documented in SECURITY.md.

Evidence & benchmarks

SWE‑bench Lite – 29 % lower actual spend and ~48 % token‑matched savings compared to a single‑model baseline (single‑seed study).
NL2Repo‑Bench – 91.1 % mean pass rate, roughly 2.3× the published ~40 % baseline. Detailed methodology is in the linked benchmark repo and a public blog post.
Reproducible benchmark scripts are shipped in the repo (CLAIMS.md), covering routing, artifact integrity, and failure classification.

Maturity & licensing

Version v1.27.8 (beta, daily‑driver). Recent releases added durability fixes, continuous planning, and a chrome‑free embedded dashboard.
Installation – pipx or pip; puppetmaster setup handles idempotent installation of adapters and MCP hooks.
Uninstall – puppetmaster uninstall removes all MCP entries; state can be purged with --purge‑state.
License – MIT.

When to use it

You already use one or more LLM‑powered coding assistants and want a single place to coordinate them.
You need audit‑ready logs of what the model did (e.g., security audits, compliance checks).
Your workflow benefits from parallel model calls and a final stitched summary.
You want to reduce cost by routing cheap models for simple steps and reserving expensive models for critical edits.

Where to learn more

Full docs: docs/README.md
Adapter setup details: docs/ADAPTERS.md
Feature matrix: docs/FEATURES.md
Benchmark claims: docs/CLAIMS.md
Dashboard usage: docs/DASHBOARD.md

Bottom line – Puppetmaster is a practical, open‑source layer that turns ad‑hoc LLM coding assistants into a reliable, stateful engineering pipeline, with built‑in cost routing, durability, and inspection tools.