Plumb CLI
Git hooks and a Claude Code skill collect decisions from commits and agent transcripts and fold them back into spec and tests.
- 148 ★ on the repository
- Last commit
Extended access
Why this level
- Diffs and agent transcripts go to the selected model provider.
- Git hooks change commit behavior and can stop commits.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/plumbDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Diffs and agent transcripts go to the selected model provider.
- Git hooks change commit behavior and can stop commits.
This is third-party code. Review the repository files before installing.
What it does
Plumb is a Python CLI that keeps spec, tests and code from drifting apart during AI-assisted development. It reads staged git changes and agent transcripts, finds decisions that were made, such as a cache choice or an API contract change, and writes them to an append-only log. It has two modes. Review mode stops a commit until you approve, reject or ignore each decision. Record mode lets the commit land and a background worker extracts the decisions. The `plumb sync` command folds approved decisions into the spec and tests.
Who it is for. Developers who commit alongside Claude Code or Codex and see the spec lag behind the code while decisions stay in chat.
Good fit when
- An agent commits often and the spec stops matching the code.
- A risky choice calls for a look at earlier recorded decisions through `plumb search`.
- A team wants to review every decision before a commit in review mode.
- Tests cover behavior that no longer matches what was agreed.
Not a fit when
- A project with no written spec and no tests.
- Diffs and agent transcripts cannot go to an external model provider.
- You need a mature product, since the author calls Plumb early alpha.
Example request
Install Plumb, run `plumb init`, choose record mode and after the next series of commits show the decision log through `plumb log`.Limitations
The author presents the tool as a proof of concept in early alpha. Analysis defaults to Anthropic Haiku and needs `ANTHROPIC_API_KEY`; another provider is set with `plumb model`. Diffs and transcripts go to the chosen provider. The pre-commit and post-commit hooks change the normal commit flow. The `.plumb/` state is meant to be committed with the code. The quality of found decisions depends on the chosen model and on how well the agent explained its choice in the transcript.
How to disable. Remove the git hooks, the Plumb block in `CLAUDE.md` and `AGENTS.md`, the `.claude/skills/plumb` skill and the `.plumb/` directory, then uninstall `plumb-dev`.
FAQ
How do review and record modes differ?
Review mode stops the commit until each decision is resolved. Record mode never blocks a commit, and a background worker extracts decisions afterwards.
What does `plumb init` create?
A `.plumb/` state directory, pre-commit and post-commit hooks, a block in `CLAUDE.md` and `AGENTS.md`, a Claude Code skill and a `.plumbignore` file.
Which model does it use?
Anthropic Haiku by default with `ANTHROPIC_API_KEY`. Pick another provider with `plumb model` and supply its key.
Which agents does it work with?
The README names Claude Code, Codex, Pi and Copilot CLI. The bundled skill is written for Claude Code.
How do I stop commits being blocked?
Switch with `plumb mode record` so commits are never blocked. Agents can force a mode for one run through the `PLUMB_MODE` variable.
Discussion
No questions or reviews yet.
Related
CLI toolsA plugin for Claude Code: you read one spec and parallel agents ship it to a commit with green tests.
A CLI that keeps the spec, tasks and proof of done in git so Claude, Codex, Grok and Cursor can hand work to each other
A Claude Code skill that drives a hard task through explore, plan, execute and reflect, writing every decision to disk.
A plugin with three skills for large development work: project analysis, phased tasks tracked as GitHub Issues, parallel agents and code review
A Claude Code plugin for development with separated roles: spec, review, TDD, QA and verification by different agents
Methods for an agent in one CLI: comparing options, solving problems and changing code in steps, 20 slash commands in all.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| Plumb (this card) | no | 148 | |
| OpenSpec | no | 74,784 | drives work from proposal and requirements to code; Plumb gathers decisions from commits already made and writes them back into the spec |
| Autospec | no | 148 | drives spec-based development from description to implementation; Plumb watches spec and code drift after commits |
README in short
Plumb illustrates a triangle of spec, tests and code. Decisions are extracted from diffs and transcripts, and the decision log lives in the repository.