百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
P

prove_it

> 编程语言
开源

Claude 代码应随附的验证线束

199 stars0 点赞0 次浏览
访问官网GitHub

工具介绍

Claude 代码应随附的验证线束

prove_it: force Claude's code to actually work

Comin' in Hot! Shipping multiple unstable releases per day at the moment. If you want prove_it to actually work, email Justin for updates

If you experience errors after an upgrade, reset your setup with prove_it reinstall && prove_it reinit. By far the most frustrating thing about Claude Code is its penchant for prematurely declaring success. Out-of-the-box, Claude will happily announce a task is complete. But has it run the tests? No. Did it add any tests? No. Did it run the code? Also no.

prove_it hooks into Claude Code's lifecycle events and runs whatever tasks you configure—test suites, lint scripts, AI code reviewers—blocking Claude until they pass.

(And in case it's not obvious, prove_it currently only works with Claude Code.)

Quick start

bash
brew install searlsco/tap/prove_it
prove_it install
cd your-project && prove_it init

Restart Claude Code and you're live.

What can prove_it do?

prove_it is a config-driven framework for enforcing quality in Claude Code sessions. You can easily configure script and subagent tasks in a few lines of JSON that:

  • Block Claude from stopping until your tests pass
  • Block git commits until a full test suite is green
  • Run AI reviewers — independent subagents that audit Claude's work for coverage gaps, logic errors, or security issues
  • Fire reviews asynchronously — expensive reviewers run in the background while Claude keeps working, then enforce their verdict on the next stop
  • Gate tasks on signals — heavyweight checks fire only when Claude declares a unit of work complete (prove_it signal done), or when Claude gets caught in a doom loop (prove_it signal stuck --message "can't figure out Liquid Glass")
  • Gate tasks on churn — reviews trigger after N lines changed (net git diff) or N lines written (gross, catches thrashing)
  • Inject context on session start — briefs your agent on what prove_it will inspect for and when, along with instructions on how to use it
  • Guard tool usage — block specific tool calls (config file edits, dangerous commands) before they execute
  • Track runs — skip re-running tasks when code hasn't changed since the last pass (via when: { sourcesModifiedSinceLastRun: true })

Out of the box, prove_it init generates the Searls-stack of configured tasks:

  • Session briefing on startup — Claude gets an orientation showing active tasks, signal instructions, and how the review process works
  • Config lock on every edit — silently blocks Claude from modifying your prove_it config
  • TDD enforcement on every edit — tracks the red-green cycle and nudges Claude to write a failing test before writing source code. Adapts behavior based on the current session phase (see Session phases).
  • TDD guidance in plans — injects a red-green TDD development approach section into every plan Claude creates
  • Fast tests on every stop — runs ./script/test_fast and blocks until it passes
  • Full tests on signal — runs ./script/test when Claude signals done (and source files were edited)
  • Async coverage review — a Haiku-powered prove-coverage subagent fires in the background after 541+ net lines of churn, enforced on the next stop
  • Done review on signal — an Opus-powered prove-done subagent runs a thorough pre-ship review when Claude signals done
  • Approach review on signal — a Sonnet-powered prove-approach subagent runs when Claude signals stuck, surfacing alternative approaches
  • Full tests on git commit — pre-commit hook runs ./script/test (Claude commits only — human commits pass through)

Every one of these is a config entry you can change, disable, or replace. The framework supports any combination of lifecycle events, conditions, and task types — the default config is just a starting point.

Setup

Install

bash
# Install the CLI
brew install searlsco/tap/prove_it

# Register prove_it hooks in ~/.claude/settings.json
prove_it install

Initialize a project

bash
cd your-project
prove_it init

This interactively sets up .claude/prove_it/config.json, creates script/test and script/test_fast stubs if you don't have them, installs git hooks, and generates a starter .claude/rules/testing.md. Restart Claude Code and you're live.

Non-interactive init

Pass flags to skip prompts (useful for CI or scripting):

bash
prove_it init --git-hooks --default-checks
Flag Default Effect
--[no-]git-hooks on Install git pre-commit/pre-push hooks
--[no-]default-checks on Include AI coverage review, pre-ship review
--[no-]automatic-git-hook-merge off Merge with existing git hooks (fails if hooks exist)
--[no-]overwrite — Overwrite customized config with current defaults

Test scripts

By default, prove_it looks for two test scripts by convention:

Script Purpose When it runs
script/test Full test suite (units, integration, linters, etc.) Before every git commit
script/test_fast Fast unit tests only Every time Claude stops work

For example, your script/test_fast script might run:

bash
#!/usr/bin/env bash
set -e
trap 'rc=$?; command -v prove_it >/dev/null 2>&1 && prove_it record --name fast-tests --result $rc' EXIT
rake test

And your full script/test command will probably run that and more:

bash
#!/usr/bin/env bash
set -e
trap 'rc=$?; command -v prove_it >/dev/null 2>&1 && prove_it record --name full-tests --result $rc' EXIT
rake test standard:fix test:system

The trap ... EXIT pattern ensures results are always recorded, even when set -e causes early exit. prove_it uses this to skip re-running tests when code hasn't changed.

Recording runs

prove_it record options:

  • --result —record pass (N=0) or fail (N!=0), exit with code N (best for traps)
  • --pass / --fail—record explicitly (exit 0 / exit 1)
  • --name —must match the task name in your config

Configuration

prove_it is configured with a hooks object in .claude/prove_it/config.json. Hooks are keyed by type (claude, git) then by event (Stop, PreToolUse, SessionStart, pre-commit, pre-push, etc.), with each event mapping to an ordered list of tasks:

json
{
  "enabled": true,
  "sources": ["src/**/*.js", "lib/**/*.js", "test/**/*.js"],
  "tests": ["test/**/*.test.js"],
  "hooks": {
    "claude": {
      "Stop": [
        { "name": "fast-tests", "type": "script", "command": "./script/test_fast" },
        { "name": "coverage-review", "type": "agent", "prompt": "Check coverage...\n\n{{session_diff}}" }
      ]
    }
  }
}

Config layers

Config files merge (later overrides earlier):

  1. ~/.claude/prove_it/config.json—global defaults
  2. .claude/prove_it/config.json—project config (commit this)
  3. .claude/prove_it/config.local.json—local overrides (gitignored, per-developer)

Hooks merge by task name: a task in a descendant config with the same name as one in an ancestor fully replaces the ancestor's task; a task with a new name is appended. Global tasks run first (most general to most specific). Other array fields (like sources) replace rather than merge.

Source and test globs

sources defines which files prove_it considers "your code" — these globs drive conditions like sourcesModifiedSinceLastRun, sourceFilesEdited, and linesChanged. Test files should be included in sources so that edits to tests are tracked as source changes.

tests identifies which source files are test files. This drives the test-first check, which enforces red-green TDD by tracking whether Claude writes and runs failing tests before implementing source code. See Session phases for how enforcement varies by activity. tests is typically a subset of sources — it doesn't need to be disjoint.

Both sources and tests are preserved across prove_it init / reinit when customized, so you won't lose your globs on upgrade.

Lifecycle events

Claude events:

Event Purpose Behavior
SessionStart Environment setup, injecting context Non-blocking. All tasks run. Output is injected into Claude's context. Use this to inject prompts, announce project state, set environment variables, or run setup scripts.
PreToolUse Guarding tool usage Blocking, fail-fast. Tasks run in order; the first failure denies the tool and stops. Use this for config protection, enforcing workflows, or vetting commands.
Stop Verifying completed work Blocking, fail-fast. Tasks run in order; the first failure sends Claude back to fix it. Put cheap tasks first (test suite), expensive ones last (AI reviewer). Async results are harvested before sync tasks run.
PostToolUse Observing tool results Non-blocking. Fires after a tool succeeds. Used by TDD enforcement to detect test passes. Matcher filters by tool name.
PostToolUseFailure Observing tool failures Non-blocking. Fires after a tool fails. Used by TDD enforcement to detect test failures. Matcher filters by tool name.

Git events:

Event Purpose Behavior
pre-commit Validating before commit Blocking, fail-fast. Runs only under Claude Code (CLAUDECODE env var)—human commits pass through instantly.
pre-push Validating before push Blocking, fail-fast. Same as pre-commit but triggers on push.

Task types

  • script—runs a shell command, fails on non-zero exit
  • agent—sends a prompt to an AI reviewer, expects PASS/FAIL response (see Agent tasks)
  • env—runs a command that outputs environment variables, injected into Claude's session (SessionStart only, see Env tasks)

Task parameters (params)

Script tasks accept a params object that is passed to the script as input.params in the stdin JSON payload:

json
{
  "name": "lock-config",
  "type": "script",
  "command": "$(prove_it prefix)/libexec/guard-config",
  "quiet": true,
  "params": {
    "paths": [".claude/prove_it/config.json", ".claude/prove_it/config.local.json"]
  }
}

Scripts read params from the parsed stdin JSON alongside tool_name, tool_input, etc. This is a generic mechanism—any script can use params to accept structured configuration without inventing CLI arg parsing.

guard-config with custom paths: The built-in guard-config script uses params.paths to decide which file paths to block. Add your own paths to guard additional files:

json
{
  "name": "lock-config",
  "type": "script",
  "command": "$(prove_it prefix)/libexec/guard-config",
  "quiet": true,
  "params": {
    "paths": [".claude/prove_it/config.json", ".claude/prove_it/config.local.json", ".env", "credentials/**"]
  }
}

When params.paths is omitted, guard-config falls back to blocking prove_it config files by default (backward compatible).

Task briefing

Tasks can include a briefing field — a string that's injected into every SessionStart orientation. This lets infrastructure tasks (like TDD enforcement) provide persistent guidance without being SessionStart tasks themselves.

json
{
  "name": "my-task",
  "type": "script",
  "command": "./my-script",
  "briefing": "Remember to frobnicate the widgets before shipping."
}

Disabling individual tasks

Set enabled: false on a task to skip it without removing it from config:

json
{ "name": "slow-review", "type": "agent", "prompt": "prove-coverage",
  "promptType": "skill", "enabled": false }

Disabled tasks are logged as SKIP with reason "Disabled".

Quiet tasks

Set quiet: true on a task to suppress all log outp

Issues· 6 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

JavaScriptshovelware

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月18日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言