AI Coding Agent Checkpoints: When Saving State Costs Less Than Starting Over

A checkpoint is insurance against replay. It costs storage, serialization, validation, and sometimes extra model tokens, but it can preserve a long-running coding agent's plan, tool results, working tree, and verification state after an interruption. The economic question is how often recovery happens and how much work must be rebuilt.

Do not confuse conversational memory with an execution checkpoint. A summary may remind the model what it was doing, but a resumable task also needs exact code state, command outputs, environment identity, pending approvals, budget consumed, and idempotency keys for external actions. Without those, resume can duplicate a deployment or repeat a paid tool call.

The Break-Even Equation

Expected checkpoint value equals interruption probability multiplied by replay cost avoided, minus checkpoint creation, storage, restore, and validation cost. If a task has a 10% chance of interruption and replay costs $8, the expected avoided loss is $0.80. A checkpoint costing $0.12 to create and an expected $0.05 to restore is economical, before considering faster completion.

Replay cost includes more than prompts. Add repository setup, dependency installation, search calls, browser steps, builds, test fixtures, and human time reapproving work. Long tool-heavy sessions often have low token prices but high environment reconstruction cost.

What to Save

Save the smallest sufficient state. A task manifest should identify repository commit, branch, worktree diff, objective, completed steps, remaining steps, model and harness versions, token and runtime budgets, and external side effects. Store references to large logs and artifacts rather than injecting them all into the resumed prompt.

Record a compact evidence summary with pointers to full command output. On restore, verify that the repository, dependencies, credentials, and upstream resources still match. A stale checkpoint can be more expensive than a fresh run if it causes the agent to debug changes that occurred while it was paused.

Choose Checkpoint Frequency

• Checkpoint after expensive milestones. Preserve state after a successful build, migration, or broad test suite.
• Checkpoint before waiting. Approvals, rate limits, and external feedback create natural interruption boundaries.
• Avoid every-turn snapshots. Excessive serialization adds storage, latency, and noisy restore choices.
• Expire aggressively. Delete state after merge or cancellation according to code and secret retention rules.

A Long-Task Example

Consider a four-hour migration with $6 of tokens, $8 of sandbox time, and one hour of developer oversight. A failure halfway through requires about $7 of machine replay and 20 minutes of human reorientation. At $90 per hour, replay exposure is $37. If interruptions affect 5% of runs, expected loss is $1.85 per task.

Two milestone checkpoints cost $0.10 in storage and serialization and add one minute of agent time. Restore validation costs another $0.20 only on interrupted runs. Expected checkpoint cost remains far below expected replay loss. For a two-minute lint fix, the equation reverses and fresh execution is simpler.

Measure Resume Quality

Track checkpoint bytes, creation latency, restore latency, replay avoided, stale restores, duplicate side effects, and resumed-task acceptance. A resume that saves tokens but produces an unsafe duplicate action is a failure. Test restore behavior through planned interruptions rather than waiting for the first production outage.

Secure and Bound the State

Checkpoints can contain source code, secrets copied into command output, customer data, and internal URLs. Encrypt at rest, scope access to the task and operator, and redact credentials before persistence. Apply the same regional and contractual controls used for the repository itself. Cheap storage is not permission to retain sensitive execution history indefinitely.

Set byte and count limits. A runaway tool can produce gigabytes of logs and make every snapshot expensive. Store hashes, tails, structured summaries, and object references for large artifacts. Reject incomplete checkpoints explicitly rather than presenting them as resumable and discovering missing state after a failure.

Design for Idempotent Resume

Every external action should have a stable idempotency key or a precondition check. Before reopening a pull request, deploying a preview, or posting a comment, inspect whether the action already happened. Mark side effects as proposed, in progress, confirmed, or uncertain so the resumed agent does not treat a network timeout as proof of failure.

Test checkpoints across harness and model upgrades. A serialized internal object may not restore after a new version, while a portable task manifest and standard artifacts usually will. Keep migration code for active checkpoints or drain old tasks before changing incompatible formats. Version the schema and fail safely when a restore is unsupported.

Bottom Line

Checkpoint long, expensive, interruption-prone tasks at verified milestones and before external waits. Save exact execution state plus compact evidence, validate freshness on restore, and expire state after use. For short deterministic work, restart. The break-even point is expected replay avoided, not the size of the conversation.