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