/puppetmaster

name: puppetmaster
description: "Operate and supervise Puppetmaster through MCP or CLI. Use for non-trivial edits, implementations, audits, reviews, broad investigations, CodeGraph lookups, routing decisions, long-running start_* jobs, MCP disconnects, stuck/empty/degraded jobs, and any request to monitor or recover Puppetmaster work."
license: MIT
compatibility: "Puppetmaster MCP tools or the puppetmaster-ai Python CLI on Windows, macOS, or Linux."
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. Grok Bot contained path is agentic (keys-only), not Cursor SDK. | | **One focused read-only review** | `start_review` | Resolves explicit adapter/platform → configured default reviewer → actionable fail-closed error. Cursor tools remain Cursor-only. | | **Broad read-only analysis** (audit, "find all X") | `start_swarm` / `start_cursor_swarm` | Parallel roles over read-only analysis; use the Cursor-specific verb only when Cursor is an explicit choice. | | **Live-site browser QA** (drive a real browser, capture real network payloads) | `start_browser_swarm` | N parallel browser workers with React-input/network-truth/strong-model guardrails. Hermes preferred; `adapter=agentic` uses stdlib CDP / OpenRouter. 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.

Head-seat recipe (Chief / Marionette)

Chief and Marionette consume **artifacts / refs / show / effort-index**. Never read worker transcripts.

• **Size** with `route_task` / `auto_route` / `start_prewalk`.
• **Spawn** a disposable Puppetmaster job (swarm roles optional). Persist

artifacts, then die. No long-lived role bots.

• **Recall** with `effort_index` (omit `effort_id` for the latest tagged

effort; `type` + `query` filter claim/check/decision). Use `artifacts` + `refs=true` for one job. `show` for the stitch. Expand a payload only when needed.

• **Quality (optional):** one-shot `gate` on the worker worktree. Reuse

Puppetmaster gate; do not invent a fake PC.

`rollup` remains the jobs/cost/tokens ledger. `effort_index` is queryable memory on top.

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` enabl