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

EventFires when
SessionStarta session starts or resumes
UserPromptSubmityou send a prompt, before Claude sees it
PreToolUsebefore a tool call; can block it
PostToolUseafter a tool call succeeds
NotificationClaude needs your permission, or has waited for input
SubagentStart / SubagentStopa subagent starts or finishes
StopClaude finishes its response
SessionEndthe 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": true so 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