Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

docs: add tmux pattern for agent handoffs (#501)

Maximilian Roos7503df1bebf2
diff --git a/.claude-plugin/skills/worktrunk/SKILL.md b/.claude-plugin/skills/worktrunk/SKILL.md
index 44ad28b77..2ebf428b9 100644
--- a/.claude-plugin/skills/worktrunk/SKILL.md
+++ b/.claude-plugin/skills/worktrunk/SKILL.md
@@ -256,3 +256,36 @@ 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
+
+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 <branch-name> "wt switch --create <branch-name> -x claude -- '<task description>'"
+```
+
+**Zellij** (check `$ZELLIJ` env var):
+```bash
+zellij run -- wt switch --create <branch-name> -x claude -- '<task description>'
+```
+
+**Requirements** (all must be true):
+- User explicitly requests spawning/handoff
+- 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 (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 2677fdde5..a0f2c9783 100644
--- a/.claude-plugin/skills/worktrunk/reference/tips-patterns.md
+++ b/.claude-plugin/skills/worktrunk/reference/tips-patterns.md
@@ -194,6 +194,31 @@ wt switch --create feature-part2 --base=@
Creates a worktree that builds on the current branch's changes.
+## Agent handoffs
+
+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.'"
+```
+
+**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 for...") or add to `CLAUDE.md`:
+
+```markdown
+When I ask you to spawn parallel worktrees, use the agent handoff pattern
+from the worktrunk skill.
+```
+
## 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 941912134..33eb5c6cf 100644
--- a/docs/content/tips-patterns.md
+++ b/docs/content/tips-patterns.md
@@ -206,6 +206,31 @@ wt switch --create feature-part2 --base=@
Creates a worktree that builds on the current branch's changes.
+## Agent handoffs
+
+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.'"
+```
+
+**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 for...") or add to `CLAUDE.md`:
+
+```markdown
+When I ask you to spawn parallel worktrees, use the agent handoff pattern
+from the worktrunk skill.
+```
+
## Bare repository layout
An alternative to the default sibling layout (`myproject.feature/`) uses a bare repository with worktrees as subdirectories: