prove_it
AGENTS.md198 starsChanged 8 months agoMITView on GitHub
prove_it is a config-driven hook framework for Claude Code. It reads .claude/prove_it/config.json from a project directory and runs matching tasks when Claude Code fires lifecycle events (SessionStart, PreToolUse, Stop). It also dispatches git hooks (pre-commit, pre-push). Use ./script/agent to launch Claude Code with the local prove_it on PATH: This prepends test/bin/prove_it (a shim to cli.js) to PATH so all hook dispatchers, libexec scripts, and transitive prove_it calls use the working tree. A local-shim-check runs on SessionStart to confirm the shim…
- Installs packages
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository4 other files it gives its agents.
- prove-featureSkill
- releaseSkill
- session-logSkill
- test-localSkill
The file
We split this AGENTS.md into the rules it gives an agent
7 rules. About 0 are common, 1 is distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 28
Stop: uses top-level decision: "block" or "approve" (different schema from PreToolUse).
- Very specific: line 47
Use ./script/agent to launch Claude Code with the local prove_it on PATH:
- Very specific: line 60
Use the /release skill. It reads RELEASE.md for the full process.
- Very specific: line 80
All config defaults live in lib/defaults.js.
- Very specific: line 93
Never add || <default> when reading from the merged config — add the default to CONFIG_DEFAULTS in lib/defaults.js instead
- Very specific: line 102
No dependencies beyond Node.js stdlib (devDependencies: standard for linting only)
- Distinctive: line 135
All child processes inherit the modified PATH: hook dispatchers, libexec scripts, test scripts, agent reviewers.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
prove_it Development Guide
Architecture
prove_it is a config-driven hook framework for Claude Code. It reads .claude/prove_it/config.json from a project directory and runs matching tasks when Claude Code fires lifecycle events (SessionStart, PreToolUse, Stop). It also dispatches git hooks (pre-commit, pre-push).
Key modules
cli.js—CLI entry point, commands: install, uninstall, init, deinit, doctor, monitor, hook, prefixlib/dispatcher/claude.js—Main dispatcher for Claude Code eventslib/dispatcher/git.js—Dispatcher for git hookslib/dispatcher/protocol.js—Output formatting for Claude Code hook APIlib/checks/script.js—Runs shell commands as taskslib/checks/agent.js—Runs AI agent reviewer taskslib/checks/env.js—Runs env tasks that inject environment variables via CLAUDE_ENV_FILElibexec/guard-config—Standalone script: blocks edits to prove_it config fileslibexec/briefing—Standalone script: renders session orientation on SessionStartlib/defaults.js—Single source of truth for config defaults (CONFIG_DEFAULTS,DEFAULT_MODELS,DEFAULT_ALLOWED_TOOLS)lib/config.js—Config loading, merging, andbuildConfig()for initlib/init.js—Project initialization, git hook shim managementlib/template.js—Template variable expansion for agent promptslib/globs.js—File matching, source detection, config path detectionlib/monitor.js—prove_it monitorCLI: tails session logs in human-readable format
Claude Code Hook API
- PreToolUse:
permissionDecisionvalid values are"allow","deny","ask"(insidehookSpecificOutput). Never use"block"or"approve"—Claude Code silently ignores them. - Stop: uses top-level
decision: "block"or"approve"(different schema from PreToolUse). - SessionStart: outputs JSON with
additionalContextand optionallysystemMessage. session_idis available in hook input for all events.
Testing
./script/test # lint + unit tests + integration tests (the verification oracle)
./script/test_fast # lint + unit tests only (runs on Stop hook)
npm run test:integration # integration tests- Unit tests:
test/*.test.js - Integration tests:
test/integration/*.test.js - Example validation:
test/examples.test.js - Hook harness:
test/integration/hook-harness.js
Running from source (local development)
Use ./script/agent to launch Claude Code with the local prove_it on PATH:
./script/agent # interactive
./script/agent -p "fix the bug" # with promptThis prepends test/bin/prove_it (a shim to cli.js) to PATH so all hook dispatchers, libexec scripts, and transitive prove_it calls use the working tree. A local-shim-check runs on SessionStart to confirm the shim is active.
The full agent testing workflow is in the Agent testing section below.
Releasing
Use the /release skill. It reads RELEASE.md for the full process.
Two-tier installation model
prove_it uses a two-tier activation model: enabled defaults to false in the
dispatcher, so prove_it does nothing unless explicitly opted in.
install/uninstallmanage global hook registrations in~/.claude/settings.jsonand global config in~/.claude/prove_it/config.json(which setsenabled: true). These never touch project files.init/deinitmanage project-level files only (.claude/prove_it/config.json, git shims). These never touch~/.claude/settings.json.
Because the global config sets enabled: true, prove_it runs in any project once
installed globally. Deleting a project's .claude/prove_it/config.json does not stop
prove_it if the global config has enabled: true—it just means no project-specific
tasks are configured.
Config defaults cascade
All config defaults live in lib/defaults.js. This is the single source of truth.
The runtime config cascade (each layer overrides the previous):
configDefaults()fromlib/defaults.js— fully-qualified base config~/.claude/prove_it/config.json— global user config (written byprove_it install)- Ancestor
.claude/prove_it/config.jsonfiles — walked root-to-cwd cwd/.claude/prove_it/config.local.json— local project overrides
By the time dispatcher code reads cfg.maxAgentTurns, it already has the
default value of 10. No || fallback patterns are needed downstream.
Rules:
- Never add
|| <default>when reading from the merged config — add the default toCONFIG_DEFAULTSinlib/defaults.jsinstead buildGlobalConfig()andbaseConfig()inlib/config.jsreferenceCONFIG_DEFAULTSso generated config files stay in sync with runtimeDEFAULT_MODELSandDEFAULT_ALLOWED_TOOLSalso live inlib/defaults.js(code-level constants, not user config, but same canonical location)
Conventions
- No dependencies beyond Node.js stdlib (devDependencies: standard for linting only)
- Linter:
npx standard --fix(run automatically by./script/test_fast) - Config format:
hooksis a two-level object{ type: { event: [tasks] } }where type isclaudeorgit, event is the lifecycle event name, and tasks carry their ownmatcher/source/triggers. Hooks merge across config layers by taskname(same-name = full replacement, new-name = append). - Infrastructure scripts live in
libexec/and are referenced via$(prove_it prefix)/libexec/<name> - Agent reviewer prompts are distributed as Claude Code skills (
lib/skills/prove-coverage.md,lib/skills/prove-done.md), resolved viapromptType: 'skill'
Agent testing
The problem
prove_it's hooks reference prove_it by name (e.g., $(prove_it prefix)/libexec/guard-config). When Claude Code fires hooks, the prove_it on PATH determines which version runs. During development, that's usually the Homebrew install—not your working tree.
The solution
script/agent launches Claude Code with test/bin/prove_it prepended to PATH. This shim resolves to the repo's cli.js, so every prove_it invocation—hooks, libexec scripts, transitive calls—uses your local source.
./script/agent # interactive
./script/agent -p "fix the bug" # with promptHow it works
script/agent
└─ PATH="$REPO_ROOT/test/bin:$PATH" claude --dangerously-skip-permissions
└─ Claude Code fires SessionStart
└─ prove_it hook claude:SessionStart
└─ resolves to test/bin/prove_it → cli.js
└─ runs local-shim-check → confirms test/bin/prove_it is active
└─ records session baseline (lazy, internal)All child processes inherit the modified PATH: hook dispatchers, libexec scripts, test scripts, agent reviewers.
Verification
The project's .claude/prove_it/config.json includes a local-shim-check as the first SessionStart task. On every session start, it runs:
which prove_it | grep -q test/bin/prove_it- Pass:
prove_it resolves to local shim: .../test/bin/prove_it - Fail:
WARNING: prove_it resolves to /opt/homebrew/bin/prove_it, not test/bin/prove_it. Use ./script/agent to launch Claude with the local version.
This is a SessionStart task, so it warns but doesn't block—the agent sees the message and knows whether it's running against local source or the installed version.
When to use what
| Scenario | Command |
| Develop prove_it with live hooks | ./script/agent |
| Run tests from the CLI | ./script/test |
| Test a single hook manually | PATH="$(pwd)/test/bin:$PATH" prove_it hook claude:Stop <<< '{...}' |
| Test an example project | cd example/basic && PATH="../../test/bin:$PATH" claude |
| Use the installed (released) version | claude (normal) |
Multi-machine sync
This repository is edited from more than one Mac. Before starting work, fetch and integrate origin/main (fast-forward when possible). After finishing, commit everything uncommitted, including changes that are not yours unless another agent is actively working in this checkout, then fetch, integrate origin/main, and push. The full rule is in the global agent instructions (~/icloud-drive/dotfiles/AGENTS.md).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

