Claude Code Has Hidden Hook System for Auto-Linting

What It Is

Claude Code includes an undocumented hook system that executes custom scripts automatically before or after tool calls. This mechanism allows developers to intercept and validate operations like file edits, writes, or bash commands before they execute. The system operates through a .claude/settings.json configuration file placed in the project root.

The hook system supports two trigger points: PreToolUse runs scripts before an action executes, while PostToolUse runs them afterward. Each hook configuration includes a matcher pattern (like “Edit|Write” or “Bash”) that determines which tool calls trigger the script, and a command specification pointing to the executable script.

Scripts receive the complete tool input as JSON via stdin, giving them full context about the pending operation. The exit code determines behavior: exit code 2 blocks the action entirely, while other codes allow it to proceed. This creates a gating mechanism for enforcing project-specific rules without manual intervention.

Why It Matters

This discovery fundamentally changes how teams can deploy AI coding assistants in production environments. Security-conscious organizations can now implement automated guardrails that prevent potentially dangerous operations without requiring constant human oversight.

The hook system addresses a critical gap in AI-assisted development: trust and validation. Before this capability, every Claude-generated bash command or file modification required manual review to ensure it aligned with security policies, coding standards, or architectural constraints. Teams working with sensitive codebases or regulated environments can now codify their review criteria into executable scripts.

For individual developers, the automation potential is significant. Linting, formatting, and style checking can happen automatically after every AI-generated edit. Instead of running npm run lint or black . after each change, the hook system ensures code quality standards apply immediately. This reduces friction in the development loop and maintains consistency across AI-assisted and manual changes.

The blocking capability (exit code 2) creates enforcement mechanisms that go beyond warnings. A pre-execution hook could prevent Claude from running rm -rf commands, accessing production databases, or modifying protected files. This transforms Claude Code from a powerful but potentially risky tool into one that respects organizational boundaries.

Getting Started

Create a .claude/settings.json file in the project root with hook configurations:

{
 "hooks": {
 "PostToolUse": [{
 "matcher": "Edit|Write",
 "hooks": [{ "type": "command", "command": "./scripts/lint.sh" }]
 }],
 "PreToolUse": [{
 "matcher": "Bash",
 "hooks": [{ "type": "command", "command": "./scripts/security-check.sh" }]
 }]
 }
}

A basic linting script might look like this:

#!/bin/bash
# scripts/lint.sh eslint . --fix exit $?

For blocking dangerous operations, a security check script could parse the JSON input:

#!/bin/bash
# scripts/security-check.sh input=$(cat)
if echo "$input" | grep -q "rm -rf"; then
 echo "Blocked: dangerous command detected"
 exit 2
fi exit 0

The matcher field accepts pipe-delimited patterns matching tool names. Common tools include Edit, Write, Bash, Read, and List. Scripts must be executable (chmod +x scripts/*.sh) and should handle JSON parsing appropriately for complex validation logic.

Context

This hook system resembles Git hooks, which have been standard in version control for years. Git’s pre-commit and post-commit hooks serve similar purposes - validating changes before they’re finalized. The key difference is that Claude’s hooks intercept AI actions rather than human commits.

Alternative approaches to code quality in AI-assisted development include post-generation review workflows, where developers manually inspect and approve changes, or CI/CD pipeline checks that catch issues after the fact. The hook system sits between these extremes, providing real-time validation without breaking the development flow.

Limitations exist: the hook system is undocumented, meaning the API could change without notice. Performance overhead from running scripts on every tool call could slow down interactions, particularly with heavy linters or complex validation logic. Scripts also need careful error handling to avoid blocking legitimate operations.

For teams already using pre-commit hooks or similar tooling, integrating Claude hooks into existing validation infrastructure should be straightforward. The JSON input format provides rich context, but parsing it reliably requires robust scripting or dedicated tools like jq for JSON manipulation.