How it works
Claude Code stores sessions as JSONL transcript files at~/.claude/projects/<encoded-cwd>/<session-id>.jsonl. When you checkpoint a session, Handshake reads these files and stores a portable session snapshot in its local database at ~/.handshake/sessions.db.
Handshake installs three event hooks into Claude Code’s ~/.claude/hooks.json:
| Hook | What it does |
|---|---|
PreCompact | Checkpoints the session before Claude Code compacts the transcript |
PostCompact | Captures the compaction summary after the transcript is condensed |
Stop | Syncs the session whenever a conversation turn ends |
~/.claude/hooks/ and keep your session record up to date in the background automatically.
Setup
Run the setup wizard once:claude mcp add, and installs the three event hook scripts into ~/.claude/hooks/. Both steps are automatic — you don’t need to touch any config files manually.
Setup requires the The hook scripts require Python 3. If Python 3 isn’t on your PATH, the hooks are skipped and you can still checkpoint manually by asking Claude Code.
claude CLI to be on your PATH for automatic MCP registration. If it isn’t found, the wizard prints the manual command to add:Checkpointing
Once set up, you can checkpoint from inside Claude Code using natural language:Stop hook also syncs your session automatically at the end of every conversation turn, so you rarely need to checkpoint manually.
Session titles
Claude Code sessions are titled from thesummary record in the JSONL transcript file. This summary is written by Claude Code when it compacts the transcript. If no summary record exists yet (for example, early in a new session), Handshake derives the title from the text of your first message instead.