← BLOG
Tutorial

Automate Your Dev Workflow with Claude Code Hooks

Hooks let you run custom shell commands when Claude Code takes specific actions. Auto-format on save, block dangerous edits, or inject context automatically.

Claude Code Hooks are shell commands that execute automatically in response to events. When Claude Code edits a file, runs a command, or starts a session, your hooks fire. This lets you build guardrails, enforce standards, and automate repetitive setup without manual intervention.

What hook events are available?

EventWhen it firesCommon use case
PreToolUseBefore Claude executes a toolBlock dangerous operations, validate inputs
PostToolUseAfter Claude executes a toolAuto-format edited files, run linters
NotificationWhen Claude sends a notificationLog to file, send to Slack
SessionStartWhen a new session beginsInject context, check environment
ConfigChangeWhen settings changeValidate configuration

How do you create a hook?

Use the interactive menu or edit settings.json directly:

bash
# Interactive hook setup
claude /hooks

# Or edit settings.json directly
# Project: .claude/settings.json
# Global: ~/.claude/settings.json

Here's a settings.json with hooks configured:

json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npx prettier --write "$CLAUDE_FILE_PATH"",
        "description": "Auto-format edited files with Prettier"
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "echo $CLAUDE_FILE_PATH | grep -q \.env && echo 'BLOCKED: Cannot edit .env files' && exit 1 || exit 0",
        "description": "Block edits to .env files"
      }
    ],
    "SessionStart": [
      {
        "command": "cat .claude/context-injection.md",
        "description": "Inject additional context at session start"
      }
    ]
  }
}

What are the most useful hooks?

1. Auto-format on edit

Run Prettier, Black, or gofmt every time Claude Code edits a file:

json
// PostToolUse hook
{
  "matcher": "Edit|Write",
  "command": "npx prettier --write \"$CLAUDE_FILE_PATH\""
}

2. Block sensitive file edits

Prevent Claude Code from modifying environment files, secrets, or critical configs:

json
// PreToolUse hook
{
  "matcher": "Edit|Write",
  "command": "echo $CLAUDE_FILE_PATH | grep -qE \"\.env|\.secret|credentials\" && exit 1 || exit 0"
}

3. Re-inject context after compaction

When Claude Code compacts its context window, important details can be lost. A hook can re-inject critical information:

json
// PostToolUse hook for compaction
{
  "matcher": "Compact",
  "command": "cat .claude/critical-context.md"
}
TIP

Start with the auto-format hook. It's the highest-value hook with the lowest risk. Once you're comfortable, add file protection and context injection.

Frequently asked questions

Can a hook block Claude Code from doing something?+
Yes. PreToolUse hooks can exit with code 1 to block the action. Claude Code will see the block message and try a different approach. This is how you create guardrails for sensitive operations.
Do hooks work in headless mode?+
Yes. Hooks execute in all modes including headless (CI/CD). This makes them useful for enforcing standards in automated pipelines where no human is reviewing each action.
What environment variables are available in hooks?+
Hooks receive context through environment variables like $CLAUDE_FILE_PATH (the file being edited), $CLAUDE_TOOL_NAME (the tool being used), and $CLAUDE_SESSION_ID. The exact variables depend on the event type.
Can hooks slow down Claude Code?+
Yes, if the hook command is slow. Keep hooks fast (under 1 second). Avoid hooks that make network requests or run heavy builds. Use async logging if you need to track actions without blocking.
← ALL POSTSSTART FREE COURSE →