Hooks for Automation

Understand what hooks are and when they run

Create PreToolUse hooks that run before actions

Create PostToolUse hooks that run after actions

Configure hooks in settings.json

Use hooks for logging, validation, and custom workflows

Hooks let you inject custom behavior into Claude Code's workflow. They are shell commands that run at specific points: before Claude uses a tool, after it uses a tool, or when a session starts.

Think of hooks as event listeners. When something happens, your hook runs. This opens up automation possibilities: logging every command Claude runs, validating changes before they happen, syncing state after edits, or enforcing project rules.

This lesson teaches you how hooks work and how to use them effectively.

Hooks are defined in your settings file and run automatically when their trigger condition is met.

Hook types:

PreToolUse - Runs before Claude uses a tool

PostToolUse - Runs after Claude uses a tool

SessionStart - Runs when a session begins

Each hook specifies:

When it triggers (the event type)

Which tools it applies to (optional filter)

What command to run

The hook receives context about the action as JSON on stdin. It can inspect this context and take action.

Hooks live in your settings file. You can set them at user level (~/.claude/settings.json) or project level (.claude/settings.json).

Basic structure:

Matcher patterns:

"Bash" - Matches all Bash tool uses

"Edit" - Matches all Edit tool uses

"*" - Matches any tool

"Bash(npm *)" - Matches Bash commands starting with npm

PreToolUse hooks run before Claude executes a tool. They can:

Log what Claude is about to do

Validate the action

Block actions that violate rules

Transform inputs

Example: Log all commands

Create a script that logs every Bash command:

Configure in settings:

Now every command Claude runs gets logged.

Example: Block dangerous patterns

Create a hook that blocks certain commands:

A non-zero exit code blocks the action.

PostToolUse hooks run after Claude completes a tool use. They can:

Log results

Trigger side effects

Update external systems

Chain additional actions

Example: Auto-format after edits

Run a formatter after Claude edits files:

Configure:

Example: Notify on file changes

Send a notification when files are edited:

SessionStart hooks run when you begin a Claude Code session. They can:

Set up the environment

Check prerequisites

Load project-specific state

Display reminders

Example: Check environment

Verify required tools are installed:

Configure:

Hooks receive JSON on stdin with context about the action:

PreToolUse and PostToolUse:

SessionStart:

Use jq to extract fields you need.

Hooks communicate back to Claude Code through exit codes and stderr:

Exit codes:

0 - Success, continue normally

Non-zero - Failure, block the action (PreToolUse) or report error (PostToolUse)

Stderr output:

JSON on stderr with an error field gets displayed to Claude:

Audit trail:

Log every action Claude takes for compliance or debugging:

Cost tracking:

Count tool uses per session:

Custom validation:

Enforce project rules before edits:

External integration:

Sync with external systems after changes:

When hooks do not work as expected:

Check the script is executable:

Test manually:

Check stderr output:

Hooks that write non-JSON to stderr may cause issues. Keep stderr output clean.

Use logging:

Add logging to your hook to see what is happening:

Hooks run custom commands at specific points in Claude's workflow

PreToolUse hooks run before actions and can block them

PostToolUse hooks run after actions and can trigger side effects

SessionStart hooks run when sessions begin

Configure hooks in settings.json with matchers and commands

Hooks receive JSON context on stdin

Non-zero exit codes block or report errors

Use hooks for logging, validation, formatting, and integration

Create a simple logging hook:

Create a script at ~/claude-hooks/log-all.sh:

Make it executable: chmod +x ~/claude-hooks/log-all.sh

Add to ~/.claude/settings.json:

Start a Claude Code session and ask Claude to run a few commands.

Check ~/claude-activity.log to see logged activity.

Remove the hook when done experimenting.

This exercise shows how hooks can observe Claude's behavior.

https://code.claude.com/docs/en/hooks - Complete hooks documentation

https://code.claude.com/docs/en/hooks#hook-examples - Hook example patterns

https://code.claude.com/docs/en/settings - Settings file format for hooks