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
// 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.

---

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt Use this file to discover all available pages before exploring further.

Automate workflows with hooks

Run shell commands automatically when Claude Code edits files, finishes tasks, or needs input. Format code, send notifications, validate commands, and enforce project rules.

Hooks are user-defined shell commands that execute at specific points in Claude Code's lifecycle. They provide deterministic control over Claude Code's behavior, ensuring certain actions always happen rather than relying on the LLM to choose to run them. Use hooks to enforce project rules, automate repetitive tasks, and integrate Claude Code with your existing tools.

For decisions that require judgment rather than deterministic rules, you can also use prompt-based hooks or agent-based hooks that use a Claude model to evaluate conditions.

For other ways to extend Claude Code, see skills for giving Claude additional instructions and executable commands, subagents for running tasks in isolated contexts, and plugins for packaging extensions to share across projects.

Set up your first hook

The fastest way to create a hook is through the /hooks interactive menu in Claude Code. This walkthrough creates a desktop notification hook, so you get alerted whenever Claude is waiting for your input instead of watching the terminal.

<Tabs>
  <Tab title="macOS">
    Uses [`osascript`](https://ss64.com/mac/osascript.html) to trigger a native macOS notification through AppleScript:

    ```
    osascript -e 'display notification "Claude Code needs your attention" with title "Claude Code"'
    ```
  </Tab>

  <Tab title="Linux">
    Uses `notify-send`, which is pre-installed on most Linux desktops with a notification daemon:

    ```
    notify-send 'Claude Code' 'Claude Code needs your attention'
    ```
  </Tab>

  <Tab title="Windows (PowerShell)">
    Uses PowerShell to show a native message box through .NET's Windows Forms:

    ```
    powershell.exe -Command "[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')"
    ```
  </Tab>
</Tabs>

What you can automate

Hooks let you run code at key points in Claude Code's lifecycle: format files after edits, block commands before they execute, send notifications when Claude needs input, inject context at session start, and more. For the full list of hook events, see the Hooks reference.

Each example includes a ready-to-use configuration block that you add to a settings file. The most common patterns:

• Get notified when Claude needs input
• Auto-format code after edits
• Block edits to protected files
• Re-inject context after compaction

Get notified when Claude needs input

Get a desktop notification whenever Claude finishes working and needs your input, so you can switch to other tasks without checking the terminal.

This hook uses the Notification event, which fires when Claude is waiting for input or permission. Each tab below uses the platform's native notification command. Add this to ~/.claude/settings.json, or use the interactive walkthrough above to configure it with /hooks:

Auto-format code after edits

Automatically run Prettier on every file Claude edits, so formatting stays consistent without manual intervention.

This hook uses the PostToolUse event with an Edit|Write matcher, so it runs only after file-editing tools. The command extracts the edited file path with jq and passes it to Prettier. Add this to .claude/settings.json in your project root:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

Block edits to protected files

Prevent Claude from modifying sensitive files like .env, package-lock.json, or anything in .git/. Claude receives feedback explaining why the edit was blocked, so it can adjust its approach.

This example uses a separate script file that the hook calls. The script checks the target file path against a list of protected patterns and exits with code 2 to block the edit.

```bash  theme={null}
#!/bin/bash
# protect-files.sh

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")

for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
    exit 2
  fi
done

exit 0
```

```bash  theme={null}
chmod +x .claude/hooks/protect-files.sh
```

```json  theme={null}
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}
```

Re-inject context after compaction

When Claude's context window fills up, compaction summarizes the conversation to free space. This can lose important details. Use a SessionStart hook with a compact matcher to re-inject critical context after every compaction.

Any text your command writes to stdout is added to Claude's context. This example reminds Claude of project conventions and recent work. Add this to .claude/settings.json in your project root:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Reminder: use Bun, not npm. Run bun test before committing. Current sprint: auth refactor.'"
          }
        ]
      }
    ]
  }
}

You can replace the echo with any command that produces dynamic output, like git log --oneline -5 to show recent commits. For injecting context on every session start, consider using CLAUDE.md instead. For environment variables, see CLAUDE_ENV_FILE in the reference.

How hooks work

Hook events fire at specific lifecycle points in Claude Code. When an event fires, all matching hooks run in parallel, and identical hook commands are automatically deduplicated. The table below shows each event and when it triggers:

Event	When it fires
SessionStart	When a session begins or resumes
UserPromptSubmit	When you submit a prompt, before Claude processes it
PreToolUse	Before a tool call executes. Can block it
PermissionRequest	When a permission dialog appears
PostToolUse	After a tool call succeeds
PostToolUseFailure	After a tool call fails
Notification	When Claude Code sends a notification
SubagentStart	When a subagent is spawned
SubagentStop	When a subagent finishes
Stop	When Claude finishes responding
PreCompact	Before context compaction
SessionEnd	When a session terminates

Each hook has a type that determines how it runs. Most hooks use "type": "command", which runs a shell command. Two other options use a Claude model to make decisions: "type": "prompt" for single-turn evaluation and "type": "agent" for multi-turn verification with tool access. See Prompt-based hooks and Agent-based hooks for details.

Read input and return output

Hooks communicate with Claude Code through stdin, stdout, stderr, and exit codes. When an event fires, Claude Code passes event-specific data as JSON to your script's stdin. Your script reads that data, does its work, and tells Claude Code what to do next via the exit code.

Hook input

Every event includes common fields like session_id and cwd, but each event type adds different data. For example, when Claude runs a Bash command, a PreToolUse hook receives something like this on stdin:

{
  "session_id": "abc123",          // unique ID for this session
  "cwd": "/Users/sarah/myproject", // working directory when the event fired
  "hook_event_name": "PreToolUse", // which event triggered this hook
  "tool_name": "Bash",             // the tool Claude is about to use
  "tool_input": {                  // the arguments Claude passed to the tool
    "command": "npm test"          // for Bash, this is the shell command
  }
}

Your script can parse that JSON and act on any of those fields. UserPromptSubmit hooks get the prompt text instead, SessionStart hooks get the source (startup, resume, compact), and so on. See Common input fields in the reference for shared fields, and each event's section for event-specific schemas.

Hook output

Your script tells Claude Code what to do next by writing to stdout or stderr and exiting with a specific code. For example, a PreToolUse hook that wants to block a command:

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q "drop table"; then
  echo "Blocked: dropping tables is not allowed" >&2  # stderr becomes Claude's feedback
  exit 2                                               # exit 2 = block the action
fi

exit 0  # exit 0 = let it proceed

The exit code determines what happens next:

• Exit 0: the action proceeds. For UserPromptSubmit and SessionStart hooks, anything you write to stdout is added to Claude's context.
• Exit 2: the action is blocked. Write a reason to stderr, and Claude receives it as feedback so it can adjust.
• Any other exit code: the action proceeds. Stderr is logged but not shown to Claude. Toggle verbose mode with Ctrl+O to see these messages in the transcript.

Structured JSON output

Exit codes give you two options: allow or block. For more control, exit 0 and print a JSON object to stdout instead.

For example, a PreToolUse hook can deny a tool call and tell Claude why, or escalate it to the user for approval:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Use rg instead of grep for better performance"
  }
}

Claude Code reads permissionDecision and cancels the tool call, then feeds permissionDecisionReason back to Claude as feedback. These three options are specific to PreToolUse:

• "allow": proceed without showing a permission prompt
• "deny": cancel the tool call and send the reason to Claude
• "ask": show the permission prompt to the user as normal

Other events use different decision patterns. For example, PostToolUse and Stop hooks use a top-level decision: "block" field, while PermissionRequest uses hookSpecificOutput.decision.behavior. See the summary table in the reference for a full breakdown by event.

For UserPromptSubmit hooks, use additionalContext instead to inject text into Claude's context. Prompt-based hooks (type: "prompt") handle output differently: see Prompt-based hooks.

Filter hooks with matchers