Automation
Plugin
puppetmaster
Puppetmaster runs multi-step engineering work through the agent tools you already use: Cursor, Claude Code, Codex, Hermes, or a provider API.
Plugin Signal67/100Solid
maintained99
capable14
documented100
adopted53
Install
$ npx -y skills add professorpalmer/Puppetmaster --agent claude-code
Run the curl in your terminal, the rest in Claude Code.
What's inside
Badges
4
README
1Puppetmaster
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.13, 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, passive provider rate-limit harvest, AWS Bedrock, OpenCode Go, and Marionette-keyed Z.AI / MiniMax / NVIDIA NIM providers 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
File tree
249professorpalmer/PuppetmasterView on GitHub
.codegraph/
.gitignore
config.json
.cursor/
rules/
puppetmaster-workflow.mdc
.env.example
.github/
workflows/
ci.yml
.gitignore
AGENTS.md
assets/
hermes-support-slack.html
hermes-support-slack.png
puppetmaster-setup-guide.png
setup-guide-slack.html
bench/
__init__.py
codegraph_ab.py
codegraph_race.py
followup_cost.py
mcp_stress.py
prompts/
example.txt
README.md
results/
.gitkeep
router_live_ab.py
router_savings.py
stress_fable5_rollout.py
stress_invocation.py
stress_new_features.py
stress_streamed_adapters.py
three_way.py
clients/
typescript/
.gitignore
package.json
puppetmaster.ts
README.md
tsconfig.json
docs/
ADAPTERS.md
ARCHITECTURE.md
CHANGELOG.md
CLAIMS.md
CLI_REFERENCE.md
CODEGRAPH.md
COMPARISON.md
COMPRESSION.md
CONTRIBUTING.md
CURSOR_AGENT_MCP.md
DAILY_DRIVER.md
DASHBOARD.md
demo.gif
design_memory_hygiene.md
design_rqgm_evaluators.md
FEATURES.md
hermes-support.png
layer-above.jpg
MOBILE.md
MODEL_ROUTING.md
OUTPUT_STYLE.md
PRODUCTION.md
README.md
receipts.svg
RELEASE_CHECKLIST.md
ROADMAP.md
sample-anchor-set.json
sample-evaluator-registry.json
sample-models.json
SECURITY.md
setup-guide.jpg
specs/
hermes-skill-injection.md
TROUBLESHOOTING.md
WHY.md
examples/
agentic-analyze.json
agentic-implement.json
claude-code-full-edit.json
cursor-dry-run-implementation.json
cursor-live.json
cursor-review.json
enterprise-workflow.json
memory-reuse.json
README.md
transcripts/
crash-recovery.txt
enterprise-workflow.txt
LICENSE
Makefile
package.json
puppetmaster/
__init__.py
__main__.py
acceptance_criteria.py
adapters/
__init__.py
_base.py
_context_budget.py
_delta_bus.py
_delta_stream.py
_facade.py
_git.py
_prompts.py
_streaming.py
agentic.py
claude_code.py
codex.py
cursor.py
hermes.py
local.py
openai.py
registry.py
affected.py
api_discovery.py
artifact_bounds.py
audit.py
bedrock.py
browser_cdp.py
browser.py
cancellation.py
claim_conflicts.py
cli/
__init__.py
_dispatch.py
_parser.py
commands_codegraph.py
commands_evaluators.py
commands_gate.py
commands_install.py
commands_jobs.py
commands_keys.py
commands_mcp.py
commands_models.py
commands_platform.py
guidance.py
helpers.py
codegraph_index_runner.py
codegraph_repair.py
codegraph_usage.py
codegraph.py
config.py
conflicts.py
cost.py
cursor_discovery.py
cursor_sdk_runner.mjs
dashboard.py
diagnostics.py
eval_harness.py
evaluators.py
execution_provenance.py
failure.py
fs_permissions.py
gates.py
hashline.py
hermes_plugin/
puppetmaster-learn/
__init__.py
plugin.yaml
README.md
hermes_spawn_tree.py
hook_installers.py
hook_runner.py
installers.py
invocation_gate.py
job_brief.py
lifecycle.py
liveness.py
mcp_registry.py
mcp_server.py
memory_cost_log.py
mmr.py
model_registry.py
models.py
openai_codex.py
openai_security.py
opencode_go.py
orchestrator.py
output_style.py
platform_billing.py
platform_lock.py
ports.py
preflight.py
prewalk.py
provider_circuit.py
provider_health.py
provider_proxy.py
providers.py
quality.py
rate_limit_headers.py
rate_limit_state.py
README.md
reads_log.py
receipt.py
redaction.py
router.py
rules.py
run_id.py
savings.py
secret_entry.py
skill_injection.py
skills/
puppetmaster/
SKILL.md
sqlite_store.py
state.py
static_catalog.py
stitcher.py
store_factory.py
store.py
swarm_launch.py
telemetry.py
tool_batch.py
tool_offload.py
update_check.py
usage.py
validation.py
win_console.py
win_process.py
worker_runtime.py
workers.py
pyproject.toml
README.md
scripts/
demo.sh
demo.tape
README.md
tests/
conftest.py
fixtures/
mutations/
edit_stale_tag_refusal.json
edit_tagged_success.json
edit_untagged_legacy.json
hashline_stale_refusal.json
hashline_tagged_success.json
hermetic_env.py
run_id_mp_worker.py
test_agentic_standalone.py
test_allowed_model_routing.py
test_artifact_bounds.py
test_auto_route_model_guard.py
test_bedrock_invoke_health.py
test_bedrock_stream.py
test_browser_cdp.py
test_codegraph_utf8.py
test_eval_harness.py
test_graph.py
test_hashline.py
test_hermetic_env.py
test_history_compaction.py
test_job_brief.py
test_marionette_keyed_providers.py
test_mcp_run_id.py
test_mutation_fixtures.py
test_openai_codex.py
test_opencode_go.py
test_prewalk.py
test_process_tree.py
test_prompt_cache.py
test_prompt_prefix.py
test_provider_circuit.py
test_puppetmaster.py
test_quality_control.py
test_rate_limit_harvest.py
test_role_routing_defaults.py
test_sqlite_connection.py
test_swarm_launch.py
test_tool_batch.py
test_tool_offload.py
test_trackable_swarm_mcp.py
test_validation_protocol.pyFAQ
puppetmaster is a Claude Code plugin with 1 hand-picked skill for automation work, indexed on Flowy. Install it with the command on its page. It includes puppetmaster. Its skills do not fire on their own yet. Request auto-invocation to have Flowy route them as you prompt. Free and open source.
- What is puppetmaster?
- Puppetmaster runs multi-step engineering work through the agent tools you already use: Cursor, Claude Code, Codex, Hermes, or a provider API.
- How do I install puppetmaster?
- Run these in Claude Code: npx -y skills add professorpalmer/Puppetmaster --agent claude-code. Then prompt normally.
- Does puppetmaster auto-invoke its skills?
- Not yet. It is indexed on Flowy as a plain plugin. Request auto-invocation on its page and Flowy will route its skills for you as you prompt.
- Is puppetmaster free?
- Yes. Flowy is free and open source, with nothing gated. You can read every skill in full before you install.