Puppetmaster: How to Route Coding Agents by Cost

If you already pay for several coding-agent CLIs, you eventually want research, planning, and implementation to run in parallel.

📑Table of Contents

1. Summary table: Puppetmaster at a glance
2. What Puppetmaster is: a supervisor layer on top of CLIs
3. Setup checklist: from install to route dry-run
4. Adapters and cost-aware routing
5. Comparison vs LangGraph, CrewAI, and native subagents
6. Fit, anti-fit, and operational caveats
7. FAQ
8. Conclusion and next actions

Hanging researcher/architect/implementer roles off one parent chat often collapses under:

• context bloat
• quota exhaustion
• expensive regeneration after failures

What Puppetmaster is

Puppetmaster is a provider-neutral open-source control plane (MIT). It turns the CLIs you already use—Cursor, Claude Code, Codex, Hermes—or keys-only agentic adapters into workers. A supervisor then routes tasks in a cost-aware way.

Results land as typed SQLite artifacts, and the project claims zero-token follow-up after stitching.

Sources this guide cross-checks

This guide cross-checks official and third-party sources:

• Official: README, PyPI package page, COMPARISON / ADAPTERS / SECURITY / MODEL_ROUTING
• Third-party: LibHunt, Libraries.io, Medium Agent Native, pepy, Snyk

The headline version in this article is research-time official daily-driver beta v1.21.10 on PyPI as puppetmaster-ai (around 2026-08-03). Mentions of 1.21.8 elsewhere are point-in-time third-party snapshots (for example Snyk/piwheels displays), not a different primary subject version.

Learning outcomes

---

Summary table: Puppetmaster at a glance

Core snapshot

Lens	Takeaway
What it is	Provider-neutral control plane that supervises existing CLI / keys-only workers (MIT, Python)
What it is not	A “build agents in code” framework like LangGraph or CrewAI
Main workers	cursor / claude-code / codex / hermes / openai / agentic / shell / local
Cost control	models.json + capability scores + balanced / cheap / quality / escalating; decisions persist as ROUTING artifacts
State	Typed SQLite artifacts (payload + evidence + confidence + sha256); claims $0 follow-up after stitch
Setup	pipx install puppetmaster-ai → puppetmaster setup → doctor / route dry-run

Maturity and fit

Lens	Takeaway
Maturity	Daily-driver beta / single-author; PyPI classifier Alpha; not a hosted multi-user product
Good fit	Teams already paying for multiple CLIs who want subscription-aware cost control, auditable routing, and fallback
Poor fit	Custom graph-first workflows, single-IDE native subagents only, or multi-tenant SaaS orchestration

Sources

Sources (as of August 2026):

• GitHub professorpalmer/Puppetmaster
• PyPI puppetmaster-ai
• docs/COMPARISON.md
• Libraries.io
• pepy.tech

---

What Puppetmaster is: a supervisor layer on top of CLIs

Definition and placement

The core claim is architectural. Puppetmaster is not primarily an SDK for authoring new agents. It is an operations layer that supervises CLIs and APIs you already pay for as independent worker processes.

The official tagline is: Provider-neutral control plane for durable-state agent swarms: subprocess workers, leases, artifacts, memory, and deterministic stitching.

Processing flow

The flow is:

1. The supervisor accepts a task
2. The model router picks worker + model by cost and capability
3. An independent worker process runs the job
4. Results are stored as typed SQLite artifacts
5. Stitch builds a structured summary (not one shared chat transcript)

The Gunicorn/Redis metaphor is useful: supervise processes, keep durable shared state, avoid turning every follow-up into another full regeneration.

Package boundaries

Package boundaries matter in install docs:

• PyPI name: puppetmaster-ai
• Import / CLI / repo name: puppetmaster
• Bare name puppetmaster is held by a 2019 abandoned project, hence the alias
• MIT license, Python >= 3.9, extras: otel / hermes / mobile

How to read the reported numbers

README-reported internal numbers are directional, not a guarantee.

• SWE-bench Lite: roughly a three-tenths real-cost drop and nearly half the tokens when cost-aware routing is paired with durable retries—but that run is single-seed and does not claim equal quality
• NL2Repo-Bench: 91.1% mean pass rate, about double a public ~40% baseline
• Medium Agent Native: frames durable-state swarms as an answer to parent-chat role sprawl and cites an approximate 46% token-cost reduction framing

Validate every percentage with your own dry-runs.

Third-party placement

Third-party catalogs place the project as follows:

• LibHunt: catalogs it among agent-swarm peers such as shipfast, forgekit, and stato
• Libraries.io: indexes puppetmaster-ai as a Gunicorn-style swarm control package
• pepy.tech: roughly 74k all-time and 33k last-30-day downloads (CI traffic included)—distribution telemetry rather than quality proof

Source

---

Setup checklist: from install to route dry-run

Do not start with a giant multi-provider fan-out. Prove the loop first.

Prerequisites

• Python >= 3.9
• Target CLIs working locally (Cursor / Claude Code / Codex / Hermes) and/or API keys for agentic
• Implement jobs refuse dirty worktrees by default—use a clean tree, a worktree, or payload.allow_dirty=true

Shortest official path

1. pipx install puppetmaster-ai (or pip)
2. puppetmaster setup (idempotent MCP/hooks/rules; optional --platforms cursor, etc.)
3. puppetmaster doctor
4. puppetmaster models init
5. puppetmaster route "task summary" dry-run (who, which model, estimated cost)
6. Run a review/plan job → inspect stitch → prefer a worktree for implement

Audit helpers, failure modes, uninstall

Audit helpers

Audit helpers include puppetmaster cost and puppetmaster audit (dry-run by default; --apply mutates scores). In v1.21.10, unresolved auto-routing fails fast before task creation.

Common failure modes

Common failure modes:

• Unauthenticated CLI / billing_or_quota (claude-code failure classes)
• Implement refused on a dirty worktree
• Empty models.json → router.registry_empty no-op fallback
• Hermes does not trust exit codes (uses git diff / stdout); browser swarms require Hermes

Uninstall and next action

Uninstall with puppetmaster uninstall plus pipx uninstall; --purge-state can remove ~/.puppetmaster/ and related state.

Next action for this section: setup → doctor → one route dry-run → one cheap analyze/review job → inspect artifacts/stitch.

---

Adapters and cost-aware routing

Common I/O and built-in adapters

Every adapter takes Task / goal / worker_id and returns structured artifacts. Built-ins from official ADAPTERS:

CLI / IDE adapters

Adapter	Role	Notes
cursor	@cursor/sdk one-shot	Needs Node/npm/CURSOR_API_KEY
claude-code	Non-interactive Claude Code CLI; default permission_mode=acceptEdits	Failures: not_authenticated / billing_or_quota / dirty_worktree
codex	codex exec --json	Rich telemetry; sandbox workspace-write / approval never / ephemeral
hermes	Headless hermes chat with process-group isolation	Only browser-capable adapter; exit code untrusted

Keys-only and helper adapters

Adapter	Role	Notes
local	Deterministic demo/contract artifacts	Not the production workhorse
shell	Bounded shell + verification	Good for constrained checks
openai	Direct Chat Completions	Captures tokens_in/out/total
agentic	Keys-only standalone worker	No external CLI (OPENAI/ANTHROPIC/GEMINI/OPENROUTER/Bedrock, etc.)

Patch artifacts

Edit-capable adapters record patch artifacts (unified diff, base SHA, revert guidance) when tracked files change.

MODEL_ROUTING pillars

MODEL_ROUTING rests on three pillars:

1. User-owned models.json registry
2. Transparent capability classifier (0..100)
3. Policies: balanced / cheap / quality / escalating

Every routing decision is persisted as a ROUTING artifact with picked/rejected reasons and estimated cost—so you can audit later.

Auto-route boundaries:

• In scope: swarm MCP / python -m puppetmaster run built-in workers
• Out of scope: IDE main-chat model picker (not hijacked)

SECURITY posture

SECURITY docs describe a local supervisor.

Absent by design

• Puppetmaster cloud
• phone-home
• default analytics

What it can do

• spawn workers
• read/write the cwd
• run shell
• classify local auth state without copying/sending secrets
• write per-project SQLite state

Guardrails

• dirty-tree refusal
• review/plan → approve → implement
• dangerously-bypass only as an external-sandbox opt-in

Constraints

• no independent security audit
• maturity is daily-driver beta / single-author

---

Comparison vs LangGraph, CrewAI, and native subagents

The useful question is layer fit, not feature-count theater.

Layer comparison: control plane vs frameworks

Option	Essence	Multi-vendor	Cost routing	Stay inside subscriptions	Durable artifacts	Auto-fallback	Setup	Maturity
Puppetmaster	Supervisor over existing CLIs	Strong	Per-task, auditable	Plan-first emphasis	Typed SQLite	Claimed	pipx + setup	Beta / single-author
LangGraph	Code your control flow	Depends on you	Build it	Build it	Build/external	Build it	Graph design is the product	High
CrewAI	Role-based rapid prototype	Medium	Limited	Limited	Framework-dependent	Framework-dependent	Low–medium	High

Anthropic stack and IDE-native options

Option	Essence	Multi-vendor	Cost routing	Stay inside subscriptions	Durable artifacts	Auto-fallback	Setup	Maturity
Claude Agent SDK / Code subagents	Anthropic-centered execution	Weak	In-provider	Easy inside one sub	Session-dependent	Provider-dependent	Low	High
IDE native subagent only	One-off IDE tasks	Weak	Manual	Inside that IDE bill	Often weak	Manual	Lowest	Product-dependent

Comparison sources

Sources: docs/COMPARISON.md, GitHub README, LibHunt (as of August 2026).

When not to pick it / when to pick it

Official “don’t pick Puppetmaster” guidance maps cleanly:

• Custom control flow in code → LangGraph
• Role-based fast prototype → CrewAI
• Anthropic-only stack → Claude Agent SDK / Code subagents
• One-off IDE tasks → native subagent

Pick it when you already pay for multiple CLIs and want:

• subscription-aware cost optimization
• auditable routing
• failure fallback
• free follow-up against completed job artifacts

Decision questions

1. Do you already pay for two or more coding-agent CLIs?
2. Do you need to audit cost and model choice after the fact?
3. Do you want results as an artifact DB rather than chat residue?
4. Can you accept beta / single-author risk?

Related reading

Related reading on this site:

• wmux multi-CLI workspace multiplexing
• Better Harness loop scoring
• Agent Teams role design
• Keystroke agent automation

---

Fit, anti-fit, and operational caveats

Good fit

• Multi-provider research fan-out
• Task-level “cheap enough” routing with escalate-on-need
• Repeated follow-up on finished work without regenerating tokens
• Using Hermes browser capability for only part of a swarm

Poor fit / caution

• Hosted multi-tenant orchestrator needs (explicitly out of scope)
• Mature framework ecosystem and long-term support as top priority
• Org gates that allow only independently audited components
• Sloppy implement jobs on dirty trees

Third-party health and maturity

Third-party health snapshots (point-in-time):

• Snyk: package health 72/100 with no known direct vulns on the displayed 1.21.8 line
• pepy: ~33k downloads in 30 days (possibly CI-heavy)

Official COMPARISON is candid that the project is young, single-author, and daily-driver beta—existing frameworks win on maturity.

Security reminder

Security reminder:

• even if Puppetmaster does not exfiltrate secrets by design, worker CLIs still touch shell and LLMs
• evaluate it under the same threat model as your current coding agents

---

FAQ

Q1. Is Puppetmaster a LangGraph replacement?

No—different layer. LangGraph is a library for coding control flow. Puppetmaster is a control plane for supervising already-paid CLIs. If the product is your custom graph, stay with LangGraph. If the product is multi-CLI operational supervision, evaluate Puppetmaster.

Q2. Which CLIs are required? All of them?

None of “all.” Wire only the adapters you use. If you do not want more CLIs, use keys-only agentic. Browser swarms specifically depend on Hermes.

Q3. Will costs actually drop?

README figures on SWE-bench Lite point to:

• about a three-tenths real-cost cut
• nearly half the tokens in the authors’ internal run
• no quality-parity claim

Medium’s third-party piece uses a ~46% framing. In practice, run route dry-run and cost in your environment before trusting any headline percentage.

Q4. Can we put this in production services?

Official positioning is supervised local engineering / daily-driver beta, not hosted multi-user. PyPI still classifies Alpha. Start with local trials and an explicit threat model.

Q5. What is the first successful path?

setup → doctor → models init → route dry-run → one cheap analyze/review job → inspect artifacts/stitch → implement in a worktree if needed. Avoid large fan-out on day one.

Q6. Hermes, Cursor, or Claude Code first?

Start with your daily driver. Need browser? Hermes. Want to leverage IDE spend? cursor or claude-code. Clear auth and dirty-tree issues with doctor first.

---

Conclusion and next actions

Takeaway

Puppetmaster is not “yet another agent SDK.” It is a control plane for supervising CLIs you already pay for, with cost-aware routing and durable typed artifacts as the main bet. This article’s subject version is research-time daily-driver beta v1.21.10.

Why try it / why trial carefully

Reasons to try it:

• multi-vendor fan-out
• auditable routing
• artifact follow-up
• fallback

Reasons to trial carefully:

• beta maturity
• single-author risk

Checklist for today

1. List the CLIs you already pay for and pick 1–2 adapters to supervise first
2. Run pipx install puppetmaster-ai and puppetmaster setup --platforms <adapter>
3. Confirm environment and estimates with puppetmaster doctor and puppetmaster route "..." dry-run
4. Run one cheap review/plan job and inspect SQLite artifacts + stitch output
5. Use the comparison table to decide whether your bottleneck is control-flow coding or operational supervision
6. Pre-commit skip conditions: multi-tenant required, unaudited components forbidden, single IDE is enough, or beta is unacceptable

Primary sources

Start from these primary sources before scaling fan-out:

• GitHub repository
• PyPI puppetmaster-ai
• COMPARISON
• ADAPTERS