adaptationio/hooks-manager

Hooks Manager

Overview

hooks-manager enables sophisticated workflow automation through Claude Code's hooks system (released June 2025).

Purpose: Create event-driven automation for code formatting, security gates, observability, and validation

Pattern: Task-based (8 operations, one per hook event + management)

Key Innovation: Hooks transform Claude Code from interactive to automated - reducing manual work by up to 92%

Hook Events Available (8):

1. UserPromptSubmit - Before Claude sees prompts
2. PreToolUse - Before tool execution
3. PostToolUse - After tool execution
4. PermissionRequest - When permissions requested
5. Notification - Important events
6. SessionStart - Session initialization
7. SessionEnd - Session cleanup
8. Stop - Conversation termination

---

When to Use

Use hooks-manager when:

• Auto-formatting code (PostToolUse after Write/Edit)
• Security gates (PreToolUse to block dangerous operations)
• Observability integration (send telemetry on all tool calls)
• Validation enforcement (block invalid operations)
• Workflow automation (trigger actions on events)
• Team standardization (enforce coding standards)

Production Impact: Companies report 92% reduction in style review time with PostToolUse formatting hooks

---

Prerequisites

Required

• Claude Code (hooks support added June 2025)
• Basic understanding of event-driven programming

Recommended

• Linter/formatter installed (ESLint, Prettier, Black)
• Security tools (if using security hooks)
• Observability platform (if using telemetry hooks)

---

Hook Operations

Operation 1: Create Formatting Hook (PostToolUse)

Purpose: Auto-format code after AI writes/edits files

Use Case: Enforce coding standards without manual intervention

Process:

1. Choose Formatter:

   # JavaScript/TypeScript
   npm install --save-dev prettier
   
   # Python
   pip install black
   
   # Multi-language
   npm install --save-dev prettier @prettier/plugin-python
   

2. Create Hook Configuration:

   {
     "event": "PostToolUse",
     "tools": ["Write", "Edit"],
     "description": "Auto-format code after Claude writes/edits files",
     "handler": {
       "command": "npx prettier --write \"$FILE\"",
       "timeout": 5000
     },
     "filters": {
       "filePatterns": ["**/*.{ts,tsx,js,jsx,py}"],
       "excludePatterns": ["node_modules/**", "*.min.js"]
     }
   }
   

3. Install Hook:

   # Global hook (all projects)
   mkdir -p ~/.claude/hooks
   echo '[above-json]' > ~/.claude/hooks/auto-format.json
   
   # Project-specific
   mkdir -p .claude/hooks
   echo '[above-json]' > .claude/hooks/auto-format.json
   

4. Test Hook:

   # Have Claude write unformatted code
   # Hook should auto-format after Write/Edit
   # Verify formatted correctly
   

Outputs:

• Hook configuration file
• Auto-formatting on all code changes
• 92% reduction in style review time

Validation:

• [ ] Hook file created
• [ ] Formatter configured correctly
• [ ] File patterns appropriate
• [ ] Tested with Claude Code
• [ ] Formatting works automatically

Time Estimate: 30-45 minutes

---

Operation 2: Create Security Hook (PreToolUse)

Purpose: Block dangerous operations before execution

Use Case: Prevent accidental production file modifications, destructive commands

Process:

1. Define Security Rules:

   {
     "event": "PreToolUse",
     "tools": ["Write", "Edit", "Bash"],
     "description": "Block dangerous operations",
     "handler": {
       "command": ".claude/hooks/security-check.sh \"$TOOL\" \"$FILE\" \"$COMMAND\""
     },
     "structuredOutput": true
   }
   

2. Create Security Check Script:

   #!/bin/bash
   # .claude/hooks/security-check.sh
   
   TOOL=$1
   FILE=$2
   COMMAND=$3
   
   # Block production file modifications
   if [[ "$FILE" == "/etc/"* ]] || [[ "$FILE" == "/usr/"* ]]; then
     echo '{"continue": false, "stopReason": "Cannot modify system files", "suppressOutput": true}'
     exit 1
   fi
   
   # Block destructive commands
   if [[ "$COMMAND" =~ rm\ -rf\ / ]] || [[ "$COMMAND" =~ dd\ if ]]; then
     echo '{"continue": false, "stopReason": "Destructive command blocked", "suppressOutput": true}'
     exit 1
   fi
   
   # Block curl/wget (security risk)
   if [[ "$COMMAND" =~ curl|wget ]]; then
     echo '{"continue": false, "stopReason": "Network commands disabled", "suppressOutput": false}'
     exit 1
   fi
   
   # Allow operation
   echo '{"continue": true}'
   exit 0
   

3. Install Security Hook:

   chmod +x .claude/hooks/security-check.sh
   # Hook JSON already configured in step 1
   

Outputs:

• Security hook blocking dangerous operations
• Protection against accidental damage
• Audit trail of blocked operations

Validation:

• [ ] Hook blocks system file modifications
• [ ] Hook blocks destructive commands
• [ ] Hook allows safe operations
• [ ] Structured JSON output correct

Time Estimate: 45-60 minutes

---

Operation 3: Create Observability Hook (Notification)

Purpose: Send telemetry to observability platform on important events

Use Case: Track AI agent decisions, tool usage, errors

Process:

1. Create Telemetry Hook:

   {
     "event": "Notification",
     "description": "Send telemetry to observability platform",
     "handler": {
       "command": ".claude/hooks/send-telemetry.sh \"$EVENT_TYPE\" \"$MESSAGE\""
     }
   }
   

2. Create Telemetry Script:

   #!/bin/bash
   # .claude/hooks/send-telemetry.sh
   
   EVENT_TYPE=$1
   MESSAGE=$2
   
   # Send to observability platform (example: Victoria Metrics)
   curl -X POST http://localhost:8428/api/v1/write \
     -d "claude_event{type=\"$EVENT_TYPE\"} 1" \
     -d "claude_message{event=\"$EVENT_TYPE\",msg=\"$MESSAGE\"} 1"
   
   # Or log to file
   echo "$(date -Iseconds) | $EVENT_TYPE | $MESSAGE" >> .claude/telemetry.log
   
   # Or send to webhook
   # curl -X POST https://your-webhook.com/telemetry \
   #   -H "Content-Type: application/json" \
   #   -d "{\"event\": \"$EVENT_TYPE\", \"message\": \"$MESSAGE\"}"
   

3. Test Telemetry:

   # Trigger notification in Claude Code
   # Check telemetry.log or observability platform
   cat .claude/telemetry.log
   

Outputs:

• Telemetry hook sending data
• Observability integration
• Decision tracking

Validation:

• [ ] Hook configured
• [ ] Telemetry script working
• [ ] Data reaches destination
• [ ] No performance impact

Time Estimate: 30-45 minutes

---

Operation 4: Create Validation Hook (PreToolUse)

Purpose: Validate inputs before tool execution

Use Case: Ensure files exist, validate JSON, check permissions

Process:

1. Create Validation Hook:

   {
     "event": "PreToolUse",
     "tools": ["Write"],
     "description": "Validate JSON before writing",
     "handler": {
       "command": ".claude/hooks/validate-json.sh \"$FILE\" \"$CONTENT\""
     },
     "structuredOutput": true
   }
   

2. Create Validation Script:

   #!/bin/bash
   # .claude/hooks/validate-json.sh
   
   FILE=$1
   CONTENT=$2
   
   # Only validate .json files
   if [[ "$FILE" != *.json ]]; then
     echo '{"continue": true}'
     exit 0
   fi
   
   # Validate JSON syntax
   if echo "$CONTENT" | jq empty 2>/dev/null; then
     echo '{"continue": true}'
     exit 0
   else
     echo '{"continue": false, "stopReason": "Invalid JSON syntax", "suppressOutput": false}'
     exit 1
   fi
   

Outputs:

• Validation hook preventing invalid writes
• JSON syntax enforcement
• Error prevention

Validation:

• [ ] Hook validates JSON files
• [ ] Hook allows non-JSON files
• [ ] Invalid JSON blocked
• [ ] Valid JSON allowed

Time Estimate: 20-30 minutes

---

Operation 5: Create MCP Tool Hook (PreToolUse)

Purpose: Control MCP tool access granularly

Use Case: Block specific MCP servers or tools

Process:

1. MCP Tool Targeting:

   {
     "event": "PreToolUse",
     "tools": ["mcp__filesystem__*"],
     "description": "Block all filesystem MCP operations",
     "handler": {
       "command": "echo '{\"continue\": false, \"stopReason\": \"Filesystem MCP disabled\"}'"
     },
     "structuredOutput": true
   }
   

2. Selective MCP Control:

   {
     "event": "PreToolUse",
     "tools": ["mcp__github__delete_repository"],
     "description": "Block dangerous GitHub operations",
     "handler": {
       "command": "echo '{\"continue\": false, \"stopReason\": \"Repository deletion disabled\"}'"
     },
     "structuredOutput": true
   }
   

Outputs:

• Fine-grained MCP control
• Security for MCP operations
• Prevent accidental damage

Validation:

• [ ] MCP tools blocked correctly
• [ ] Tool targeting works (mcp__server__tool pattern)
• [ ] Safe operations allowed

Time Estimate: 20-30 minutes

---

Operation 6: Create Comprehensive Hook (SessionStart)

Purpose: Initialize environment on session start

Use Case: Load context, set variables, validate environment

Process:

1. Session Start Hook:

   {
     "event": "SessionStart",
     "description": "Initialize session with context and validation",
     "handler": {
       "command": ".claude/hooks/session-init.sh"
     }
   }
   

2. Initialization Script:

   #!/bin/bash
   # .claude/hooks/session-init.sh
   
   echo "🚀 Claude Code Session Starting..."
   
   # Load project context
   if [ -f ".claude/PROJECT_CONTEXT.md" ]; then
     echo "📋 Project context available"
   fi
   
   # Check git status
   if git status --porcelain | grep -q .; then
     echo "⚠️  Uncommitted changes detected"
   fi
   
   # Load environment
   if [ -f ".env" ]; then
     echo "🔐 Environment variables available"
   fi
   
   # Run pre-flight checks
   if [ -f ".claude/hooks/pre-flight-check.sh" ]; then
     bash .claude/hooks/pre-flight-check.sh
   fi
   
   echo "✅ Session initialized"
   

Outputs:

• Session initialization automation
• Context loading
• Environment validation

Validation:

• [ ] Hook runs on session start
• [ ] Context loaded correctly
• [ ] Environment validated

Time Estimate: 15-20 minutes

---

Operation 7: Deploy and Manage Hooks

Purpose: Install, update, remove, and audit hooks

Process:

1. Deploy Hook (global or project):

   # Deploy to global (~/.claude/hooks/)
   deploy-hook --global formatting-hook.json
   
   # Deploy to project (.claude/hooks/)
   deploy-hook --project security-hook.json
   

2. List Active Hooks:

   # List all hooks
   ls -la ~/.claude/hooks/
   ls -la .claude/hooks/
   
   # Parse and display
   for hook in .claude/hooks/*.json; do
     echo "Hook: $(basename $hook)"
     jq '.event, .description' $hook
   done
   

3. Validate Hook:

   # Test hook in safe environment
   validate-hook formatting-hook.json
   
   # Expected:
   # ✅ JSON valid
   # ✅ Handler command exists
   # ✅ Event type valid
   # ✅ Structured output correct
   

4. Remove Hook:

   # Disable hook
   rm .claude/hooks/formatting-hook.json
   
   # Or rename to .disabled
   mv .claude/hooks/security-hook.json .claude/hooks/security-hook.json.disabled
   

Outputs:

• Hook deployment automation
• Hook management interface
• Validation before deployment

Validation:

• [ ] Can deploy hooks globally and per-project
• [ ] Can list active hooks
• [ ] Can validate hooks safely
• [ ] Can remove/disable hooks

Time Estimate: 30-45 minutes

---

Operation 8: Security Audit Hooks

Purpose: Review all active hooks for security issues

Process:

1. Audit All Hooks:

   # Scan all hook files
   for hook in ~/.claude/hooks/*.json .claude/hooks/*.json; do
     echo "Auditing: $hook"
   
     # Check for dangerous patterns
     if grep -q "rm -rf\|dd if\|curl.*sudo" $hook; then
       echo "⚠️  Dangerous command detected"
     fi
   
     # Check for credential leaks
     if grep -q "password\|secret\|token\|api_key" $hook; then
       echo "⚠️  Potential credential exposure"
     fi
   
     # Validate JSON structure
     jq empty $hook 2>/dev/null || echo "❌ Invalid JSON"
   done
   

2. Generate Security Report:

   # Hook Security Audit
   
   ## Hooks Scanned: 8
   
   ### HIGH RISK
   None
   
   ### MEDIUM RISK
   1. observability-hook.json
      - Issue: Sends data to external URL
      - Recommendation: Validate URL is trusted
   
   ### LOW RISK
   2. formatting-hook.json
      - Info: Executes npx prettier (safe)
   
   ## Recommendations
   - Review observability destination
   - Consider encrypting telemetry data
   

Outputs:

• Security audit report
• Risk assessment
• Recommendations

Validation:

• [ ] All hooks scanned
• [ ] Security issues identified
• [ ] Recommendations provided

Time Estimate: 20-30 minutes

---

Hook Templates

Template 1: Auto-Format (PostToolUse)

{
  "event": "PostToolUse",
  "tools": ["Write", "Edit"],
  "description": "Auto-format code after Claude writes",
  "handler": {
    "command": "npx prettier --write \"$FILE\"",
    "timeout": 5000
  },
  "filters": {
    "filePatterns": ["**/*.{ts,tsx,js,jsx}"],
    "excludePatterns": ["node_modules/**", "dist/**", "build/**"]
  }
}

Impact: 92% reduction in style review time

---

Template 2: Security Gate (PreToolUse)

{
  "event": "PreToolUse",
  "tools": ["Write", "Edit", "Bash"],
  "description": "Block modifications to production files",
  "handler": {
    "command": ".claude/hooks/security-gate.sh \"$TOOL\" \"$FILE\" \"$COMMAND\""
  },
  "structuredOutput": true
}

Impact: Prevents accidental production damage

---

Template 3: Telemetry (Notification)

{
  "event": "Notification",
  "description": "Send telemetry on important events",
  "handler": {
    "command": ".claude/hooks/telemetry.sh \"$EVENT_TYPE\" \"$MESSAGE\""
  }
}

Impact: Full observability of AI agent behavior

---

Template 4: Validation (PreToolUse)

{
  "event": "PreToolUse",
  "tools": ["Write"],
  "description": "Validate JSON/YAML before writing",
  "handler": {
    "command": ".claude/hooks/validate-syntax.sh \"$FILE\" \"$CONTENT\""
  },
  "structuredOutput": true
}

Impact: Prevent invalid file writes

---

Template 5: Context Loading (SessionStart)

{
  "event": "SessionStart",
  "description": "Load project context on session start",
  "handler": {
    "command": ".claude/hooks/load-context.sh"
  }
}

Impact: Automatic context initialization

---

Template 6: Cleanup (SessionEnd)

{
  "event": "SessionEnd",
  "description": "Save state and cleanup on session end",
  "handler": {
    "command": ".claude/hooks/session-cleanup.sh"
  }
}

Impact: Automatic state preservation

---

Best Practices

1. Structured JSON Output (For Control)

Standard Exit Codes (Simple):

• 0: Continue
• Non-zero: Block

Structured JSON (Advanced):

{
  "continue": false,
  "stopReason": "Custom blocking reason shown to user",
  "suppressOutput": true
}

When to Use:

• Need custom error messages
• Want to suppress default output
• Complex control flow

---

2. MCP Tool Targeting

Patterns:

• mcp__*: All MCP tools
• mcp__server__*: All tools from specific server
• mcp__server__tool: Specific tool only

Examples:

// Block all filesystem MCP
"tools": ["mcp__filesystem__*"]

// Block specific GitHub operation
"tools": ["mcp__github__delete_repository"]

// Allow specific, block others
"tools": ["mcp__github__*"],
"handler": "allow-list-check.sh"

---

3. File Pattern Filters

{
  "filePatterns": [
    "src/**/*.ts",           // Include source files
    "tests/**/*.test.ts"     // Include tests
  ],
  "excludePatterns": [
    "node_modules/**",       // Exclude dependencies
    "**/*.min.js",           // Exclude minified
    ".git/**"                // Exclude git internals
  ]
}

Tip: Start inclusive, add exclusions as needed

---

4. Performance Considerations

Hook Execution:

• Hooks run synchronously (blocking)
• Keep handlers fast (<5 seconds)
• Use timeouts to prevent hangs
• Async operations: spawn background process, return immediately

Example (Fast hook):

#!/bin/bash
# Quick validation
if [ ! -f "$FILE" ]; then
  echo '{"continue": false, "stopReason": "File does not exist"}'
  exit 1
fi
echo '{"continue": true}'
exit 0

Example (Slow operation - backgrounded):

#!/bin/bash
# Start slow operation in background
(sleep 10 && heavy-operation.sh "$FILE") &

# Return immediately
echo '{"continue": true}'
exit 0

---

5. Security Best Practices

Never in hooks:

• Hardcode credentials
• Execute untrusted input
• Modify critical system files
• Expose sensitive data in logs

Always in hooks:

• Validate all inputs
• Use allowlists (not denylists)
• Log security events
• Fail securely (deny by default)

---

Common Hook Patterns

Pattern 1: Code Quality Enforcement

PostToolUse Chain:

Write/Edit → Prettier (format) → ESLint (lint) → TypeScript (type check)

Implementation:

[
  {
    "event": "PostToolUse",
    "tools": ["Write", "Edit"],
    "handler": "npx prettier --write \"$FILE\""
  },
  {
    "event": "PostToolUse",
    "tools": ["Write", "Edit"],
    "handler": "npx eslint --fix \"$FILE\""
  }
]

Result: All AI code automatically meets quality standards

---

Pattern 2: Test-on-Save

PostToolUse Test Runner:

{
  "event": "PostToolUse",
  "tools": ["Write", "Edit"],
  "description": "Run tests after code changes",
  "handler": {
    "command": ".claude/hooks/run-tests.sh \"$FILE\""
  },
  "filters": {
    "filePatterns": ["src/**/*.ts"]
  }
}

run-tests.sh:

#!/bin/bash
FILE=$1

# Find corresponding test file
TEST_FILE="${FILE/.ts/.test.ts}"
TEST_FILE="${TEST_FILE/src\//tests\/}"

if [ -f "$TEST_FILE" ]; then
  npm test -- "$TEST_FILE" --silent
fi

Result: Immediate test feedback on every change

---

Pattern 3: Security Guardrails

Multi-Layer Security:

PreToolUse → Path traversal check → Permission check → Allowlist check → Allow/Block

Result: Comprehensive security enforcement

---

Pattern 4: Observability Pipeline

Multi-Hook Telemetry:

SessionStart → Log session init
PreToolUse → Log tool attempts
PostToolUse → Log tool results + timing
Notification → Log important events
SessionEnd → Log session summary + metrics

Result: Complete observability of AI behavior

---

Troubleshooting

Hook Not Firing

Checklist:

• [ ] Hook file in correct location (~/.claude/hooks/ or .claude/hooks/)
• [ ] Hook file is valid JSON (test with jq empty hook.json)
• [ ] Event type correct (UserPromptSubmit, PreToolUse, etc.)
• [ ] Tool name matches (case-sensitive)
• [ ] Claude Code version supports hooks (June 2025+)

Debug:

# Test hook JSON
jq empty .claude/hooks/my-hook.json

# Check hook location
ls -la .claude/hooks/

# Test handler command manually
bash .claude/hooks/handler.sh "test args"

---

Hook Blocking Everything

Issue: PreToolUse hook with {"continue": false} blocks all operations

Fix:

• Check handler script logic
• Ensure conditions are correct
• Add fallback: if unsure, allow (fail open vs. fail closed)
• Test with specific files before deploying

---

Performance Impact

Issue: Hook adds 2-5 seconds to every operation

Solutions:

• Optimize handler script (remove slow operations)
• Use background processes for slow tasks
• Add caching (don't re-validate unchanged files)
• Set timeout limits
• Consider removing hook if not valuable

---

Appendix A: Hook Event Reference

UserPromptSubmit

Trigger: Before Claude processes user prompt Use: Validate prompts, inject context, enhance prompts Variables: $PROMPT

PreToolUse

Trigger: Before tool execution Use: Security gates, validation, logging Variables: $TOOL, $FILE, $COMMAND, $CONTENT Control: Can block operation

PostToolUse

Trigger: After tool execution Use: Auto-format, linting, testing, cleanup Variables: $TOOL, $FILE, $RESULT

PermissionRequest

Trigger: When Claude requests permissions Use: Auto-approve safe operations, log requests Variables: $PERMISSION_TYPE

Notification

Trigger: Important events Use: Telemetry, alerting, logging Variables: $EVENT_TYPE, $MESSAGE

SessionStart

Trigger: Session initialization Use: Load context, validate environment Variables: None

SessionEnd

Trigger: Session termination Use: Save state, cleanup, metrics Variables: None

Stop

Trigger: Conversation stop Use: Final cleanup, state saving Variables: $REASON

---

Appendix B: Structured JSON Control

Basic Control (Exit Codes)

# Allow
exit 0

# Block
exit 1

Advanced Control (JSON)

{
  "continue": boolean,        // Allow operation?
  "stopReason": "string",     // Why blocked (shown to user)
  "suppressOutput": boolean   // Hide default blocking message?
}

When to Use JSON:

• Custom error messages
• Silent blocking
• Complex control logic

---

Quick Reference

The 8 Hook Events

| Event | When | Use For | Can Block? | |-------|------|---------|------------| | UserPromptSubmit | Before prompt processed | Prompt validation/enhancement | Yes | | PreToolUse | Before tool runs | Security, validation | Yes | | PostToolUse | After tool runs | Format, lint, test | No | | PermissionRequest | Permissions requested | Auto-approve, logging | Yes | | Notification | Important events | Telemetry, alerts | No | | SessionStart | Session begins | Init, context load | No | | SessionEnd | Session ends | Cleanup, save state | No | | Stop | Conversation stops | Final cleanup | No |

Common Use Cases

| Use Case | Hook Event | Typical Impact | |----------|------------|----------------| | Auto-format code | PostToolUse | 92% style review reduction | | Security gates | PreToolUse | Prevent production damage | | Run tests on save | PostToolUse | Immediate feedback | | Observability | Notification | Full behavior tracking | | JSON validation | PreToolUse | Prevent invalid writes | | Context loading | SessionStart | Auto-initialization | | State saving | SessionEnd | Preserve progress | | MCP control | PreToolUse | Granular tool access |

---

hooks-manager enables transformative automation in Claude Code through event-driven hooks, reducing manual work by up to 92% while enforcing security, quality, and observability standards.

For templates, see examples/. For troubleshooting, see Troubleshooting section.