Session checkpoint/resume: auto-save WIP to memory to survive the usage-cap block

[JoshuaVSherman]

Why

On the 5-hour usage cap, Claude Code warns at ~98% and then blocks for 2+ hours. Whatever we're mid-doing can be lost, and the next session starts cold. We want work-in-progress state auto-saved to memory so nothing is lost and the next session resumes cleanly.

What

A local Claude Code mechanism (checkpoint skill + SessionStart surfacing) that durably records "where we left off" and offers to resume it.

Behavior

• Continuous checkpoints at milestones — save whenever state meaningfully changes (finished a step, made a decision, committed/pushed, switched tasks). Err toward saving more often. This is the reliable backbone.
• Best-effort save at 97% — one additional save if/when the usage-cap warning is reachable from a hook, fired slightly early (97%) to leave margin before the block. Backstop only.
• Auto-surface on resume — at the start of a new session, read the latest checkpoint and proactively show one ignorable line: "Last time we were doing X, next was Y — continue?"

Checkpoint content

• Goal (one sentence)
• What's done so far (key steps)
• Immediate next step to resume on
• Where: repo, branch, files touched, open PR/issue
• Any blocker or open decision

Storage (two places, each save)

1. Per-directory checkpoint file in that working directory's memory dir (so reopening that exact project auto-resumes in place).
2. One global "latest" checkpoint in a fixed known location, so any session — any surface (terminal or VS Code) or directory — can find the most recent checkpoint and resume. Closes the cross-surface / different-folder gap.

Acceptance criteria

• Checkpoints written at milestones during normal work, to both the per-directory file and the global "latest" file.
• A new session auto-surfaces the latest checkpoint as a single ignorable resume prompt.
• Checkpoint captures the content fields above — enough for a cold session to resume without re-explaining.

Open feasibility item (verify before building the 97% piece)

The 97% best-effort trigger depends on whether the harness exposes a live usage-cap percentage to a hook (and whether there's any model turn left at that point). Verify against current Claude Code docs:

1. Do Stop / PreCompact hook payloads (or the statusline JSON) expose a usable usage-cap / quota signal?
2. Is there a turn available after the ~98% warning to complete a save before the block?

If neither is reachable, ship the continuous-milestone + auto-surface parts (fully buildable today) and drop the 97% trigger to best-effort or out of scope.

Notes

• All local ~/.claude/ config — a checkpoint skill + SessionStart surfacing; no app repo code.
• Distinct from the gemma-cli /checkpoint + /resume work (that's the Python REPL); this is Claude Code's own session.