handoff

To preserve Claude session context when switching instances, use a CLI session-management workflow that collects current state, beads, and git status, then transfers them to a new instance via mail and auto-primes it through hooks. Run gt handoff with explicit -c or -m options to safely execute the context transfer.

Context-switching for Claude sessions is the process of transferring working state and subject matter to a fresh instance to avoid losing progress. You need it when cycling to a new Claude instance during continuous work, ensuring hooks and repository state persist across restarts.

To hand off a Claude session using the command line, run gt handoff with explicit -c or -m options. This command coordinates state collection from your current session, sends the context to a new Claude session, and auto-primes it via SessionStart hooks for continuous work.

Handoff requires a CLI workflow environment and maintains hook, beads, and git state across sessions. It enforces safe usage by requiring explicit -c or -m options, but lists no external package dependencies, relying on internal hooks and mail for state persistence and session respawn.

Claude session context disappears on restart because the fresh instance lacks your previous working state. Without a state-persistence mechanism to collect and transfer inbox, beads, and repository state, the new session starts blank, breaking continuous work across context-switching boundaries.

Limitations of using CLI hooks for Claude state persistence include the requirement to use explicit -c or -m options for safe usage, dependence on a specific CLI workflow (gt handoff), and the need to properly coordinate SessionStart auto-priming to ensure hooks and git state transfer correctly.