Creating Claude Code Hooks

Use this skill when creating, improving, or publishing Claude Code hooks. Provides essential guidance on hook format, event handling, I/O conventions, and package structure.

When to Use This Skill

Activate this skill when:

User asks to create a new Claude Code hook
User wants to publish a hook as a PRPM package
User needs to understand hook format or events
User is troubleshooting hook execution
User asks about hook vs skill vs command differences

Quick Reference

Hook File Format

Aspect	Requirement
Location	`.claude/hooks/<event-name>`
Format	Executable file (shell, TypeScript, Python, etc.)
Permissions	Must be executable ( `chmod +x` )
Shebang	Required ( `#!/bin/bash` or `#!/usr/bin/env node` )
Input	JSON via stdin
Output	Text via stdout (shown to user)
Exit Codes	`0` = success, `2` = block, other = error

Available Events

Event	When It Fires	Common Use Cases
`session-start`	New session begins	Environment setup, logging, checks
`user-prompt-submit`	Before user input processes	Validation, enhancement, filtering
`tool-call`	Before tool execution	Permission checks, logging, modification
`assistant-response`	After assistant responds	Formatting, logging, cleanup

Hook Format Requirements

File Location

Project hooks:

.claude/hooks/session-start
.claude/hooks/user-prompt-submit

User-global hooks:

~/.claude/hooks/session-start
~/.claude/hooks/tool-call

Executable Requirements

Every hook MUST:

Have a shebang line:

bash

#!/bin/bash
# or
#!/usr/bin/env node
# or
#!/usr/bin/env python3

Be executable:

bash

chmod +x .claude/hooks/session-start

Handle JSON input from stdin:

bash

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

Exit with appropriate code:

bash

exit 0  # Success
exit 2  # Block operation
exit 1  # Error (logs but continues)

Input/Output Format

JSON Input Structure

Hooks receive JSON via stdin with event-specific data:

json

{
  "event": "tool-call",
  "timestamp": "2025-01-15T10:30:00Z",
  "session_id": "abc123",
  "current_dir": "/path/to/project",
  "input": {
    "file_path": "/path/to/file.ts",
    "command": "npm test",
    "old_string": "...",
    "new_string": "..."
  }
}

Stdout Output

Normal output shows in transcript
Empty output runs silently
Use stderr (
```
>&2
```
) for errors

Exit Codes

Code	Meaning	Behavior
`0`	Success	Continue normally
`2`	Block	Stop operation, show error
`1` or other	Error	Log error, continue

Schema Validation

Hooks should validate against the JSON schema:

Schema URL: https://github.com/pr-pm/prpm/blob/main/packages/converters/schemas/claude-hook.schema.json

Required frontmatter fields:

```
name
```
- Hook identifier (lowercase, hyphens only)
```
description
```
- What the hook does
```
event
```
- Event type (optional, inferred from filename)
```
language
```
- bash, typescript, javascript, python, binary (optional)
```
hookType: "hook"
```
- For round-trip conversion

Common Mistakes

Mistake	Problem	Solution
Not quoting variables	Breaks on spaces	Always use `"$VAR"`
Missing shebang	Won't execute	Add `#!/bin/bash`
Not executable	Permission denied	Run `chmod +x hook-file`
Logging to stdout	Clutters transcript	Use stderr: `echo "log" >&2`
Wrong exit code	Doesn't block when needed	Use `exit 2` to block
No input validation	Security risk	Always validate JSON fields
Slow operations	Blocks Claude	Run in background or use PostToolUse
Absolute paths missing	Can't find scripts	Use `$CLAUDE_PLUGIN_ROOT`

Basic Hook Examples

Shell Script Hook

bash

#!/bin/bash
# .claude/hooks/session-start

# Log session start
echo "Session started at $(date)" >> ~/.claude/session.log

# Check environment
if ! command -v node &> /dev/null; then
  echo "Warning: Node.js not installed" >&2
fi

# Output to user
echo "Development environment ready"
exit 0

TypeScript Hook

typescript

#!/usr/bin/env node
// .claude/hooks/user-prompt-submit

import { readFileSync } from 'fs';

// Read JSON from stdin
const input = readFileSync(0, 'utf-8');
const data = JSON.parse(input);

// Validate prompt
if (data.prompt.includes('API_KEY')) {
  console.error('Warning: Prompt may contain secrets');
  process.exit(2); // Block
}

console.log('Prompt validated');
process.exit(0);

Best Practices

1. Keep Hooks Fast

Target < 100ms for PreToolUse hooks:

Cache results where possible
Run heavy operations in background
Use specific matchers, not wildcards

2. Handle Errors Gracefully

bash

# Check dependencies exist
if ! command -v jq &> /dev/null; then
  echo "jq not installed, skipping" >&2
  exit 0
fi

# Validate input
FILE=$(echo "$INPUT" | jq -r '.input.file_path // empty')
if [[ -z "$FILE" ]]; then
  echo "No file path provided" >&2
  exit 1
fi

3. Use Shebangs

Always start with shebang:

bash

#!/bin/bash
#!/usr/bin/env node
#!/usr/bin/env python3

4. Secure Sensitive Files

bash

BLOCKED=(".env" ".env.*" "*.pem" "*.key")
for pattern in "${BLOCKED[@]}"; do
  case "$FILE" in
    $pattern)
      echo "Blocked: $FILE is sensitive" >&2
      exit 2
      ;;
  esac
done

5. Quote All Variables

bash

# WRONG - breaks on spaces
prettier --write $FILE

# RIGHT - handles spaces
prettier --write "$FILE"

6. Log for Debugging

bash

LOG_FILE=~/.claude-hooks/debug.log

# Log to file
echo "[$(date)] Processing $FILE" >> "$LOG_FILE"

# Log to stderr (shows in transcript)
echo "Hook running..." >&2

Publishing as PRPM Package

Package Structure

my-hook/
├── prpm.json          # Package manifest
├── HOOK.md            # Hook documentation
└── hook-script.sh     # Hook executable

prpm.json

json

{
  "name": "@username/hook-name",
  "version": "1.0.0",
  "description": "Brief description shown in search",
  "author": "Your Name",
  "format": "claude",
  "subtype": "hook",
  "tags": ["automation", "security", "formatting"],
  "main": "HOOK.md"
}

HOOK.md Format

markdown

---
name: session-logger
description: Logs session start/end times for tracking
event: SessionStart
language: bash
hookType: hook
---

# Session Logger Hook

Logs Claude Code session activity for tracking and debugging.

## Installation

This hook will be installed to `.claude/hooks/session-start`.

## Behavior

- Logs session start time to `~/.claude/session.log`
- Displays environment status
- Runs silent dependency checks

## Requirements

- bash 4.0+
- write access to `~/.claude/`

## Source Code

\`\`\`bash
#!/bin/bash
echo "Session started at $(date)" >> ~/.claude/session.log
echo "Environment ready"
exit 0
\`\`\`

Publishing Process

bash

# Test locally first
prpm test

# Publish to registry
prpm publish

# Version bumps
prpm publish patch  # 1.0.0 -> 1.0.1
prpm publish minor  # 1.0.0 -> 1.1.0
prpm publish major  # 1.0.0 -> 2.0.0

Security Requirements

Input Validation

bash

# Parse JSON safely
INPUT=$(cat)
if ! FILE=$(echo "$INPUT" | jq -r '.input.file_path // empty' 2>&1); then
  echo "JSON parse failed" >&2
  exit 1
fi

# Validate field exists
[[ -n "$FILE" ]] || exit 1

Path Sanitization

bash

# Prevent directory traversal
if [[ "$FILE" == *".."* ]]; then
  echo "Path traversal detected" >&2
  exit 2
fi

# Keep in project directory
if [[ "$FILE" != "$CLAUDE_PROJECT_DIR"* ]]; then
  echo "File outside project" >&2
  exit 2
fi

User Confirmation

Claude Code automatically:

Requires confirmation before installing hooks
Shows hook source code to user
Warns about hook execution
Displays hook output in transcript

Hooks vs Skills vs Commands

Feature	Hooks	Skills	Commands
Format	Executable code	Markdown	Markdown
Trigger	Automatic (events)	Automatic (context)	Manual ( `/command` )
Language	Any executable	N/A	N/A
Use Case	Automation, validation	Reference, patterns	Quick tasks
Security	Requires confirmation	No special permissions	Inherits from session

Examples:

Hook: Auto-format files on save
Skill: Reference guide for testing patterns
Command:
```
/review-pr
```
quick code review

Related Resources

claude-hook-writer skill - Detailed hook development guidance
typescript-hook-writer skill - TypeScript-specific hook development
Claude Code Docs
Schema

Checklist for New Hooks

Before publishing:

Shebang line included
File is executable (
```
chmod +x
```
)
Validates all stdin input
Quotes all variables
Handles missing dependencies gracefully
Uses appropriate exit codes
Logs errors to stderr or file
Tests with edge cases (spaces, Unicode, missing fields)
Documents dependencies in HOOK.md
Includes installation instructions
Source code included in documentation
Clear description and tags in prpm.json
Version number is semantic

creating-claude-hooks

NPX Install

Tags

SKILL.md Content

Creating Claude Code Hooks

When to Use This Skill

Quick Reference

Hook File Format

Available Events

Hook Format Requirements

File Location

Executable Requirements

Input/Output Format

JSON Input Structure

Stdout Output

Exit Codes

Schema Validation

Common Mistakes

Basic Hook Examples

Shell Script Hook

TypeScript Hook

Best Practices

1. Keep Hooks Fast

2. Handle Errors Gracefully

3. Use Shebangs

4. Secure Sensitive Files

5. Quote All Variables

6. Log for Debugging

Publishing as PRPM Package

Package Structure

prpm.json

HOOK.md Format

Publishing Process

Security Requirements

Input Validation

Path Sanitization

User Confirmation

Hooks vs Skills vs Commands

Related Resources

Checklist for New Hooks