Claude Code Hooks

Guide for creating hooks that execute shell commands or scripts in response to Claude Code events and tool calls.

When to Use This Skill

Activate this skill when:

• Creating event-driven automations

• Implementing custom validation or formatting

• Integrating with external tools and services

• Setting up project-specific workflows

• Responding to tool execution events

What Are Hooks?

Hooks are shell commands that execute automatically in response to specific events:

• Tool Call Hooks: Trigger before/after specific tool calls

• Lifecycle Hooks: Trigger on plugin install/uninstall

• User Prompt Hooks: Trigger when users submit prompts

• Custom Events: Application-specific trigger points

Hook Configuration

Location

Hooks are configured in:

• Plugin: <plugin-root>/.claude-plugin/hooks.json

• User-level: .claude/hooks.json

• Plugin manifest: Inline in plugin.json

File Structure

Standalone hooks.json:

{ "onToolCall": { "Write": { "before": ["./hooks/format-check.sh"], "after": ["./hooks/lint.sh"] }, "Bash": { "before": ["./hooks/validate-command.sh"] } }, "onInstall": ["./hooks/setup.sh"], "onUninstall": ["./hooks/cleanup.sh"], "onUserPromptSubmit": ["./hooks/log-prompt.sh"] }

Inline in plugin.json:

{ "hooks": { "onToolCall": { "Write": { "after": ["prettier --write {{file_path}}"] } } } }

Hook Types

Tool Call Hooks

Execute before or after specific tool calls.

Available Tools:

• Read , Write , Edit , MultiEdit

• Bash , BashOutput

• Glob , Grep

• Task , Skill , SlashCommand

• TodoWrite

• WebFetch , WebSearch

• AskUserQuestion

Example:

{ "onToolCall": { "Write": { "before": [ "echo 'Writing file: {{file_path}}'", "./hooks/backup.sh {{file_path}}" ], "after": [ "prettier --write {{file_path}}", "git add {{file_path}}" ] }, "Edit": { "after": ["eslint --fix {{file_path}}"] } } }

Lifecycle Hooks

Execute during plugin installation/uninstallation.

{ "onInstall": [ "./hooks/setup-dependencies.sh", "npm install", "echo 'Plugin installed successfully'" ], "onUninstall": [ "./hooks/cleanup.sh", "echo 'Plugin uninstalled'" ] }

User Prompt Submit Hook

Execute when user submits a prompt:

{ "onUserPromptSubmit": [ "./hooks/log-interaction.sh '{{prompt}}'", "./hooks/check-context.sh" ] }

Hook Variables

Hooks have access to context-specific variables using {{variable}} syntax.

Tool Call Variables

Different tools provide different variables:

Write Tool:

• {{file_path}} : Path to file being written

• {{content}} : Content being written (before hooks only)

Edit Tool:

• {{file_path}} : Path to file being edited

• {{old_string}} : String being replaced

• {{new_string}} : Replacement string

Bash Tool:

• {{command}} : Command being executed

Read Tool:

• {{file_path}} : Path to file being read

Global Variables

Available in all hooks:

• {{cwd}} : Current working directory

• {{timestamp}} : Current Unix timestamp

• {{user}} : Current user

• {{plugin_root}} : Plugin installation directory

User Prompt Variables

• {{prompt}} : User's submitted prompt text

Hook Examples

Auto-Format on Write

{ "onToolCall": { "Write": { "after": [ "prettier --write {{file_path}}", "eslint --fix {{file_path}}" ] } } }

Pre-Commit Validation

{ "onToolCall": { "Bash": { "before": ["./hooks/validate-git-command.sh '{{command}}'"] } } }

validate-git-command.sh:

#!/bin/bash

COMMAND="$1"

Block force push to main/master

if [[ "$COMMAND" =~ "git push --force" ]] && [[ "$COMMAND" =~ "main|master" ]]; then echo "ERROR: Force push to main/master is not allowed" exit 1 fi

exit 0

Automatic Backups

{ "onToolCall": { "Write": { "before": ["cp {{file_path}} {{file_path}}.backup"] }, "Edit": { "before": ["cp {{file_path}} {{file_path}}.backup"] } } }

Logging and Analytics

{ "onToolCall": { "Write": { "after": ["./hooks/log-file-change.sh {{file_path}}"] } }, "onUserPromptSubmit": ["./hooks/log-prompt.sh '{{prompt}}'"] }

log-file-change.sh:

#!/bin/bash

FILE="$1" TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

echo "$TIMESTAMP - Modified: $FILE" >> .claude/file-changes.log

Integration with External Tools

{ "onToolCall": { "Write": { "after": [ "notify-send 'File Updated' 'Modified {{file_path}}'", "curl -X POST https://api.example.com/notify -d 'file={{file_path}}'" ] } } }

Hook Execution

Execution Order

Multiple hooks execute in array order:

{ "onToolCall": { "Write": { "after": [ "echo 'Step 1'", // Runs first "echo 'Step 2'", // Runs second "echo 'Step 3'" // Runs third ] } } }

Exit Codes

Before Hooks:

• Exit code 0 : Continue with tool execution

• Exit code non-zero: Block tool execution, show error to user

After Hooks:

• Exit codes are logged but don't affect tool execution

• Tool has already completed

Error Handling

#!/bin/bash

Before hook - blocks tool on error

if [[ ! -f "$1" ]]; then echo "ERROR: File does not exist" exit 1 # Blocks tool execution fi

Validation passed

exit 0

Best Practices

Keep Hooks Fast

Hooks block execution - keep them lightweight:

{ "onToolCall": { "Write": { // ✅ Fast linter "after": ["eslint --fix {{file_path}}"]

  // ❌ Slow test suite
  // "after": ["npm test"]
}

} }

Use Absolute Paths

Reference scripts with paths relative to plugin:

{ "onInstall": ["${CLAUDE_PLUGIN_ROOT}/hooks/setup.sh"] }

Validate Input

Always validate hook variables:

#!/bin/bash

FILE="$1"

if [[ -z "$FILE" ]]; then echo "ERROR: No file path provided" exit 1 fi

if [[ ! -f "$FILE" ]]; then echo "ERROR: File does not exist: $FILE" exit 1 fi

Provide Clear Feedback

#!/bin/bash

echo "Running pre-commit checks..."

if ! npm run lint; then echo "❌ Linting failed. Please fix errors before committing." exit 1 fi

echo "✅ All checks passed" exit 0

Handle Edge Cases

#!/bin/bash

Handle files with spaces in names

FILE="$1"

Validate file type

if [[ ! "$FILE" =~ .(js|ts|jsx|tsx)$ ]]; then

Skip non-JavaScript files silently

exit 0 fi

Run formatter

prettier --write "$FILE"

Security Considerations

Validate Commands

Before hooks can block dangerous operations:

{ "onToolCall": { "Bash": { "before": ["./hooks/validate-command.sh '{{command}}'"] } } }

validate-command.sh:

#!/bin/bash

COMMAND="$1"

Block dangerous patterns

DANGEROUS_PATTERNS=( "rm -rf /" "dd if=" "mkfs" "> /dev/sda" )

for pattern in "${DANGEROUS_PATTERNS[@]}"; do if [[ "$COMMAND" =~ $pattern ]]; then echo "ERROR: Dangerous command blocked: $pattern" exit 1 fi done

exit 0

Limit Hook Scope

Only hook necessary tools:

{ // ✅ Specific tools only "onToolCall": { "Write": { "after": ["./format.sh {{file_path}}"] } }

// ❌ Don't hook everything unnecessarily }

Sanitize Variables

#!/bin/bash

Sanitize file path

FILE=$(realpath "$1")

Ensure file is within project

if [[ ! "$FILE" =~ ^$(pwd) ]]; then echo "ERROR: File outside project directory" exit 1 fi

Debugging Hooks

Enable Verbose Output

{ "onToolCall": { "Write": { "before": ["set -x; ./hooks/debug.sh {{file_path}}; set +x"] } } }

Log Hook Execution

#!/bin/bash

LOG_FILE=".claude/hooks.log" TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

echo "$TIMESTAMP - Hook: $0, Args: $@" >> "$LOG_FILE"

Rest of hook logic...

Test Hooks Manually

Test hook with sample data

./hooks/format.sh "src/main.js"

Check exit code

echo $?

Common Hook Patterns

Auto-Format Pipeline

{ "onToolCall": { "Write": { "after": [ "prettier --write {{file_path}}", "eslint --fix {{file_path}}" ] }, "Edit": { "after": [ "prettier --write {{file_path}}", "eslint --fix {{file_path}}" ] } } }

Test on Write

{ "onToolCall": { "Write": { "after": ["./hooks/run-relevant-tests.sh {{file_path}}"] } } }

Git Integration

{ "onToolCall": { "Write": { "after": ["git add {{file_path}}"] }, "Edit": { "after": ["git add {{file_path}}"] } } }

Troubleshooting

Hook Not Executing

• Check hook file has execute permissions: chmod +x hooks/script.sh

• Verify path is correct relative to plugin root

• Check JSON syntax in hooks.json

• Look for errors in Claude Code logs

Hook Blocking Tool

• Check exit code of before hooks

• Add debug logging

• Test hook script manually

• Verify validation logic

Variables Not Substituting

• Check variable name spelling: {{file_path}} not {{filepath}}

• Verify variable is available for that tool

• Quote variables in bash: "{{file_path}}"

Templates

Reference templates for common hook configurations:

claude-hooks/ └── templates/ ├── plugin-hook.md # Plugin hook configuration example └── skill-hook.md # Skill/subagent frontmatter hooks example

Plugin Hook Template

Example configuration for defining hooks in a plugin's hooks/hooks.json :

• PostToolUse hook with Write|Edit matcher

• Uses ${CLAUDE_PLUGIN_ROOT} for script references

• Includes timeout configuration

Skill Hook Template

Example frontmatter for embedding hooks directly in skills:

• Supported events: PreToolUse, PostToolUse, Stop

• Hooks scoped to component lifecycle

• Runs only when skill/subagent is active

References

For more information:

• Claude Code Hooks Documentation: https://code.claude.com/docs/en/hooks

• Plugin Configuration: https://code.claude.com/docs/en/plugins#hooks