feat(switch): add --tmux flag to run worktree creation in tmux #476

lucasoeth · 2026-01-08T20:32:15Z

Summary

Add --tmux flag to wt switch that runs worktree creation in a new tmux window/session
Add --detach flag to run the tmux session in background instead of attaching
All hooks (post-create, post-start, post-switch) run inside tmux
Shell stays open at worktree path after completion

Usage

# Create worktree in new tmux session (attached)
wt switch --create feature --tmux

# Create worktree in detached tmux session (background)
wt switch --create feature --tmux --detach

Behavior

Context	Default (`--tmux`)	With `--detach`
Already in tmux	New window, switches to it	New window, switches to it
Not in tmux	New session, attaches	New session, detached

Test plan

--tmux conflicts with --execute (clap enforced)
--detach requires --tmux (clap enforced)
Help page snapshot updated
Manual testing with tmux

🤖 Generated with Claude Code

Add --tmux flag to `wt switch` that runs the entire worktree creation (including all hooks) in a new tmux window/session instead of the current terminal. Behavior: - If already in tmux: creates new window and switches to it - If not in tmux: creates new session and attaches (default) - With --detach: creates detached session in background The shell stays open at the worktree path after completion, so you can start working immediately. Co-Authored-By: Claude Opus 4.5 <[email protected]>

max-sixty · 2026-01-08T20:51:08Z

I'm open to something like this. Can we discuss the options?

Currently I use zellij, and my workflow is "new-tab", and then wsl expands to wt switch --create --execute=claude, and I add -- 'Please fix foo' to the end.

What's yours? What's the advantage of having "new-tab" be within worktrunk?

Instead of failing or creating duplicates, --tmux now: - Attaches to existing session (when outside tmux) - Switches to existing window (when inside tmux) Co-Authored-By: Claude Opus 4.5 <[email protected]>

Pass --execute and args through to the inner wt command when using --tmux. This enables launching editors/agents in the tmux session: wt switch --create feature --tmux --execute claude -- 'Fix bug' Co-Authored-By: Claude Opus 4.5 <[email protected]>

lucasoeth · 2026-01-08T21:09:12Z

The use case is agent-initiated worktree creation — Claude Code spawning parallel worktrees for handoffs that continue in the background. Your workflow works because you do the "new-tab" step manually, but when Claude wants to spawn a handoff there's no human to press new-tab first. It needs one atomic command that creates a detached session, creates the worktree inside it, runs the handoff, and continues in background.

That said, open to a more general approach. Could do something like --detach-via "zellij run --" where the user provides the wrapper command. That would be multiplexer-agnostic but puts more on the user. The tmux integration is what Claude Code needs today, but happy to generalize if there's a cleaner design.

When a detached tmux session fails quickly (within 2 seconds), capture the output and display it in the original shell. This helps diagnose errors without having to attach to a dead session. Uses tmux's remain-on-exit option to keep the pane around for capture, then cleans up the session after extracting the error output. Co-Authored-By: Claude Opus 4.5 <[email protected]>

Co-Authored-By: Claude Opus 4.5 <[email protected]>

- Replace consecutive str::replace() calls with char-based iteration - Reduce function arguments by introducing TmuxSwitchOptions struct - Apply cargo fmt formatting Co-Authored-By: Claude Opus 4.5 <[email protected]>

tmux.rs uses .output() for quick status checks (session exists, window exists, capture pane) that don't need shell_exec logging. Co-Authored-By: Claude Opus 4.5 <[email protected]>

Update help snapshots and skill reference docs to include the new --tmux and --detach flags on wt switch. Co-Authored-By: Claude Opus 4.5 <[email protected]>

Environment variables from the current shell are now exported in the tmux session, so hooks and commands have access to API keys, custom paths, and other env vars. Excludes internal vars like PWD, TMUX, SHLVL, etc. Co-Authored-By: Claude Opus 4.5 <[email protected]>

Instead of embedding all env exports in the command string (which can exceed shell limits), write them to a temp file and source it. The file is removed after sourcing. Co-Authored-By: Claude Opus 4.5 <[email protected]>

max-sixty · 2026-01-08T23:55:06Z

this is actually a very cool pattern, I haven't tried it much myself, it could be great

though I'm not sure it should be something in Worktrunk... am I right that this could be:

tmux new-session -d -s fix-auth-bug "wt switch --create fix-auth-bug -x claude -- \
  'The login session expires after 5 minutes. Find the session timeout config and extend it to 24 hours.'"

...which is verbose, but tractable

could we start by having it as a Tip / Pattern at first? my preference would be to get more reps from folks running this sort of workflow before adding a feature to Worktrunk, unless it unlocks something significant we can't otherwise do — wdyt?

lucasoeth · 2026-01-09T09:17:24Z

@max-sixty I like your suggestion, what about adding it as a skill that people can install?

max-sixty · 2026-01-09T14:48:40Z

yes great!

@claude can you draft a PR which adds this as a Tip & Pattern, and a section in our existing Claude Code Skill?

claude · 2026-01-09T14:49:26Z

Claude finished @max-sixty's task in 2m 16s —— View job • claude/pr-476-20260109-1449 • Create PR ➔

Task completed

Todo List:

Explore docs structure to find where tips/patterns belong
Explore Claude Code Skill structure
Add tmux pattern to Tips/Patterns documentation
Add tmux pattern to Claude Code Skill
Commit and push changes
Provide PR URL

Summary

I've added the tmux pattern for agent handoffs to the documentation as a Tip & Pattern. The documentation includes:

Pattern: Launch worktree creation in a detached tmux session for parallel agent workflows:

tmux new-session -d -s fix-auth-bug "wt switch --create fix-auth-bug -x claude -- \
  'The login session expires after 5 minutes. Find the session timeout config and extend it to 24 hours.'"

Files updated:

docs/content/tips-patterns.md - Added new "Agent handoffs in tmux" section
docs/content/claude-code.md - Added same section to Claude Code integration page
.claude-plugin/skills/worktrunk/reference/tips-patterns.md - Updated skill reference
.claude-plugin/skills/worktrunk/reference/claude-code.md - Updated skill reference

The pattern includes examples for both tmux and zellij users, and explains that all hooks run inside the multiplexer session, with the shell staying open at the worktree path after completion.

Branch: claude/pr-476-20260109-1449

lucasoeth and others added 2 commits January 8, 2026 21:55

feat(switch): reuse existing tmux session/window when available

eb992a2

Instead of failing or creating duplicates, --tmux now: - Attaches to existing session (when outside tmux) - Switches to existing window (when inside tmux) Co-Authored-By: Claude Opus 4.5 <[email protected]>

lucasoeth and others added 7 commits January 8, 2026 22:19

feat(switch): add -t and -d shorthands for --tmux and --detach

c46eaaf

Co-Authored-By: Claude Opus 4.5 <[email protected]>

fix: address clippy warnings and formatting

6a74870

- Replace consecutive str::replace() calls with char-based iteration - Reduce function arguments by introducing TmuxSwitchOptions struct - Apply cargo fmt formatting Co-Authored-By: Claude Opus 4.5 <[email protected]>

chore: exclude tmux.rs from no-direct-cmd-output hook

c3fdc4e

tmux.rs uses .output() for quick status checks (session exists, window exists, capture pane) that don't need shell_exec logging. Co-Authored-By: Claude Opus 4.5 <[email protected]>

chore: update snapshots for --tmux and --detach flags

eed1a45

Update help snapshots and skill reference docs to include the new --tmux and --detach flags on wt switch. Co-Authored-By: Claude Opus 4.5 <[email protected]>

lucasoeth closed this Jan 9, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(switch): add --tmux flag to run worktree creation in tmux #476

feat(switch): add --tmux flag to run worktree creation in tmux #476

Uh oh!

lucasoeth commented Jan 8, 2026

Uh oh!

max-sixty commented Jan 8, 2026

Uh oh!

lucasoeth commented Jan 8, 2026

Uh oh!

max-sixty commented Jan 8, 2026

Uh oh!

lucasoeth commented Jan 9, 2026

Uh oh!

max-sixty commented Jan 9, 2026

Uh oh!

claude bot commented Jan 9, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

feat(switch): add --tmux flag to run worktree creation in tmux #476

feat(switch): add --tmux flag to run worktree creation in tmux #476

Uh oh!

Conversation

lucasoeth commented Jan 8, 2026

Summary

Usage

Behavior

Test plan

Uh oh!

max-sixty commented Jan 8, 2026

Uh oh!

lucasoeth commented Jan 8, 2026

Uh oh!

max-sixty commented Jan 8, 2026

Uh oh!

lucasoeth commented Jan 9, 2026

Uh oh!

max-sixty commented Jan 9, 2026

Uh oh!

claude bot commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Task completed

Summary

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

claude bot commented Jan 9, 2026 •

edited

Loading