[FEATURE] Add context window awareness, warnings, and graceful handoff before session death Labels: enhancement, UX

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

When a Claude Code session approaches its context limit, there is no warning and no recovery mechanism. The session simply stops functioning — mid-task, mid-sentence. All accumulated context, decisions, and progress are lost.

This disproportionately punishes productive sessions. The faster and deeper the work, the faster context burns, and the harder the crash. It always happens at the worst possible time — peak flow state, deep in a complex task.

The current workflow requires me to manually try to sense when Claude is "getting dumb," hope /compact works (it's unreliable), and accept that when context dies, everything is gone. There's no fuel gauge, no warning, no state preservation, no handoff. Additionally, transient errors like "Images exceed API limit" can wedge a session unrecoverably, compounding the problem.

I'm investing heavily in CLAUDE.md files, skills, memory, and SOPs — but all of that is undermined when sessions die without warning. It feels like flying a rocket plane at Mach 9 with no fuel gauge. When you run out of gas, it just explodes.

Proposed Solution

At ~80% context capacity, Claude should proactively warn the user: "Context is getting low. Consider starting a new session."

At ~90% capacity, Claude should automatically save session state to disk (e.g., .session-handoff.md) containing:

What was accomplished this session
What's currently in progress
What's remaining
Key decisions and context that would be lost
A ready-to-paste prompt to resume in a new session
The ideal experience: "Hey, we're running low. I've saved our progress to .session-handoff.md — start a new chat and I'll pick up where we left off."

Additionally, transient errors (like "Images exceed API limit") should not permanently wedge a session. These should fail gracefully and allow the conversation to continue.

Alternative Solutions

Automatic /compact at a threshold — Instead of waiting for the user to notice degradation, trigger compaction automatically when context usage crosses a threshold. This is the lowest-effort fix that would help immediately.
Memory file auto-save — Claude Code already has a memory system (MEMORY.md). On approaching the limit, automatically write session context there so the next session inherits it without any user action.

Session export command — A manual /handoff or /save-session command that generates a continuity prompt on demand, so users can proactively save state before hitting the wall.

Shorter, more frequent sessions by design — Encourage task-scoped sessions with built-in checkpointing (like git commits for conversation state) rather than long-running monolithic sessions that accumulate fragile context.

Priority

Critical - Blocking my work

Feature Category

CLI commands and flags

Use Case Example

I'm building an AI-powered photo renaming service — Python script, Claude API integration, launchd service, EXIF handling, gallery generator.

Claude and I are deep in a session. We've designed, built, debugged, and tested a feature. It's working. The code is done.

I ask Claude to commit and push. The finish line. And Claude just has a brain fault. Mid-session, no warning. Gone.

I start a new session. The new Claude has zero context. It greets me with "How can I help you today?" — no idea that finished, tested code is sitting there uncommitted. No idea what we built, what changed, or what decisions were made. I don't even know where to start re-explaining it.

With this feature, the dying session would have warned me at ~80% ("Context is getting low"), and at ~90% would have automatically saved a handoff file with what was accomplished, what's ready to commit, and a resumption prompt. The next session reads it and picks up at the finish line instead of the starting line.

Additional Context

<img width="619" height="458" alt="Image" src="https://github.com/user-attachments/assets/de1e28ff-e61c-408c-8f7a-3195fc3906e1" />