Recover coding work after context compaction
Preserve the reason for the change, check the state on disk, and resume from evidence rather than a stale summary.
Contents
- Context, memory, and repository state are different things
- Write a checkpoint before the handoff becomes urgent
- Give the checkpoint a reliable home
- Capture identity and file state
- Understand what the local replay demonstrated
- Reopen the intended session
- Compact with a preservation goal
- Verify before editing after a restart
- Invalidate stale evidence explicitly
- Keep recurring memory small and reviewable
- Frequently asked questions
To recover a coding task after context compaction, first restore the goal, then verify the worktree, then resume the smallest unfinished step. A conversation summary can tell an agent what it intended to do. It cannot establish that a test finished, that a branch still points at the same commit, or that a draft pull request was actually created.
The same procedure helps after a crashed terminal, an interrupted tool call, a new session, or a handoff between agents. The details of reopening a conversation vary by client. The durable evidence can remain ordinary files and Git state.
Download the checkpoint template and snapshot helper. The helper was exercised in a temporary Git repository, including a change made without moving HEAD. The replay below tests state detection; it is not a measured experiment comparing model compaction quality.
Context, memory, and repository state are different things#
A model's active context includes the instructions, conversation material, and tool results it receives for its next step. Persistent notes live outside that active window. The repository and running environment are separate again.
| State | What it can preserve | What still needs checking |
|---|---|---|
| Conversation history | Requests, discussion, tool messages | What is currently active or summarized |
| Compacted context | A shorter account of earlier work | Details omitted or made stale by later changes |
| Task checkpoint | Decisions, evidence locations, next actions | Whether recorded facts still match reality |
| Git commits and working files | Actual source changes | Uncommitted, untracked, and unrelated work |
| Running environment | Servers, jobs, databases, sessions | Whether processes survived and which revision they use |
| External services | PRs, deployments, issue updates | Whether an attempted action completed |
Anthropic's long-running harness account describes using progress artifacts and Git history to help later sessions regain their bearings. Its central engineering lesson is useful here: leave something the next session can inspect instead of expecting a compressed conversation to carry every operational fact.
For the broader distinction between a single session and the system around it, see context, harness, and loop engineering.
Write a checkpoint before the handoff becomes urgent#
A checkpoint is a concise handoff document, not a transcript. It should let another contributor answer:
- What outcome was requested?
- What must remain unchanged?
- Which checkout contains the work?
- What is complete, and how was that established?
- What remains uncertain?
- What should happen next?
The download includes a longer template. A small task might use:
# Task checkpoint
Objective: cap retry delays at 60 seconds.
Non-goal: change the retry schedule before it reaches the cap.
Repository/worktree: /path/to/project-fix
Branch: fix/retry-cap
HEAD: <full commit SHA>
Changed files: retry_delay.py
Untracked files to preserve: notes/reproduction.txt
Verified:
- Original cap test fails on attempt 9.
- Failure log saved outside the checkout.
Changed, not yet verified:
- Applied min(calculated_delay, cap).
Next:
1. Run the targeted cap test.
2. Run the complete existing suite.
3. Review the diff for unrelated changes.
External effects: none.
Stop if: expected behavior differs from the agreed 60-second cap.This is a worked example, not a report of a real production repair. Its most important line is “changed, not yet verified.” A less careful summary might turn “applied a fix” into “fixed,” causing the next session to skip the check.
Store commands with outcomes, timestamps where useful, and the revision or file state they tested. “Tests passed earlier” is weak evidence when files have changed since.
Give the checkpoint a reliable home#
For a one-off task, a Markdown file outside the repository can be enough. For a shared task, use a location both contributors can access, such as a task workspace or a versioned team handoff document.
Choose deliberately:
| Location | Useful for | Limitation |
|---|---|---|
| Outside the worktree | Private local investigations and logs | Another machine will not automatically receive it |
| Gitignored file in the worktree | Convenient local notes | A fresh worktree or clone may not contain it |
| Committed task document | Team-visible handoffs and review | Must exclude secrets and temporary machine-specific data |
| Scheduler's task memory | Recurring work and failure deduplication | Depends on the scheduler and execution environment |
Do not overwrite the repository's standing instructions with a task diary. Keep long-lived conventions in AGENTS.md or CLAUDE.md. Keep volatile investigation state with the task.
Before cleaning up a worktree, inspect it for untracked notes and generated evidence that must survive. A session ID does not substitute for those files.
Capture identity and file state#
The supplied capture_state.py requires Python 3.9 or later and Git. It prints a JSON snapshot without editing the repository.
From the downloaded example directory, run:
python3 capture_state.py \
--repo /path/to/project-fix \
retry_delay.py test_retry_delay.py \
> /path/outside-project/checkpoint-state.jsonReplace the paths and select the files relevant to your task. The repository must already contain a commit. The output includes:
- Repository root and branch.
- Full HEAD SHA.
- A hash of the tracked working-tree diff against HEAD.
- Git's working-tree status.
- Content hashes of the explicitly selected files.
- Capture time.
Save the output outside the worktree so writing the snapshot does not itself change the measured tree. Do not select credential files. If a selected path resolves outside the repository, the helper rejects it.
The hashes detect differences; they do not store a recoverable copy of the content. The helper also does not capture every untracked or ignored file, the full staging-area contents, databases, running processes, or remote service state. Select relevant new files explicitly and record any external prerequisites separately.
For important unfinished edits, use your normal backup or version-control practice in addition to this snapshot.
Understand what the local replay demonstrated#
We tested the helper with a small disposable repository:
- Commit a file containing
value = 1. - Change it to
value = 2without committing. - Capture its state twice.
- Change it to
value = 3, still without committing. - Capture it again.
| Comparison | HEAD | Tracked diff hash | Selected file hash |
|---|---|---|---|
| First snapshot versus immediate replay | Same | Same | Same |
| First snapshot versus later edit | Same | Different | Different |
This is why “same branch, same commit” is insufficient for recovery. Uncommitted changes can invalidate an earlier test while leaving both values unchanged.
The test also confirmed that selecting a path outside the repository is rejected. These are checks of the helper's mechanics, not a guarantee that the snapshot covers every dependency of a real application.
Reopen the intended session#
Use the same worktree when continuing work, and identify the session deliberately when several are active.
| Client | Resume a specific session | Continue the most recent session in the current directory |
|---|---|---|
| Claude Code | claude --resume SESSION_ID | claude --continue |
| Codex | codex resume SESSION_ID | codex resume --last |
These commands were checked against the Claude CLI reference, OpenAI's developer-command reference, and local CLI help for Claude Code 2.1.287 and Codex 0.160.0.
Prefer an explicit session ID when “latest” might refer to a different investigation. If you moved the repository or changed machines, confirm how the client locates its saved sessions before assuming a continuation command selects the intended one.
A conversation can also be unavailable. In that case, start a new session and give it the checkpoint, source checkout, and relevant evidence. A well-written checkpoint should support that fallback.
Compact with a preservation goal#
Codex documents /compact for summarizing an extended conversation and freeing active context. Claude Code also supports /compact, including a focus instruction such as:
/compact Preserve the agreed acceptance criteria, current branch and
revision, changed-but-unverified work, evidence paths, and next step.See Codex's command reference and Claude's context-management explanation.
Write the durable checkpoint first. A preservation request can guide summarization, but it cannot make an absent log or unrecorded decision appear. Do not rely on any client keeping the same active instructions forever across an upgrade or a configuration change.
Also distinguish this article's handoff checkpoint from a client's file-rewind feature. A Markdown checkpoint describes state; it does not undo edits. A file rewind does not roll back a remote deployment or an issue comment.
Verify before editing after a restart#
Give the resumed agent an explicit recovery request:
Read the checkpoint and its evidence before changing files.
Confirm the repository root, worktree, branch, and HEAD.
Compare the selected file hashes with current contents.
Separate facts that still hold from stale or unverified claims.
Inspect pending external actions before retrying them.
Then state the next bounded step and continue within the original scope.The recovery procedure should be short enough to follow every time:
- Confirm identity. Inspect the root path, branch, HEAD, and working-tree status.
- Read the current diff. Establish what the previous session actually changed.
- Reconcile the checkpoint. Mark mismatches instead of silently accepting its narrative.
- Check external effects. Look for an existing draft PR or completed job before repeating a request.
- Restore prerequisites. Check the interpreter, dependencies, services, and required fixtures.
- Run the smallest decisive check. Establish the current baseline before continuing implementation.
- Update the checkpoint. Record new evidence and the remaining work.
Avoid running a build, migration, or test twice simply because the last message lacks a result. First determine whether the original process is still running. A missing response can mean interrupted observation rather than failed execution.
Invalidate stale evidence explicitly#
A useful checkpoint distinguishes a historical observation from a current assertion.
| Change since the checkpoint | What to reconsider |
|---|---|
| Relevant source file changed | Tests and review of that behavior |
| Dependency lockfile changed | Setup, reproducibility, affected checks |
| Base branch moved or code was rebased | Integration assumptions and conflict resolution |
| Acceptance criteria changed | Whether completed work still meets the task |
| Environment or test service changed | Results dependent on that environment |
| External action has uncertain status | Whether retrying would duplicate the action |
Suppose a previous session tested a 60-second retry cap, and a maintainer subsequently requests 30 seconds. The old passing result remains a true historical fact. It no longer proves the current acceptance criterion.
Record both: “60-second behavior verified at the earlier file state; 30-second requirement not yet implemented.” This preserves useful evidence without letting memory override the current request.
Do not solve a mismatch by resetting away changes you do not recognize. Another contributor may own them. Inspect, identify ownership, and isolate your next action.
Keep recurring memory small and reviewable#
Agentastic scheduled tasks keep local task memory outside the repository. That is useful for recording previously diagnosed failures and existing proposals. Manager Agents keep their longer-lived working knowledge in a separate home with a Git-backed wiki.
Those storage mechanisms make continuity possible, but the agent still needs to distinguish observation, decision, and assumption. Append new outcomes with enough identity to connect them to the right task. Periodically replace obsolete summaries with a concise current account while preserving evidence that matters.
For a scheduled repair, carry forward the attempt count and unresolved blocker. A new session must not reset the budget merely because its conversation is fresh. The scheduled CI guide shows that ledger pattern.
A successful recovery ends with the agent able to explain what is known, what changed, and what action comes next. It should not need to reread an entire transcript—or trust an old “done” message—to continue safely and efficiently.
Download Agentastic for macOS to keep the task workspace, agent session, and verification tools together during the handoff.
Frequently asked questions#
What is context compaction in a coding agent?#
It reduces the conversation material kept in the model's active context, often by summarizing earlier turns. It helps a long session continue, but it is not a backup of source files, running processes, or remote actions.
Does resuming a session restore my repository?#
Do not assume it does. Resume retrieves conversation state according to the client. The working directory, files, branch, services, and external effects must be checked separately.
What should an agent checkpoint contain?#
Record the objective, acceptance criteria, repository and worktree identity, source revision, changed files, decisions, verification evidence, outstanding work, external effects, and the next bounded action.
How can I tell whether progress notes are stale?#
Compare their recorded revision and file state with the current worktree, inspect intervening changes, and rerun checks whose inputs changed. A matching branch name alone is not enough.
Can I move a task from Claude Code to Codex?#
A plain-text checkpoint and the source files can support a cross-provider handoff. Do not assume the clients share session-history formats, automatic memory, permissions, or compaction behavior.