PlumbBob is first and foremost a Claude Code plugin — twelve /pb-* skills you fire from your IDE to run LLM-assisted coding as a loop you control. The easiest way to get it is the robmclarty/agent-tools marketplace; a small CLI rides underneath for power users and other hosts.
You drive the loop inside Claude Code, in a git repo. Under the hood the bundled CLI runs on Node ≥ 22.18 (node builtins plus one deliberate dependency, checkride) — the marketplace plugin brings it along, so there's nothing else to set up.
The marketplace plugin is the primary path, and the one to reach for. The npm install is for power users, scripting, or hosts other than Claude Code. Pick one — both register a Claude Code plugin named plumbbob, so running both collides.
Claude Code installs the published package for you — skills, hook, and the CLI on PATH — so you run no npm i -g and no init. This is the whole install.
For scripting, non-Claude-Code hosts, or driving the mechanical verbs directly. Installs the CLI (also a pb shorthand), then links the skills and hook into Claude Code in place.
Restart Claude Code (or /reload-plugins) to activate, then run plumbbob doctor (or /pb-doctor in-session) to confirm the wiring.
Inside any git repo with a clean tree, four moves take a goal end to end.
Everything the model must stay true to lives in one file — intent.md, written before any code: the Frame, the Decisions and Constraints (each with its because), and the Steps — each carrying a done-when (a checkable finish line) and a seam (the files it's expected to touch).
/pb-build carries a step straight through the verify tick and stops:
Nothing is locked and nothing refuses you — the loop does a step's labor, pulls up to the line, and waits for you to advance it. You are the clock. Approving commits the step as a checkpoint against a recorded baseline; a wrong turn costs one step, not the afternoon. --auto lets the agent self-approve and chain step after step until the plan is done — halting the moment a check goes red or the self-review finds a mismatch. A range like 1-3 is a bounded auto.
/pb-build is the default engine, not the only one — the loop doesn't care who writes the code. Implement a step by hand, vibe it in another session, or use another harness entirely, then run /pb-verify instead: same check, same pause, same checkpoint. It reads the diff, not the author.
A mid-build "ooh, what if…" never derails the step. /pb-park captures it to a list in one line; /pb-harvest triages the list at the next boundary — proposing exactly one class per item: blocker (the plan was wrong; fold in now), tangent (defer or kill — the default), or pivot signal (the approach is wrong; stop and replan). You call each one.
The full reference for all twelve skills — inputs, effects, when to reach for each — is on the API page, alongside the CLI verbs they shell out to.
PlumbBob's executor is author-blind: the tick reads the diff, not who wrote it. So you can plug your own agent in. A user-authored agent is anything executable that speaks one small JSON envelope — there's no SDK to import and no language to adopt. A twelve-line bash script is a complete agent.
Everything is downstream of three rules. When you wonder why the contract refuses something, it's one of these.
Four streams, one shape — a subprocess convention run in production since Terraform's external data source shipped it in 2017. Read stdin to EOF for the StepContext; write one JSON object and nothing else to stdout; narrate freely on stderr (streamed live); exit 0 to make the envelope authoritative.
Drop the agent under .plumbbob/agents/<name>/ (or ~/.plumbbob/agents/ for personal ones), then bind it to a step's lifecycle slot in the build's harness.json: before (context in, at build time), build (authors the diff in your place, still verified the same way), or after (advisory review at the verify pause). /pb-plan authors the bindings at plan time; plumbbob agent list shows what's resolvable. A worked example — a local-model reviewer via Ollama — ships in the repo's docs/local-model-review.md.
A middle ground between long-horizon autonomy and one-step-at-a-time vibing. The reframe is simple: attention is the scarce resource. The model is cheap, fast, and replaceable; your attention is none of those. So you design the process around it, not around the machine's throughput.
The failures look opposite but share a root. Two things destroy attention, and the whole method follows from refusing them: the collision between producing and consuming (you can't form intent and absorb output in the same moment — reading overwrites planning), and premature convergence (when implementation arrives before the decisions, you're committed to a shape you never chose).
The three modes aren't ranked — each is right for a band of work, sorted by how much of it is judgment and how settled that judgment is. Vibe when judgment doesn't matter (throwaway prototypes, spikes you'll delete). Attention-first when judgment is load-bearing and unsettled — most real features, bugs, and refactors you care about. Full autonomy when judgment is settled and the work is large. The poles are the special cases; the middle is where most work that matters lives, which is why attention-first is a default posture rather than a compromise. PlumbBob is the layer below Ridgeline, which runs the settled, large work autonomously.
A system prompt can ask a model to plan first and stop for review. What it can't do is hold the line when the model doesn't. PlumbBob splits that problem across two planes — and is honest about which half is enforceable.
On the work plane the pause is unenforceable, deliberately. A hard lock on every edit buys ritual, not control: a determined model routes around it, and a denial mid-thought leaves no legal move. So PlumbBob guides here rather than fighting — a status dashboard re-injected into every skill keeps the model oriented, and the skills fall into the plan/build/pause rhythm because they were built to. Guidance you fall into, not a lock you fight.
The record is a different plane, and there the tick is latched. checkpoint refuses to land a step until the harness records a human turn since that step began — so the agent cannot self-commit past you. The refusal simply is the pause. It extends the deterministic edges to the one boundary the product is named after, while leaving human what must be human: you, reading the diff.
The latch's payoff is a receipt, not a claim. A headless skill-eval harness sweeps the loop — prose-only baseline vs. the shipped latch, N=5 per contract, every assertion a mechanical read of git state — and commits each receipt to the repo.
And when a raw commit does slip the ledger, status says so and the checkpoint record makes recovery one command. Cheap recovery, not a cage, is the control that matters.
The latch is one of five. The others: a gate that refuses red (checkpoint won't record over a red check gate, start refuses a dirty tree); one SHA per verified step (a ledger of checkpoints, not one diff at the end); a preservation-aware revert (/pb-revert resets to a recorded SHA while keeping your plan and notes, and restores only SHAs the loop wrote); and a build record that rides the PR (the tracked builds/<slug>/ folder merges into main with the branch). Guidance on the work, a latch on the record.