puppetmaster-ai 1.21.9

Gunicorn-style agent swarms with Redis-like shared memory and artifact stitching. (Imported as `puppetmaster`; published as `puppetmaster-ai` because the bare PyPI name is held by an abandoned 2019 project, name-reassignment pending.)

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
• Quickstart
• How it works
• Evidence
• More documentation
• Uninstall
• Status
• License

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

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.21.9, suitable for supervised local engineering rather than hosted multi-user use. The current release includes SQLite-backed jobs, Cursor Agent MCP support, full-edit adapters, constrained model routing, AWS Bedrock, and OpenCode Go subscription support through the agentic adapter. See the feature matrix and CHANGELOG.md for the current details.

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

License

MIT