Session continuity and cold resume

Reopening a session that has sat idle for hours or days normally forces a full prefix re-write, and the model still has to relearn where you were. Session continuity gives you that context back cheaply: a token-free reconstruction you can paste into a new session, an automatic hint when a new prompt matches an old session, and a browsable history of every checkpoint.

What it does

Smart compaction saves checkpoints. Session continuity is how you spend them.

When you start a fresh session about a topic you worked on before, the work you already did lives in checkpoints on disk. Continuity surfaces it three ways. Cold-Resume-Lean reconstructs a compact context block from those checkpoints and the session log without calling the model at all. The prompt-continuity hook watches each new prompt and injects a short hint when it matches a prior session’s topic. The fresh-session nudge tells you, on a low-quality fresh start, that a richer resume is available.

The shared idea is breadcrumb continuity: leave a trail of cheap, structured markers as you work, then follow the trail back instead of re-deriving the path.

Cold-Resume-Lean

Cold-Resume-Lean rebuilds context for a cold or forgotten session at zero LLM cost. It reads checkpoints and the session log, joins them, and emits a lean block you can inject directly. No summarization model runs, so reconstruction makes no paid model call. Pasting or restoring the resulting block still adds input tokens to the new session.

Run it with no session argument to list candidate sessions, or with a number or session ID to emit a block:

cd ~/.claude/skills/token-optimizer/scripts
python3 measure.py resume-lean                  # list candidate sessions
python3 measure.py resume-lean 1                # emit the block for candidate #1
python3 measure.py resume-lean SESSION_ID --print
python3 measure.py resume-lean --days 14        # widen the lookback window

The --print output is built to drop straight into a new run:

claude "$(cd ~/.claude/skills/token-optimizer/scripts && python3 measure.py resume-lean 1 --print)"

Cold-Resume-Lean works across Claude Code, Codex, OpenClaw, and OpenCode, so the same reconstruction reopens a session no matter which surface created it.

Why it is free

Reconstruction is pure file work: read the checkpoints, read the session log, join them, format the block. There is no model call, so reconstruction has no model-call cost. The lean block still has an input-token cost when used; it avoids reloading the entire old prefix, not every cache write.

Prompt continuity (the automatic hint)

The prompt-continuity hook runs on every user prompt. It checks whether your prompt matches the topic of a prior session and, if it does, injects a lean context hint through the hook’s additionalContext channel. The match is keyword-based and the hook runs under an 8-second wall-clock budget, so work is bounded, but a hook can still use time within that budget.

This is the hands-off path: you start typing about yesterday’s work, and the relevant breadcrumb appears without you running a command. It fires automatically through the UserPromptSubmit hook when the plugin is installed.

cd ~/.claude/skills/token-optimizer/scripts
python3 measure.py prompt-continuity   # the command the hook runs; rarely run by hand

The fresh-session nudge

When you start a fresh session whose context fill is meaningful but whose quality is low, continuity surfaces a nudge: a richer resume is available from a prior checkpoint. Two thresholds gate it so it stays quiet on genuinely new work.

Condition	Variable	Default
Quality below	TOKEN_OPTIMIZER_FRESH_NUDGE_QUALITY	70
Fill at least	TOKEN_OPTIMIZER_FRESH_NUDGE_MIN_FILL	45

Both are defined in the configuration reference. Raise the quality threshold to nudge more often, or lower it to nudge less.

Codex continue-last

Codex has its own continuation flow. The continue-last command renders a topic-matched hint from a prior Codex session for use in a continuation prompt.

TOKEN_OPTIMIZER_RUNTIME=codex python3 measure.py continue-last
TOKEN_OPTIMIZER_RUNTIME=codex python3 measure.py continue-last --topic "auth refactor"

The codex-continue-last verb is an alias for the same behavior.

Browsing and measuring checkpoints

List every saved checkpoint, newest first, with its age and filename:

cd ~/.claude/skills/token-optimizer/scripts
python3 measure.py list-checkpoints

For aggregate telemetry (count, recency, session coverage) over a window, enable checkpoint telemetry and run the stats command:

cd ~/.claude/skills/token-optimizer/scripts
TOKEN_OPTIMIZER_CHECKPOINT_TELEMETRY=1 python3 measure.py checkpoint-stats --days 14

checkpoint-stats requires TOKEN_OPTIMIZER_CHECKPOINT_TELEMETRY=1 because telemetry collection is off by default.

Default state

The automatic hint is on. Prompt-continuity fires on every prompt through the UserPromptSubmit hook for plugin users, and the fresh-session nudge fires on eligible fresh starts.

The manual reopener is on demand: resume-lean, continue-last, and list-checkpoints run only when you call them.

Checkpoint telemetry (checkpoint-stats) is off until you set TOKEN_OPTIMIZER_CHECKPOINT_TELEMETRY=1.

How to turn it on and off

Cold-Resume-Lean, continue-last, and list-checkpoints are read-only commands you invoke by hand. There is nothing to disable; just do not run them.

The automatic prompt-continuity hint comes from the prompt-continuity hook. To stop it, remove its UserPromptSubmit wiring from the same install source that provides it. setup-smart-compact --uninstall removes capture/restore hooks, not the prompt-continuity hook:

cd ~/.claude/skills/token-optimizer/scripts
# Plugin users: disable/uninstall the plugin, or adjust its hook configuration.
# Script users: remove the prompt-continuity UserPromptSubmit entry in settings.json.

To quiet the fresh-session nudge without removing hooks, lower its quality threshold so it rarely qualifies, for example TOKEN_OPTIMIZER_FRESH_NUDGE_QUALITY=0.

Removing checkpoint data

Uninstalling the hooks leaves existing checkpoints on disk. For Python-managed checkpoint deletion, inspect purge first; its list is not universal adapter coverage. See your data and privacy.

Defaults and thresholds

Setting	Default	Notes
Prompt-continuity budget	8 seconds	Wall-clock; misses cost nothing
resume-lean lookback	recent sessions	Widen with --days N
Fresh nudge quality floor	70	TOKEN_OPTIMIZER_FRESH_NUDGE_QUALITY
Fresh nudge minimum fill	45	TOKEN_OPTIMIZER_FRESH_NUDGE_MIN_FILL
Checkpoint telemetry	off	Set TOKEN_OPTIMIZER_CHECKPOINT_TELEMETRY=1 for stats
Cold-Resume-Lean cost	zero LLM tokens	Pure file reconstruction

Risk rating

None. Every continuity feature is additive and read-only with respect to your conversation. Cold-Resume-Lean reads files and prints a block. The prompt-continuity hint is injected only on a topic match and is bounded by an 8-second budget that fails open on a miss. Nothing here can corrupt or delete a session.

Related environment variables

• TOKEN_OPTIMIZER_FRESH_NUDGE_QUALITY, TOKEN_OPTIMIZER_FRESH_NUDGE_MIN_FILL (fresh-session nudge gates)
• TOKEN_OPTIMIZER_CHECKPOINT_TELEMETRY (enables checkpoint-stats)
• TOKEN_OPTIMIZER_CONTINUITY (OpenCode enable flag)
• TOKEN_OPTIMIZER_CHECKPOINT_RETENTION_DAYS, TOKEN_OPTIMIZER_CHECKPOINT_RETENTION_MAX, TOKEN_OPTIMIZER_RELEVANCE_THRESHOLD (OpenCode/OpenClaw restore tuning)

Defined with defaults in the configuration reference.

Platform availability

Cold-Resume-Lean spans Claude Code, Codex, OpenClaw, and OpenCode. The automatic prompt-continuity hint runs on Claude Code (CLI and VS Code). continue-last is the Codex path. See the capability matrix.

Related

• Smart compaction: how checkpoints are captured, including progressive and milestone triggers.
• Compaction model: why a cold resume is expensive without continuity.
• Cache economics: the prefix re-write cost a resume avoids.
• Configuration: every continuity variable.