Guide
Claude Code hooks, explained with a real example.
Hooks let you run your own code on events inside a Claude Code session. This guide covers the events, the input, the rules for writing a safe hook, and the hook Agent Peeps ships.
What a hook is
A hook is a command Claude Code runs when something happens in a session: a prompt is submitted, a tool is about to run, a tool finished, the session needs your attention, the turn ends. Hooks live under the hooks key of a settings file: ~/.claude/settings.json for all projects, or .claude/settings.json inside one project.
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [{ "type": "command", "command": "npx prettier --write \"$CLAUDE_PROJECT_DIR\"" }]
}
]
}
}matcher filters by tool name for the tool events (a regular expression, or * / empty for every tool).
The events
| Event | Fires when |
|---|---|
SessionStart | a session starts or resumes |
UserPromptSubmit | you send a prompt, before Claude sees it |
PreToolUse | before a tool call; can block it |
PostToolUse | after a tool call succeeds |
Notification | Claude needs your permission, or has waited for input |
SubagentStart / SubagentStop | a subagent starts or finishes |
Stop | Claude finishes its response |
SessionEnd | the session ends |
Check the official Claude Code hooks reference for the full, current list: new events are added over time.
What a hook receives
Each hook gets one JSON object on stdin. The common fields are session_id, cwd and hook_event_name; tool events add tool_name and tool_input:
{
"session_id": "4b1c...",
"cwd": "/home/me/app",
"hook_event_name": "PreToolUse",
"tool_name": "Edit",
"tool_input": { "file_path": "/home/me/app/src/auth.ts", "old_string": "...", "new_string": "..." }
}The exit code matters. 0 means carry on. For PreToolUse, exit code 2 blocks the tool call and the text on stderr is shown to Claude, which is how you write guard rails such as "never touch .env".
Rules for a hook that never gets in the way
- Always exit 0 unless blocking is the point. Catch every error.
- Be fast. Hooks run on every matching event; a slow hook slows every tool call. Mark observers
"async": trueso Claude doesn't wait for them. - Use the exec form (
"command": "node", "args": [...]) to avoid shell quoting problems with spaces in paths. - Never print to stdout unless the event expects a decision from you.
A real example: the Agent Peeps hook
Agent Peeps shows a live sticker per Claude Code session. Its whole integration is one hook, added to nine events by npx agentpeeps init:
{
"matcher": "*",
"hooks": [{
"type": "command",
"command": "node",
"args": ["/home/you/.agent-presence/app/node_modules/agentpeeps/cli.js", "emit", "claude"],
"async": true
}]
}emit reads the event from stdin, turns it into one line ({"agent":"claude","state":"writing","file":"src/auth.ts",...}) and appends it to ~/.agent-presence/events.jsonl. It wraps everything in try, rotates the log at 5 MB and always exits 0. The overlay tails that file, so the hook itself never touches a window or the network.
It maps tools to states: Edit and Write are writing, Read, Grep and Glob are reading, Bash is running, Agent is delegating, and a Notification becomes needs you. The source is one file on GitHub.
Try it in one command
Agent Peeps is free and open source (MIT). It only reads hook events on your machine: no account, no server, no network.
$ npx agentpeeps init $ npx agentpeeps overlay
See the stickers in your browser · Read the docs · Star it on GitHub