Skip to content

Create Hook Command

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

Your Task (/create-hook)

  1. Analyze environment - Detect tooling and existing hooks
  2. Suggest hooks - Based on your project configuration
  3. Configure hook - Ask targeted questions and create the script
  4. 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:

  1. Trigger timing: When should it run?
  2. PreToolUse: Before file operations (can block)
  3. PostToolUse: After file operations (feedback/fixes)
  4. UserPromptSubmit: Before processing requests

  5. Other event types as needed

  6. Tool matcher: Which tools should trigger it? (Write, Edit, Bash, * etc)

  7. Scope: global, project, or project-local

  8. Response approach:

  9. Exit codes only: Simple (exit 0 = success, exit 2 = block in PreToolUse)
  10. JSON response: Advanced control (blocking, context, decisions)

  11. Guide based on complexity: simple pass/fail → exit codes, rich feedback → JSON

  12. Blocking behavior (if relevant): "Should this stop operations when issues are found?"

  13. PreToolUse: Can block operations (security, validation)

  14. PostToolUse: Usually provide feedback only

  15. Claude integration (CRITICAL): "Should Claude Code automatically see and fix issues this hook detects?"

  16. If YES: Use additionalContext for error communication

  17. If NO: Use suppressOutput: true for silent operation

  18. Context pollution: "Should successful operations be silent to avoid noise?"

  19. Recommend YES for formatting, routine checks

  20. Recommend NO for security alerts, critical errors

  21. 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:

  1. Test expected success scenario - Create conditions where hook should pass
  2. 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.