continue-in-new-session

name

continue-in-new-session

description

Use when handing off to a fresh Claude session in the same worktree — splits the current tmux pane top-bottom (anchored to this session's pane) and launches a new `claude --dangerously-skip-permissions` pre-loaded with an initial prompt. The prompt can be a handoff doc reference (`@<doc>`), a slash command (`/brainstorming`, `/writing-plans @<spec>`, `/subagent-driven-development @<plan>`), or any free-text instruction — pass skill args through verbatim. Triggers on phrases like "continue in new session", "fresh session", "hand off to new claude", or after producing a spec/plan/handoff that's ready for the next phase.

Continue in New Session

Overview

Hand off the current spec or plan to a fresh Claude session in a new tmux pane. Preserves clean context for the next phase by starting a brand-new session with just the right slash command + file reference.

When to Use

• User passed a handoff doc / prompt as skill args → launch the new session with it
• Just produced a handoff summary (e.g. via /handoff) → next session reads it and continues
• Just finished a spec (brainstorming output) → next session runs /writing-plans @<spec>
• Just finished a plan (writing-plans output) → next session runs /subagent-driven-development @<plan>
• Starting a fresh exploration/discussion → next session runs /brainstorming
• User says "continue in new session", "spin up a fresh claude", or similar handoff phrasing

Don't use when:

• Not running inside tmux ($TMUX is empty) — abort with a clear message
• The current conversation should continue here (mid-debug, mid-review, mid-implementation)

What You Do

1. Decide the initial prompt the new session boots with. In priority order:

   • User gave skill args → use them as the prompt verbatim (normalize any @<file> to an absolute path). This is the override — don't second-guess it.
   • Handoff doc just produced (e.g. via /handoff) → read @<absolute-path> and continue.
   • Spec finished → /writing-plans @<absolute-spec-path>.
   • Plan finished, ready to implement → /subagent-driven-development @<absolute-plan-path>.
   • Fresh exploration / discussion → /brainstorming.
   • Otherwise → any free-text instruction describing the next task.

   The prompt is just a string handed to claude; it need not be a slash command.

2. Absolute paths only. Every @<file> in the prompt must be absolute — the new pane inherits cwd but the prompt is parsed before that matters, and references must survive a different cwd.

3. Verify tmux: check $TMUX is non-empty. If not, tell the user "Not running inside tmux — can't split the pane" and stop.

4. Run the split in a single Bash call. Always target $TMUX_PANE — the pane this session actually runs in — so the split lands here even if the user's focus moved to another pane/window. <prompt> is whatever you picked in step 1:

   tmux split-window -v -t "$TMUX_PANE" -c "$PWD" \
     "claude --dangerously-skip-permissions '<prompt>'"
   

   Flags:

   • -v = top-bottom split (new pane below)
   • -t "$TMUX_PANE" = split THIS pane, not the window's active pane. tmux exports $TMUX_PANE (e.g. %3) into every process in a pane, so it points at the session you're running in regardless of where focus is.
   • -c "$PWD" = new pane starts in this claude session's cwd. The Bash tool runs as a child of the claude process, so $PWD is claude's real working dir. Do not use #{pane_current_path} — that tracks the cwd of the pane's login shell (claude's parent), which drifts from claude's cwd whenever claude works in a different dir than the shell was started in (e.g. a worktree), spawning the new session in the wrong tree.
   • Use the full claude --dangerously-skip-permissions — clawd is a zsh alias and won't expand inside tmux's /bin/sh
   • The prompt is single-quoted. If the prompt itself contains a single quote ('), escape it as '\'' or rephrase — otherwise the shell command breaks. (Free-text prompts with apostrophes are the main risk; slash commands and @-paths are safe.)

5. Tell the user in one sentence what prompt (+ file, if any) you sent.

Examples

After finishing a plan at /path/to/repo/plans/2026-04-19-thing.md:

tmux split-window -v -t "$TMUX_PANE" -c "$PWD" \
  "claude --dangerously-skip-permissions '/subagent-driven-development @/path/to/repo/plans/2026-04-19-thing.md'"

Handing off a handoff doc at /path/to/repo/HANDOFF.md:

tmux split-window -v -t "$TMUX_PANE" -c "$PWD" \
  "claude --dangerously-skip-permissions 'read @/path/to/repo/HANDOFF.md and continue'"

Free-text prompt (user-supplied args):

tmux split-window -v -t "$TMUX_PANE" -c "$PWD" \
  "claude --dangerously-skip-permissions 'implement the rate limiter we discussed, start with the token bucket'"

Starting a fresh exploration:

tmux split-window -v -t "$TMUX_PANE" -c "$PWD" \
  "claude --dangerously-skip-permissions '/brainstorming'"

Then say e.g.: "Spawned new session in bottom pane with /brainstorming."

Common Mistakes

Mistake	Fix
Using clawd in the tmux command	tmux runs commands via /bin/sh, not zsh — aliases don't expand. Use claude --dangerously-skip-permissions.
Omitting -t "$TMUX_PANE"	Split targets the window's active pane — wrong if focus moved. Always anchor to $TMUX_PANE, the pane this session runs in.
Using -c "#{pane_current_path}" for cwd	That's the login shell's cwd, not claude's — spawns in the wrong worktree when they differ. Use -c "$PWD" (claude's real cwd via the Bash tool).
Forgetting -c entirely	New pane starts in $HOME, breaking relative file refs.
Using -h instead of -v	-h is side-by-side; this skill is top-bottom.
Running outside tmux	Always check $TMUX first. Abort with a clear message.
Sending a relative file path	The new session's cwd may differ — always pass absolute paths.
Quoting the prompt with double-quotes	Outer arg uses double-quotes already; use single-quotes around the prompt to avoid escaping hell.
Unescaped apostrophe in a free-text prompt	The prompt is single-quoted — an inner ' ends the quote. Escape as '\'' or rephrase to drop the apostrophe.
Forcing a slash command when the user gave a plain prompt	The prompt is any string. If the user handed you free text or a handoff doc, pass it through — don't wrap it in a superpowers command.