Start with the official Claude Code hooks docs
For the native Claude Code feature, start with Anthropic’s hooks guide for setup and workflows, then use the Hooks reference for detailed configuration and event behavior. The guide describes hooks as user-defined shell commands that Claude Code runs at specific points in its lifecycle.
Use those official pages as the specification—not a third-party tutorial or a hook library’s README.
What hooks do
Claude Code hooks let you run code when specified lifecycle events occur—for example, to format code, send a notification, validate an action, or enforce a project rule. They provide a way to automate actions instead of relying on Claude to decide to run them. The guide also describes prompt-based and agent-based hooks for cases that call for judgment.
A documented starting point
Anthropic’s hooks guide starts with a desktop notification hook. It instructs you to open ~/.claude/settings.json, create the file if needed, and add a Notification hook. If the file already has a hooks key, add Notification alongside the existing event keys rather than replacing the whole object.
The guide’s example uses osascript on macOS and an empty matcher for its notification example, which alerts you when Claude is waiting for input:
{
"hooks": {
"Notification": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
}
]
}
]
}
}
Add the event to the existing hooks object if you already have other hooks, then save the settings file. This command is macOS-specific; the guide links to Linux and Windows alternatives. For exact matcher behavior and to check how the configuration is recognized in your environment, consult the Hooks reference and its /hooks and troubleshooting sections. The retrieved guide passage does not specify whether edits take effect in an already-running session or require an approval step, so don’t assume either; follow the current official instructions for that detail.
Do Claude Code hooks work with a production Claude API integration?
Choose the documentation for the developer surface you are using:
- Using Claude Code: Follow the Claude Code hooks guide and reference for hooks configured in Claude Code.
- Building an agent with the Claude Agent SDK: Use Anthropic’s Agent SDK hooks documentation for that programmatic agent workflow. Do not assume it is the same as configuring a direct Messages API request.
- Calling the Messages API directly: Anthropic describes Messages as direct model access, where your application manages conversation state and writes its own tool loop. That is distinct from running Claude Code’s hook lifecycle. For a direct API integration, put relevant deterministic checks in your application’s orchestration. See the Claude Platform documentation.
Decision rule: If you need automation around Claude Code events, start with the Claude Code hooks docs. If your application calls the model directly, use the Claude API documentation and implement the relevant application-side workflow there. If you are building an agent with the Agent SDK, follow its hooks documentation rather than treating a Messages API request as a Claude Code session.
Further reading
- Claude Code hooks guide — setup and common workflows.
- Claude Code Hooks reference — detailed event and configuration reference.
- Claude Agent SDK hooks — hooks for programmatic agent workflows.
- Claude Platform documentation — direct Claude API and managed-agent developer surfaces.
Sources
Automate actions with hooks — Claude Code Docs
Hooks reference — Claude Code Docs
Intercept and control agent behavior with hooks — Claude Code Docs