Feature Request: Auto-branch into new session with summarized context when context limit is reached instead of forcing to /clear

The Problem

When a Claude Code session hits its maximum context window, the session effectively dies. Compaction can only compress so much - once you've compacted multiple times and the summary itself fills the window, you're stuck. The only option is to start a fresh session and manually re-explain everything from scratch. This is the single most frustrating experience in Claude Code.

What happens today (the painful flow)

1. User is deep into a multi-hour task - 15+ files read, bugs diagnosed, half the implementation done
2. Context fills up. Auto-compaction fires. Session continues.
3. More work. Context fills again. Auto-compaction fires again. Summaries get summarized. Fidelity degrades.
4. Eventually: "I'm running low on context and may not be able to continue this conversation much longer"
5. User is forced to /clear or start a new session
6. In the new session, Claude knows nothing - not which files were modified, not what approach was chosen, not what was already tried and failed, not what the user's preferences are for this task
7. User spends 10-15 minutes re-explaining the task, re-reading files, re-establishing context
8. The cycle repeats if the task is large enough

This creates a hard ceiling on task complexity. Any task that exceeds ~1 session's worth of context becomes exponentially more painful, not because Claude can't do it, but because the tooling forces a total memory wipe at the worst possible moment.

The User Experience (Frustration in Detail)

1. Loss of momentum at peak productivity

The context limit always hits at the worst time - deep into implementation when Claude has the most accumulated understanding. You're mid-flow, Claude knows exactly which files are involved, what patterns to follow, what was already tried. Then it's all gone. Starting over feels like explaining a project to a new contractor who hasn't read any of the docs.

2. Re-orientation tax is brutal

A new session doesn't just lack the conversation - it lacks all the implicit understanding Claude built up:

• Which files exist and what they contain
• The project's coding patterns and conventions
• What approaches were already tried and rejected
• The user's preferences expressed during the session
• Partial work-in-progress and what's left to do

Re-establishing this costs real tokens, real time, and real user patience. Users often give up on complex tasks rather than face the re-orientation tax a second time.

3. Compaction quality degrades with each pass

Each compaction is lossy. Summary of a summary of a summary loses critical details:

• Exact file paths become vague references
• Specific line numbers disappear
• Nuanced decisions ("we chose approach B because approach A had a race condition on line 47") become "we chose approach B"
• Error messages that took 20 minutes to diagnose are compressed away, risking re-investigation

4. Users develop anti-patterns to cope

• Breaking naturally continuous tasks into artificial sub-tasks
• Keeping manual notes of what Claude should "remember" to paste into new sessions
• Writing overly detailed CLAUDE.md entries for things that are really session-specific
• Avoiding ambitious tasks entirely because "it won't fit in one session"
• Starting over 3-4 times on the same task, each time getting slightly further before hitting the wall

5. No graceful degradation

The transition from "productive session" to "dead session" is a cliff, not a slope. One moment Claude is fully context-aware and productive. The next, it's a blank slate. There's no middle ground, no gradual handoff, no continuity mechanism.

Proposed Solution: Session Branching

When context reaches its limit (or a user-defined threshold), automatically branch into a new session with a structured handoff summary.

How it would work:

1. Context reaches X% capacity (configurable, default 85%)
2. Claude Code displays: "Context is nearly full. Branch to a new session with carried-over context? [Y/n]"
3. If yes, Claude generates a structured handoff document containing:

• Task description: What the user is trying to accomplish
• Current status: What's done, what's in progress, what's remaining
• Modified files: List of all files created/edited with brief descriptions of changes
• Key decisions: Architectural choices made and why
• Failed approaches: What was tried and didn't work (to avoid re-investigation)
• Active errors/blockers: Any unresolved issues
• User preferences: Patterns and conventions expressed during the session

1. A new session starts with this handoff document injected as initial context
2. Claude in the new session acknowledges the handoff and continues seamlessly

The handoff document should be:

• Stored on disk (e.g., .claude/sessions/handoff-<timestamp>.md) so users can review/edit it before the new session ingests it
• Editable by the user before the new session starts - allowing them to trim irrelevant context or add corrections
• Structured, not prose - using headings and bullet points so the new session can parse it efficiently
• Focused on actionable state (what to do next) not historical narrative (what happened)

Alternative/complementary approaches:

| Approach | Description |
|---|---|
| Auto-branch | Fully automatic - detect limit, generate handoff, spawn new session |
| /branch | Manual command - user triggers the handoff when they choose |
| /checkpoint | Save a resumable snapshot mid-session (before hitting limits) |
| /continue | Start a new session that reads the most recent handoff file automatically |
| Session chaining | Link sessions so /history shows the full chain across branches |

Example user experience (proposed):

[After 90 minutes of work, context at 87%]

Claude: Context is approaching its limit. I can branch to a new session 
        with a summary of our work so far.

        Current progress:
        - 4/7 API endpoints migrated to new auth system
        - Files modified: auth.ts, middleware.ts, routes/users.ts, routes/jobs.ts
        - Remaining: routes/exams.ts, routes/analytics.ts, routes/integrations.ts

        Branch now? [Y] Yes  [n] No  [e] Edit handoff first

User: Y

[New session starts]

Claude: Continuing from previous session. I have context on the auth 
        migration - 4 of 7 endpoints are done. Next up is routes/exams.ts. 
        Let me read that file and continue.

What this solves:

• No more hard ceiling on task complexity
• No more manual re-orientation tax
• No more lost context at peak productivity
• No more anti-patterns (manual notes, artificial task splitting)
• Multi-hour tasks become viable without user frustration
• Failed approaches are preserved, preventing wasted re-investigation

What this does NOT solve (and that's OK):

• It won't give a single session infinite context (that's a model limitation)
• The handoff summary is still lossy (but structured loss is far better than total loss)
• Very long task chains will still accumulate summarization drift (but each individual session operates at full fidelity)

Priority justification

This is arguably the #1 quality-of-life improvement possible for Claude Code power users. Every developer who uses Claude Code for non-trivial tasks hits this wall regularly. The current experience - "figure it out yourself when context dies" - is the single biggest source of friction in the product. A graceful branching mechanism would transform Claude Code from a tool with a hard complexity ceiling into one that can handle arbitrarily large tasks through chained sessions.