← Agentic coding The wiring · Mechanism

The power of hooks

Hooks are small shell commands that fire on an agent's lifecycle events — the deterministic control surface around a non-deterministic model. They scale from a one-line formatter to an entire orchestration layer.

01

What a hook is

In Claude Code, hooks are shell commands you register in settings.json that fire on lifecycle events. The model is non-deterministic; hooks are how you bolt deterministic behavior onto it — block a dangerous edit, auto-format after a write, inject context before the model sees a prompt.

The events: PreToolUse, PostToolUse, UserPromptSubmit, Stop, SubagentStop, SessionStart, SessionEnd, Notification, PreCompact. Matchers target specific tools — for example, only Edit, or only Bash. A hook can allow or deny a tool call: exit code 2 blocks it, or return JSON on stdout to inject text the model then reads.

02

Where a hook fires

Every tool call passes through a lifecycle. Hooks are the taps you bolt onto that pipe — before the call, after it, and at the boundaries of each session and turn.

User promptyou type
UserPromptSubmitinject · rewrite
model reasonspicks a tool
PreToolUseallow · block
tool runsEdit / Bash / …
PostToolUseformat · lint
model continuesnext thought
Stopnotify · loop

The pipe runs top to bottom; the accent steps are the hook taps. The model decides what to do — hooks decide what's allowed to happen.

03

Start simple

The simplest useful hook is a PostToolUse formatter. Register it once and every file the agent writes comes out clean:

settings.json (excerpt) 
"hooks": {
  "PostToolUse": [
    {
      "matcher": "Edit",
      "hooks": [
        {
          "type": "command",
          "command": "prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\""
        }
      ]
    }
  ]
}
04

Then it gets serious

One hook is a convenience. A handful of hooks wired together is an orchestration layer. That's exactly what oh-my-claudecode (OMC, by Yeachan-Heo) does: the same small set of lifecycle events drives a full system.

SessionStart injects the previous session's summary and project memory so the agent knows where it left off. UserPromptSubmit watches for "magic keywords" — type autopilot and a hook silently expands an entire skill into the prompt before the model ever sees it. A Stop hook re-launches the agent immediately, so "the boulder never stops." The same pattern has been ported across agents: oh-my-codex (omx) for OpenAI Codex CLI, and oh-my-openagent / oh-my-opencode for the OpenCode ecosystem.

$autopilot
SessionStart UserPromptSubmit Stop
Plan analyst · architect
→
Execute
parallel agents
→
QA build · test · fix
→
Review security · quality
Stop hook re-runs unfinished work — the boulder never stops

One keyword unfolds into a crew: plan, parallel build, QA, review — looping until the work is actually done. All of it choreographed by three hooks.

The same three lifecycle events, composed, are the entire trick:

What that complexity actually buys, in practice — the modes I reach for:

05

How I actually use it

My take

This very page was assembled by an agent whose every turn ran through hooks — session memory restored at start, a magic keyword expanding a skill, a Stop loop keeping it going, even a hook compressing its replies. I didn't configure any of that per-task; it was just the environment the agent ran in.

I reach for hooks whenever I want determinism around the model instead of hoping it behaves. Format enforcement, protected-path guards, notification on completion — these are all things I don't want to leave to the model's judgment. Hooks are where I write the rules down.

06

Sources