/create-hook

name: create-hook
description: Create and configure git hooks with intelligent project analysis, suggestions, and automated testing
argument-hint: Optional hook type or description of desired behavior

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?

• `PreToolUse`: Before file operations (can block)
• `PostToolUse`: After file operations (feedback/fixes)
• `UserPromptSubmit`: Before processing requests
• Other event types as needed

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

3. **Scope**: `global`, `project`, or `project-local`

4. **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

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

• PreToolUse: Can block operations (security, validation)
• PostToolUse: Usually provide feedback only

6. **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

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

• Recommend YES for formatting, routine checks
• Recommend NO for security alerts, critical errors

8. **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

• _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