Claude Code context handoff: compact, clear, resume, and revision checks

A Claude Code context handoff should tell the next session what remains to do, which file revision the notes describe, and which decisions are still open. A transcript alone can leave you searching for that information. This guide proposes a small HANDOFF.json record and an offline revision check. Neither is a built-in Claude Code feature, and we have not tested whether a model follows the record.

#Choose compact, clear, or resume

Use the command that matches the interruption. The following behavior is documented by Anthropic and was checked on October 23, 2026.

Anthropic describes automatic compaction near context limits and manual compaction with a focus instruction. For example, /compact Preserve the next action, pending decisions, and test results expresses what you want retained; it is not a test of retention. See best practices.

Resuming a compacted session continues from its compaction summary and remaining messages; it does not reload the messages that the last compaction summarized. Saved sessions can be reopened after /clear. See session management. Before continuing edits, compare the working files with the state the conversation describes.

#Keep durable instructions separate from this task's state

Anthropic documents CLAUDE.md and auto memory as ways to carry context across sessions. It also distinguishes instructions from enforced configuration. Use project instructions for recurring conventions; use the handoff below for one interrupted task. See memory documentation.

HANDOFF.json is our chosen filename. Saving it creates no special auto-loading guarantee. Explicitly ask the resumed or new session to read it. Do not turn a pending proposal into an approved decision while shortening the notes. If a meeting supplied the proposal, retain its source and date in the decision text; Circleback MCP setup covers retrieving those source statements.

#A reusable handoff template

Copy this structure, replace the placeholders, and save it beside the work. Keep credentials and private source material out of shared copies. An empty testEvidence array means that this record contains no test evidence.

{
  "version": 1,
  "goal": "Review the proposed retry limit",
  "file": {
    "path": "retry.js",
    "sha256": "REPLACE_WITH_64_LOWERCASE_HEX_CHARACTERS"
  },
  "pendingDecisions": ["Owner has not approved the retry limit"],
  "nextAction": "Read the retry test, then ask the owner about the limit",
  "testEvidence": []
}

Calculate the hash from the file bytes when you write the record. On macOS, shasum -a 256 retry.js prints the digest. The placeholder deliberately fails validation. After actually running a test, you can append a record such as the following; replace the example command, timestamp and exit code with the observed values.

{"command":"node --test retry.test.js","exitCode":0,"checkedAt":"2026-10-23T00:00:00Z"}

The timestamp and result are historical evidence. A matching hash does not prove that the recorded test ran or that dependencies and other files are unchanged. Rerun the relevant test before reporting current success.

#Reproduce the file-revision check offline

Save these four downloads in the same folder: validator, demo, filled handoff, and synthetic target. With Node.js 22+ or Bun, run one of these commands:

node context-handoff-demo.mjs
# Or:
bun context-handoff-demo.mjs

The demo reads only the supplied sample files, alters a copy in memory, and prints:

{
  "valid": "valid",
  "changed": "changed-file",
  "malformed": "invalid-handoff",
  "missingData": "invalid-handoff",
  "missingFile": "missing-file"
}

The validator checks required fields, the supplied filename, and SHA-256 of supplied bytes. It does not open the path inside the JSON or execute recorded commands. Its test suite also covers a wrong filename, invalid field types, and empty evidence. No network, Claude invocation, hook, or file write is involved in the demo.

A valid result means the record has the expected shape and its digest matches the supplied file. SHA-256 does not validate meaning, authorize actions, authenticate the author, or protect against someone changing both file and record. This single-file example does not certify a repository revision. On changed-file, inspect the change and revise the handoff after review; do not merely replace the hash to make the check pass.

#Start the next session with an explicit request

After choosing resume or a new session, provide a request like this:

Read HANDOFF.json and the referenced work file before editing.
Compare the recorded revision with the current file.
If it differs, explain the difference before continuing.
Keep pendingDecisions pending. Report the next action and available test evidence.
Ask for any missing decision; do not infer approval from these notes.

This is a proposed workflow, not evidence that AI obeyed it. Review the response against the record, resolve the open decision with its owner, and rerun the relevant checks. The offline experiment establishes only what the validator accepts and rejects.