Puppetmaster

PyPI CI License: MIT Python

Puppetmaster runs multi-step engineering work through the agent tools you already use: Cursor, Claude Code, Codex, Hermes, Antigravity (Gemini 3.7 / 3.6 / 3.5 / 3.1 Pro), 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.
Puppetmaster demo showing routing, worker fan-out, and a stitched summary

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
# Pi TUI/pilot (not a worker adapter):
puppetmaster setup --platforms pi

Restart Cursor, Codex, Claude, Antigravity, Hermes, or Pi 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, Antigravity, 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 review for this repo on my configured reviewer platform 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 platform reviewer codex
puppetmaster review "Review this repo for release blockers"
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 / Antigravity / 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:

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.25, 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 (including Google Antigravity CLI agy with Gemini 3.7 / 3.6 / 3.5 / 3.1 Pro), 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. v1.22.13 makes puppetmaster dashboard exit on Ctrl-C on Windows and release its listening socket. v1.22.16 adds the Google Antigravity (agy) adapter. v1.22.17 makes jobs safely resumable (job_ref / monitor_with / launch idempotency) and quality-aware on delivery. v1.22.18 extracts build_cost_report so CLI / MCP / Mari share one reusable cost JSON. v1.22.19 externalizes routing roles, makes cheap cheapest-sufficient (old behavior is absolute-cheapest), and fail-closes requested review. v1.22.20 adds a configurable default reviewer platform (platform reviewer / generic review) with explicit > configured default > fail-closed precedence and no implicit Cursor. v1.22.21 adds an effort-level artifact index (effort-index / puppetmaster_effort_index) so Chief/Marionette recall compact refs across jobs without transcripts. v1.22.22 makes the Grok Bot contained path default to keys-only agentic workers when Cursor is not installed (same artifacts / effort-index; no grok-bot adapter). v1.22.23 adds a Pi TUI/pilot package (install-pi-mcp / setup --platforms pi; no pi worker adapter). v1.22.24 adds named cells (cell-status / cell-inspect / puppetmaster_cell_status): inspectable per-job sqlite + serial inbox + hibernate/alarm, without V8/Wrangler/S3/LTX. Additive CLI/MCP only; harness/SSE/session JSON unchanged. v1.22.25 closes cell sqlite handles (WAL checkpoint) so inspect/tempdir teardown does not WinError 32 on Windows. See the feature matrix, research guide, Grok Bot harness, Pi pilot, and CHANGELOG.md for the current details.

PyPI uses the package name puppetmaster-ai; the import name, CLI, and repository use puppetmaster.

License

MIT

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (1.22.28)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for CaryPalmer from gravatar.com CaryPalmer

Credits

Author: Cary

License

MIT License (MIT License)

Requires

Python >=3.9

Provides Extra

otel hermes mobile

Tags

agents swarm orchestration cursor llm redis sqlite

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

puppetmaster_ai-1.22.25.tar.gz (1.2 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

puppetmaster_ai-1.22.25-py3-none-any.whl (881.5 kB view details)

Uploaded Python 3

File details

Details for the file puppetmaster_ai-1.22.25.tar.gz.

File metadata

  • Download URL: puppetmaster_ai-1.22.25.tar.gz
  • Upload date:
  • Size: 1.2 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/7.0.0 CPython/3.13.5

File hashes

Hashes for puppetmaster_ai-1.22.25.tar.gz
Algorithm Hash digest
SHA256 149aadad55ce06b767695bab12e4801165581680f4d69b73e4f048a2f64c81d0
MD5 70dd67eec3584307c71c3f5cdb0ae596
BLAKE2b-256 ad383f3409e5a402fc900a8aba98296fe91ad4a4c7d8b75273d0dd241e4292a6

See more details on using hashes here.

File details

Details for the file puppetmaster_ai-1.22.25-py3-none-any.whl.

File metadata

File hashes

Hashes for puppetmaster_ai-1.22.25-py3-none-any.whl
Algorithm Hash digest
SHA256 047ccf42808b5e722aeb32ba1ae769d756b75f3e469c465b3e99781249d43dac
MD5 6066526f1456ecc9e709ad3c0758a82f
BLAKE2b-256 ef54fa4b6fa3b73a48dcacf71faae74dc6e9c7b079f3d94f421f89844a5c2974

See more details on using hashes here.

Release history Release notifications | RSS feed

1.22.28

2 files

1.22.27

2 files

1.22.26

2 files

This release

1.22.25 This release

2 files

1.22.24

2 files

1.22.23

2 files

1.22.22

2 files

1.22.21

2 files

1.22.20

2 files

1.22.18

2 files

1.22.17

2 files

1.22.16

2 files

1.22.15

2 files

1.22.14

2 files

1.22.13

2 files

1.22.12

2 files

1.22.11

2 files

1.22.9

2 files

1.22.8

2 files

1.22.7

2 files

1.22.6

2 files

1.22.5

2 files

1.22.4

2 files

1.22.3

2 files

1.22.2

2 files

1.22.1

2 files

1.22.0

2 files

1.21.14

2 files

1.21.13

2 files

1.21.12

2 files

1.21.11

2 files

1.21.10

2 files

1.21.9

2 files

1.21.8

2 files

1.21.7

2 files

1.21.6

2 files

1.21.5

2 files

1.21.4

2 files

1.21.3

2 files

1.21.2

2 files

1.21.1

2 files

1.21.0

2 files

1.20.10

2 files

1.20.9

2 files

1.20.8

2 files

1.20.7

2 files

1.20.6

2 files

1.20.5

2 files

1.20.3

2 files

1.20.2

2 files

1.20.1

2 files

1.20.0

2 files

1.19.16

2 files

1.19.15

2 files

1.19.14

2 files

1.19.13

2 files

1.19.12

2 files

1.19.8

2 files

1.19.7

2 files

1.19.6

2 files

1.19.5

2 files

1.19.4

2 files

1.19.3

2 files

1.19.2

2 files

1.19.1

2 files

1.19.0

2 files

1.18.1

2 files

1.18.0

2 files

1.17.0

2 files

1.16.0

2 files

1.15.0

2 files

1.14.2

2 files

1.14.1

2 files

1.14.0

2 files

1.13.0

2 files

1.12.1

2 files

1.12.0

2 files

1.11.1

2 files

1.11.0

2 files

1.10.3

2 files

1.10.2

2 files

1.10.1

2 files

1.10.0

2 files

1.9.0

2 files

1.7.0

2 files

1.5.1

2 files

1.4.0

2 files

1.3.0

2 files

1.2.0

2 files

1.1.0

2 files

1.0.0

2 files

0.9.102

2 files

0.9.101

2 files

0.9.100

2 files

0.9.99

2 files

0.9.98

2 files

0.9.97

2 files

0.9.95

2 files

0.9.93

2 files

0.9.92

2 files

0.9.91

2 files

0.9.90

2 files

0.9.89

2 files

0.9.88

2 files

0.9.87

2 files

0.9.86

2 files

0.9.85

2 files

0.9.84

2 files

0.9.83

2 files

0.9.82

2 files

0.9.81

2 files

0.9.80

2 files

0.9.79

2 files

0.9.78

2 files

0.9.77

2 files

0.9.76

2 files

0.9.75

2 files

0.9.71

2 files

0.9.70

2 files

0.9.67

2 files

0.9.66

2 files

0.9.65

2 files

0.9.64

2 files

0.9.63

2 files

0.9.62

2 files

0.9.61

2 files

0.9.60

2 files

0.9.59

2 files

0.9.58

2 files

0.9.56

2 files

0.9.55

2 files

0.9.54

2 files

0.9.53

2 files

0.9.52

2 files

0.9.51

2 files

0.9.50

2 files

0.9.49

2 files

0.9.48

2 files

0.9.47

2 files

0.9.46

2 files

0.9.45

2 files

0.9.44

2 files

0.9.43

2 files

0.9.42

2 files

0.9.41

2 files

0.9.40

2 files

0.9.39

2 files

0.9.38

2 files

0.9.37

2 files

0.9.36

2 files

0.9.35

2 files

0.9.34

2 files

0.9.33

2 files

0.9.32

2 files

0.9.31

2 files

0.9.30

2 files

0.9.29

2 files

0.9.28

2 files

0.9.27

2 files

0.9.26

2 files

0.9.25

2 files

0.9.24

2 files

0.9.23

2 files

0.9.22

2 files

0.9.21

2 files

0.9.20

2 files

0.9.19

2 files

0.9.18

2 files

0.9.17

2 files

0.9.16

2 files

0.9.15

2 files

0.9.14

2 files

0.9.13

2 files

0.9.12

2 files

0.9.11

2 files

0.9.10

2 files

0.9.9

2 files

0.9.8

2 files

0.9.7

2 files

0.9.6

2 files

0.9.5

2 files

0.9.4

2 files

0.9.3

2 files

0.9.2

2 files

0.9.1

2 files

0.8.0

2 files

0.7.2

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page