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.mdindex 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.mdgrep -A 30 "### post-create" reference/hook.mdgrep -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.mdindex 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 layoutAn 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.mdindex 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 layoutAn alternative to the default sibling layout (`myproject.feature/`) uses a bare repository with worktrees as subdirectories: