# Puppetmaster keeps worker output in SQLite so a later model reads it instead of inheriting it > A zero-dependency Python package that supervises agent CLIs as leased subprocess workers, stores typed artifacts in SQLite, and stitches a summary back to the parent. The PyPI name is puppetmaster-ai because the bare name belongs to an abandoned 2019 project, and setup writes MCP tools into every host you point it at. **professorpalmer/Puppetmaster** — Provider-neutral control plane for durable-state agent swarms: subprocess workers, leases, artifacts, memory, and deterministic stitching. - Repository: https://github.com/professorpalmer/Puppetmaster - Stars: 466 · Forks: 42 - Language: Python - License: MIT - Published: 2026-09-10 · Updated: 2026-09-10 · Language: en - Canonical page: https://hysenlabs.com/projects/professorpalmer-puppetmaster ## Workers write artifacts, they do not share a transcript The architecture line states it compactly: ```text pilots (MCP): Cursor Agent / Grok Bot / Claude Desktop / Pi / OMP workers: cursor / claude-code / codex / hermes / antigravity / fx / agentic | v supervisor -> model router -> independent workers -> SQLite artifacts ``` Workers claim tasks, write artifacts containing payloads and evidence, and do not share one growing transcript. The parent agent receives a stitched result and can inspect the stored artifacts afterwards. Two vocabularies sit on top of that. Pilots are the things that call MCP tools: Cursor Agent, Grok Bot, Claude Desktop, Pi, OMP. Adapters are the leased workers: cursor, claude-code, codex, hermes, antigravity, fx, agentic. So the same tool call that you make from Cursor starts a worker, and the worker is a separate process with a lease. ## A later model reads the working set at no cost and gets no KV cache The stated advantage is arithmetic. Follow-up inspection is a SQLite read at zero dollars, and a later model retrieves that working set rather than inheriting another model's provider key-value cache. That distinction is the whole argument for durable state. A shared transcript means every follow-up pays to re-read everything a previous model produced. A SQLite artifact means the next model pays only for what it decides to load. The cost is that nothing is inherited implicitly. If an artifact does not record the reasoning behind a conclusion, the next worker does not get it, which puts the burden on the artifact schema rather than on context length. ## Setup writes into your editor, and one environment variable turns the hooks off Install is two commands: ```bash pipx install puppetmaster-ai # or: pip install puppetmaster-ai puppetmaster setup # installs MCP tools, rules, and hooks ``` Setup is described as idempotent, skipping platforms that are not installed and printing each change, and it asks you to enable at least one adapter. You can narrow it with a platform flag: ```bash puppetmaster setup --platforms cursor # Pi TUI/pilot (not a worker adapter): puppetmaster setup --platforms pi ``` After it runs you restart Cursor, Codex, Claude, Antigravity, Hermes, Pi or OMP, and the host gains the puppetmaster_* MCP tools plus hooks that suggest delegation for larger tasks. Those hooks are disabled with PUPPETMASTER_AUTO_INVOKE_DISABLED=1, and for CI you pass a comma list or --platforms all. Another adapter can be added later with puppetmaster platform enable . ## Grok Bot gets HTTP and a bearer token instead of a stdio server Grok Bot is the odd one out. Cursor's Grok Bot assistant attaches remote MCP connectors over streamable HTTP or SSE, and cannot register python -m puppetmaster.mcp_server the way Cursor Agent, Claude Desktop and Codex do. So the same tool handlers are served over HTTP: ```bash export PUPPETMASTER_MCP_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')" python -m puppetmaster mcp serve-remote --scope supervise ``` In the bot you add an MCP server with the printed /mcp URL and an Authorization bearer header. Use a TLS tunnel if the bot is off-box. The scope flag is a permission control. Default --scope supervise omits implement and edit, and --scope implement is passed only when you want the remote client to start full-edit workers. ## The published name is puppetmaster-ai because the bare name is taken The package metadata explains the naming in the description field: the project is imported as puppetmaster, published as puppetmaster-ai because the bare PyPI name is held by an abandoned 2019 project, with name reassignment pending. So both spellings are correct in different contexts. pipx install puppetmaster-ai gets the package; python -m puppetmaster runs it; the classifiers and the licence are MIT; and the status is Development Status 3, Alpha. What is absent is as notable as what is present. dependencies is an empty list. Everything optional is in extras: OpenTelemetry packages for tracing, PyYAML for registering with Hermes, and qrcode with Pillow for the phone dashboard. The stated reason for each is that a missing optional leaves the core working rather than broken. ## Every tuning knob in the env example has a kill switch The .env.example is unusually careful. Artifact persistence is bounded by default, with a 262144 byte maximum, a 48000 character text field cap, a 20000 character patch diff cap and 500 patch files, and oversized text spilling to an offload directory under the job with a head and tail preview left inline. Set PUPPETMASTER_ARTIFACT_BOUNDS=0 to disable the bounding. Concurrent read segments are capped at 8 workers, with a switch forcing fully sequential batches. The provider circuit breaker for agentic calls opens after 3 consecutive retryable failures, does a half-open probe after a 30 second cooldown, and can be disabled entirely. Each of the three groups has a documented kill switch. That pattern is worth noting: a system meant to survive failures treats its own mitigation mechanisms as things a user may want to turn off. The provider keys follow the same shape. Six are listed as ordinary optional values, OpenAI, Anthropic, Gemini, Google and OpenRouter among them, plus an OpenCode Go subscription key that routes to opencode.ai rather than to OpenRouter, and two more for Marionette-keyed providers including ZAI and MiniMax at an Anthropic-compatible endpoint. The agentic adapter is documented as using whichever key is visible, so it is the one worker that needs no external CLI. ## The measured results come with their own caveat attached Two numbers are offered, and the qualifications are part of the claims. On SWE-bench Lite the reported figure is 29 percent lower actual spend with cost routing and durable retries, and 47 to 48 percent token-matched savings. The text immediately says this is a single-seed study and does not establish quality parity. On NL2Repo-Bench the reported figure is a 91.1 percent mean pass rate, about 2.28 times the published baseline of about 40 percent. The second claim is the larger one and carries less caveat, which is the reverse of how benchmark claims usually go. Both point at separate repositories or pages for the methodology, so the studies are meant to be checked rather than taken on the summary line. There is a first-run verification path as well, for checking that an installed Codex route actually delivers. Running puppetmaster setup --verify-first-run with an exact registry identifier makes one live call in temporary state and returns nonzero if it cannot prove delivery within 120 seconds. Ordinary setup does not make that call, so the check is opt-in precisely because it costs money. ## Conclusion Use it if you run long engineering jobs through Cursor, Claude Code, Codex or a provider API and need the output to survive the process that produced it, since the SQLite artifact store is the point rather than the orchestration. Read the measured-results section carefully: the savings study is single-seed and explicitly does not claim quality parity. Check the package name before you install, since it is puppetmaster-ai rather than puppetmaster. And read what setup writes, because it installs MCP tools, rules and hooks into each host and can be disabled with one environment variable. ## FAQ ### How do I install Puppetmaster? Run pipx install puppetmaster-ai, or pip install puppetmaster-ai, then run puppetmaster setup. Setup installs MCP tools, rules and hooks, is idempotent, skips platforms that are not installed, and prints each change it makes. ### Why is the PyPI package called puppetmaster-ai? Because the bare puppetmaster name on PyPI is held by an abandoned 2019 project. The project is imported as puppetmaster but published as puppetmaster-ai, and the description notes that name reassignment is pending. ### What is the difference between a pilot and an adapter in Puppetmaster? Pilots call MCP tools and are Cursor Agent, Grok Bot, Claude Desktop, Pi and OMP. Adapters are the leased workers they start: cursor, claude-code, codex, hermes, antigravity, fx and agentic. ### How does Puppetmaster avoid resending context between agents? Workers write typed artifacts into SQLite rather than sharing a growing transcript, so follow-up inspection is a database read rather than another model call. A later model retrieves the stored working set instead of inheriting a previous provider's KV cache. ### What results does Puppetmaster report? On SWE-bench Lite, 29 percent lower actual spend and 47 to 48 percent token-matched savings, described as a single-seed study that does not establish quality parity. On NL2Repo-Bench, a 91.1 percent mean pass rate against a published baseline of about 40 percent. ## Sources - [Issues](https://github.com/professorpalmer/Puppetmaster/issues) - [License: MIT](https://github.com/professorpalmer/Puppetmaster/blob/main/LICENSE) - [professorpalmer/Puppetmaster on GitHub](https://github.com/professorpalmer/Puppetmaster) - [README](https://github.com/professorpalmer/Puppetmaster/blob/main/README.md) - [Releases](https://github.com/professorpalmer/Puppetmaster/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/professorpalmer-puppetmaster