Skip to content

Resume ​

The module behind /resume, it answers the question what did I start and never finish. It reads the Claude Desktop app's own session sidecars, keeps the sessions still open under the current project, reads the tail of each transcript, and hands back a ranked list to archive, resume, or drop. Nothing on disk says whether a session finished, so the module splits the job in two: a deterministic pass sorts the list, and an agent reads every tail and decides.

The first-order value is triage and archiving, not resumption. Measured over the open sessions in this repo, roughly half were finished work that had simply never been tidied away.

In Practice ​

The whole pass.

/resume

Triages every open session (scans the sidecars, reads every tail, writes sessions.nuon), works through the ranked list assigning a verdict to every unjudged row, then proposes the finished pile for archiving in one block.

Jump straight to a row.

/resume 3

Goes to row 3 of the ranked list without re-triaging.

Pick up one session by id.

/resume local_4257eb00

Prints that session's cleaned tail and asks what to do with it. An id only needs to be a prefix, find-row in resume.nu matches on either the session id or the cli session id.

Just the counts.

/resume check

Runs resume sweep, the cheap clock pass: it re-triages only when the ledger has gone stale past stale_days (14 by default), otherwise it just reports the ledger's age. Writes nothing new and offers no archiving either way.

The session start line. With the module installed, a project with open sessions gets one line at the top of a fresh session, something in the shape of of the sessions open in this project 5 look unfinished n 12 look finished but were never archived, nu .claude/resume/resume.nu top lists them n /resume works through them. It is read straight off the stored ledger (resume offer in resume.nu), never a scan, so ignoring it costs one line rather than the ~1.2 seconds a scan over the sidecar folder would cost on every launch.

An example outcome. After a triage pass, resume batch lists every row an agent judged done or talk in a single block, sorted so anything whose activity has moved since it was judged floats to the top with a note to re-triage it first. You confirm the whole list in one go rather than one row at a time, then each confirmed row is archived with its own archive_session call, sidecar re-read immediately before it.

The Two Lanes ​

The script sorts, the agent decides. The ledger lane (resume triage) computes what is countable and assigns a read order. It never writes a verdict. The judgement lane is an agent reading every tail and assigning one of four verdicts, plus live, which the script assigns on its own.

verdictmeans
donethe last request was satisfied, it was just never archived
openwaiting on you, a question, an offer, an unsettled fork
midcut off mid work
talka question answered or something explained, nothing was ever going to be built
liverunning right now, the script marks it, never you

The rubric an agent works from is references/triage.md, and it is explicit that done is a verdict about the last exchange, never about the whole thread, a row can carry obvious next work and still read done on the narrower test.

The tier a row lands in is a reading order and never a verdict:

tierreads as
1~94% not-done, read first
2genuinely ambiguous
3~94% done, the archive candidates

That split was scored against 77 hand-labelled rows out of an 86-row snapshot, the other 9 had moved on since the snapshot was taken and are described by a stale label rather than a wrong tier. The strongest free signal behind it is writes since the agent was last handed the turn, Edit/Write/MultiEdit/NotebookEdit calls counted from the last turn handover, which resets at a Stop hook or a task notification and not only at something you typed. The tell that keeps it honest is that a real prompt arrives as a bare string in the content slot, while a tool result is a block list and an injected skill body is a text block, get that test wrong and writes get miscounted against the wrong segment.

Key Files ​

resume.nu ​

The whole tool. Subcommands scan, triage, top, show, verdict, batch, sweep, offer. scan walks the sidecars and filters by cwd prefix. triage runs the ledger lane and writes the store. show <id> renders a cleaned tail, main chain only, tool calls reduced to their names, thinking and tool results dropped, trimmed from the oldest end to fit the token budget (--file renders straight off a path with no sidecar involved, which is also the fixture gate's way in). verdict is the only door a judgement comes through. batch proposes the archive pile. offer is the one-line session start print.

resume.nuon ​

The config. Decisions only, no paths and no session ids, so a wrong or missing file can only fail to offer something and never produce a wrong answer. inject_tokens (15000) is the one worth leaving alone, it lands just past p90 of a real session's cleaned size so a typical session injects whole.

SKILL.md ​

The procedure an agent follows when /resume runs: triage, read the whole ranked list (not just tier 1), assign a verdict to every unjudged row through verdict, propose the batch, archive what you confirmed one archive_session call at a time, and work the unfinished rows one at a time with show.

references/triage.md ​

The four-verdict rubric. The worked example of why done is about the last exchange and not the thread, the free-signal table with its catches (writes > 0 still misses mid work 7% of the time, and a done row that gets archived on a miss loses its transcript for good), and the rule that reading every tail, including tier 3, costs about 7.4k tokens for a whole triage pass, cheap enough that pre-filtering buys nothing.

commands/resume.md ​

The /resume command. Routes to the skill and carries the same argument shapes as the by-hand tool: empty, a number, an id, or check.

hooks/resume-offer.nu ​

The parked capture mode's post hook. It runs after a parked prompt has already landed on disk, calls resume offer and prints its stdout to stderr per the capture hook contract, and swallows anything that goes wrong rather than blocking the parked write. It exists so there is one implementation of the offer and not two that drift.

inject/resume.nuon ​

The session start injector entry, a kind: "script" record folded in by the inject-resume pointer in context/injectors' defaults.nuon. It calls resume.nu offer, deliberately not a hand-rolled SessionStart hook, which is the shape M6.B exists to stop.

module.json ​

The install manifest. One part, resume, group: "sessions", hard needs on injection-engine and capture's engine. It copies the script, config, hooks, injector entry, skill, references, and command into a project, and declares .claude/resume/sessions.nuon as a creates entry with mode: "prompt", since it is a store an install has to be asked about rather than silently overwriting.

USAGE.md ​

The thin end-user doc, the source of truth this page fills out. It carries the same commands, the by-hand subcommand list, and the "what it never does" rules, read it for the quick version.

What It Never Does ​

  • Archive anything on its own. batch proposes, you confirm the whole list, and the archiving itself is a separate step.
  • Archive from a CLI session at all. archive_session is not a Claude Code built-in, it is an MCP tool off the desktop app's own ccd_session_mgmt session server, so a CLI session can triage and propose a batch and the archiving half simply is not there.
  • Write a sidecar. They are the desktop app's private state, read only, no exceptions.
  • Grow its own appender. A parked prompt rides context/capture's new parked mode, and the offer hangs off that mode's post hook so the prompt is on disk before a character of offer is printed.
  • Read the handoff and task pile. .claude/HANDOFF-*.md and .claude/TASK-*.md are held back to a later pass, that pile needs reconciling before it can be a source.

What Is Not Proven Yet ​

This module was built end to end from spec on 2026-09-10 and the fixture gate at harness/tests/resume/run.nu reports every gate green as of that date. What the gate does not cover: nothing is installed into a real project yet, archive_session has never actually been called, the session start offer has never fired from a real session launch, and the rollover path for a session spread across priorCliSessionIds is code-read only.

Connects to ​

  • context/injectors carries the session start offer, resume folds in as a kind: "script" entry rather than registering its own SessionStart hook.
  • context/capture supplies the parked mode and its post hook, resume rides it instead of writing its own log appender.
  • The Claude Desktop app's ccd_session_mgmt MCP server is where archive_session actually lives, resume proposes rows for it but never calls it from outside a desktop session.
  • The condensed, end-user version of this page is the module's own USAGE.md, at harness/modules/resume/USAGE.md – that one is the thin command and gotcha reference, this page is the fuller depth of the same module.