Claude Code /handoff — snapshot a session to a doc, then /clear and reload it in a fresh thread in the same process (via tmux input injection)

clear-and-prompt.sh

#!/usr/bin/env bash
# clear-and-prompt.sh — hand off the current Claude Code session.
#
# Clears THIS tmux-hosted Claude session and submits a fresh prompt, both
# delivered AFTER the current turn yields. The sender detaches and waits, so the
# REPL is idle when the keystrokes land (otherwise /clear would be swallowed as
# typeahead while Claude is still generating).
#
# Usage: clear-and-prompt.sh <pane-id> <prompt-text>
#   <pane-id>     usually "$TMUX_PANE" of the Claude session
#   <prompt-text> the prompt to type and submit after /clear
set -euo pipefail

pane="${1:?pane id required (pass \$TMUX_PANE)}"
prompt="${2:?prompt text required}"

command -v tmux >/dev/null 2>&1 || { echo "tmux not found" >&2; exit 1; }
tmux list-panes -a -F '#{pane_id}' 2>/dev/null | grep -qx "$pane" \
  || { echo "pane '$pane' not in any tmux session" >&2; exit 1; }

# Detach the sender so it outlives this turn ending.
nohup bash -c '
  pane="$1"; prompt="$2"
  sleep 2                                    # let the turn yield / REPL go idle
  tmux send-keys -t "$pane" "/clear" Enter   # wipe context -> fresh thread
  sleep 2                                     # let /clear settle
  tmux send-keys -t "$pane" -l "$prompt"      # type the new prompt literally
  tmux send-keys -t "$pane" Enter             # submit it
' _ "$pane" "$prompt" >/dev/null 2>&1 &
disown 2>/dev/null || true

echo "handoff scheduled for pane $pane"

handoff.md

description	Snapshot this session into a handoff doc, then /clear and reload it in a fresh thread
argument-hint	what the next session should focus on

You are performing a CONTEXT HANDOFF for the current Claude Code session: capture everything needed to continue, then clear this session and reload from the doc in a fresh thread (same process, empty context).

The user's steering for this handoff — what the next session should focus on and any specific instructions: $ARGUMENTS

Do this, in order:

1. Compose a handoff document that lets a fresh session with ZERO prior context continue this work. Include:

   • Goal — the overall task/objective.
   • Current state — what's done, in progress, verified vs. not.
   • Key files & locations — paths touched or relevant, one line each.
   • Decisions & constraints — choices made and why; anything to NOT do.
   • Next steps — concrete, ordered actions, weighted toward the user's steering above.
   • Gotchas / commands — how to run/test, env quirks, non-obvious context.
   • Open questions — anything unresolved. Tight, factual prose. Assume a competent reader with no memory of this conversation.

2. Write the doc. Mint a unique path in /tmp and write there with the Write tool:

   • Run: echo "/tmp/handoff-$(date +%Y%m%d-%H%M%S).md"
   • Write the document to that exact path.

3. Verify you are in tmux. Run echo "$TMUX_PANE". If it is EMPTY, STOP — do not clear anything; tell the user this session is not running inside tmux so the in-place handoff is impossible, and point them at the doc you just wrote.

4. Launch the handoff (only if $TMUX_PANE is non-empty). Run, substituting the real pane id and the doc path from step 2:

   bash ~/.claude/handoff/clear-and-prompt.sh "$TMUX_PANE" "Continue from a handoff. Read <DOC_PATH> in full, then carry out the work it describes."
   

5. End your turn immediately with a one-line confirmation, e.g. "Handoff written to — clearing and reloading now." Do NOT keep working: the turn must yield so the queued /clear can fire on an idle REPL.