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. Under Claude Code the same file also loads the plugin's mods module, which runs inside the host rather than as a program; see Mods.
| Hook | Command | Timeout | Purpose |
|---|---|---|---|
SessionStart | kevin session-start | 15s | Pre-init: the setup banner. Post-init: the banner with any notices, and today's date in your timezone, the last session tail, today's reports, your pinned 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 | Refuse a shell command, with the fix, when it would write a home-relative projects/, knowledge/, or reports/ path from outside the home; leave the session outside the home (Claude Code only, when the session was launched there; a cd carries over to later commands, so git -C or a subshell cd is the way; cd $HOME reads like cd ~); or reach shared temp files by a pattern or a hand-picked $TMPDIR name instead of the path mktemp printed (a single-quoted '$TMPDIR' is plain text) |
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 .state/secrets/.env and settings.local.json, and applies prefix heuristics for common key formats. The transcript never carries a secret into the knowledge tree.
Codex
Run the same home from OpenAI Codex. Per-home hooks and MCP registration, a permission profile generated from the home's settings, and the limits that remain.
Mods
The plugin's in-process module for Claude Code. Instant commands, queued prompts, this conversation's reports, repo manuals on first touch, sync progress, and notices above the prompt.