Create Hook Command

Analyze the project, suggest practical hooks, and create them with proper testing.

Your Task (/create-hook)

Analyze environment - Detect tooling and existing hooks
Suggest hooks - Based on your project configuration
Configure hook - Ask targeted questions and create the script
Test & validate - Ensure the hook works correctly

Your Workflow

1. Environment Analysis & Suggestions

Automatically detect the project tooling and suggest relevant hooks:

When TypeScript is detected (tsconfig.json):

PostToolUse hook: "Type-check files after editing"
PreToolUse hook: "Block edits with type errors"

When Prettier is detected (.prettierrc, prettier.config.js):

PostToolUse hook: "Auto-format files after editing"
PreToolUse hook: "Require formatted code"

When ESLint is detected (.eslintrc.*):

PostToolUse hook: "Lint and auto-fix after editing"
PreToolUse hook: "Block commits with linting errors"

When package.json has scripts:

test script → "Run tests before commits"
build script → "Validate build before commits"

When a git repository is detected:

PreToolUse/Bash hook: "Prevent commits with secrets"
PostToolUse hook: "Security scan on file changes"

Decision Tree:

Project has TypeScript? → Suggest type checking hooks
Project has formatter? → Suggest formatting hooks
Project has tests? → Suggest test validation hooks
Security sensitive? → Suggest security hooks
+ Scan for additional patterns and suggest custom hooks based on:
  - Custom scripts in package.json
  - Unique file patterns or extensions
  - Development workflow indicators
  - Project-specific tooling configurations

2. Hook Configuration

Start by asking: "What should this hook do?" and offer relevant suggestions from your analysis.

Then understand the context from the user's description and only ask about details you're unsure about:

Trigger timing: When should it run?
- PreToolUse: Before file operations (can block)
- PostToolUse: After file operations (feedback/fixes)
- UserPromptSubmit: Before processing requests
- Other event types as needed
Tool matcher: Which tools should trigger it? (Write, Edit, Bash, * etc)
Scope: global, project, or project-local
Response approach:
- Exit codes only: Simple (exit 0 = success, exit 2 = block in PreToolUse)
- JSON response: Advanced control (blocking, context, decisions)
- Guide based on complexity: simple pass/fail → exit codes, rich feedback → JSON
Blocking behavior (if relevant): "Should this stop operations when issues are found?"
- PreToolUse: Can block operations (security, validation)
- PostToolUse: Usually provide feedback only
Claude integration (CRITICAL): "Should Claude Code automatically see and fix issues this hook detects?"
- If YES: Use additionalContext for error communication
- If NO: Use suppressOutput: true for silent operation
Context pollution: "Should successful operations be silent to avoid noise?"
- Recommend YES for formatting, routine checks
- Recommend NO for security alerts, critical errors
File filtering: "What file types should this hook process?"

3. Hook Creation

You should:

Create hooks directory: ~/.claude/hooks/ or .claude/hooks/ based on scope
Generate script: Create hook script with:
- Proper shebang and executable permissions
- Project-specific commands (use detected config paths)
- Comments explaining the hook's purpose
Update settings: Add hook configuration to appropriate settings.json
Use absolute paths: Avoid relative paths to scripts and executables. Use $CLAUDE_PROJECT_DIR to reference project root
Offer validation: Ask if the user wants you to test the hook

Key Implementation Standards:

Read JSON from stdin (never use argv)
Use top-level additionalContext/systemMessage for Claude communication
Include suppressOutput: true for successful operations
Provide specific error counts and actionable feedback
Focus on changed files rather than entire codebase
Support common development workflows

⚠️ CRITICAL: Input/Output Format

This is where most hook implementations fail. Pay extra attention to:

Input: Reading JSON from stdin correctly (not argv)
Output: Using correct top-level JSON structure for Claude communication
Documentation: Consulting official docs for exact schemas when in doubt

4. Testing & Validation

CRITICAL: Test both happy and sad paths:

Happy Path Testing:

Test expected success scenario - Create conditions where hook should pass
- Examples: TypeScript (valid code), Linting (formatted code), Security (safe commands)

Sad Path Testing: 2. Test expected failure scenario - Create conditions where hook should fail/warn

Examples: TypeScript (type errors), Linting (unformatted code), Security (dangerous operations)

Verification Steps: 3. Verify expected behavior: Check if it blocks/warns/provides context as intended

Example Testing Process:

For a hook preventing file deletion: Create a test file, attempt the protected action, and verify the hook prevents it

If Issues Occur, you should:

Check hook registration in settings
Verify script permissions (chmod +x)
Test with simplified version first
Debug with detailed hook execution analysis

Hook Templates

Type Checking (PostToolUse)

#!/usr/bin/env node
// Read stdin JSON, check .ts/.tsx files only
// Run: npx tsc --noEmit --pretty
// Output: JSON with additionalContext for errors

Auto-formatting (PostToolUse)

#!/usr/bin/env node
// Read stdin JSON, check supported file types
// Run: npx prettier --write [file]
// Output: JSON with suppressOutput: true

Security Scanning (PreToolUse)

#!/bin/bash
# Read stdin JSON, check for secrets/keys
# Block if dangerous patterns found
# Exit 2 to block, 0 to continue

Complete templates available at: https://docs.claude.com/en/docs/claude-code/hooks#examples

Quick Reference

📖 Official Docs: https://docs.claude.com/en/docs/claude-code/hooks.md

Common Patterns:

stdin input: JSON.parse(process.stdin.read())
File filtering: Check extensions before processing
Success response: {continue: true, suppressOutput: true}
Error response: {continue: true, additionalContext: "error details"}
Block operation: exit(2) in PreToolUse hooks

Hook Types by Use Case:

Code Quality: PostToolUse for feedback and fixes
Security: PreToolUse to block dangerous operations
CI/CD: PreToolUse to validate before commits
Development: PostToolUse for automated improvements

Hook Execution Best Practices:

Hooks run in parallel according to official documentation
Design for independence since execution order isn't guaranteed
Plan hook interactions carefully when multiple hooks affect the same files

Success Criteria

✅ Hook created successfully when:

Script has executable permissions
Registered in correct settings.json
Responds correctly to test scenarios
Integrates properly with Claude for automated fixes
Follows project conventions and detected tooling

Result: The user gets a working hook that enhances their development workflow with intelligent automation and quality checks.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!