claude-code-hooks

Claude Code Hooks

This skill provides assistance for working with Claude Code hooks to enable automation of workflows and integration of external tools through an event-driven system.

About Hooks

Hooks are event-driven automation scripts that execute automatically when specific events occur during Claude Code's operation. Think of them as "middleware" for Claude's actions—they intercept events to validate inputs, enrich context, automate workflows, or integrate external tools, transforming Claude from a general assistant into a policy-aware, context-enriched agent.

What Hooks Provide

1. Input validation - Block dangerous operations, enforce security policies, prevent path traversal
2. Workflow automation - Auto-format code, run linters, backup files, send notifications
3. Context enrichment - Load git status, inject project context, add session information
4. External integration - Connect to APIs, trigger CI/CD, log to external systems
5. Decision control - Auto-approve safe operations, require confirmation for sensitive actions

Anatomy of a Hook

Every hook consists of configuration in settings.json and an optional validation script:

.claude/
├── settings.json         - Hook configuration (required)
│   └── hooks:
│       └── EventName:    - Which event to hook (PreToolUse, PostToolUse, etc.)
│           └── matcher:  - Which tools to match (regex pattern)
│               └── command: - What to execute (shell command or script)
└── hooks/                - Hook scripts (optional)
    └── script-name.py    - Validation/automation logic

Configuration (required)

Hooks are configured in settings.json with event type, tool matcher, and command:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/validate-bash.py",
            "timeout": 60
          }
        ]
      }
    ]
  }
}