Building claude-session-management

1. The purpose

Claude Code identifies every session by a GUID. That is fine for the machine and useless for a human: after a few weeks of daily use, dozens of sessions accumulate per project and the resume picker becomes a wall of look-alike topic titles. The insight this system is built on is simple: the sessions worth returning to are exactly the ones you bothered to name with /rename.

So the goal was a small system that:

• records every exit of a named session — its name, the folder it ran in, the exact exit timestamp, and its GUID;
• resumes any of them from anywhere, with one command that jumps to the right folder and relaunches with the right claude invocation;
• hands off a session's working state as a numbered document, so a future session (or another person) can continue with full context;
• travels with the repo — everything lives in one folder inside claude-workdocs, reached from ~/.claude through a single symlink.

2. Architecture at a glance

Everything sits in ~/claude-workdocs/.claude/claude-session-management/ and is reached through a single folder-level symlink at ~/.claude/claude-session-management — the same pattern the repo already uses for ~/.claude/rules, settings.json, and CLAUDE.md. Move the repo, recreate one link, and the whole system moves with it.

3. The components

4. What we used, and how

4.1 The discovery that makes it work: transcript title records

The SessionEnd hook payload contains session_id, transcript_path, cwd, and reason — but not the session's name. Digging into the transcript .jsonl files revealed two distinct record types:

{"type":"ai-title","aiTitle":"Locate biks-claude-tools marketplace folder", ...}
{"type":"custom-title","customTitle":"claude-workspace-management", ...}

ai-title is the auto-generated topic title every session gets; custom-title appears only when a human runs /rename. That is the whole filter: grep the transcript for the last custom-title record. Present → log it. Absent → exit silently. The log records intent, not noise.

4.2 The hook (Claude Code SessionEnd)

Registered in the user-level settings.json:

"SessionEnd": [
  {
    "matcher": "*",
    "hooks": [
      { "type": "command",
        "command": "$HOME/.claude/claude-session-management/log-session-end.sh" }
    ]
  }
]

The script's safety habits, all of which earned their keep during testing:

• Atomic appends — write to a temp file, then mv over the target.
• Symlink resolution before writing — mv onto a symlink replaces the link, not the target. The script resolves with readlink first, so the repo wiring can never be silently disconnected.
• Never destroy data — a log that fails JSON validation is set aside as claude-session-history.json.corrupt.<epoch>, never overwritten.
• Testability — the target file honors a CLAUDE_SESSION_HISTORY_FILE override, so every code path was pipe-tested with synthetic hook payloads before registration.

4.3 The resume picker (a sourced zsh script)

The one non-obvious design decision: resume-claude must be a shell function that sources the script, not an executable. A subprocess can neither change your terminal's directory nor see the zsh functions (claudey, claude-max, deep-claude…) you use to launch Claude with different configurations. Sourcing runs the logic inside your interactive shell, so the cd sticks and any invocation works:

# ~/.zshrc
resume-claude() {
    source "$HOME/.claude/claude-session-management/claude-session-resume.sh" "$@"
}

The picker itself is jq doing the heavy lifting — group the log by sessionId, keep each session's latest exit, sort newest-first — followed by two prompts (which session, which invocation, default claude-max) and finally cd <folder> && <invocation> --resume <GUID>. Being sourced also imposes discipline: no set -e, no exit (only return) — you are running inside the user's live shell.

resume-claude --prune compacts the log: the latest entry per session stays, everything superseded moves (never deletes) to the archive file.

4.4 The handoff subsystem

Handoffs reuse an idea from the mattpocock-skills plugin, whose handoff skill sets disable-model-invocation: true — it cannot be called through the Skill tool, only typed by a human. The fix was to replicate its (small, good) prompt inside our own /session-handoff command: summarize the conversation for a fresh agent, add a "Suggested skills" section, reference existing artifacts by path instead of duplicating them, redact secrets, and honor an optional argument describing the next session's focus.

The current session is identified without any environment variable, via the live registry ~/.claude/sessions/*.json: the busy session in the current folder with the freshest statusUpdatedAt is, by construction, the one running the command — and its registry entry carries the session name.

5. Rebuilding it from scratch

Prerequisites: Claude Code CLI, jq, zsh. Full sources live in ~/.claude/claude-session-management/; the steps below are the skeleton.

1. Create the folder and (optionally) the symlink.

   mkdir -p ~/claude-workdocs/.claude/claude-session-management/handoff
   ln -s ~/claude-workdocs/.claude/claude-session-management \
         ~/.claude/claude-session-management

   Skip the symlink and use a plain ~/.claude/claude-session-management folder if you don't keep your Claude config in a repo.
2. Write the exit logger (log-session-end.sh). Core logic:

   INPUT=$(cat)   # hook payload on stdin
   transcript=$(jq -r '.transcript_path // empty' <<< "$INPUT")
   cwd=$(jq -r '.cwd // empty' <<< "$INPUT")
   sid=$(jq -r '.session_id // empty' <<< "$INPUT")
   
   name=$(grep '"type":"custom-title"' "$transcript" | tail -1 \
          | jq -r '.customTitle // empty')
   [ -n "$name" ] || exit 0            # unnamed -> not our business
   
   entry=$(jq -n --arg n "$name" --arg c "$cwd" \
               --arg t "$(date '+%Y-%m-%dT%H:%M:%S%z')" --arg s "$sid" \
     '{sessionName:$n, folder:$c, exitTimestamp:$t, sessionId:$s}')
   # append atomically: jq '. + [$e]' -> tmp -> mv

3. Register the hook in ~/.claude/settings.json under hooks.SessionEnd (JSON block shown in §4.2), then reload hooks (/hooks) or restart.
4. Write the resume picker (claude-session-resume.sh) and the resume-claude() function in ~/.zshrc. Remember: the script is sourced — use return, never exit; don't set -e/pipefail; dedupe with jq 'group_by(.sessionId) | map(max_by(.exitTimestamp))'.
5. Add the handoff pieces: next-handoff-name.sh (session detection from ~/.claude/sessions/ + the 001→999→A01 sequence) and a /session-handoff command markdown in ~/.claude/commands/ that runs the helper, writes the handoff, and reports the path.
6. Test before trusting. Every script here was verified by piping synthetic hook payloads and fabricated logs through it (file-target overrides make this safe), covering: unnamed session → no entry; named → entry; append; corrupt file set-aside; symlink survival; prune idempotence; 999→A01 rollover.

6. Using it day to day

7. Lessons worth stealing

• Hooks beat memory. "Every time X happens, do Y" is a job for the harness, not for an assistant's recollection. The SessionEnd hook fires deterministically, forever.
• The transcript is an API. Claude Code's .jsonl transcripts carry structured records (custom-title, ai-title, …) that hooks can query with grep + jq — no private APIs needed.
• Respect the symlink topology. mv replaces links, not targets. Any script that writes through a symlinked config tree must resolve first.
• Sourced scripts are a different dialect. No exit, no set -e, local everywhere — you're a guest in the user's shell.
• Make every script testable headlessly. A single env-var override for the data file turned every feature into a pipe-testable unit before it ever ran for real.