Auto-Run Tests Before Stop Hook

Hook Type

Stop -- Fires when Claude is about to finish, spawns an agent to run tests.

Description

This hook uses an agent-based Stop hook to automatically run your project's test suite before Claude finishes. If tests fail, the agent reports the failures and Claude continues working to fix them. This creates a built-in quality gate that ensures every Claude session ends with passing tests.

Patterns/Rules

• Triggers every time Claude attempts to stop
• Spawns a subagent with a 120-second timeout (configurable)
• The subagent runs the test suite and checks results
• If tests pass: Claude stops normally
• If tests fail: Claude continues to fix the failures
• $ARGUMENTS passes context about what was changed

Configuration

Basic Version

Copy
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Run the project's test suite to verify all tests pass. Execute the appropriate test command for this project (e.g., npm test, pytest, go test ./..., cargo test). Report the results. If any tests fail, list the specific failures. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

Language-Specific Versions

Node.js / TypeScript:

Copy
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Run 'npm test' or 'pnpm test' (whichever is configured). Parse the output for failures. Also run 'npx tsc --noEmit' to check for type errors. Report all failures with file paths and line numbers. $ARGUMENTS",
            "timeout": 180
          }
        ]
      }
    ]
  }
}

Python:

Copy
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Run 'pytest -v --tb=short' to execute the test suite. Also run 'mypy .' if a mypy.ini or pyproject.toml with mypy config exists. Report all failures with tracebacks. $ARGUMENTS",
            "timeout": 180
          }
        ]
      }
    ]
  }
}

Action

When Claude attempts to stop:

1. The Stop hook spawns a subagent
2. The subagent detects and runs the project's test suite
3. If all tests pass: the agent confirms and Claude stops
4. If tests fail: the agent reports failures and Claude continues working
5. The cycle repeats until all tests pass or the user intervenes