From 98e8b7d3d57e995d8feaa569d2ad47d352e07596 Mon Sep 17 00:00:00 2001 From: Maximilian Roos Date: Fri, 9 Jan 2026 13:27:23 -0800 Subject: [PATCH 1/4] docs: add tmux pattern for agent handoffs Add documentation for spawning worktrees with Claude running in detached tmux sessions, allowing one Claude session to hand off work to another in the background. Added to: - Tips & Patterns (near end, with other advanced patterns) - Claude Code Skill (as "Advanced" section with explicit requirements) The skill guidance requires: explicit user request, running in tmux, and authorization via CLAUDE.md or explicit instruction. Related to #476 Co-Authored-By: Claude --- .claude-plugin/skills/worktrunk/SKILL.md | 21 +++++++++++++++++++ .../worktrunk/reference/tips-patterns.md | 18 ++++++++++++++++ docs/content/tips-patterns.md | 18 ++++++++++++++++ 3 files changed, 57 insertions(+) diff --git a/.claude-plugin/skills/worktrunk/SKILL.md b/.claude-plugin/skills/worktrunk/SKILL.md index 44ad28b77..ba0ea10c0 100644 --- a/.claude-plugin/skills/worktrunk/SKILL.md +++ b/.claude-plugin/skills/worktrunk/SKILL.md @@ -256,3 +256,24 @@ grep -A 20 "## Setup" reference/llm-commits.md grep -A 30 "### post-create" reference/hook.md grep -A 20 "## Warning Messages" reference/shell-integration.md ``` + +## Advanced: Agent Handoffs in tmux + +When the user requests spawning a worktree with Claude in a background session ("spawn a worktree for...", "hand off to another agent"), and they're in tmux, use this pattern: + +```bash +tmux new-session -d -s "wt switch --create -x claude -- ''" +``` + +**Requirements** (all must be true): +- User explicitly requests spawning/handoff +- User is in tmux (check `$TMUX` env var) +- User's CLAUDE.md or explicit instruction authorizes this pattern + +**Do not use this pattern** for normal worktree operations. + +Example: +```bash +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.'" +``` diff --git a/.claude-plugin/skills/worktrunk/reference/tips-patterns.md b/.claude-plugin/skills/worktrunk/reference/tips-patterns.md index ec7a53d3e..d716267b3 100644 --- a/.claude-plugin/skills/worktrunk/reference/tips-patterns.md +++ b/.claude-plugin/skills/worktrunk/reference/tips-patterns.md @@ -192,6 +192,24 @@ wt switch --create feature-part2 --base=@ Creates a worktree that builds on the current branch's changes. +## Agent handoffs in tmux + +Spawn a worktree with Claude running in a detached tmux session: + +```bash +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.'" +``` + +This lets one Claude session hand off work to another that runs in the background. Hooks run inside the tmux session. + +The [worktrunk skill](https://worktrunk.dev/claude-code/) includes guidance for Claude Code to execute this pattern. To enable it, request it explicitly ("spawn a parallel worktree in tmux for...") or add to `CLAUDE.md`: + +```markdown +When I ask you to spawn parallel worktrees, use tmux to create detached sessions +with `wt switch --create -x claude` inside. +``` + ## Bare repository layout An alternative to the default sibling layout (`myproject.feature/`) uses a bare repository with worktrees as subdirectories: diff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.md index 7c3474f51..0d1177dff 100644 --- a/docs/content/tips-patterns.md +++ b/docs/content/tips-patterns.md @@ -204,6 +204,24 @@ wt switch --create feature-part2 --base=@ Creates a worktree that builds on the current branch's changes. +## Agent handoffs in tmux + +Spawn a worktree with Claude running in a detached tmux session: + +```bash +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.'" +``` + +This lets one Claude session hand off work to another that runs in the background. Hooks run inside the tmux session. + +The [worktrunk skill](@/claude-code.md) includes guidance for Claude Code to execute this pattern. To enable it, request it explicitly ("spawn a parallel worktree in tmux for...") or add to `CLAUDE.md`: + +```markdown +When I ask you to spawn parallel worktrees, use tmux to create detached sessions +with `wt switch --create -x claude` inside. +``` + ## Bare repository layout An alternative to the default sibling layout (`myproject.feature/`) uses a bare repository with worktrees as subdirectories: From 2cb4254a504a348b76f37e7bae878630e0afd04c Mon Sep 17 00:00:00 2001 From: Maximilian Roos Date: Fri, 9 Jan 2026 13:57:52 -0800 Subject: [PATCH 2/4] docs: clarify CLAUDE.md example wording Co-Authored-By: Claude --- .claude-plugin/skills/worktrunk/reference/tips-patterns.md | 4 ++-- docs/content/tips-patterns.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.claude-plugin/skills/worktrunk/reference/tips-patterns.md b/.claude-plugin/skills/worktrunk/reference/tips-patterns.md index d716267b3..dfc4df642 100644 --- a/.claude-plugin/skills/worktrunk/reference/tips-patterns.md +++ b/.claude-plugin/skills/worktrunk/reference/tips-patterns.md @@ -206,8 +206,8 @@ This lets one Claude session hand off work to another that runs in the backgroun The [worktrunk skill](https://worktrunk.dev/claude-code/) includes guidance for Claude Code to execute this pattern. To enable it, request it explicitly ("spawn a parallel worktree in tmux for...") or add to `CLAUDE.md`: ```markdown -When I ask you to spawn parallel worktrees, use tmux to create detached sessions -with `wt switch --create -x claude` inside. +When I ask you to spawn parallel worktrees, run `wt switch --create -x claude` +in a detached tmux session. ``` ## Bare repository layout diff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.md index 0d1177dff..8723c97ce 100644 --- a/docs/content/tips-patterns.md +++ b/docs/content/tips-patterns.md @@ -218,8 +218,8 @@ This lets one Claude session hand off work to another that runs in the backgroun The [worktrunk skill](@/claude-code.md) includes guidance for Claude Code to execute this pattern. To enable it, request it explicitly ("spawn a parallel worktree in tmux for...") or add to `CLAUDE.md`: ```markdown -When I ask you to spawn parallel worktrees, use tmux to create detached sessions -with `wt switch --create -x claude` inside. +When I ask you to spawn parallel worktrees, run `wt switch --create -x claude` +in a detached tmux session. ``` ## Bare repository layout From ecbcb2854f02a877ca3fa4b477c8ea02bf9ab011 Mon Sep 17 00:00:00 2001 From: Maximilian Roos Date: Fri, 9 Jan 2026 14:03:58 -0800 Subject: [PATCH 3/4] docs: reference skill instead of partial command Co-Authored-By: Claude --- .claude-plugin/skills/worktrunk/reference/tips-patterns.md | 4 ++-- docs/content/tips-patterns.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.claude-plugin/skills/worktrunk/reference/tips-patterns.md b/.claude-plugin/skills/worktrunk/reference/tips-patterns.md index dfc4df642..2feb942ce 100644 --- a/.claude-plugin/skills/worktrunk/reference/tips-patterns.md +++ b/.claude-plugin/skills/worktrunk/reference/tips-patterns.md @@ -206,8 +206,8 @@ This lets one Claude session hand off work to another that runs in the backgroun The [worktrunk skill](https://worktrunk.dev/claude-code/) includes guidance for Claude Code to execute this pattern. To enable it, request it explicitly ("spawn a parallel worktree in tmux for...") or add to `CLAUDE.md`: ```markdown -When I ask you to spawn parallel worktrees, run `wt switch --create -x claude` -in a detached tmux session. +When I ask you to spawn parallel worktrees, use the tmux handoff pattern +from the worktrunk skill. ``` ## Bare repository layout diff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.md index 8723c97ce..59d8dd835 100644 --- a/docs/content/tips-patterns.md +++ b/docs/content/tips-patterns.md @@ -218,8 +218,8 @@ This lets one Claude session hand off work to another that runs in the backgroun The [worktrunk skill](@/claude-code.md) includes guidance for Claude Code to execute this pattern. To enable it, request it explicitly ("spawn a parallel worktree in tmux for...") or add to `CLAUDE.md`: ```markdown -When I ask you to spawn parallel worktrees, run `wt switch --create -x claude` -in a detached tmux session. +When I ask you to spawn parallel worktrees, use the tmux handoff pattern +from the worktrunk skill. ``` ## Bare repository layout From e0918971cae6bc45e139755332bad72104fc4e33 Mon Sep 17 00:00:00 2001 From: Maximilian Roos Date: Sat, 10 Jan 2026 11:57:37 -0800 Subject: [PATCH 4/4] docs: add Zellij equivalent for agent handoffs Add `zellij run` as an alternative to tmux for spawning worktrees with Claude in the background. Rename section from "Agent handoffs in tmux" to "Agent handoffs" to be multiplexer-agnostic. The skill guidance now checks both $TMUX and $ZELLIJ env vars. Co-Authored-By: Claude --- .claude-plugin/skills/worktrunk/SKILL.md | 20 +++++++++++++++---- .../worktrunk/reference/tips-patterns.md | 17 +++++++++++----- docs/content/tips-patterns.md | 17 +++++++++++----- 3 files changed, 40 insertions(+), 14 deletions(-) diff --git a/.claude-plugin/skills/worktrunk/SKILL.md b/.claude-plugin/skills/worktrunk/SKILL.md index ba0ea10c0..2ebf428b9 100644 --- a/.claude-plugin/skills/worktrunk/SKILL.md +++ b/.claude-plugin/skills/worktrunk/SKILL.md @@ -257,23 +257,35 @@ grep -A 30 "### post-create" reference/hook.md grep -A 20 "## Warning Messages" reference/shell-integration.md ``` -## Advanced: Agent Handoffs in tmux +## Advanced: Agent Handoffs -When the user requests spawning a worktree with Claude in a background session ("spawn a worktree for...", "hand off to another agent"), and they're in tmux, use this pattern: +When the user requests spawning a worktree with Claude in a background session ("spawn a worktree for...", "hand off to another agent"), use the appropriate pattern for their terminal multiplexer: +**tmux** (check `$TMUX` env var): ```bash tmux new-session -d -s "wt switch --create -x claude -- ''" ``` +**Zellij** (check `$ZELLIJ` env var): +```bash +zellij run -- wt switch --create -x claude -- '' +``` + **Requirements** (all must be true): - User explicitly requests spawning/handoff -- User is in tmux (check `$TMUX` env var) +- User is in a supported multiplexer (tmux or Zellij) - User's CLAUDE.md or explicit instruction authorizes this pattern **Do not use this pattern** for normal worktree operations. -Example: +Example (tmux): ```bash 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.'" ``` + +Example (Zellij): +```bash +zellij run -- 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.' +``` diff --git a/.claude-plugin/skills/worktrunk/reference/tips-patterns.md b/.claude-plugin/skills/worktrunk/reference/tips-patterns.md index 2feb942ce..bd8cb6c86 100644 --- a/.claude-plugin/skills/worktrunk/reference/tips-patterns.md +++ b/.claude-plugin/skills/worktrunk/reference/tips-patterns.md @@ -192,21 +192,28 @@ wt switch --create feature-part2 --base=@ Creates a worktree that builds on the current branch's changes. -## Agent handoffs in tmux +## Agent handoffs -Spawn a worktree with Claude running in a detached tmux session: +Spawn a worktree with Claude running in the background: +**tmux** (new detached session): ```bash 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.'" ``` -This lets one Claude session hand off work to another that runs in the background. Hooks run inside the tmux session. +**Zellij** (new pane in current session): +```bash +zellij run -- 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.' +``` + +This lets one Claude session hand off work to another that runs in the background. Hooks run inside the multiplexer session/pane. -The [worktrunk skill](https://worktrunk.dev/claude-code/) includes guidance for Claude Code to execute this pattern. To enable it, request it explicitly ("spawn a parallel worktree in tmux for...") or add to `CLAUDE.md`: +The [worktrunk skill](https://worktrunk.dev/claude-code/) includes guidance for Claude Code to execute this pattern. To enable it, request it explicitly ("spawn a parallel worktree for...") or add to `CLAUDE.md`: ```markdown -When I ask you to spawn parallel worktrees, use the tmux handoff pattern +When I ask you to spawn parallel worktrees, use the agent handoff pattern from the worktrunk skill. ``` diff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.md index 59d8dd835..fc01b601e 100644 --- a/docs/content/tips-patterns.md +++ b/docs/content/tips-patterns.md @@ -204,21 +204,28 @@ wt switch --create feature-part2 --base=@ Creates a worktree that builds on the current branch's changes. -## Agent handoffs in tmux +## Agent handoffs -Spawn a worktree with Claude running in a detached tmux session: +Spawn a worktree with Claude running in the background: +**tmux** (new detached session): ```bash 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.'" ``` -This lets one Claude session hand off work to another that runs in the background. Hooks run inside the tmux session. +**Zellij** (new pane in current session): +```bash +zellij run -- 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.' +``` + +This lets one Claude session hand off work to another that runs in the background. Hooks run inside the multiplexer session/pane. -The [worktrunk skill](@/claude-code.md) includes guidance for Claude Code to execute this pattern. To enable it, request it explicitly ("spawn a parallel worktree in tmux for...") or add to `CLAUDE.md`: +The [worktrunk skill](@/claude-code.md) includes guidance for Claude Code to execute this pattern. To enable it, request it explicitly ("spawn a parallel worktree for...") or add to `CLAUDE.md`: ```markdown -When I ask you to spawn parallel worktrees, use the tmux handoff pattern +When I ask you to spawn parallel worktrees, use the agent handoff pattern from the worktrunk skill. ```