Puppetmaster: A Durable Job Store and Supervisor for Agent CLI Workers

The problem Puppetmaster targets: agent work that outlives one chat session

Agent CLIs are good at a single bounded task and bad at being a system of record. A Cursor Agent or Codex run produces a transcript. If the process dies, or you want to compare three attempts at the same refactor, the transcript is what you have. Puppetmaster's README frames the project as a supervisor and job store: it starts independent workers, routes tasks to an available model, and keeps typed results in SQLite so jobs can be inspected and resumed. The audience named in the README is developers doing repository investigations, audits, refactors and implementations. That is a narrower audience than "anyone using AI agents". The pitch assumes you already have at least one agent CLI installed and configured, and that you want the orchestration layer to be separate from the model provider.

Pilots, adapters and the supervisor path

The README draws a distinction that matters more than any feature list. Pilots (Cursor Agent, Grok Bot, Claude Desktop, Pi, OMP) call MCP tools. Adapters (cursor, claude-code, codex, hermes, antigravity, agentic) are leased workers. The data flow shown in the README is supervisor, then model router, then independent workers, then SQLite artifacts. So a pilot asks for work, the supervisor picks a worker, the worker runs as a subprocess, and the typed result lands in SQLite. Two details follow from that shape. First, the workers are subprocesses, not library calls, which means whatever the underlying CLI can do (permission modes, edit behaviour) is what the worker can do. Second, routing is a registry lookup rather than a hardcoded provider: `puppetmaster route "Security audit every endpoint" --role audit` is the shell form, and `puppetmaster platform reviewer codex` sets a role binding. The `agentic` adapter is the exception to the CLI dependency, needing only a provider API key.

Install, setup and the config surface you actually touch

Installation is two commands: `pipx install puppetmaster-ai` (or `pip install puppetmaster-ai`), then `puppetmaster setup`. The README states that setup is idempotent, skips platforms that are not installed, and prints each change. It asks you to enable at least one adapter, either interactively or with `--platforms cursor`, `--platforms pi`, `--platforms omp`, or a comma list, and `--platforms all` for CI. `puppetmaster platform enable <name>` adds another adapter later. Hooks that suggest delegation for larger tasks can be turned off with `PUPPETMASTER_AUTO_INVOKE_DISABLED=1`. The host has to be restarted after setup for the `puppetmaster_*` MCP tools to appear. One env var is worth flagging: `PUPPETMASTER_MCP_TOKEN`, generated in the README example with `python -c 'import secrets; print(secrets.token_urlsafe(32))'`, is the bearer token for the remote MCP server. That is a shared secret guarding job control, so treat it as one.

Grok Bot needs remote MCP, and that changes your deployment

This is the sharpest constraint in the material. Cursor's Grok Bot assistant attaches remote MCP connectors only (streamable HTTP or SSE). It cannot register `python -m puppetmaster.mcp_server` the way Cursor Agent, Claude Desktop and Codex do. Puppetmaster's answer is `python -m puppetmaster mcp serve-remote --scope supervise`, with an equivalent `puppetmaster-mcp-remote --scope supervise`. The README is explicit about scope: default `--scope supervise` omits implement and edit, and you pass `--scope implement` only when you want the remote client to start full-edit workers. There is no `grok-bot` adapter and no CreateAgent fleet. If the bot is off-box, the README says to use a TLS tunnel. So adopting Puppetmaster for Grok Bot means running a listening HTTP service with a bearer token and a tunnel, not just installing a CLI. That is a materially different security posture from the stdio path, and the default scope is the mitigation the project offers.

Where it is the wrong tool

The costs are real and mostly structural. Puppetmaster sits on top of agent CLIs, so its failure modes include theirs: a worker that hangs or exits badly is a subprocess problem the supervisor has to contain, and the README does not describe a timeout policy for workers in the material available here. The routing layer assumes your adapters are installed and authenticated on the same host; the README notes that when Cursor is not installed, implement, prewalk and swarm fall back to keys-only `agentic` workers, which is a capability reduction, not a substitute. There is no homepage listed, and the project ships releases several times a day (v1.27.6, v1.27.7, v1.27.8 all on 2026-09-10), which suggests a fast-moving interface. If you need a frozen API or a long support window, that cadence is a liability. And if your work is one-off questions rather than multi-step jobs you want to resume, the SQLite job store and lease machinery buy you nothing you would miss.

How it compares to a hand-rolled subprocess runner

The obvious alternative is a shell script or a small Python runner that shells out to `claude` or `codex` and writes JSON to a file. That approach gives you total control and no dependency. The difference in approach is what Puppetmaster adds on top: a model router with role bindings (`puppetmaster platform reviewer codex`), leases so two pilots do not grab the same worker, typed artifacts in SQLite rather than ad hoc JSON, and MCP tool handlers so a chat client can start and poll jobs by ID. The README's quickstart shows the polling discipline it expects: "Poll status/logs by job id. Do not edit until you summarize findings and ask for approval." A hand-rolled runner can replicate the storage but not the MCP integration or the shared registry across pilots. If you only ever drive one CLI from one terminal, the script wins on simplicity. The moment a second client needs to see the same job, the script becomes the thing you rewrite.

Evidence, licences and what to verify before you commit

The README reports two measured results. On SWE-bench Lite it claims 29% lower actual spend with cost routing and durable retries, and 47 to 48% token-matched savings, while stating plainly that this is a single-seed study and does not establish quality parity. On NL2Repo-Bench it reports a 91.1% mean pass rate against a published baseline of roughly 40%. Both link to external methodology pages. I have not run either benchmark, and the README's own caveat on the first one is the honest framing: cost savings are not quality parity. The licence is MIT, which permits commercial use and modification; the README does not discuss what obligations, if any, attach to redistributing the bundled MCP setup scripts, and nothing here should be read as legal advice. On maintenance cost, the release cadence is the signal. Three patch releases in one day implies you should pin a version in any CI that depends on the CLI surface, and re-read `docs/CLI_REFERENCE.md` before upgrading. The `puppetmaster setup --verify-first-run codex/<model>` check is opt-in, makes one live call in temporary state, and returns nonzero if it cannot prove delivery within 120 seconds. That is the cheapest way to confirm your chosen route actually works before you build on it.

Editorial conclusion

Adopt Puppetmaster if you already run Cursor, Claude Code, Codex or similar CLIs and want job IDs, leases and a SQLite artifact store instead of chat scrollback. Skip it if you need a hosted control plane, a stable API surface, or you cannot run a TLS tunnel for off-box MCP clients. Before committing, verify two things on your own machine: that `puppetmaster setup --verify-first-run codex/<model>` returns zero for the exact registry ID you intend to use, and that `puppetmaster doctor` reports no missing adapters for your platform list.

Official sources

1. Issues
2. License: MIT
3. professorpalmer/Puppetmaster on GitHub
4. README
5. Releases