/puppetmaster

name: puppetmaster
description: "Operate Puppetmaster multi-agent orchestrator via MCP verbs (edit, swarm, implement, route, monitor)."
version: 1.2.0
author: professorpalmer
license: MIT
platforms: [linux, macos, windows]
metadata:
  hermes:
    tags: [orchestrator, multi-agent, swarm, mcp, routing, codegraph]
    category: autonomous-ai-agents
    related_skills: [codex, claude-code, opencode]

Puppetmaster

Multi-agent orchestrator that runs adapter workers (Cursor SDK / Claude Code / Codex / Hermes) as durable, SQLite-backed subprocesses with leases, structured JSON artifacts, per-task model routing, and isolated git worktrees. Published on PyPI as `puppetmaster-ai`; the **CLI mirrors every MCP verb**.

Prefer Puppetmaster verbs over a solo grep/read loop or the built-in delegation for: single focused edits that benefit from CodeGraph or cheap-model routing, broad investigation, multi-file audits, and cross-cutting changes.

Surfaces (two, in priority order)

1. **MCP tools** — names are prefixed `mcp_puppetmaster_puppetmaster_*`. Use `tool_search` to find a verb, `tool_describe` to load its schema, `tool_call` to invoke. This is the primary path. 2. **CLI fallback** (`python -m puppetmaster ...`) when MCP isn't connected. The MCP server shells out to its own resolved interpreter, so MCP can work even when `python -m puppetmaster` fails in the *current* venv.

Match the verb to the task shape

| Task shape | Verb | Why | |---|---|---| | **One focused edit** ("fix this fn", "add a flag", "wire up retries") | `edit` | Cheapest sufficient model + CodeGraph + in-place edit + synchronous diff. The snappy path between editing inline and a full implement job. | | **One coupled multi-file feature** | `start_implement` | Isolated clean worktree, one coherent PATCH artifact. | | **Broad read-only analysis** (audit, review, "find all X") | `start_swarm` / `start_cursor_swarm` | Parallel roles over read-only analysis. | | **Live-site browser QA** (drive a real browser, capture real network payloads) | `start_browser_swarm` | N parallel Hermes browser workers with React-input/network-truth/strong-model guardrails. Hermes-only; ACTING AGENT (side effects). | | **"Where is X / what calls Y"** | `codegraph_search` | Structural lookup before reading files. | | **"What model / how much?"** | `route_task` | Pure decision, no spend. |

• **Trivial edits stay inline** (typo, rename, one-line comment) — don't pay the

worker round-trip.

• **A single coupled feature is NOT a swarm.** Fanning out one tightly-coupled

change makes parallel workers stack uncoordinated commits. Use one worker.

• **Label every job.** Pass a short `label` (3–6 words) to any `start_*` / `edit`

verb so the dashboard and `jobs` list stay scannable instead of showing bare `job_<hash>` ids. Omitted labels fall back to a title derived from the goal.

The `edit` verb (lightweight single in-place edit)

`puppetmaster_edit "<instruction>"` — the daily-driver verb for one focused change:

• **Cheapest sufficient model** by default (`routing_policy=cheap`); pin with

`model` to override routing.

• **CodeGraph** locates the edit site instead of grepping.
• **Edits the working tree in place** (`allow_dirty`) — no isolated worktree.
• **Synchronous** — returns the diff immediately, no `job_id` to poll.
• Still captures a reviewable **PATCH artifact**; the `require_diff` gate fails a

no-op edit closed, so a "done" edit that changed nothing can't pass.

Use `start_implement` instead when the change is coupled/multi-file and wants an isolated worktree.

CodeGraph (the exploration layer — use BEFORE reading files)

For any "where is X / what calls Y / what implements Z" question, query CodeGraph first, then read only the files it points to. Verbs: `codegraph_search`, `codegraph_context`, `codegraph_affected`, `codegraph_files`, `codegraph_status`, `codegraph_init`.

• **ALWAYS pass `cwd=<workspace>` explicitly.** The codegraph tools default cwd to

`$HOME`, not the repo — without it, `codegraph_status` reports "Not initialized" even for a healthy index.

• If `.codegraph/` doesn't exist, run `codegraph_init` once first.
• **Lookups always delegate, never grep.** A structural "where is X / who calls Y /

what implements Z / find all / trace" query is cheap and strictly beats an inline grep, so the invocation gate routes it to CodeGraph regardless of score. Don't fall back to ripgrep for a symbol/usage/impl question — reach for `codegraph_search`. (Plain text matches — log strings, config values — may still use ripgrep.)

Routing

• `auto_route: true` enables per-task model routing (default true when no `model`

is pinned).

• `routing_policy`: `balanced` (cheapest sufficient — default), `cheap`,

`quality`, `escalating`. Optional caps: `max_cost_usd`, `min_capability`.

• Registry lives at `~/.puppetmaster/models.json` (`puppetmaster models init`

seeds it). `route_task` dry-runs a decision and shows rejected alternatives.

• **Platform lock** (`~/.puppetmaster/platform.json`, a denylist) restricts which

adapters the router may pick. Lock rejections mid-migration are expected, not failures.

Output style (optional "Signal-maximizer")

Workers can be told to write tighter. Off by default. Shapes *form*, not reasoning, so it never lowers answer quality — the win is readability and latency, with a small cost bonus on output-heavy roles (output tokens are a minority of an agentic bill).

• Enable globally: `PUPPETMASTER_OUTPUT_STYLE=terse` (or `lithic`).
• Enable per task: `payload.output_style = "terse" | "lithic" | "off"`. An

explicit payload value wins over the env; `"off"` opts one spec out.

• `terse` — drop ceremony, filler, hedging, restatement; one claim per line;

state uncertainty as fact (`unconfirmed: X`). Safe; recommended tier.

• `lithic` — `terse` plus telegraphic glue-dropping (articles/copulas). Marginal

extra savings, mild quality risk; best for machine-consumed artifa