Hooks
Deterministic event handlers that fire during AI assistant sessions to inject memory, collect stats, and surface suggestions.
What Hooks Are
Hooks are shell commands that run automatically at specific points in an AI assistant session. They bridge Bootspring's session intelligence into Claude Code and Codex without requiring manual tool calls.
When you install hooks with bootspring hook install, Bootspring writes deterministic handler configurations to .claude/settings.local.json and .codex/hooks.json.
Hook Events
| Event | When it fires | What it does |
|---|---|---|
UserPromptSubmit | Before a user prompt is sent to the assistant | Injects memory context (persona, project context, preferences, session notes) |
PostToolUse | After each tool call completes | Collects session stats (tokens, costs, timing, tool usage) |
Stop | When the assistant session ends | Saves a session snapshot to .bootspring/memory/sessions/ |
Handler Ordering
Each event runs up to three handlers in a fixed order:
- stats -- Collect metrics from the event
- suggest -- Evaluate patterns and generate suggestions
- recall -- Search memory and inject relevant context
This ordering is deterministic and enforced by the dispatcher. It ensures stats are collected before suggestions are generated, and both complete before memory context is injected.
Hook Profiles
| Profile | Handlers | Use case |
|---|---|---|
minimal | recall only | Lightweight memory injection, no tracking overhead |
standard | stats + suggest + recall | Default for most projects |
strict | all handlers + validation | Full telemetry with config validation on each event |
Switch profiles with:
Memory Injection
On every UserPromptSubmit, the recall handler injects structured XML blocks into the assistant's context:
- persona -- Your name, role, communication style
- project_context -- Repo name, tech stack, structure, conventions (auto-populated)
- user_preferences -- Workflow preferences, commit conventions, tooling
- session_notes -- Carry-over notes from the previous session
This gives the assistant immediate orientation without needing to re-read files or ask questions.
Error Isolation
Each handler runs in its own subprocess. If one handler fails (times out, crashes, returns invalid output), the others continue unaffected. A broken stats collector never blocks memory injection.
Installation
Storage
Hook configurations are written to:
.claude/settings.local.json-- Claude Code hooks.codex/hooks.json-- Codex hooks
Memory data is stored in .bootspring/memory/ (see Session Intelligence).
Further Reading
- CLI reference for hook commands
- Session Intelligence -- the data layer hooks feed into
- Observer -- the analytics engine powered by hook-collected stats