Claude Hooks

Claude Hooks are user-defined shell commands that Claude Code runs at fixed points in its lifecycle. Official docs stress the difference from skills: hooks are deterministic. Formatters, notifications, protected-file blocks, and permission auto-approves always run, instead of waiting for the model to remember. For judgment calls you can also attach prompt-based or agent-based hooks. HTTP hooks exist for remote listeners.

The current guide's examples include desktop notifications when Claude needs input, auto-format after edits, blocking edits to protected files, re-injecting context after compaction, auditing config changes, and reloading env when the directory changes. Matchers can filter by tool name and arguments. Configure hooks in a settings file (user or project), not in chat.

Key Features

• Lifecycle shell: Docs mention events such as UserPromptSubmit, PreToolUse, PostToolUse, and Stop, plus notification-style hooks.
• Input/output contract: Hooks read JSON on stdin and can return structured JSON or an exit code.
• Matchers: Limit a hook to one tool or argument pattern.
• Prompt- and agent-based hooks: Use a model when the rule is not a regex.
• Not a skill: Skills teach. Hooks enforce.

Use Cases

• Format and lint after every edit.
• Block writes to secrets or generated files.
• Notify when the agent is waiting, so you can leave the terminal.

Pricing

Hooks ship with Claude Code. No separate SKU. You still pay the Claude plan or API that runs the session. Recheck claude.com/pricing.

Getting Started

1. Read Automate actions with hooks.
2. Add a hooks block to a settings file as the first-hook walkthrough shows.
3. Start with a notification hook, then a PostToolUse formatter.
4. For schemas, use the hooks reference linked from that guide.

Frequently Asked Questions

Can a hook stop Claude?

Yes. Official examples include blocking edits and auto-approving specific permission prompts. Read the exit-code and JSON output rules before you rely on a block.

Hooks vs skills?

Skills are instructions loaded on demand. Hooks always fire at an event. Use both: a skill for the procedure, a hook for the gate.

Where do they live?

In settings files, and they can be packaged inside a plugin.

Alternatives

• Claude Skills: Procedures, not enforcement.
• Claude Plugins: How you distribute hooks.
• Claude Code: The host.

Tips

1. Keep hooks short and boring. Long LLM hooks become a second agent.
2. Log hook failures. Silent formatters waste a session.
3. Recheck event names in the reference. The set has grown past the original five-event blog posts.

Conclusion

Hooks are how you make Claude Code obey the repo. Start from the hooks guide, add one notification and one formatter, then package the rest.