claude-code-hooks

name	claude-code-hooks
description	Guide for implementing Claude Code hooks - automated scripts that execute at specific workflow points. Use when building hooks, understanding hook events, or troubleshooting hook configuration.

Claude Code Hooks Implementation Guide

Implement automated hooks that execute bash commands or TypeScript scripts in response to Claude Code events.

Quick Reference

9 Available Hook Events

1. PreToolUse - Before tool execution (validation, blocking)
2. PostToolUse - After tool success (formatting, testing)
3. Notification - On Claude notifications
4. UserPromptSubmit - Before processing user input (context injection)
5. Stop - When main agent finishes responding
6. SubagentStop - When subagent completes
7. PreCompact - Before context compaction
8. SessionStart - Session begins
9. SessionEnd - Session ends

Hook Input (stdin JSON)

{
  "session_id": "...",
  "transcript_path": "...",
  "cwd": "/current/working/dir",
  "permission_mode": "default",
  "hook_event_name": "PostToolUse",
  "tool_name": "Write",
  "tool_input": {"file_path": "...", "content": "..."},
  "tool_response": "..."
}

Hook Output Mechanisms

Exit Codes:

• 0 - Success (stdout → transcript, or context if UserPromptSubmit)
• 2 - Blocking error (stderr → Claude feedback)
• Other - Non-blocking error (shown to user)

JSON Output (stdout):

{
  "continue": true,
  "stopReason": "optional message",
  "suppressOutput": true,
  "decision": "allow|deny|ask",
  "hookSpecificOutput": {}
}

Recommended: Use claude-hooks-sdk for TypeScript

For TypeScript hooks, use the SDK for type safety and utilities:

bun add claude-hooks-sdk

#!/usr/bin/env bun
import { HookManager, success, block, createLogger } from 'claude-hooks-sdk';

const logger = createLogger('my-hook');

const manager = new HookManager({
  logEvents: true,
  clientId: 'my-hook',
  trackEdits: true,
});

manager.onPreToolUse(async (input) => {
  if (input.tool_name === 'Bash' && input.tool_input.command.includes('rm -rf /')) {
    logger.warn('Blocked dangerous command');
    return block('Dangerous command blocked');
  }
  return success();
});

manager.run();

Common Use Cases

1. Code Formatting (PostToolUse)

Configuration (.claude/settings.json):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/format-code.sh"
          }
        ]
      }
    ]
  }
}

Script (.claude/hooks/format-code.sh):

#!/bin/bash
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path')

if [[ "$FILE_PATH" =~ \.(ts|tsx|js|jsx)$ ]]; then
  npx prettier --write "$FILE_PATH" 2>&1
  echo "✓ Formatted: $FILE_PATH"
fi

exit 0

2. Security Validation (PreToolUse)

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')

# Block dangerous patterns
if [[ "$COMMAND" =~ (rm\ -rf\ /|\.\./) ]]; then
  echo '{"decision": "deny", "continue": false}' | jq
  echo "❌ Blocked: Dangerous command" >&2
  exit 2
fi

echo '{"decision": "allow", "continue": true}' | jq
exit 0

3. Context Injection (UserPromptSubmit)

Using SDK (recommended):

#!/usr/bin/env bun
import { createUserPromptSubmitHook } from 'claude-hooks-sdk';

// ONE LINE - injects session ID and name into Claude's context
createUserPromptSubmitHook();

4. Environment Setup (SessionStart)

#!/bin/bash
if [ ! -d "node_modules" ]; then
  bun install
fi

if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo "export NODE_ENV=development" >> "$CLAUDE_ENV_FILE"
fi

echo "✓ Environment ready"
exit 0

Configuration Patterns

Project-Specific Hooks

Store in .claude/settings.json (project root):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {"type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/format.sh"}
        ]
      }
    ]
  }
}

Global Hooks

Store in ~/.claude/settings.json (user home).

Troubleshooting

Hook Not Executing

1. Check matcher pattern (case-sensitive)
2. Verify script permissions: chmod +x script.sh
3. Enable debug mode: claude --debug

Hook Blocking Execution

1. Exit code 2 blocks, other codes don't
2. {"decision": "deny"} blocks PreToolUse

Resources

• Official Claude Code Hooks Docs
• claude-hooks-sdk on npm
• claude-hooks-sdk on GitHub