Puppetmaster
A provider-neutral control plane for durable-state agent swarms: persistent job state, cost-aware model routing, SQLite artifacts, and deterministic stitching that turn your existing coding agents into reviewable durable workers.
- Source repo
- professorpalmer/Puppetmaster
- Stars
- ★ 471
- Last updated
- 2d ago
- License
- MIT
- Primary language
- Python
- FA score
- 68/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A developer working in Cursor Agent or Codex who wants to delegate large audits or refactors to a background durable job instead of blocking a single session
- Not a fit if
- Users wanting zero-config setup with no external agent CLI installed
- Long-running deployments that cannot stop processes for the schema v5 migration
- Source review
- 68/100 · Some gaps
What does this agent do, and when should you use it?
Puppetmaster is a local, durable-state agent control plane that orchestrates the agent tools you already use — Cursor Agent, Grok Bot, Claude Code, Codex, Hermes, Antigravity, or a plain provider API — as leasable subprocess workers behind MCP tools. It launches independent workers, routes tasks to an available model, and stores typed artifacts with evidence in SQLite so jobs can be inspected, resumed, and re-read at zero inference cost. The README positions it as a daily-driver beta at v1.24.0 for supervised local engineering work such as repository investigations, audits, refactors, and implementations. It is distributed via the PyPI package puppetmaster-ai and exposes both a puppetmaster CLI and an MCP server. The repository ships reproducible benchmark scripts with scope statements in CLAIMS.md, reporting results such as reduced SWE-bench Lite spend and an NL2Repo-Bench pass rate, while explicitly noting these are single-condition measurements, not guarantees.
After pipx install puppetmaster-ai, running puppetmaster setup registers the puppetmaster_* MCP tools, rules, and hooks for installed platforms. Architecturally it distinguishes pilots (Cursor Agent, Grok Bot, Claude Desktop, Pi, OMP — MCP tool callers) from adapters (cursor, claude-code, codex, hermes, antigravity, agentic — the leased workers). A supervisor receives tasks, passes them through a model router to independent workers; workers claim tasks and write artifacts containing payloads and evidence without sharing one growing transcript, and the supervisor returns a stitched summary. Operations go through CLI commands such as puppetmaster doctor, puppetmaster route, puppetmaster review, and puppetmaster claude; artifacts are inspected with puppetmaster artifacts <job_id>, and python -m puppetmaster dashboard opens a live job dashboard. Grok Bot is served over remote MCP (streamable HTTP) via puppetmaster mcp serve-remote with Bearer token auth. Optionally, CodeGraph provides structural code context injected before worker calls.
- A developer working in Cursor Agent or Codex who wants to delegate large audits or refactors to a background durable job instead of blocking a single session
- A reviewer running a release-blocker review (puppetmaster review) who wants artifacts and evidence preserved for later inspection
- A user with multiple models/platforms configured who wants cost-aware routing to cut spend (README reports ~29% lower actual spend on SWE-bench Lite)
- A Grok Bot user connecting via a remote MCP connector to start and watch durable jobs on another box
- A user with no external agent CLIs who drives workers through the built-in agentic adapter using an OpenAI or OpenRouter API key
- An engineer running long multi-step implementation jobs that must resume after interruption and produce typed artifacts with content hashes
How do you install or deploy this agent?
Install from PyPI via pipx or pip:
pipx install puppetmaster-ai
puppetmaster setupsetup is idempotent, installs MCP tools, rules, and hooks, and asks you to enable at least one adapter, e.g. puppetmaster setup --platforms cursor. Grok Bot skips the stdio install: export PUPPETMASTER_MCP_TOKEN=... then run python -m puppetmaster mcp serve-remote --scope supervise. The built-in agentic adapter needs only a provider API key (OPENROUTER_API_KEY, OPENAI_API_KEY, ...). Requires Python 3.9+.
How do you use this agent?
Inside Cursor Agent, Grok Bot, or Codex, prompt: "Use Puppetmaster to run doctor in this repo and summarize what is missing." From the shell: run puppetmaster doctor to check the environment; dispatch work with puppetmaster route "Security audit every endpoint" --role audit; start supervised jobs with puppetmaster review "..." or puppetmaster claude "Implement the approved change..."; inspect with puppetmaster last, puppetmaster show, and puppetmaster artifacts <job_id>; open python -m puppetmaster dashboard for a live view. Assign roles with puppetmaster platform reviewer codex; disable auto-delegation hooks with PUPPETMASTER_AUTO_INVOKE_DISABLED=1. Verify an installed route with puppetmaster setup --verify-first-run codex/<model>.
What are this agent's strengths and limitations?
- Durable SQLite state makes jobs inspectable and resumable; follow-up inspection is a free read rather than re-inference
- Provider-neutral: one control plane drives Cursor, Claude Code, Codex, Hermes, Antigravity, and a pure-API agentic adapter
- Cost routing with durable retries reportedly cut SWE-bench Lite actual spend by 29% in a documented single-seed study (linked from the README)
- Typed artifacts with evidence fields and content hashes make output reviewable; reproducible benchmark scripts and CLAIMS.md document scope
- Idempotent puppetmaster setup gives one-command MCP/hook onboarding, plus operational aids like --verify-first-run and a clean uninstall command
- Benchmark evidence is single-condition: the SWE-bench Lite study is single-seed and does not establish quality parity, and NL2Repo-Bench is the author's own benchmark
- Requires at least one installed external agent CLI or a provider API key; it cannot run fully offline
- State lives in local SQLite (~/.puppetmaster/); migrating to schema v5 requires stopping long-lived processes and restarting supervisors, workers, MCP servers, and dashboards — a real migration coordination cost
- Budget reservations cannot constrain opaque provider overruns, so cumulative spend can exceed allowances
- Grok Bot needs a separate remote MCP deployment with token auth and a distinct path from the stdio install, adding configuration complexity
How does this agent compare with similar options?
The README explicitly differentiates Puppetmaster from LangGraph and CrewAI: those libraries help you build an agent, while Puppetmaster sits above them as a control plane coordinating existing agent CLIs and adapters; see WHY.md and COMPARISON.md in the repo.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Puppetmaster This agent | 68 · Some gaps | CLIFree + model costs | ★ 471 | 2d ago | Python | Codex · Claude Code |
| T3 Code | 52 · Major gaps | — | ★ 30k | today | TypeScript | Codex · Claude Code |
| Coven | 79 · Good | CLIFree | ★ 73 | today | Rust | Codex · Claude Code |
| ctx Local Agent History Search | 61 · Some gaps | CLIFree | ★ 1.2k | 18d ago | Rust | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Least privilege: opt-in platform setup, remote MCP defaults to `--scope supervise` omitting edit rights, uninstall preserves state unless `--purge-state`; adequate. Deducted: setup writes to host tool MCP configs, hooks, and rules — system-level external modification whose boundaries are asserted in docs, not evidenced in code. User confirmation: quickstart shows review/plan-then-approval flow, hooks disable via env var, `--dry-run` exists; deducted because auto-delegate hooks are on by default and opting out requires discovering an env var. Data flow: SQLite artifacts, `puppetmaster artifacts`, dashboard; good. Sensitive data: hermetic_env shows systematic credential-env awareness; remote MCP uses bearer token; deducted as token storage and TLS are left to the user ("Use a TLS tunnel if the bot is off-box"). Dependency security: zero core runtime deps, optional extras with floors and purpose comments, optional @cursor/sdk only; thorough. External effects: modifies host IDE/CLI configs and spawns subprocess workers; documented, but no backup mechanism for host config changes shown. Rollback: uninstall with `--dry-run`/`--purge-state`, crash-demo and recovery regression tests; good. Source attribution: author is only "Cary"; benchmark "independent" results hosted on the same author's GitHub Pages, so independence is questionable.
Self-consistency: PyPI/import name split explained; minor lag between README v1.27.1 and pyproject v1.27.2 costs a point; schema v5, attempt ledger, and budget docs cohere. Dependency availability: zero runtime deps plus lazy imports with actionable hints; CI on 3 OSes × 2 Pythons; Windows 3.9 excluded with only a comment — deducted. Failure messages: doctor command, adapter failure classification, verbose hermetic_env messages; quality not statically verifiable, so 2.
Audience: developers doing repo investigations/audits/refactors — clear. Boundaries: self-described 'daily-driver beta… supervised local engineering'; benchmark disclaimers explicit. Trigger precision: delegation hooks target 'larger tasks' and are disableable, but the mechanism is asserted, not shown in these files. Environment fit: 3-OS CI, Python 3.9–3.12, pipx/PyPI; adequate.
Information architecture: TOC, docs index, CI-verified README links; excellent. Install notes: install/uninstall/setup/verify-first-run, idempotency and CI modes; excellent. Naming stability: PyPI/import name split explained, but package. 0.1.0 disagrees with Python 1.27.x; deducted. Examples/FAQ: quickstart plus DAILY_DRIVER, MODEL_ROUTING, CLI_REFERENCE; strong. Known limitations: Status section, CLAIMS caveats, budget overrun disclosure, schema-cutover downtime note; honest and thorough. License: full MIT, consistent across files; full marks. Versioning/changelog: changelog linked with per-release notes, but CHANGELOG.md itself not in evidence and 'Alpha' classifier strains against 'daily-driver beta v1.27'; deducted. Maintenance responsibility: single 'Cary' authorship; no governance/contributing/security-policy file in evidence; deducted.
Output usability: typed artifacts, evidence fields, content hashes, stitched summaries, dashboard; well designed for inspectability, though actual output quality is not statically verifiable. Marginal value: durable state, cost routing, retries over raw agent CLIs — differentiation is clear (WHY/COMPARISON docs); claims rest on unverified benchmarks. Cost benefit: 47–48% token-matched savings headline; single-seed, no quality-parity evidence by the authors' own admission, so evidence strength is moderate.
Claim traceability: benchmarks link to dedicated repo and methodology; CLAIMS.md promises reproducible scripts and caveats; CI smoke tests exist; core performance claims are not reproducible within this repo's files. Cross-source corroboration: both SWE-bench and NL2Repo-Bench results are published through the same author's channels with no third-party replication; the word 'independent' overstates, heavily deducted. Fact/inference separation: README proactively separates measurements from guarantees (single-seed, provider overrun caveats); good.
- `puppetmaster setup` modifies host tool configs (Cursor/Claude Code/Codex MCP entries, hooks, rules). Back up these configs and preview changes before running.
- Auto-delegate hooks are enabled by default and only disabled via `PUPPETMASTER_AUTO_INVOKE_DISABLED=1`; teams that do not want autonomous delegation should disable them explicitly before deployment.
- The remote MCP endpoint's transport security is left to the operator (README suggests a TLS tunnel off-box); never expose it on an untrusted network and protect the bearer token.
- SWE-bench and NL2Repo-Bench results are published through the same author's channels; the 'independent' benchmark is not third-party replication and should not drive procurement decisions alone.
- Version claims disagree (README v1.27.1, pyproject v1.27.2, package. 0.1.0); treat pyproject as authoritative and watch for doc lag.
- Single-maintainer project with no visible governance or security disclosure channel; assess key-person risk before production use.
- SQLite schema v5 migration requires stopping long-lived processes; read the migration notes and back up `~/.puppetmaster/` before upgrading.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
Opt-in: one shared Codex host for a flow walk. A Codex worker starts its own codex exec process: the launcher, the native binary, a login-shell snapshot and git probes. Native Codex runs its subagents as threads in one process. Codex lab R200 measured about 114 s from codex exec launch to the first model turn for each cold builder, because the lab guards every process. R202 measured 0.05 s from a native subagent spawn to its own turn. - Set "defaults": {"codex_host": true} in the graph, or PUPPETMASTER_CODEX_HOST=1 for the walker. A graph value wins. Off by default. …View on GitHub ↗ -
Release notes excerpt
A nested builder's revise no longer blocks follow-up reuse. Codex R196 (PM 1.46.1, one builder per region inside each group, map reuse on): the follow-up named regions in groups 01 and 03 only. Groups 00 and 02 did not reuse ("its item graph reads the request"), so 8 extra region builders ran. - _reads_request removed revise only from the entry node itself. When the entry is a map, the inner builder's revise (with {{prev}}) stayed in the searched text, and the item counted as one that reads the request. …View on GitHub ↗ -
Release notes excerpt
A map inside a map item knows the outer items' writers. R179 replica, one builder per region inside each of the four groups: a region builder in group_00 wrote only its own files, but its write-scope gate charged it with 79 render files from builders in the other groups. Its item failed although the builder passed. - An outer item's scope now includes what the items of its own inner maps write (_item_scopes). The outer map's disjoint check covers them too. - A nested map gives its items the outer peer scopes as well as its own …View on GitHub ↗