{"id":51421512,"url":"https://github.com/professorpalmer/puppetmaster","last_synced_at":"2026-07-14T23:01:09.794Z","repository":{"id":356148020,"uuid":"1231210975","full_name":"professorpalmer/Puppetmaster","owner":"professorpalmer","description":"Provider-neutral control plane for durable-state agent swarms: subprocess workers, leases, artifacts, memory, and deterministic stitching.","archived":false,"fork":false,"pushed_at":"2026-07-13T15:40:41.000Z","size":6652,"stargazers_count":192,"open_issues_count":0,"forks_count":20,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-07-13T17:14:43.575Z","etag":null,"topics":["agent-swarms","agents","ai-agents","claude-code","codex","cursor","distributed-systems","llm","orchestration","sqlite"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/professorpalmer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/SECURITY.md","support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-06T18:35:01.000Z","updated_at":"2026-07-13T15:37:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/professorpalmer/Puppetmaster","commit_stats":null,"previous_names":["professorpalmer/puppetmaster"],"tags_count":145,"template":false,"template_full_name":null,"purl":"pkg:github/professorpalmer/Puppetmaster","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/professorpalmer%2FPuppetmaster","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/professorpalmer%2FPuppetmaster/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/professorpalmer%2FPuppetmaster/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/professorpalmer%2FPuppetmaster/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/professorpalmer","download_url":"https://codeload.github.com/professorpalmer/Puppetmaster/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/professorpalmer%2FPuppetmaster/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35482263,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-14T02:00:06.603Z","response_time":114,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-swarms","agents","ai-agents","claude-code","codex","cursor","distributed-systems","llm","orchestration","sqlite"],"created_at":"2026-07-05T00:02:40.415Z","updated_at":"2026-07-14T23:01:09.787Z","avatar_url":"https://github.com/professorpalmer.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Puppetmaster\n\n[![PyPI](https://img.shields.io/pypi/v/puppetmaster-ai.svg)](https://pypi.org/project/puppetmaster-ai/)\n[![CI](https://github.com/professorpalmer/Puppetmaster/actions/workflows/ci.yml/badge.svg)](https://github.com/professorpalmer/Puppetmaster/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/professorpalmer/Puppetmaster/blob/main/LICENSE)\n[![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://github.com/professorpalmer/Puppetmaster/blob/main/pyproject.toml)\n\nPuppetmaster turns the agent CLIs you already pay for — Cursor, Claude Code (Anthropic or AWS Bedrock), the OpenAI API, the Codex CLI, or Hermes — into an orchestrator. Or run it with no external CLI at all: point the built-in `agentic` adapter at any provider API key (OpenAI, Anthropic, Gemini, OpenRouter, **AWS Bedrock** IAM/BYOK) and it runs the whole tool-use loop itself — ideal for CI, containers, and headless servers. Bedrock uses the Converse API (and ConverseStream for live text/reasoning/tool deltas) with live account model discovery and the same prompt-cache / token / cost metering as other providers. Either way it routes each task to the cheapest model that can handle it, runs workers as independent processes, and stores their output as typed SQLite artifacts, so follow-up reads cost zero tokens.\n\n\u003cimg src=\"https://raw.githubusercontent.com/professorpalmer/Puppetmaster/main/docs/demo.gif\" alt=\"Puppetmaster 60-second demo: cost routing, swarm fan-out, stitched summary, and zero-token follow-ups\" width=\"100%\" /\u003e\n\n## Contents\n\n- [Install](https://github.com/professorpalmer/Puppetmaster#install) and [Uninstall](https://github.com/professorpalmer/Puppetmaster#uninstall)\n- [What it does](https://github.com/professorpalmer/Puppetmaster#what-it-does) — the object model, and how it differs from agent frameworks\n- [Why it's credible](https://github.com/professorpalmer/Puppetmaster#why-its-credible) — four claims, four reproducible receipts\n- [Quickstart](https://github.com/professorpalmer/Puppetmaster#quickstart) — prompts and shell recipes\n- [Recommended setup](https://github.com/professorpalmer/Puppetmaster#recommended-setup) — a cheap chat model that delegates the real work\n- [Auto-invocation](https://github.com/professorpalmer/Puppetmaster#auto-invocation) — how delegation fires without reminding the agent\n- [Output style and compression](https://github.com/professorpalmer/Puppetmaster#output-style-and-compression)\n- [Status](https://github.com/professorpalmer/Puppetmaster#status)\n\nDocumentation lives in [`docs/`](https://github.com/professorpalmer/Puppetmaster/blob/main/docs/README.md):\n\n- Design and rationale — [WHY.md](https://github.com/professorpalmer/Puppetmaster/blob/main/docs/WHY.md)\n- How it compares to LangGraph / CrewAI / native subagents — [COMPARISON.md](https://github.com/professorpalmer/Puppetmaster/blob/main/docs/COMPARISON.md)\n- The proof behind the claims — [CLAIMS.md](https://github.com/professorpalmer/Puppetmaster/blob/main/docs/CLAIMS.md)\n- Everything that ships, with the adapter table — [FEATURES.md](https://github.com/professorpalmer/Puppetmaster/blob/main/docs/FEATURES.md)\n- Safety and threat model — [SECURITY.md](https://github.com/professorpalmer/Puppetmaster/blob/main/docs/SECURITY.md)\n- Prompt and shell recipes — [DAILY_DRIVER.md](https://github.com/professorpalmer/Puppetmaster/blob/main/docs/DAILY_DRIVER.md)\n- The live job dashboard — [DASHBOARD.md](https://github.com/professorpalmer/Puppetmaster/blob/main/docs/DASHBOARD.md)\n- Watch swarms from your phone (Tailscale + QR) — [MOBILE.md](https://github.com/professorpalmer/Puppetmaster/blob/main/docs/MOBILE.md)\n- Model routing, architecture, adapters, CodeGraph, CLI — see the [docs index](https://github.com/professorpalmer/Puppetmaster/blob/main/docs/README.md)\n\n## Install\n\n```bash\npipx install puppetmaster-ai     # or: pip install puppetmaster-ai\npuppetmaster setup               # doctor + models init + MCP installers + rules + hooks — idempotent\n```\n\nThat is the whole install. `setup` runs each step idempotently, skips any tool that isn't present, and prints what it did. Restart Cursor (or open a fresh Codex, Claude, or Hermes session) and the agent gains the `puppetmaster_*` MCP tools, a rule nudging it to use them, and [auto-invocation hooks](https://github.com/professorpalmer/Puppetmaster#auto-invocation) that delegate real work. The whole thing is kill-switchable with `PUPPETMASTER_AUTO_INVOKE_DISABLED=1`.\n\nSetup starts with every platform off and asks you to enable at least one execution adapter (`--platforms cursor`, or an interactive pick). A single platform is the expected setup; enabling several is opt-in and unlocks cross-platform router fallback and free-tier hopping. Add more later with `puppetmaster platform enable \u003cname\u003e`. For CI, pass `--platforms \u003ccomma-list\u003e` or `--platforms all`.\n\nHermes has an optional in-depth setup branch (learn flywheel, skill promotion, skill injection); see [ADAPTERS.md](https://github.com/professorpalmer/Puppetmaster/blob/main/docs/ADAPTERS.md#hermes). The `agentic` adapter needs only a provider API key (no external CLI) — see [ADAPTERS.md#agentic](https://github.com/professorpalmer/Puppetmaster/blob/main/docs/ADAPTERS.md#agentic) and [DAILY_DRIVER.md](https://github.com/professorpalmer/Puppetmaster/blob/main/docs/DAILY_DRIVER.md#keys-only-recipe-no-external-cli). To run benchmarks or hack on the code, clone instead — see [CONTRIBUTING.md](https://github.com/professorpalmer/Puppetmaster/blob/main/docs/CONTRIBUTING.md).\n\n## Uninstall\n\n```bash\npuppetmaster uninstall          # MCP registrations, hooks, rules — idempotent\npip uninstall puppetmaster-ai   # or: pipx uninstall puppetmaster-ai\n```\n\n`uninstall` removes only Puppetmaster-owned artifacts (its MCP entries, auto-invocation hooks, and rule files or marked blocks) and leaves other MCP servers untouched. Swarm state under `~/.puppetmaster/` and workspace `.codegraph/` are kept unless you pass `--purge-state`. Use `--dry-run` to preview and `--cwd` to target another workspace.\n\n## What it does\n\nThink of it as Redis or Gunicorn for agentic engineering: a supervisor in front of worker processes, with durable shared state.\n\n```text\nCursor / Claude Code / OpenAI / Codex / Hermes / agentic (keys-only) / shell\n        |\n        v\nPuppetmaster supervisor  -\u003e  task-aware model router (routes by cost)\n        |\n        v\nindependent worker processes  -\u003e  SQLite (typed artifacts, events, memory)\n        |\n        v\nlive artifact board  -\u003e  stitched summary  -\u003e  zero-token follow-up reads\n```\n\nIt isn't meant to beat native IDE subagents at every small task. It's for work that gets messy: long repo investigations, conflicting hypotheses, repeated handoffs, flaky memory, and code changes that need evidence, replay, and approval gates.\n\nLangGraph, CrewAI, and the Claude Agent SDK are libraries you write code against to build an agent. Puppetmaster sits one layer up — it drives the agent CLIs you already pay for, routes each task to the cheapest sufficient model, keeps spend inside your subscription, and self-heals when a provider goes down. The rationale and the side-by-side are in [WHY.md](https://github.com/professorpalmer/Puppetmaster/blob/main/docs/WHY.md) and [COMPARISON.md](https://github.com/professorpalmer/Puppetmaster/blob/main/docs/COMPARISON.md).\n\nYou can see the whole story in one command, with no API keys:\n\n```bash\n./scripts/demo.sh                  # 60-second tour on a clean machine\npython -m puppetmaster dashboard   # live web board for any job (see docs/DASHBOARD.md)\n```\n\n## Why it's credible\n\nEvery number is reproducible from a script in [`bench/`](https://github.com/professorpalmer/Puppetmaster/tree/main/bench/); full method and caveats in [CLAIMS.md](https://github.com/professorpalmer/Puppetmaster/blob/main/docs/CLAIMS.md).\n\n1. Cost is fixed on two axes. New work routes to the cheapest sufficient model (35% cheaper on a fixture; 98.8% cheaper in a live OpenAI A/B). Follow-ups are SQLite reads, not new runs (40 queries, $0.00, 0.5 ms each).\n2. Workers don't share a transcript. They lease tasks and emit typed artifacts (payload, evidence, confidence, sha256); the stitcher reads JSON, not stdout. Inspect with `puppetmaster artifacts \u003cjob_id\u003e`.\n3. CodeGraph context is injected before the model call, so workers look up \"where is X / what calls Y\" structurally instead of grepping, and fall back to grep without it.\n4. A dead provider doesn't kill the swarm. Billing, quota, auth, and missing-CLI failures are marked `FAILED` and rerouted to the next funded adapter, preferring plan-billed models. Validated live and surfaced in the summary's alerts.\n\nBeyond those internal receipts, the durable-state thesis holds up on an **independent third-party benchmark**. On [NL2Repo-Bench](https://professorpalmer.github.io/durable-state-vs-context/) (build a full Python library from a natural-language spec, scored by the benchmark's own pytest suites), durable-state orchestration reaches a **91.1% mean test-pass rate — about 2.28× the ~40% published state of the art** — and solves 53% of libraries to a fully green upstream suite. This is a field/single-vs-swarm comparison with only the agent swapped (not the clean 3-arm control), and packaging-bound failures are kept in the denominator — full method, caveats, and the controlled JS→TS study are in the paper ([site](https://professorpalmer.github.io/durable-state-vs-context/) · [Zenodo/DOI](https://doi.org/10.5281/zenodo.20709565)). The [SWE-bench Lite cost/quality study](https://github.com/professorpalmer/swebench-pm) is a controlled 3-arm study where the CodeGraph-context + router arm lands about **47% cheaper than the frontier baseline at equal quality**.\n\n## Quickstart\n\nInside Cursor Agent or Codex:\n\n```text\nUse Puppetmaster to run doctor in this repo and summarize what is missing.\n```\n\n```text\nUse Puppetmaster to start a cursor swarm for this repo and return the job id immediately.\nProblem: users get logged out after refresh and token-refresh tests are flaky.\nConstraints: keep the patch focused, preserve public API behavior, run relevant tests.\nDo review/plan first. Poll status/logs by job id. Do not edit until you summarize findings and ask for approval.\n```\n\nFrom the shell:\n\n```bash\npuppetmaster doctor\npuppetmaster route \"Security audit every endpoint\" --role audit   # dry-run routing decision\npuppetmaster cursor \"Review this repo for release blockers\" --review --dry-run\npuppetmaster claude \"Implement the approved change and run focused tests\" --permission-mode acceptEdits\npuppetmaster show $(puppetmaster last)\n```\n\nMore recipes — including high/low effort model variants via `puppetmaster models setup` — are in [DAILY_DRIVER.md](https://github.com/professorpalmer/Puppetmaster/blob/main/docs/DAILY_DRIVER.md) and [MODEL_ROUTING.md](https://github.com/professorpalmer/Puppetmaster/blob/main/docs/MODEL_ROUTING.md).\n\n## Recommended setup\n\nThe pattern that works best, and the one `setup` nudges your agent toward, is to keep a cheap conversational model in your IDE chat window and let it hand the technical work to Puppetmaster.\n\n```text\nYou -- chat --\u003e cheap conversational model (fast, low cost)\n                      |\n                      |  \"this is real work\" -\u003e delegate\n                      v\n              Puppetmaster (routes to the cheapest sufficient model,\n              runs durable workers, stores typed artifacts)\n```\n\nConversational asks stay instant and cheap. Real engineering — multi-file investigation, a refactor, a review, an implementation — gets the full machine: cost routing, independent workers, durable artifacts, replay, and zero-token follow-up reads. Context compounds in artifacts and promoted memory that later jobs reuse, instead of in a chat scrollback that evaporates.\n\nDon't try to route every chat message through Puppetmaster to \"capture context.\" Spinning a durable worker for \"hi\" or \"what's this function\" inverts the value: it adds orchestration cost to the cheapest turns, and it fights the IDE, which has no clean intercept-every-message hook. Let the cheap model triage; let Puppetmaster do the work that deserves a job.\n\n## Auto-invocation\n\nThe hard part of that pattern is getting the host agent to actually delegate without reminders. `setup` installs a classifier-gated enforcement layer for it:\n\n- A pure-function gate (`puppetmaster should-delegate \"\u003cprompt\u003e\"`) answers delegate-vs-inline in microseconds with no LLM and no network. Typos, renames, one-liners, and quick questions stay inline; audits, refactors, migrations, and other broad-scope work delegate.\n- Deterministic hooks in Cursor's `.cursor/hooks.json` and Claude Code's `.claude/settings.json` inject a \"delegate now\" directive on prompt submit and redirect genuinely broad shell searches to the Puppetmaster/CodeGraph equivalent. Read-only inspection (git log/show/diff, listing a directory, single-file greps, native Grep/Glob) passes through. Hooks fail open and never wedge a session. Add `--global` to cover every repo.\n- An optional proxy (`puppetmaster proxy`) extends the same gate to OpenAI-compatible clients that closed harnesses can't hook.\n\nThere is no universal deterministic invocation: closed harnesses won't let anything sit on their provider wire. So the system is tiered — soft rules everywhere, hard hooks where the host exposes them, proxy only for clients routed through it — and fully kill-switchable with `PUPPETMASTER_AUTO_INVOKE_DISABLED=1`.\n\n## Output style and compression\n\nWorkers can optionally write tighter prose. `PUPPETMASTER_OUTPUT_STYLE=terse` (or `lithic`, or per-task `payload.output_style`) constrains form, not reasoning, so it trades verbosity for readability and latency without lowering answer quality. See [OUTPUT_STYLE.md](https://github.com/professorpalmer/Puppetmaster/blob/main/docs/OUTPUT_STYLE.md).\n\nPuppetmaster does not bundle input-side context compressors (RTK, Headroom, caveman). We measured them: the net savings are small and the failure modes (a compressor dropping data the agent then re-reads) run the wrong way for a coding agent. [COMPRESSION.md](https://github.com/professorpalmer/Puppetmaster/blob/main/docs/COMPRESSION.md) shows the evidence and how to wire one yourself if you want it.\n\nMarionette (the harness that rides Puppetmaster) implements complementary input-side savings: savings-gated tool-output offload, absolute-token compaction advice, append-only KV-cache context, and live OpenRouter pricing for swarm jobs the local registry does not know. See [Marionette's token economics (README)](https://github.com/professorpalmer/marionette/blob/main/README.md#core-capabilities).\n\n## Status\n\nDaily-driver beta, currently at v1.19.3. Real runtime contract, automated tests, SQLite backend, fail-closed jobs, a live Cursor Agent MCP, validated full-edit adapters, and AWS Bedrock as a first-class agentic provider (Converse + ConverseStream). Credible for supervised local engineering; not yet a hosted multi-user service. Full feature matrix in [FEATURES.md](https://github.com/professorpalmer/Puppetmaster/blob/main/docs/FEATURES.md).\n\n**v1.19.3 highlights:** Bedrock ConverseStream for live agentic chat deltas — real eventstream parsing for text, reasoning, and toolUse chunks via stdlib (no boto3); `bedrock_chat_stream` preferred over fake chunked non-SSE on the streaming path.\n\n**v1.19.1 highlights:** Bedrock Converse multi-model daily driver — account model discovery (`ListFoundationModels` + `ListInferenceProfiles`), Converse prompt-cache stamps, and token/cost parity with other providers (`price_job` cache-read discount, Marionette `cache_savings_usd`).\n\n**v1.19.0 highlights:** AWS Bedrock as a first-class agentic provider (BYOK) — `provider=bedrock` in the provider registry, stdlib-only `bedrock.py` (bearer or SigV4 IAM, no boto3), live model discovery merged into the agentic registry.\n\nPyPI lists the package as [`puppetmaster-ai`](https://pypi.org/project/puppetmaster-ai/); [PEP 503 normalization](https://peps.python.org/pep-0503/#normalized-names) collides `puppetmaster` with an abandoned 2019 package. The import name, CLI, repo, and brand stay `puppetmaster`.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprofessorpalmer%2Fpuppetmaster","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprofessorpalmer%2Fpuppetmaster","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprofessorpalmer%2Fpuppetmaster/lists"}