claude-code - 💡(How to fix) Fix [FEATURE] /handover — user-curated session hand-off with fresh context [2 comments, 2 participants]

Summary

Native slash command for intentional, user-curated session hand-offs to a fresh context window. Distinct from /compact (automatic, in-place, lossy on decisions) and from /resume / --fork-session (both reload existing history).

Problem

Long Claude Code sessions hit context pressure. Native options today:

• /compact — automatic summary; recent tool output crowds out earlier decisions; user can't cherry-pick what survives; quality is noticeably lower than what the model produces when explicitly asked to write a hand-over prompt
• /resume / --continue — reloads the bloated history, doesn't free space
• --fork-session — branches from current point, but full history still loaded
• CLAUDE.md / auto-memory — solves cross-session durable facts, not mid-session transient state

The community workaround: ask the model to write a hand-over prompt (goal, decisions, constraints, current state, next steps, dead-ends), /clear, paste into a new session. In practice this produces significantly higher-fidelity continuity than /compact — the model, when prompted explicitly to draft a hand-off, preserves load-bearing decisions and rationale that the auto-compact summary loses. But it's friction users repeat session after session.

Proposed Solution

A /handover command that:

1. Drafts a structured hand-off prompt from the current session, surfacing:
   • Goal
   • Decisions made (with rationale)
   • Constraints discovered
   • Current state (files modified, branch, in-progress changes)
   • Next steps
   • Approaches tried and rejected
2. Shows the draft inline with accept / cancel / edit options. Default flow is one-keystroke accept — no mandatory editor round-trip. An optional shortcut (e.g. Ctrl+G, or a --edit flag) opens the draft in \$EDITOR for users who want to curate before committing.
3. Starts a fresh session in the same cwd, pre-seeded with the (optionally curated) hand-off as the first user message.
4. Archives the original session with bidirectional links (handed-off-to / handover-from) so it's still navigable in the picker — same plumbing as proposed in #49146.
5. Flags: --edit (open in \$EDITOR before commit); --non-interactive (SDK / scripted use).

Why This Is Different From Existing Issues

• #49146 — improves /compact's UX (preserve archive, continue in new session). Still automatic summarisation. /handover is a different mode: explicit user-triggered, with a different drafting prompt aimed at intent fidelity rather than transcript compression.
• #51998 — session templates: reusable starting points for parallel branches ("read 50 files once, fork to N feature branches"). /handover is a linear baton-pass for one ongoing thread of work.
• #38210 — agent auto-restart. Automation-focused, not interactive.

Complementary, not duplicates. /handover could share the archive-and-link plumbing with #49146.

Why User-Driven Timing Matters

/compact fires on context pressure. But the right time to hand off often has nothing to do with token count:

• Finished a discrete sub-task and want to start the next phase fresh
• The session has accumulated dead-end exploration that's polluting the model's framing
• Switching from research mode to implementation mode and want a clean slate
• About to step away and want a self-contained baton for tomorrow / for a colleague

Today the user has to either wait for /compact to fire (wrong moment, lossy output) or do the manual hand-off dance. /handover gives them an explicit "I decide when to turn the page" lever, decoupled from context window mechanics.

Why The Curated Step Matters (Optional, Not Mandatory)

The reason model-drafted hand-overs beat /compact is fidelity of intent, not fidelity of detail — the prompt itself is doing the work. The default flow should be one-keystroke accept of the draft, because the draft is already good. Editing is the safety valve for users who want to drop a rejected approach or add a constraint the model missed, not a mandatory step.

Workflow Integration

• New hook events PreHandover / PostHandover, parallel to PreCompact / PostCompact.
• --promote-durable flag asks the user to mark facts as durable → auto-appended to CLAUDE.md or auto-memory rather than carried only in the hand-off. Over repeated hand-offs, durable knowledge migrates out of the prompt and into memory; the prompt naturally shrinks.

Priority

Medium-high. With 1M-context models and longer agentic workflows, /compact's lossiness is a recurring pain point. The manual workaround is widespread and produces noticeably better continuity than the native option — making it native both standardises a converged-on pattern and gives users explicit control over hand-off timing.