tmux-worktree-session

name	tmux-worktree-session
description	Use when creating or switching to a git worktree inside tmux while keeping session continuity. Supports codex and claude by auto-detecting the current session and launching resume, fork, or new sessions in a split pane.

Tmux Worktree Session

Use this skill when the user wants to:

• create a worktree from an active session without losing context
• split tmux and continue in the new worktree
• resume or fork Codex or Claude session state in the new pane

Command

Use global command wts from any git repo.

wts <name> [options]

Defaults

• worktree path: sibling directory ../<repo>.worktrees/<name-with-slashes-replaced>
• split orientation: horizontal
• mode: resume
• agent: auto (detects codex or claude from env/pane process)

Common Flows

1. Resume current session in a new worktree pane:

wts feature/my-task

2. Fork instead of resume:

wts feature/my-task --mode fork

3. Start a fresh session:

wts feature/my-task --mode new

4. Preview without changes:

wts feature/my-task --dry-run

Key Options

• --agent auto|codex|claude
• --mode resume|fork|new
• --orientation h|v
• --branch <branch-name>
• --base <base-branch>
• --copy-env (copy .env* from main repo to new worktree)
• --no-create (error if worktree does not exist)
• --no-select (leave cursor in original pane)

Safety Notes

• Run inside tmux only.
• Keep sibling worktrees to avoid nested instruction-file recursion issues.
• Avoid driving the exact same resumed session in two panes at once.