On this page
TLDR
Checkpoints save and restore conversation state. A full deep-dive guide is coming soon.
What it is
A checkpoint is a saved state snapshot of a multi-turn Claude session, designed for resuming long-running work across days or after infrastructure failures. After turn 12 of a 30-turn project, save state (history, file context, progress) to disk. Tomorrow, load that checkpoint, continue from turn 13, agent picks up with full context. Checkpoints are state persistence, not summarization.
The critical distinction: checkpoints preserve the full conversation thread, not a summary. Different from progressive summarization, which compresses history. Summarization loses transactional details (order IDs, amounts, deadlines); checkpoints keep them verbatim in the original messages. When you resume, Claude sees the full prior conversation. Preserves precision for financial, legal, medical use cases.
Checkpoints are scoped to single-session resumption, not multi-session fusion. Session A crashes at turn 12, load checkpoint, resume in same session at turn 13. You do not fork session A into session B. Linear resumption, not branching (that would be fork_session, a different pattern).
The use-case cluster is long-running work: multi-day research, 20+ file refactor, hour-spanning data pipelines. Triggers: daily boundaries, infrastructure limits, failure recovery. After 8 hours of work, save a checkpoint. If Claude times out at 2 AM, load yesterday's checkpoint. Checkpoints are the human-friendly recovery mechanism for work too large for one continuous session.
How it works
Checkpointing has three stages. Capture: at a milestone, export conversation history (messages, tool results, file state) to JSON. Not a summary, the exact message sequence. Store: in version control, cloud storage, or local disk. Restore: next session, load the file, inject messages back into Claude's context, continue. Claude resumes with full memory of prior turns.
The message list in a checkpoint is immutable. When you restore, you inject all prior messages exactly as they were. No rewriting, no compression, no summarization. This is why precision is preserved: a customer ID from turn 8 is still verbatim in turn 13. Contrast with summarization, where turn 8-10 collapse to two sentences.
Checkpoints face one challenge: context window limits. A 30-turn project generates a large message list; by turn 25, prior messages may get lost in the middle (lost-in-the-middle). Mitigation: include a persistent case-facts block at the start of restored context. The block does not expire even as the conversation grows.
Restoration is not automatic. You explicitly load the checkpoint and confirm before continuing. Prevents accidental context corruption (merging unrelated sessions). Flow: end session → save checkpoint → next day → load → confirm → continue. The explicit gate is where you spot issues before proceeding.
Where you'll see it
Multi-day medical records extraction
1000 clinical notes, 12 hours/day. Save checkpoint after batch 333; next morning, load and continue from batch 334 with same schema and learned patterns. Without checkpointing, day 2 would re-extract or start fresh.
Cross-service API refactor over 3 days
Day 1 = dependency mapping, day 2 = schema refactoring, day 3 = migration tests. Each day saves a checkpoint. Day 2 finds an issue, revert to day 1's checkpoint and adjust. Without checkpoints, lose day 1's analysis.
Show 2 more examples
Failure recovery in overnight batch
Pipeline processes 10M records via Batch API. Cluster restarts at 7.2M. Checkpoint saved every 1M records: load 7M, resume at 7M+1. Without checkpoints, restarting wastes compute on 7M records.
Long-form content with iterative refinement
50-page guide. Day 1: chapters 1-10 + checkpoint. Day 2: chapters 11-20 with full prior context. Day 3: chapters 21-50 with all consistency. Without checkpoints, day 2 lacks chapter 1-10 details.
Code examples
import Anthropic from "@anthropic-ai/sdk";
import fs from "fs";
const client = new Anthropic();
interface Checkpoint {
messages: Anthropic.MessageParam[];
metadata: { savedAt: string; phase: string; objective: string };
}
function saveCheckpoint(messages: Anthropic.MessageParam[], phase: string, objective: string) {
const cp: Checkpoint = {
messages,
metadata: { savedAt: new Date().toISOString(), phase, objective },
};
fs.writeFileSync("checkpoint.json", JSON.stringify(cp, null, 2));
console.log(`Saved at phase ${phase}`);
}
function loadCheckpoint(): Checkpoint {
const data = fs.readFileSync("checkpoint.json", "utf-8");
return JSON.parse(data);
}
async function resume() {
const cp = loadCheckpoint();
const messages = cp.messages;
console.log(`Resuming at ${cp.metadata.phase}, ${messages.length} prior messages`);
messages.push({ role: "user", content: "Continue. What patterns emerge?" });
const resp = await client.messages.create({
model: "claude-opus-4-5",
max_tokens: 4096,
system: `You are continuing a multi-day research project. Phase: ${cp.metadata.phase}. Objective: ${cp.metadata.objective}.`,
messages,
});
messages.push({ role: "assistant", content: resp.content });
saveCheckpoint(messages, `phase ${parseInt(cp.metadata.phase) + 1}`, cp.metadata.objective);
}Looks right, isn't
Each row pairs a plausible-looking pattern with the failure it actually creates. These are the shapes exam distractors are built from.
Summarize the conversation at each checkpoint to save tokens.
Summarization erases precision.
Checkpoints preserve the full thread; summarization is the opposite approach (and is tested as an anti-pattern).
Checkpoints and fork_session do the same thing.
Different.
Checkpoints resume linearly (A → A+1 → A+2). fork_session branches (A → A1 AND A2). Don't confuse them.
If a session crashes, just start over; files are saved.
Files survive but agent context does not.
A new session lacks the prior conversation: Claude repeats analysis, misses nuances, makes inconsistent decisions. Checkpoints preserve agent reasoning, not just output files.
Use checkpoints only for infrastructure failures.
Checkpoints are for any resumption: daily breaks, phase boundaries, human review gates.
Waiting for failure is reactive; checkpointing by design is proactive.
Merge two checkpoints from different sessions into one.
Checkpoints are single-session snapshots.
Merging is not supported; corrupts context. To combine work, use manual synthesis or explicit hand-offs (output of A as input to B).
Side-by-side
| Aspect | Checkpoints | Summarization | fork_session | Subagent |
|---|---|---|---|---|
| Preserves full conversation? | Yes, verbatim | No (summary) | Yes per fork | No, isolated |
| Precision loss? | None | High | None | Yes |
| Resumption pattern | Linear | Lossy | Branching | Sequential |
| Token budget impact | Grows with history | Reduced (lossy) | Per branch | Current turn only |
| Use case | Multi-day work, recovery | Long convos, cost | Comparing approaches | Parallel tasks |
| Reversibility | Yes (reload prior) | No (data lost) | Yes (merge decision) | No (work discarded) |
Decision tree
Will the task span multiple days or sessions?
Is losing fine-grained context details unacceptable?
Need to compare 2+ approaches from same starting point?
Resilient to infrastructure failures?
Have explicit approval gates or human-in-the-loop decisions?
Question patterns
6 V2 questions wired to this concept. Tap an answer to check it instantly - you'll see whether it's right and why - then expand the full breakdown for the mental model and all four rationales.
A subagent returns stop_reason: max_tokens with a partial summary. Production code aborts. What should it do instead?
Frequently asked
Showing 10 of 10 questions