claude-code - 💡(How to fix) Fix Feature request: Session checkpoints, branching, and merge (git-like session management) [2 comments, 2 participants]

Summary

Git gives developers checkpoint/branch/merge for code. Conversation sessions deserve equivalent primitives. The Web UI already supports conversation branching via message edits — the CLI should expose similar capabilities.

Motivation

When using Claude Code for complex, multi-step tasks (refactoring, debugging, architecture exploration), the conversation session accumulates valuable state:

• Tool call history (which files were read, what commands returned)
• Permission grants (approved tools and paths)
• Failed approaches and their error context
• Prompt cache alignment

Currently, the only session operations available are:

• /clear — destroys all context
• /compact — lossy compression
• --resume — continue from where you left off

There's no way to save a point in time, explore a direction safely, or merge learnings from a parallel exploration back.

Proposed Primitives

1. Checkpoint (save/restore)

/checkpoint save <name>     # snapshot current session state
/checkpoint restore <name>  # return to that exact state
/checkpoint list            # show available checkpoints

Use case: Before attempting a risky refactoring or architectural change, save a checkpoint. If the approach fails after 30 turns of exploration, restore instantly instead of starting fresh with a handoff document.

Why not just use a handoff document?

• A handoff document is lossy compression. The author must decide what to include.
• Restoring a checkpoint preserves full execution context: tool results, error messages, file contents that were read, permission state.
• Prompt cache hits on restore (same conversation prefix) vs. full cache miss on new session.
• In practice, new sessions from handoff documents often repeat the same failed approaches because the failure context was summarized away.

2. Branch

/session branch <name>      # fork current session into a named branch
/session switch <name>      # switch between branches
/session list               # show branches

Use case: Mid-debugging, an urgent deploy issue comes in. Branch the session, handle the deploy with full context isolation, switch back to debugging without cross-contamination.

3. Merge (summarize)

/session merge <source> [--summarize]

Use case: After exploring an approach in a branch for 30+ turns, merge the conclusions back to the main session — without bringing all the exploratory noise that would consume context window.

With --summarize, the model itself generates a summary of what happened in the branch, producing it as its own output rather than injecting foreign context. This means the merged content integrates naturally as "things I concluded" rather than "things I was told."

Technical Context

The session JSONL already uses a DAG structure (UUID + parentUUID chain), which naturally supports branching. The leafUuid pointer in the file header identifies the current head. The infrastructure for branching appears to exist internally — this request is about exposing it as user-facing CLI primitives.

The VM Snapshot Analogy

A checkpoint is to a handoff document what a VM snapshot is to a Dockerfile:

• Both get you to a working state
• But the snapshot is lossless and instant
• The Dockerfile (handoff doc) requires rebuilding state from scratch, is lossy by design, and can't capture runtime state

Real-World Pain Point

In long-running development sessions, compaction events cause context loss. Developers working with persistent AI assistants (agents that maintain state across sessions) face a recurring pattern:

1. Build up rich context over 50+ turns
2. Hit compaction or need to context-switch
3. Write a handoff/summary document
4. Resume in new session, re-read files, re-establish context
5. Watch the new session fall into the same holes the previous one already dug out of — because the failure context was lost in summarization

Checkpoints would eliminate steps 3-5 entirely for the "exploration gone wrong" case, and branching would prevent the need for context-switching workarounds.