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

[EloB]

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.

[github-actions[bot]]

Found 3 possible duplicate issues:

1. https://github.com/anthropics/claude-code/issues/10352
2. https://github.com/anthropics/claude-code/issues/9119
3. https://github.com/anthropics/claude-code/issues/6001

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[EloB]

Their tickets talk about implementing it in VSCode extension. This is about adding the functionality to Claude Code headless. This feature most be implemented before you can implement it in VSCode extension.

[github-actions[bot]]

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.