Puppetmaster
essentialDurable-state agent orchestration that a vanilla Claude cannot replicate — cost routing, subprocess workers, typed artifacts, and zero-token reads, all
What it is
A provider-neutral control plane that runs agent CLIs (Cursor, Claude Code, OpenAI, Codex, Hermes) or its own built-in agentic loop as subprocess workers, with a SQLite-backed durable state store for typed artifacts, leases, and memory. Includes a cost-aware model router that selects the cheapest sufficient model per task, automatic provider fallback, and an MCP server that exposes orchestration tools to the host agent.
How it differs from vanilla Claude
A vanilla Claude (Claude Code or MCP client) can spawn subagents via tool calls, but has no durable cross-task state, no typed artifact persistence, no cost-aware routing across providers, no subprocess isolation with lease-based task dispatch, and no zero-token follow-up reads. Claude's subagent output lives in the chat transcript — it evaporates on session end, costs tokens to reread, and cannot be structurally queried. Puppetmaster stores every worker's output as a typed SQLite artifact that follow-up tasks read for free.
Skill, plugin, or workflow shift?
MCP — the primary integration point is via MCP tools (`puppetmaster_*`) that the host agent invokes to start swarms, poll status, read artifacts, and route tasks. The setup command also installs auto-invocation hooks and rule files that nudge the host agent to delegate work to Puppetmaster. It's a plugin that changes how the agent works, not just what it can call.
Devil's advocate — is this just complexity?
A capable agent (Claude Code with the right system prompt) can already decompose work, run parallel tool calls, and store intermediate results in files or a simple SQLite database without Puppetmaster. The artifact schema, the leaser, and the stitcher are all logic you could write in a few hundred lines of Python plus a bash loop that fans out to `claude --print`. The 'zero-token reads' claim conflates storage cost with thinking cost — reading SQLite is free in absolute terms but the LLM still pays inference cost to interpret the data. The MCP server adds a moving part; the auto-invocation hooks feel like magic that could break silently. For most single-repo tasks, a vanilla agent with a disciplined file-output convention will achieve 80% of the value at zero dependency overhead.
What would make it better
Ship a zero-install Docker image with all adapters preconfigured for CI use. Add a 'lite mode' that skips the MCP server and dashboard for single-threaded use. Provide explicit cost breakdown per task in the CLI output (not just a summary). Reduce the mental model: 'swarm', 'lease', 'stitcher', 'artifact board' is a lot of concepts — a single `puppetmaster run <prompt>` that hides everything would lower friction. Integrate with common observability backends (OpenTelemetry, Datadog) for production deployments.
The honest case for it
Puppetmaster solves a genuine gap: vanilla LLM agents have no durable, queryable, cross-session state. If you regularly run multi-step investigations, CI-bound agent tasks, or cost-sensitive pipeline work, the combination of subprocess isolation, typed artifacts, and provider-aware router delivers capabilities that no single agent can reproduce unaided. The independent benchmark result (2.28x state-of-the-art on NL2Repo-Bench) is an objective signal that the architecture pattern is not just complexity theater — it produces measurably better outcomes for complex tasks.
Who it's for
Audience fit
Depth and leverage for a technical engineer who wants to understand it and level up their workflow — not just offload work.
Value for someone who wants a more capable tool without the technical depth — accessible, does-it-for-you.
Engineers building multi-agent pipelines or CI-bound AI workflows get concrete leverage — cost routing, durable artifacts, zero-token follow-ups, provider fallback. Vibe coders in a single IDE chat window will see complexity overhead with little marginal gain for casual tasks.