Hooks
Hooks are lifecycle triggers — pre-commit, post-edit, session-start, and similar events that fire automatically when something happens in a Claude Code session. They’re the right primitive when you want deterministic automation rather than guided behaviour.
The distinction matters. A pre-commit hook that runs your linter is reliable: it runs every time, regardless of what’s happening in the conversation. A CLAUDE.md rule that says “run the linter before commits” is persuadable — Claude can be talked out of it, or simply forget under load. When the rule must hold, hooks beat instructions.
Where they live
Section titled “Where they live”Hooks are configured in settings.json at user, project, or local scope:
- User-level —
~/.claude/settings.json. Hooks defined here apply across every project. - Project-level —
<repo>/.claude/settings.json. Committed with the repo, applies to everyone working on it. - Local-only —
<repo>/.claude/settings.local.json. Personal hooks for this project, not committed.
Each hook entry binds a trigger (PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, and others) to a shell command. When the event fires, the command runs.
When to reach for them
Section titled “When to reach for them”For the Playbook’s typical projects, hooks are out of active practice. The existing primitives — CLAUDE.md for rules, settings.json permissions for hard blocks, subagents for delegated work — cover the ground for solo and small-team builds.
Hooks become useful when you’ve outgrown that surface. The clearest cases:
- Event-driven security enforcement. Automatic secret scanning before any commit, or blocking edits to sensitive paths regardless of what Claude was asked to do.
- Session-start automation. Auto-running an orientation skill or context loader the moment Claude Code launches in a project.
- Post-edit guardrails. Running a formatter, linter, or type-checker after every code edit, before the next prompt.
If none of those apply, don’t reach for hooks yet. The existing model is simpler and covers the common cases.
Status
Section titled “Status”This page is intentionally a stub. A deeper treatment — concrete hook templates, the full event vocabulary, the interaction between hooks and settings.json permissions — is in the backlog and will be drafted when the use cases come into the Playbook’s active practice.