Puppetmaster
Puppetmaster runs multi-step engineering work through the agent tools you already use: Cursor, Claude Code, Codex, Hermes, or a provider API. It starts independent workers, routes tasks to an available model, and stores their typed results in SQLite so jobs can be inspected and resumed. It is aimed at developers who want durable state and reviewable output for repository investigations, audits, refactors, and implementations.
Measured results
- SWE-bench Lite: 29% lower actual spend with cost routing and durable retries; 47–48% token-matched savings. This is a single-seed study and does not establish quality parity. Study.
- NL2Repo-Bench: 91.1% mean pass rate, about 2.28× the published ~40% baseline. Benchmark and methodology.
Contents
Install
pipx install puppetmaster-ai # or: pip install puppetmaster-ai
puppetmaster setup # installs MCP tools, rules, and hooks
setup is idempotent, skips platforms that are not installed, and prints each change. It asks you to enable at least one adapter; for example:
puppetmaster setup --platforms cursor
Restart Cursor, Codex, Claude, or Hermes after setup. The host then has the puppetmaster_* MCP tools and, where supported, hooks that suggest delegation for larger tasks. Disable those hooks with PUPPETMASTER_AUTO_INVOKE_DISABLED=1. For CI, use --platforms <comma-list> or --platforms all. Add another adapter later with puppetmaster platform enable <name>.
The built-in agentic adapter needs only a provider API key, so it can run without an external CLI. See adapter setup for provider and Hermes details.
Quickstart
Inside Cursor Agent or Codex:
Use Puppetmaster to run doctor in this repo and summarize what is missing.
For a supervised change:
Use Puppetmaster to start a cursor swarm for this repo and return the job id immediately.
Problem: users get logged out after refresh and token-refresh tests are flaky.
Constraints: keep the patch focused, preserve public API behavior, run relevant tests.
Do review/plan first. Poll status/logs by job id. Do not edit until you summarize findings and ask for approval.
From the shell:
puppetmaster doctor
puppetmaster route "Security audit every endpoint" --role audit
puppetmaster cursor "Review this repo for release blockers" --review --dry-run
puppetmaster claude "Implement the approved change and run focused tests" --permission-mode acceptEdits
puppetmaster show "$(puppetmaster last)"
More recipes are in DAILY_DRIVER.md and MODEL_ROUTING.md.
How it works
Puppetmaster is a supervisor and job store for agent CLIs and provider adapters:
Cursor / Claude Code / Codex / Hermes / agentic
|
v
supervisor -> model router -> independent workers -> SQLite artifacts
|
v
stitched summary
Workers claim tasks, write artifacts containing payloads and evidence, and do not share one growing transcript. The parent agent receives the stitched result and can inspect the stored artifacts with:
puppetmaster artifacts <job_id>
python -m puppetmaster dashboard
CodeGraph is an optional structural code index. When installed, Puppetmaster adds task-relevant CodeGraph context before worker calls; otherwise workers use ordinary repository inspection. See CODEGRAPH.md.
Puppetmaster sits above libraries such as LangGraph and CrewAI: those libraries help you build an agent, while Puppetmaster coordinates existing agent CLIs and adapters. See WHY.md and COMPARISON.md.
Evidence
The repository includes reproducible benchmark scripts and their scope and caveats in CLAIMS.md. The receipts cover:
- routing fixture results and follow-up reads from completed SQLite artifacts;
- typed artifacts, evidence fields, and content hashes;
- CodeGraph context injection and adapter failure classification.
These are measurements of the included workflows, not guarantees for every repository or model. An independent durable-state benchmark is documented here.
More documentation
The docs index covers:
- FEATURES.md — adapters and shipped features
- SECURITY.md — safety and threat model
- DASHBOARD.md — live job dashboard
- OUTPUT_STYLE.md and COMPRESSION.md — output and context options
- MOBILE.md — watching jobs from a phone
- RESEARCH.md — durable autoresearch claims, runs, publishing, and verification
Uninstall
puppetmaster uninstall
pip uninstall puppetmaster-ai # or: pipx uninstall puppetmaster-ai
uninstall removes Puppetmaster-owned MCP entries, hooks, and rules. It keeps ~/.puppetmaster/ and workspace .codegraph/ unless you pass --purge-state; use --dry-run to preview.
Status
Puppetmaster is a daily-driver beta at v1.22.12, suitable for supervised local engineering rather than hosted multi-user use. The current release includes SQLite-backed jobs, Cursor Agent MCP support, Grok Bot remote MCP (streamable HTTP pilot path), full-edit adapters, live-site browser swarms (Hermes preferred; agentic/OpenRouter via stdlib CDP), durable autoresearch claim/run/publish/verify loops, constrained model routing with optional evidence-backed role scorecards and a SWE-bench Bash Only community-prior connector (issue #28 / PR #30; Grok 4.6 remains the Cursor workhorse for ambitious and agentic work), shared verified context (admitted gists + dashboard Frontier), passive provider rate-limit harvest, AWS Bedrock, OpenCode Go, and Marionette-keyed Z.AI / MiniMax / NVIDIA NIM providers through the agentic adapter. Codex and Claude Code now send large prompts on stdin so Windows CreateProcess no longer fails with WinError 206. Spawned workers are exempt from the delegate-first gate so they do not try to start a swarm they cannot reach. v1.22.12 honors advertised swarm timeouts on run / swarm / start_cursor_swarm (instead of a silent 90s / 270s fallback), uses an explicit max_timeout_seconds as given, and reports the limit that actually killed the worker. See the feature matrix, research guide, Grok Bot harness, and CHANGELOG.md for the current details.
PyPI uses the package name puppetmaster-ai; the import name, CLI, and repository use puppetmaster.
License
MIT
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file puppetmaster_ai-1.22.12.tar.gz.
File metadata
- Download URL: puppetmaster_ai-1.22.12.tar.gz
- Upload date:
- Size: 1.1 MB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.14.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
41fd9fdf0175274da1ec181df45320aa2e0524610609b77544312de88c7ef21f
|
|
| MD5 |
5021b9aed03837e5df1bd56533090405
|
|
| BLAKE2b-256 |
560e8ed2bf1b4686e79e05082777b327a7187595015817d05661bf504c08a765
|
File details
Details for the file puppetmaster_ai-1.22.12-py3-none-any.whl.
File metadata
- Download URL: puppetmaster_ai-1.22.12-py3-none-any.whl
- Upload date:
- Size: 792.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.14.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
d6c061268722cd8cf410e24065a7999079450c3bddba52ae00119d1b6e5eb287
|
|
| MD5 |
65b4d920433a18f2ea13261397e7d39b
|
|
| BLAKE2b-256 |
d3377235c01b2c7a04306bbac0ddbf072a542d648b74f992f3b2e04900d60bdd
|
