$ show searlsco/prove_it
prove_it is a config-driven hook framework specifically designed for Claude Code, an AI coding assistant. It intercepts lifecycle events (SessionStart, PreToolUse, PostToolUse, Stop, TaskCompleted) and git hooks (pre-commit, pre-push) to run configurable verification tasks. These tasks include shell scripts, AI agent reviews (using Claude subprocesses), and environment variable injection. The tool enforces code quality by blocking or approving AI actions based on pass/fail results, preventing premature completion of tasks. Architecture-wise, prove_it is a Node.js CLI tool (≥18) with a modular design: config loading from layered JSON files, condition evaluation (`when`) for gating tasks, git-backed churn tracking, template expansion, and session state management. The dispatcher module handles all hook events, evaluates conditions, runs tasks synchronously or asynchronously, and returns structured responses to Claude Code. A sophisticated appeal system allows developers to override AI reviewer failures via a backchannel mechanism. The codebase demonstrates strong software engineering practices: extensive unit and integration tests (using node:test), clean functional modules, and a clear separation of concerns. Key reusable patterns include the layered config merging algorithm, the template engine with conditional blocks, and the condition evaluation system with AND/OR semantics. While the tool is tightly coupled to Claude Code's hook API (introducing ecosystem drift risk), its internal architecture is well-crafted and could serve as a reference for building similar verification frameworks. The project is actively maintained with frequent releases (v0.72.0), comprehensive documentation, and real-world example projects. Its quality is solid but not exceptional due to the inherent complexity of the config surface and the reliance on external AI services. The tool effectively solves the problem of AI overconfidence in code generation by forcing verification steps to pass before progress can be made.
The LLM identified 4 files worth highlighting for reuse:
Implements a composable condition evaluation system supporting AND (object), OR (array of objects) semantics, with lazy evaluation, bootstrap side effects for git churn tracking, and a two-phase evaluation (cheap gates first, activity conditions second). The pattern is isolated and could be extracted as a generic condition engine for any event-driven system.
Provides a lightweight template engine with custom placeholders ({{var}}) and conditional blocks ({{#var}}...{{/var}}). Supports lazy variable resolvers, session-aware expansion, and unknown variable detection. The engine is self-contained (string processing) and could be extracted with minimal changes for any project needing template expansion.
Handles config loading, merging, and validation across three layers: global, project, and local overrides. Features deep merge with key-based replacement for tasks, schema validation with detailed error messages, and build-time defaults. The mergeDeep and mergeHooks functions are pure and reusable for any multi-layer configuration system.
Implements code churn tracking using git lightweight refs under a custom namespace (refs/worktree/prove_it/). Tracks net lines changed and gross lines written with stale ref detection, CAS-based atomic counter increments, and working tree snapshots. Demonstrates non-obvious use of git plumbing for state persistence and could be adapted for other git-based metrics tracking.