writing-hooks

Writing Claude Code Hooks

Hooks are shell scripts Claude Code runs at lifecycle events (before/after a tool, on session start, before compaction, on stop). They observe tool calls and can block a dangerous one. This reference covers the file format, exit codes, per-event stdin JSON, the profile system, parsing, settings.json wiring, and testing.

Use when

• Writing or editing a hook under .claude/scripts/hooks/.
• Wiring a hook into .claude/settings.json.
• Debugging why a hook blocks, warns, or gets skipped.

Do not use when

• Authoring agents or slash commands → use the writing-agents / writing-commands skills.
• The task is application code, not lifecycle automation.

Hard Rules

• Default to exit 0. Use exit 2 only when you are certain the action must be blocked — a hook must never crash Claude Code.
• On any unexpected error, fail open (exit 0); a broken hook must not stop the user's work.
• Do NOT use set -e — one failing command must not abort the whole hook.
• Keep every hook under ~1-2 seconds; guard external calls with the timeout command; never block on the network.
• Always quote paths ("$FILE_PATH"); confirm a file exists before reading it.
• timeout: in settings.json is in SECONDS, not milliseconds.
• Hooks observe and warn — they do not modify files.

Hook File Anatomy

Hooks are .sh files in .claude/scripts/hooks/.

#!/bin/bash
# hook-name.sh — [Event] hook
# Description of what this hook does
# Profile: [always|fast|standard|strict]   # see Profile System

# Read hook input from stdin (JSON)
INPUT=$(cat)

# Parse fields with jq (if available) or node
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)

# Your validation logic here

exit 0

Exit Codes

Code	Meaning	Effect
0	Allow	Tool call proceeds (or no output for info-only hooks)
2	BLOCK	Tool call is rejected; stderr message shown to Claude
Other	Error	Hook failure logged, tool call proceeds (fail-open)