Claude Code Custom Hooks: Automate Linting and Testing

Quick Verdict: Claude Code hooks give you programmatic control over what the CLI agent does before reading files, after editing code, or before executing shell commands. By binding automated linting, test runs, and security guards directly into the execution lifecycle, you prevent flawed edits from landing in your git working tree. I use pre-tool and post-tool hooks daily to keep terminal agents from breaking build scripts.

What Are Claude Code Hooks and Why They Matter

CLI coding agents move fast. They inspect directory trees, patch multiple files across modules, and trigger terminal commands in seconds. Speed helps development, but unrestrained edits introduce silent syntax regressions, broken imports, and secret leaks.

Hooks solve this problem at the lifecycle boundary. Instead of hoping an AI model remembers instructions in a prompt file, hooks enforce deterministic shell execution at predefined trigger points. When Claude Code attempts to run a bash tool or update a source file, the configured hook script runs first. If that script exits with a non-zero status code, the agent stops immediately and receives the error output to fix its mistakes.

I configure these lifecycle hooks in every team repository. Deterministic checks remove cognitive overhead, allowing developers to focus on architecture while automated shell scripts catch runtime flaws.

The Claude Code Lifecycle Event Model

Claude Code exposes structured hooks triggered during distinct execution phases. Understanding when each hook runs allows you to place verification logic without slowing down agent latency.

• PreToolUse: Fires immediately before Claude executes a tool (e.g., FileEdit, Bash, Glob). Use this hook to block destructive commands, protect sensitive environment files, or validate path parameters.
• PostToolUse: Fires immediately after a tool finishes execution. Use this hook to trigger fast linters (Ruff, ESLint, Biome) or formatters against modified files.
• PrePrompt / UserInput: Fires when receiving user instructions before sending them to the model context. Use this hook to inject dynamic repository context or branch metadata.
• Stop / SessionEnd: Fires when a session finishes. Use this hook to run full test suites, calculate diff sizes, or clean temporary sandbox files.

These events allow fine-grained control over agent operations without modifying the core CLI binaries.

Setting Up Your First Hook Configuration

Claude Code reads lifecycle configurations from .claude/settings.json located in your project root or user home directory. The configuration structure defines events, match patterns, and executable commands.

Here is a production-ready configuration structure for a Python and TypeScript project:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "FileEdit|FileWrite",
        "command": "bash .claude/hooks/post-edit.sh"
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "bash .claude/hooks/guard-bash.sh"
      }
    ]
  }
}

The matcher field filters relevant tool names using regular expressions. The command field executes standard shell binaries available in your system path.

Building a Fast Post-Edit Linting Hook

Post-edit hooks must run in under 500 milliseconds. Slow linters degrade agent velocity and waste token budgets on repetitive turns. In Python workflows, use Ruff; in JavaScript or TypeScript workflows, use Biome or ESLint with cache flags.

Create the file .claude/hooks/post-edit.sh and grant execution permissions:

#!/usr/bin/env bash
set -eo pipefail

# Read environment variables injected by Claude Code
CHANGED_FILE="${CLAUDE_TOOL_INPUT_PATH:-}"

if [[ -z "$CHANGED_FILE" || ! -f "$CHANGED_FILE" ]]; then
  exit 0
fi

# Run fast Python linter if a python file changed
if [[ "$CHANGED_FILE" =~ \.py$ ]]; then
  ruff check --fix "$CHANGED_FILE"
  ruff format "$CHANGED_FILE"
fi

# Run fast JS/TS linter if web files changed
if [[ "$CHANGED_FILE" =~ \.(js|ts|tsx|jsx)$ ]]; then
  npx biome check --write "$CHANGED_FILE"
fi

exit 0

When Claude Code modifies a Python script with unformatted indentation or missing imports, Ruff cleans the file instantly. Claude receives clean file state in subsequent turns, eliminating redundant formatting prompts.

Also Read:

SSE vs WebSockets for LLM Streaming APIs in FastAPI

Creating Pre-Tool Security and Destructive Command Guards

AI agents executing terminal commands can accidentally trigger destructive operations, such as recursive removals, force git pushes, or dropping production database tables. A PreToolUse guard prevents disastrous shell invocations before execution.

Create .claude/hooks/guard-bash.sh with explicit boundary checks:

#!/usr/bin/env bash
set -eo pipefail

COMMAND="${CLAUDE_TOOL_INPUT_COMMAND:-}"

# Define banned patterns
BANNED_PATTERNS=(
  "rm -rf /"
  "rm -rf ~"
  "git push --force"
  "git push -f"
  "drop database"
  "DROP TABLE"
  ":(){ :|:& };:"
)

for pattern in "${BANNED_PATTERNS[@]}"; do
  if [[ "$COMMAND" =~ $pattern ]]; then
    echo "SECURITY ERROR: Command contains blocked destructive pattern: '$pattern'" >&2
    exit 1
  fi
done

# Block direct modifications to production env files
if [[ "$COMMAND" =~ \.env\.production ]]; then
  echo "SECURITY ERROR: Direct edits to .env.production via bash are prohibited." >&2
  exit 1
fi

exit 0

If the model generates a dangerous command, the hook exits with status 1. Claude Code catches the error message and explains the refusal to the developer.

Comparison of Claude Code Hook Methods

Different verification strategies offer trade-offs between execution speed, feedback quality, and context token overhead.

I recommend pairing lightweight static linters on PostToolUse with comprehensive test suites on SessionEnd. This balance prevents latency bottlenecks during active code generation.

Automating Unit Tests on Targeted Edits

Running entire test suites after every single file edit stalls agent performance. Instead, map the edited file to its corresponding test file and execute targeted test runners.

#!/usr/bin/env bash
CHANGED_FILE="${CLAUDE_TOOL_INPUT_PATH:-}"

if [[ "$CHANGED_FILE" =~ src/(.*)\.py$ ]]; then
  MODULE="${BASH_REMATCH[1]}"
  TEST_FILE="tests/test_${MODULE}.py"
  
  if [[ -f "$TEST_FILE" ]]; then
    pytest "$TEST_FILE" -q --tb=short
  fi
fi

exit 0

When the agent edits src/auth.py, pytest executes only tests/test_auth.py. If a regression occurs, the test failure surfaces immediately in Claude’s output buffer, allowing the model to correct its logic before proceeding.

Injecting Dynamic Context with PrePrompt Hooks

Developers often struggle with AI models generating code based on outdated repository assumptions. A PrePrompt hook injects live environment details before the user query reaches the model. This guarantees accurate reasoning without manually writing repository descriptions.

Consider a script that gathers active git branch names, unstaged file diff summaries, and running docker service statuses:

#!/usr/bin/env bash
# .claude/hooks/inject-context.sh
BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
STATUS=$(git status --short 2>/dev/null | head -n 10)

echo "--- DYNAMIC REPO CONTEXT ---"
echo "Current Branch: $BRANCH"
echo "Recent Modified Files:"
echo "$STATUS"
echo "----------------------------"

Registering this script under the PrePrompt hook ensures Claude Code receives immediate awareness of ongoing workspace modifications. The agent avoids proposing modifications to files currently undergoing concurrent work.

Managing Hook Performance and Token Budgets

Every stdout or stderr stream returned by a hook script enters the agent’s context window. Excessive log output drains context limits and inflates API inference costs. Optimizing hook output requires deliberate output filtering.

Follow these practical guidelines for hook output management:

• Silence Clean Runs: If a linter or test passes without issues, return an empty output with exit code 0. Avoid printing verbose success banners.
• Truncate Error Traces: Limit compiler error outputs to the top 15 lines. Giant stack traces push previous conversational history out of active context.
• Cache Intermediate Artifacts: Utilize build cache flags (such as --cache-dir in linters) to prevent CPU thrashing across consecutive edits.

Advanced Team Standardization and Sharing

Engineering teams benefit when hook configurations live directly in version control. Committing .claude/settings.json and repository scripts under .claude/hooks/ guarantees consistent execution across all developer machines.

When multiple engineers run CLI agents concurrently, centralized scripts prevent configuration drift. New team members clone the codebase and immediately inherit established linting and security boundaries without manual environment setup.

Troubleshooting Common Hook Issues

When configuring custom hooks, developers frequently encounter three common pitfalls:

• Hanging Processes: Interactive commands (e.g., prompts asking for confirmation) freeze the CLI session. Always pass non-interactive flags like -y or --no-input in hook scripts.
• Exit Code Mismanagement: A hook that exits with code 0 signals success, while any non-zero exit code blocks execution. Ensure your scripts handle expected edge cases gracefully without returning accidental failure codes.
• Slow External Network Calls: Avoid making HTTP requests or remote package updates inside pre-tool or post-tool hooks. Keep all lifecycle checks local to the file system.

Review your terminal agent workflows alongside our guide on AI coding agent rules files that actually work to combine deterministic hooks with clear instruction guidelines. You can also explore our breakdown on how to build a custom MCP server with Python for broader tool integration, check our comparison of Cursor vs GitHub Copilot, and learn best practices in MCP server security and credential protection.

For official hook specifications and advanced agent features, consult the Anthropic Claude Code documentation, the official Ruff linter repository, the Biome toolchain guide, and the pytest testing framework.

Final Takeaways and Next Steps

Automated hooks transform AI coding assistants from unpredictable generators into reliable software engineering tools. Binding linters, targeted unit tests, and security guards directly to agent lifecycle events guarantees clean git diffs and protects critical infrastructure.

Start by configuring a basic post-edit formatter in your primary repository, verify execution times in local development, and gradually introduce security rules to streamline your AI coding workflow.