Continuity progress — resume a new thread warm instead of re-exploring

A tiny, opt-in, per-project system that lets a fresh Claude Code thread pick up where the last one left off, without paying to re-explore the codebase.

The problem it solves

As a thread fills its context window, per-turn cost climbs, so you start a new thread. But a fresh thread has lost everything and re-explores the codebase — burning the savings the restart was for.

How it works (two files, one idea: write to disk, not to context)

• Write = manual, in-thread. You type /progress near the end of a working thread (right before you start a fresh one). Because you're in the live thread, the whole codebase and conversation are already loaded and paid for — so the model distills that into .claude/state/progress.md with no extra model call and no re-scan. This is the cheap moment to capture an expensive understanding, so capture it well: progress.md is optimized to be a complete, load-bearing handoff, not to be short.
• Read = automatic. A trivial SessionStart hook injects progress.md into the next thread when it opens in the same project. That's the only automatic behavior.

Two files under .claude/state/:

• progress.md — the always-current head: Objective, Current state, Architecture & key decisions (each cited), an Active references map, Next steps, Open questions & risks, Pointers. Rewritten in full each /progress. Density-governed (written to the point of diminishing returns), no hard cap.
• LOG.md — an append-only, actively cited decision reference. progress.md cites entries by id (#L007); a resuming thread pulls only the cited entry it needs, like following a footnote. Entry headers are the index: grep '^## ' .claude/state/LOG.md.

There is no per-turn hook and no background model call — the system costs nothing while you work, and only does anything when you run /progress or open a new thread.

Install

Recommended — as a plugin (works on any machine, no hardcoded paths). See QUICKSTART.md:

/plugin marketplace add shaunthebuilder/continuity-ledger
/plugin install continuity-ledger@continuity-ledger

Then in any project, run /continuity-ledger:progress before starting a fresh thread. The plugin ships a SessionStart hook that is data-gated — it injects nothing (and costs nothing) in a project until you've created a progress.md there by running the command. So it's opt-in by use, project by project, even though the plugin is installed once globally.

Alternative — standalone per project (shorter /progress command, no plugin):

bash /path/to/context-distillation/install.sh            # from inside the target project
bash /path/to/context-distillation/install.sh /path/to/project

This copies the hook + a /progress skill into the project's .claude/, seeds state/, and merges one SessionStart entry into .claude/settings.json (idempotent; existing hooks preserved). Never touches ~/.claude. Requires jq. Use the plugin or the standalone install for a given project, not both.

Use

• Work normally. Near the end of a thread, run /progress to capture state.
• Start a new thread in the same project — the prior progress.md is auto-injected.
• /progress show — print the current head.
• /progress ref <#Lxxx | topic> — pull a cited LOG entry (by id) or entries matching a topic.
• /progress rebuild — re-derive progress.md from LOG.md + a fresh repo look (fixes drift).
• /progress disable / /progress enable — temporary per-project off/on switch.

Uninstall

bash /path/to/context-distillation/uninstall.sh /path/to/project
# add --purge-state to also delete the accumulated progress.md/LOG.md

or /progress uninstall / /install-progress uninstall from inside the project.

Should you keep it? Prove it first.

This is opt-in on purpose. Whether it actually helps depends on your workflow (how often you restart threads, how big the codebase is). The validation/ directory has an A/B harness that measures token usage and build quality on a synthetic multi-thread task and applies an explicit adopt/reject rule. See validation/README.md. Recommendation: run it (or just trial the system on one real project for a week) before trusting it everywhere.

Layout

context-distillation/
  install.sh / uninstall.sh        # per-project install / removal
  hooks/inject-state.sh            # SessionStart: read-only, injects progress.md
  skills/progress/SKILL.md         # the manual /progress skill (update/show/ref/rebuild/...)
  templates/                       # progress.md / LOG.md seeds
  validation/                      # A/B harness: does it actually improve tokens + quality?

(The global /install-progress launcher lives at ~/.claude/skills/install-progress/.)