myclaude/docs/HOOKS.md

Claude Code Hooks Guide

Hooks are shell scripts or commands that execute in response to Claude Code events.

Available Hook Types

1. UserPromptSubmit

Runs after user submits a prompt, before Claude processes it.

Use cases:

• Auto-activate skills based on keywords
• Add context injection
• Log user requests

2. PostToolUse

Runs after Claude uses a tool.

Use cases:

• Validate tool outputs
• Run additional checks (linting, formatting)
• Log tool usage

3. Stop

Runs when Claude Code session ends.

Use cases:

• Cleanup temporary files
• Generate session reports
• Commit changes automatically

Configuration

Hooks are configured in .claude/settings.json:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/hooks/skill-activation-prompt.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/hooks/post-tool-check.sh"
          }
        ]
      }
    ]
  }
}

Creating Custom Hooks

Example: Pre-Commit Hook

File: hooks/pre-commit.sh

#!/bin/bash
set -e

# Get staged files
STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM)

# Run tests on Go files
GO_FILES=$(echo "$STAGED_FILES" | grep '\.go$' || true)
if [ -n "$GO_FILES" ]; then
  go test ./... -short || exit 1
fi

# Validate JSON files
JSON_FILES=$(echo "$STAGED_FILES" | grep '\.json$' || true)
if [ -n "$JSON_FILES" ]; then
  for file in $JSON_FILES; do
    jq empty "$file" || exit 1
  done
fi

echo "✅ Pre-commit checks passed"

Register in settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/hooks/pre-commit.sh"
          }
        ]
      }
    ]
  }
}

Example: Auto-Format Hook

File: hooks/auto-format.sh

#!/bin/bash

# Format Go files
find . -name "*.go" -exec gofmt -w {} \;

# Format JSON files
find . -name "*.json" -exec jq --indent 2 . {} \; -exec mv {} {}.tmp \; -exec mv {}.tmp {} \;

echo "✅ Files formatted"

Environment Variables

Hooks have access to:

• $CLAUDE_PROJECT_DIR - Project root directory
• $PWD - Current working directory
• All shell environment variables

Best Practices

1. Keep hooks fast - Slow hooks block Claude Code
2. Handle errors gracefully - Return non-zero on failure
3. Use absolute paths - Reference $CLAUDE_PROJECT_DIR
4. Make scripts executable - chmod +x hooks/script.sh
5. Test independently - Run hooks manually first
6. Document behavior - Add comments explaining logic

Debugging Hooks

Enable verbose logging:

# Add to your hook
set -x  # Print commands
set -e  # Exit on error

Test manually:

cd /path/to/project
./hooks/your-hook.sh
echo $?  # Check exit code

Built-in Hooks

This repository includes:

Hook	File	Purpose
Skill Activation	skill-activation-prompt.sh	Auto-suggest skills
Pre-commit	pre-commit.sh	Code quality checks

Disabling Hooks

Remove hook configuration from .claude/settings.json or set empty array:

{
  "hooks": {
    "UserPromptSubmit": []
  }
}

Troubleshooting

Hook not running?

• Check .claude/settings.json syntax
• Verify script is executable: ls -l hooks/
• Check script path is correct

Hook failing silently?

• Add set -e to script
• Check exit codes: echo $?
• Add logging: echo "debug" >> /tmp/hook.log

Further Reading

• Claude Code Hooks Documentation
• Bash Scripting Guide