How it works
Codex stores sessions in two places:~/.codex/session_index.jsonl— a line-delimited JSON index of all sessions, each entry containing the session ID, thread name (title), and last-updated timestamp.~/.codex/sessions/YYYY/MM/DD/rollout-<datetime>-<id>.jsonl— the full transcript for each session, containing message records, tool calls, git state, and working directory.
| Hook | What it does |
|---|---|
PreCompact | Checkpoints the session before Codex compacts the transcript |
PostCompact | Captures the compaction summary after compaction |
Stop | Syncs the session at the end of each conversation turn |
~/.codex/hooks/ and are registered in ~/.codex/hooks.json. Handshake is also registered as an MCP server in ~/.codex/config.toml under the [mcp_servers.handshake] block.
Setup
Run the setup wizard once:~/.codex/config.toml, installs the three hook scripts into ~/.codex/hooks/, and registers them in ~/.codex/hooks.json. If a config file already exists it is backed up before being modified.
After setup, open Codex and run
/hooks to trust the Handshake hook scripts. Codex requires explicit trust before executing hook commands.Checkpointing
You can checkpoint and restore sessions from inside Codex using natural language:Auto-ingestion
Codex sessions are automatically synced to Handshake whenever you runlist my sessions or handshake list from the CLI. Handshake reads ~/.codex/session_index.jsonl and ingests any sessions it hasn’t seen before — so your Codex history is always available even without an explicit checkpoint. Explicitly checkpointing a session with checkpoint this session adds a summary and decision log to the record, which produces a richer restore brief when you switch agents.