Automate Workflows with Hooks

What hooks enable

Hooks add an automation layer to Claude Code without modifying its code. Common uses:

• Auto-format files after writing
• Block dangerous commands (rm -rf, git push --force)
• Generate session reports on stop
• Preserve key info before compaction
• Ask an LLM “is this change safe?” and block on the answer

Configuration locations

Basic structure

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_response.filePath // .tool_input.file_path' | { read -r f; prettier --write \"$f\"; } 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

Common events

Three hook types

1. command — run a shell command

{
  "type": "command",
  "command": "jq -r '.tool_input.command' >> ~/.claude/bash-log.txt"
}

Receives the event JSON on stdin. Use jq to extract fields.

2. prompt — ask an LLM

{
  "type": "prompt",
  "prompt": "Decide if this command makes a destructive system change. Answer 'block' or 'allow': $ARGUMENTS"
}

The LLM answer drives block/allow. Runs on a small fast model.

3. agent — run an agent

{
  "type": "agent",
  "prompt": "Verify that unit tests were added alongside the file changes"
}

For complex verification. Higher token cost.

Example: block dangerous commands

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Decide if this shell command permanently deletes data or makes hard-to-reverse changes. Answer 'block' or 'allow': $ARGUMENTS"
          }
        ]
      }
    ]
  }
}

Example: auto-format after write

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_response.filePath // .tool_input.file_path' | { read -r f; case \"$f\" in *.ts|*.tsx|*.js|*.jsx|*.json|*.md) prettier --write \"$f\";; esac; } 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

Per-extension formatter selection.

Example: stop-time report

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"systemMessage\": \"Session ended — review changed files before closing.\"}'"
          }
        ]
      }
    ]
  }
}

JSON output with systemMessage is shown to the user.

Debugging checklist

1. JSON syntax — jq . settings.json to validate
2. Matcher pattern — exact tool name (e.g. Write|Edit)
3. Test the command directly — echo '{"tool_input":{"file_path":"test.ts"}}' | <hook command>
4. Restart — new hooks need a Claude Code restart or one open of /hooks so the watcher picks them up
5. Debug mode — claude --debug shows hook execution logs

Use hookify

hookify generates hooks from natural language. If hand-writing JSON feels heavy, draft with hookify first and apply the result to settings.json.

Next steps

• hookify — define hooks in plain language
• Claude Code Setup — project-aware hook recommendations
• Writing a Great CLAUDE.md — separate hook automation from CLAUDE.md rules