explaingit

ianymu/claude-verify-before-stop

★ 0ShellAudience · developerComplexity · 2/5ActiveLicenseSetup · easy

TLDR

A Claude Code Stop hook that blocks the AI from ending a session until a recent VERIFIED log entry proves it actually ran tests or checks against the changed files.

Mindmap

mindmap
  root((verify-before-stop))
    Inputs
      Git diff
      Stop hook event
      Verify log
    Outputs
      Block or allow stop
      Instructions to agent
    Use Cases
      Force test runs
      Guard merges
      Audit AI sessions
    Tech Stack
      Bash
      Python
      Claude Code

Things people build with this

USE CASE 1

Stop Claude Code from ending a session until it has logged a VERIFIED entry for the changed files.

USE CASE 2

Force the agent to run npm test, curl, or psql checks and write proof to .claude/state/stop-verify.log.

USE CASE 3

Add a workflow guard so AI-written code cannot be merged without evidence the tests were executed.

USE CASE 4

Use as a template for building other Stop hooks that gate session exit on project-specific checks.

Tech stack

BashPythonClaude CodeGit

Getting it running

Difficulty · easy Time to first run · 5min

Only needs bash, Python 3, and a Stop hook entry in .claude/settings.json pointing at the downloaded script.

MIT license, so you can use, modify, and redistribute the script commercially as long as you keep the copyright notice.

In plain English

verify-before-stop is a small shell script that plugs into Claude Code, Anthropic's command line coding assistant, and stops a coding session from ending until the AI has actually proved it tested its work. The problem the author describes is familiar to anyone who has used these tools: the model says all tests are passing, you merge the change, and production breaks. The script does not try to make the model smarter, it adds a workflow guard at the moment the session would end. Claude Code has a system called Stop hooks: a script the tool runs when a session is about to end. This project hooks into that. When the model tries to stop, the script first checks git for changed or untracked files. If files were changed, it looks for a recent VERIFIED entry in a log file at .claude/state/stop-verify.log written within the last five minutes. If that entry is missing, the script blocks the stop and prints exact instructions telling the model what it has to do. If no files were touched, the stop goes through with no friction. Inside a session, the agent is expected to log proof of what it ran. The README shows an example: run npm test, then append a VERIFY_ACTION line and a VERIFIED line to the log. The same pattern works with curl for HTTP services, psql for database checks, or Playwright for UI tests. Installation is short. You make a .claude/hooks directory in your project, download the script with curl, mark it executable, and add a Stop hook entry to .claude/settings.json that points at the script. The dependencies are bash and Python 3 from the standard library. The script is MIT licensed and pitched as the free sample from a paid pack of six Claude Code productivity hooks. The README also discusses compatibility with related projects and an academic reference on agent failure modes.

Copy-paste prompts

Prompt 1
Walk me through how the Stop hook reads git status and the .claude/state/stop-verify.log to decide whether to block a session exit.
Prompt 2
Show me the exact .claude/settings.json entry I need to add to wire verify-before-stop into a new project.
Prompt 3
Help me extend the verify script so it also requires a Playwright run to be logged before the session can stop.
Prompt 4
Explain what VERIFY_ACTION and VERIFIED lines should look like for a Python project that uses pytest and ruff.
Prompt 5
Debug why the hook keeps blocking my stop even though I ran the tests, by inspecting the timestamp window in the script.
Open on GitHub → Explain another repo

Generated 2026-05-22 · Model: sonnet-4-6 · Verify against the repo before relying on details.