Hooks Reference

Every BoB hook, by event. Extracted from handbook §14.

← docs home

Hooks Reference

Hooks are shell scripts wired into Claude Code events via ~/.claude/settings.json. They run automatically at the right moment — never invoke them manually.

Hooks receive ALL data via stdin as JSON. There are no magic variable substitutions.

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')

Template: templates/hooks/command-hook.sh. Requires jq.

Hooks by event

Event	Hook	Purpose
SessionStart	temporal-context.sh	Inject current date/time so Claude doesn’t drift
SessionStart	autoloop-inject.sh / warp-drive-inject.sh	Restore loop state on session resume
SessionStart	loop-notes-inject.sh	Inject the project’s loop episodic-memory notes (discovered hidden rules) as context (#588)
PreToolUse	strip-ai-boilerplate.sh	Strip generic AI prose from outgoing edits
PreToolUse	check-branch.sh	Block writes on master/main
PreToolUse	session-branch-guard.sh	Guard against committing to wrong branch
PreToolUse	rdb-enforce-ask-remote.sh	When _rdb.enabled, force ask_remote over AskUserQuestion
PreToolUse	autoloop-gate.sh / warp-drive-gate.sh	Block tool calls outside the current loop phase
PreToolUse	validate-commit-message.sh	Reject commits with generic / AI-boilerplate messages
PreToolUse	validate-pr-requirements.sh	PR must reference a requirement issue
PreToolUse	validate-requirement-refs.sh	Requirement IDs in commit messages must resolve
PreToolUse	pre-release-checklist.sh	Run before release commands
PreToolUse	dev-auto-start.sh	Auto-start dev server when project requires it
PreToolUse	autonomous-audit-log.sh	At automation L3 only, record every auto-approved tool call (tool, target, ts) to a per-session JSONL audit log; strict no-op at L1/L2 (#420)
PostToolUse	warp-drive-edit-tracker.sh	Track edits during a warp-drive chunk
PostToolUse	warp-drive-commit-detector.sh	Detect commits and advance the state machine
PostToolUse	warp-drive-docs-detector.sh	Detect doc changes and route to journal
PostToolUse	capture-decision.sh	Capture AskUserQuestion / RDB ask_remote outcomes to the decision log (#332)
Stop	autoloop-stop.sh / warp-drive-stop.sh	Persist state on session stop
Stop	warp-drive-pre-exit.sh	Cleanup before exit
Stop	session-summary-reminder.sh	Remind to capture session summary
Stop	stop-notify-rdb.sh	Notify Telegram when warp-drive stops
SubagentStop	swarm-result-gate.sh	Block a swarm worker’s stop when its result fails the per-worker gate (#579)

(Exact wiring lives in ~/.claude/settings.json. Use make check-hooks to verify all hook scripts exist and are executable.)

Git hooks (distinct from Claude Code hooks)

Separately from the settings.json event hooks above, cdi installs a git commit-msg hook (templates/git/hooks/commit-msg) into each project. It runs for every commit — Claude-made or human — and does two things in order:

1. Strips AI boilerplate (Co-Authored-By: Claude, 🤖 Generated, …).
2. On projects with automated versioning (.versionrc.json / commitlint.config.* present), enforces Conventional Commits — commitlint if installed, else a built-in dependency-free check (#278). Non-versioned projects keep strip-only behavior. See the versioning guide.

Decision log — outer improvement loop (#332)

capture-decision.sh (above) records the stream of user decisions so they can later be distilled into updated, version-controlled instructions. The capture writers and the schema live under scripts/decision-log/ and schemas/:

• Log: <project-root>/.claude/.decisions.jsonl — JSONL, append-only, one record per decision. Runtime state, gitignored (the distilled output is what gets git-tracked, not the raw stream).
• Schema (source of truth): schemas/decision-log.schema.json, validated in make check against a committed sample fixture.
• Sources: AskUserQuestion and RDB ask_remote (captured automatically by the hook); /code-review accept/reject (captured via scripts/decision-log/log-code-review.sh, since a slash command’s outcome is not a hookable tool call).
• Rotation: see scripts/decision-log/README.md.

---