Puppetmaster
Puppetmaster runs multi-step engineering work through the agent tools you already use: Cursor, Grok Bot, 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.
Grok Bot: only remote MCP, not the stdio server Cursor Agent uses. Puppetmaster is the durable worker runtime behind that chat — same jobs, artifacts, and effort-index, over streamable HTTP. See Grok Bot.
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
# Pi TUI/pilot (not a worker adapter):
puppetmaster setup --platforms pi
# OMP / oh-my-pi TUI/pilot (not a worker adapter):
puppetmaster setup --platforms omp
Restart Cursor, Codex, Claude, Antigravity, Hermes, Pi, or OMP 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>.
Grok Bot does not use that stdio install. Start remote MCP and add the printed connector instead (Grok Bot).
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.
Grok Bot
Cursor's Grok Bot assistant attaches remote MCP connectors only (streamable HTTP / SSE). It cannot register python -m puppetmaster.mcp_server the way Cursor Agent, Claude Desktop, and Codex do. Serve the same tool handlers over HTTP and Grok Bot can start and watch durable jobs on this box:
export PUPPETMASTER_MCP_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
python -m puppetmaster mcp serve-remote --scope supervise
# equivalent: puppetmaster-mcp-remote --scope supervise
# one-shot PoC (prints connector JSON): ./scripts/grok-bot-remote-poc.sh
In Grok Bot → Add MCP server, use the printed /mcp URL and Authorization: Bearer <token>. Use a TLS tunnel if the bot is off-box. Confirm tools load, then puppetmaster_doctor and puppetmaster_start_implement or puppetmaster_start_agentic.
When Cursor is not installed on that host, implement / prewalk / swarm pick keys-only agentic workers (OPENROUTER_API_KEY, OPENAI_API_KEY, …). There is no grok-bot adapter and no CreateAgent fleet. Default --scope supervise omits implement/edit; pass --scope implement only when you want the remote client to start full-edit workers.
Connector JSON, handshake notes, and auth: GROK_BOT.md.
Quickstart
Inside Cursor Agent, Grok Bot, 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)"
To verify an installed Codex route on macOS, Linux, or Windows, run
puppetmaster setup --verify-first-run codex/<model> with an exact registry ID.
This opt-in check makes one live call in temporary state and returns nonzero if
it cannot prove delivery within 120 seconds. Ordinary setup does not make this
call. See first-run verification.
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. Grok Bot, Cursor Agent, Pi, and OMP are pilots (they call MCP tools); cursor / claude-code / agentic / … are adapters (leased workers):
pilots (MCP): Cursor Agent / Grok Bot / Claude Desktop / Pi / OMP
workers: 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. Follow-up inspection is a SQLite read at $0. A later model retrieves that working set; it does not inherit another model's provider KV cache. The parent agent receives the stitched result and can inspect the stored artifacts with:
puppetmaster artifacts <job_id>
python -m puppetmaster dashboard
A host pane (for example Marionette) can load a chrome-free job view at http://127.0.0.1:<port>/?job=<id>&embed=1.
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:
- GROK_BOT.md — Grok Bot as remote MCP pilot (streamable HTTP; not a worker adapter)
- FEATURES.md — adapters, pilots, and shipped features
- SECURITY.md — safety and threat model
- DASHBOARD.md — live job dashboard
- CONCURRENT_SESSIONS.md — operating concurrent agent sessions, state scope, dashboard URLs, and worktrees
- OUTPUT_STYLE.md and [COMPRESSION.md](https://github.com/professorpalmer/Puppetmaste