[FEATURE] Expose checkpoint restore / rewind in headless Claude Code (for editor & automation integrations)

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Claude Code provides a checkpoint / rewind mechanism in interactive usage, which is extremely valuable for safely iterating on code changes.

However, there is currently no documented or supported way to restore / rewind a checkpoint in headless mode (e.g. when using claude -p ... in scripts, automation, or editor integrations).

This limitation affects more than just CI workflows:

• Editor integrations (such as the VS Code extension) cannot reliably rewind code changes programmatically.
• Automated or tool-driven flows cannot “undo and retry” using Claude Code’s native checkpoint semantics.
• Users and tool authors are forced to reimplement rollback using git resets or filesystem snapshots, duplicating functionality that already exists.

Without a non-interactive restore API, checkpointing is effectively UI-only, which limits reuse across first-party and third-party tooling.

Proposed Solution

Expose checkpoint restore / rewind functionality to headless Claude Code via a stable, non-interactive interface.

This request is intentionally narrow:

• It does not propose a new checkpoint system.
• It only asks for a way to restore / rewind an existing checkpoint programmatically.

Two possible interfaces (either would satisfy this requirement):

Option 1: CLI flag for restoring a checkpoint

Provide a dedicated flag to restore a checkpoint by ID:

claude --checkpoint <uuid> --checkpoint-scope code|conversation|both

This would allow tools and scripts to trigger rewind behavior explicitly and deterministically.

Option 2: stdin control message (control_checkpoint)

Expose restore functionality via structured stdin messages:

`json
{ "type": "control_checkpoint", "uuid": "message-id", "scope": "code|conversation|both"}
`

This approach is particularly well-suited for:

• editor integrations (e.g. VS Code),
• long-running headless sessions,
• tools that already stream prompts and responses.

Key Expectations

• Restore scope support: code, conversation, or both
• Fully non-interactive operation (no TUI)
• Deterministic checkpoint identification (ID/UUID or equivalent)
• Clear success/failure signaling (exit codes and/or structured output)
• Usable by first-party tools (e.g. VS Code extension) and third-party integrations

Alternative Solutions

Current workarounds include:

• Git commit/reset wrappers (heavy-handed and pollute history)
• Filesystem snapshots or directory copying (slow and platform-specific)
• Restarting sessions and re-running from scratch (inefficient and non-deterministic)

None of these integrate with Claude Code’s existing checkpoint semantics or allow selective restore (code vs conversation).

Priority

High - Significant impact on productivity

Feature Category

CLI commands and flags

Use Case Example

Example editor-driven scenario:

1. A user triggers a refactor from the VS Code extension.
2. Claude Code applies changes, but the result is incorrect.
3. The extension needs to offer an “Undo / Rewind” action.
4. Without headless restore support, this requires external git or filesystem hacks.
5. With this feature, the extension can restore the checkpoint directly and retry or revert cleanly.

Additional Context

• This feature would allow checkpoint/rewind to be reused consistently across:
• interactive CLI,
• headless automation,
• first-party editor extensions.
• Exposing restore programmatically enables safer, more reliable tooling without duplicating rollback logic.
• Happy to help test or validate an implementation from an integration perspective.