Hook
A hook is a user-configured script that runs on agent events like PreToolUse or Stop, used to enforce policies, run checks, or customize behavior.
A hook is a user-configured script or command that an agentic coding CLI runs on specific events — before a tool call, after one, when the session ends, when the user submits a prompt. In Claude Code, hooks are the primary extension point for enforcing policies, running automatic checks, or customizing output without modifying the CLI itself.
Why it matters
Hooks let you wire in deterministic behavior around a non-deterministic agent. "Always run the formatter after the agent edits a Python file." "Block any write to .env." "Play a sound when the session stops." None of that relies on the LLM deciding to do it — the harness guarantees the hook fires.
For teams using Claude Code at scale, hooks are often the difference between "agent is a cool toy" and "agent is a safe part of our pipeline." You can enforce test runs, audit tool use, or reject dangerous commands without asking the model to remember.
How it works
Claude Code hooks are configured in settings.json (global at ~/.claude/settings.json or project-local at .claude/settings.json). The key events include:
- PreToolUse — fires before the agent calls a tool; can inspect and block
- PostToolUse — fires after a tool call completes
- UserPromptSubmit — fires when the user submits a turn
- Stop — fires when the agent ends its turn
- Notification — fires on status notifications
Each hook is a shell command. It receives JSON on stdin describing the event and can respond by exiting with a status code, emitting JSON to stdout (to modify behavior), or just doing a side effect.
Example: block writes to .env files by matching the tool name and arguments, exiting with code 2 to veto.
How it's used
Common hooks developers ship:
- Auto-format on every file edit (prettier, ruff, rustfmt)
- Run the linter after each agent turn
- Block destructive shell commands (
rm -rf /,git push --force) - Log every tool call to a local audit file
- Desktop notifications when the agent stops
Other CLIs (Codex CLI) have similar mechanisms; the Claude Code hook system is currently the most developed.
Related terms
- Slash command — user-triggered, hooks are event-triggered
- Subagent — another extension mechanism
- Tool use — what hooks often intercept
- Sandbox — a broader safety mechanism
- MCP — extending capabilities vs. intercepting them
FAQ
Do hooks slow down the agent?
Each hook adds its own runtime. Fast hooks (milliseconds) are imperceptible; heavy ones (running the full test suite on every tool call) will slow things down noticeably. Scope hooks carefully.
Can hooks see the LLM's full reasoning?
They see the tool calls the LLM emits, plus metadata like prompts and responses depending on event type. They don't see internal chain-of-thought that wasn't emitted to the transcript.
Related terms
- Agentic codingAgentic coding is software development where an LLM-powered agent plans, edits, runs, and verifies code on its own using tools, not just autocomplete.
- AI pair programmingAI pair programming is a collaboration style where an LLM assistant sits alongside you, suggesting code and reviewing changes in real time as you work.
- ANSI escape codesANSI escape codes are control sequences that terminals interpret for colors, cursor movement, and screen clearing — the language of every modern CLI UI.
- Autonomous agentAn autonomous agent is an AI program that perceives, decides, and acts on its own toward a goal — the architecture behind modern coding CLIs.
- CheckpointA checkpoint is a saved snapshot of file state that lets you roll back an AI coding agent's changes to a known-good point.
- Claude CodeClaude Code is Anthropic's official command-line agent that plans, edits, runs, and verifies code across your repo using Claude models and tool use.