Claude Code Hooks Reference

Everything you need on one page when writing a hook: the full event list with the values each matcher accepts, the fields every hook gets on stdin, the settings.json and statusLine shapes, and what exit codes mean. The last section documents the per-session state file that AgentManager derives from these events, for anyone who wants to read it from their own scripts. To generate a config instead of writing one, use the hooks builder.

• Hook events
• What every hook receives on stdin
• settings.json schema
• statusLine schema and its stdin
• Exit codes
• AgentManager session state file

Hook events

Claude Code currently defines 33 hook events. The third column lists what the matcher field filters on for that event, with example values. Events marked “—” ignore the matcher and always fire. A matcher made of plain names separated by | is an exact match; anything containing regex characters is treated as a JavaScript regular expression. An empty matcher matches everything.

What every hook receives on stdin

Each hook command gets one JSON object on stdin. These fields are present for every event; each event adds its own on top (for example tool_name and tool_input on the tool events, notification_type on Notification, error_type on StopFailure, reason on SessionEnd).

settings.json schema

Hooks live under the top-level hooks key in any of ~/.claude/settings.json (user), .claude/settings.json (project, committed) or .claude/settings.local.json (project, ignored by git). Files merge; a hook defined in several files runs from each.

{
  "hooks": {
    "<EventName>": [
      {
        "matcher": "<optional filter>",
        "hooks": [
          { "type": "command", "command": "<shell command>", "timeout": 600 }
        ]
      }
    ]
  }
}

statusLine schema and its stdin

The status line is a separate top-level key with exactly one slot. Its command runs after every assistant response and receives data that hooks never see: context-window usage and rate-limit state.

{
  "statusLine": {
    "type": "command",
    "command": "<shell command>",
    "padding": 0,
    "refreshInterval": 5,
    "hideVimModeIndicator": false
  }
}

Exit codes

AgentManager session state file

AgentManager's hook reduces the events above to one JSON file per session at ~/.claude/agent-manager/sessions/<session_id>.json. The file is rewritten in place on every event, so treat a parse failure as “read again”, not as corruption. The derivation rules are described in Tracking Claude Code session status with hooks.

A second file, ~/.claude/agent-manager/stats/<session_id>.json, is written by the statusLine pass-through. It carries the context_window, rate_limits and model objects from the status-line stdin unchanged, plus a marker when PreCompact has fired. The status-line command you had before installing is preserved in ~/.claude/agent-manager/statusline-original.json and still runs.