Skip to content

Claude Hooks

What it is

Claude Hooks are middleware patterns and JSON-based configuration standards used to wrap Claude Code sessions with deterministic guardrails. As of June 2026, they natively support MCP 3.0 and allow for complex PreToolUse and PostToolUse logic to be injected into the agentic loop.

What problem it solves

Autonomous agents like Claude 4.8 Opus and GPT-5.5 can occasionally overlook repository-specific rules or security constraints. Claude Hooks solve this by providing an "interceptor" layer that can block or modify tool calls based on hard-coded conditions (e.g., preventing a commit if secrets are detected or automatically formatting code).

Where it fits in the stack

Development & Ops / Workflow Guardrails. It acts as a configuration and orchestration layer sitting directly between the agent and the operating system, often integrated via specialized MCP servers or custom shell wrappers.

Typical use cases

  • Security Interception: Scanning for credentials or PII before the git_commit or write_file tools are allowed to execute.
  • Automated Formatting: Running prettier, ruff, or eslint automatically after a write_file operation to ensure style compliance.
  • Workflow Notifications: Sending a Slack, Teams, or Chronos MCP alert when a long-running refactor session completes.
  • Environment Verification: Ensuring a clean Git state, active VPN connection, or passing test suite before allowing the agent to proceed.

Strengths

  • Deterministic: Logic is executed by the shell or a local runtime, not the LLM, ensuring 100% compliance with defined rules.
  • Transparency: Uses standard JSON schemas (hooks.json) that are easy to audit, version control, and share across teams.
  • Low Friction: Integrates directly with existing CLI agents like Aider, Cursor, and Claude Code via standard wrapper patterns.
  • Extensible: Supports any local binary or script as a hook action.

Limitations

  • Configuration Overhead: Requires maintaining .claude/hooks.json or equivalent setup files which can drift from project needs.
  • Latency: Multiple complex hooks (especially network-dependent ones) can add measurable delay to the agent's "thinking" loop.
  • Local Tool Reliance: Hooks depend on the presence of local binaries (e.g., grep, npm, python) which must be present in the execution environment.

When to use it

  • In shared team environments where standardized coding practices and security gates must be enforced.
  • When delegating sensitive tasks (e.g., infrastructure-as-code or production database migrations) to an autonomous agent.
  • To automate the feedback loop between the agent and local CI/CD scripts.

When not to use it

  • For rapid, exploratory prototyping where strict rules might hinder velocity.
  • In small, single-file scripts where natural language instructions in the system prompt are sufficient.
  • If the environment lacks the necessary tooling to execute the hook actions reliably.

Getting started

Configuration Directory

Claude Hooks typically look for configuration in the .claude/ directory of your repository root.

mkdir -p .claude
touch .claude/hooks.json

Implementing a Wrapper

Since hooks are often implemented as middleware, you can wrap your agent execution in a script:

# Example: run-claude-with-hooks.sh
# Runs a pre-hook script before starting the Claude Code session
python3 scripts/pre_hook_audit.py && claude && bash scripts/post_hook_cleanup.sh

v0.4 Hooks Schema

The June 2026 schema supports conditional execution based on tool arguments:

{
  "version": "0.4",
  "hooks": [
    {
      "name": "Audit Commits",
      "tool": "git_commit",
      "type": "PreToolUse",
      "action": "scripts/audit_msg.py"
    }
  ]
}

CLI examples

Manual Hook Execution

Test your pre-commit hook manually before the agent runs to ensure it behaves correctly:

python3 scripts/scan_secrets.py --staged --verbose

Validating Hook Environment

Ensure all tools required by your hooks are available in the current $PATH:

which eslint prettier python3 ruff

Monitoring Hook Logs

View the output of middleware execution during an active agent session for debugging:

tail -f .claude/hooks.log

API examples

Hook Definition (JSON)

Define hooks using the standard middleware pattern for Claude Code and MCP 3.0.

{
  "hooks": [
    {
      "name": "Pre-Commit Secret Scan",
      "type": "PreToolUse",
      "tool": "git_commit",
      "action": "scripts/scan_secrets.sh",
      "on_failure": "abort"
    },
    {
      "name": "Post-Write Lint",
      "type": "PostToolUse",
      "tool": "write_file",
      "action": "npx eslint {{filepath}} --fix",
      "on_failure": "warn"
    }
  ]
}

Custom Python Hook (Middleware Logic)

import sys
import json

def pre_tool_hook(tool_name, arguments):
    if tool_name == "delete_file" and "protected" in arguments["path"]:
        print("Error: Cannot delete protected files.")
        sys.exit(1)
    return True

# Hook implementation logic here

Sources / references

Contribution Metadata

  • Last reviewed: 2026-06-28
  • Confidence: high