bug-gate

A pre-commit hook that reviews your staged Python diff with Claude and blocks the commit only on findings a code reviewer would mark severity: bug — logic errors, inverted conditions, wrong variable used, resource leaks. Style, naming, performance and architecture are explicitly out of scope: deterministic linters do that better.

Built for repositories where AI agents write code: an agent never rolls back a buggy commit — it piles fix-fix-fix commits on top. The only place to stop a bug from entering history is before the commit, which is why this is a pre-commit hook and not a pre-push or CI check.

Requirements

• Claude Code CLI installed and authenticated (claude on PATH) — the hook calls it headless (claude -p).
• git, Python ≥ 3.10.

Usage

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/goldenprofile/bug-gate
    rev: v0.1.0
    hooks:
      - id: bug-gate
        args: [--model, sonnet]

Options

Arg	Default	Meaning
--model	sonnet (env BUG_GATE_MODEL)	Claude model alias for the review
--timeout	180 (env BUG_GATE_TIMEOUT)	seconds before fail-open
--max-diff-kb	200	diffs larger than this skip review (fail-open)
--exclude	—	git pathspec to exclude, repeatable: args: [--exclude, "migrations/*"]

Behavior contract

• High precision over recall. Every finding must carry a concrete failure_scenario (input/state → wrong behavior); the model is instructed to stay silent when unsure. An empty report is the normal outcome.
• Fail-open on infrastructure. Missing CLI, timeout, API error, unparsable output — the hook warns loudly and lets the commit through. It never blocks work because an API is down.
• Diff-hash cache. An approved diff is remembered (.git/bug-gate-approved); re-committing the same staged diff after another hook failed is free and instant.
• Sanctioned bypass for a false positive: SKIP=bug-gate git commit ... (pre-commit's standard mechanism — no --no-verify needed).

Cost and latency

A ~200-line diff reviewed by Sonnet costs roughly $0.02–0.03 and takes 15–40 seconds. Use --model haiku where speed matters more than depth.

CI

The same hook runs in CI via pre-commit run bug-gate; without an authenticated claude CLI it fail-opens with a warning, so it degrades gracefully where no API key is configured.