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.28, 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. v1.22.27 warns when a dashboard is serving a forked/wrong project state dir (wrapper-cwd above the git checkout) via doctor state-identity, dashboard header tag, and /api/diagnostics — warn-only, no path relocation. v1.22.28 answers CDP websocket pings with RFC 6455 pongs, rejects a mismatched Sec-WebSocket-Accept, fail-closes audit actual_tokens_measured unless tokens_estimated is explicitly False, and computes headline token/cost drift on measured runs only. v1.22.26 splits artifact confidence into explicit statuses so worker self-rating cannot admit memory or shared gists (ARTIFACT_STATUS.md). 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:
Latest release

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.28.tar.gz (1.3 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.28-py3-none-any.whl (900.7 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: puppetmaster_ai-1.22.28.tar.gz
  • Upload date:
  • Size: 1.3 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.28.tar.gz
Algorithm Hash digest
SHA256 b865d39f9ffbb298ea35ad96d6daae34b7f69d956874934deb71f5eec9b3e393
MD5 a008c47c2f9fab65e4195500396223ce
BLAKE2b-256 3c3bf54d16a7be23577ac18651c388edf11f1b6ebe5cd88b3aaa5f4014e4b0c9

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for puppetmaster_ai-1.22.28-py3-none-any.whl
Algorithm Hash digest
SHA256 ccb70e67120b4af855276ebfd86eccfab9d38f7c1322930f23596ab45f02cd86
MD5 045a7107ca3721fab86953a9a429ee54
BLAKE2b-256 994b0b7cff1154d9dd00d405577faf5cb22b2c6026f8203c60b1e4c72d94f240

See more details on using hashes here.

Release history Release notifications | RSS feed

This release

1.22.28 This release

2 files

1.22.27

2 files

1.22.26

2 files

1.22.25

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