Hooks
The four moments the plugin hooks into, on either host, and what each one does.
Every hook shells into bin/kevin with a --hook-protocol=<host> flag. Claude Code runs them from the plugin's hooks/claude.json; Codex runs the same entry points from a per-home .codex/hooks.json. A new host adds a protocol, not a script. See Hosts.
| Hook | Command | Timeout | Purpose |
|---|---|---|---|
SessionStart | kevin session-start | 15s | Pre-init: the setup banner. Post-init: today's date in your timezone, the last session tail, today's reports, and recent git activity, capped at 10KB. Under Codex the whole static stack rides along too |
SessionEnd | kevin session-capture --mode=session-end | 30s | Append the transcript to knowledge/raw/sessions/YYYY-MM-DD.md with secret redaction |
PreCompact | kevin session-capture --mode=pre-compact | 30s | The same capture before auto-compaction, so mid-session context is not lost |
PreToolUse (Bash) | kevin guard | 5s | Block a home-relative projects/, knowledge/, or reports/ write while the effective cwd is outside the home; tell the model the absolute path |
Why the hooks live in the plugin
Every host runs the hooks only for sessions started in the home (Claude Code because the plugin is enabled there, Codex because the hooks are wired there). A session can therefore only ever be captured by the agent it launched in. Two agents on one machine cannot write into each other's memory, and nothing needs configuring to guarantee it. The cost is that a session started outside a home is not captured at all. See Onboarding.
Session files
Capture appends to one file per day. Each block header carries the session id, the harness and model that produced it, and the turn range, so a resumed session appends a continuation block rather than a new file. A session index (raw/sessions/index.json) keys the capture cursor and the compile's continuation source, and is reconstructable from the day-file headers.
Redaction
Before writing, capture exact-matches every value in .kevin/secrets/.env and settings.local.json, and applies prefix heuristics for common key formats. The transcript never carries a secret into the knowledge tree.