Skip to content

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

docs: add tmux session per worktree pattern (#667)

Maximilian Roos2bb6393f9397
diff --git a/.claude-plugin/skills/worktrunk/reference/tips-patterns.md b/.claude-plugin/skills/worktrunk/reference/tips-patterns.md
index 0b04d2a3c..4ddf544c5 100644
--- a/.claude-plugin/skills/worktrunk/reference/tips-patterns.md
+++ b/.claude-plugin/skills/worktrunk/reference/tips-patterns.md
@@ -210,6 +210,44 @@ When I ask you to spawn parallel worktrees, use the agent handoff pattern
from the worktrunk skill.
```
+## Tmux session per worktree
+
+Each worktree gets its own tmux session with a multi-pane layout. Sessions are named after the branch for easy identification.
+
+```toml
+# .config/wt.toml
+[post-create]
+tmux = """
+S="{{ branch | sanitize }}"
+W="{{ worktree_path }}"
+tmux new-session -d -s "$S" -c "$W" -n dev
+
+# Create 4-pane layout: shell | backend / claude | frontend
+tmux split-window -h -t "$S:dev" -c "$W"
+tmux split-window -v -t "$S:dev.0" -c "$W"
+tmux split-window -v -t "$S:dev.2" -c "$W"
+
+# Start services in each pane
+tmux send-keys -t "$S:dev.1" 'npm run backend' Enter
+tmux send-keys -t "$S:dev.2" 'claude' Enter
+tmux send-keys -t "$S:dev.3" 'npm run frontend' Enter
+
+tmux select-pane -t "$S:dev.0"
+echo "✓ Session '$S' — attach with: tmux attach -t $S"
+"""
+
+[pre-remove]
+tmux = "tmux kill-session -t '{{ branch | sanitize }}' 2>/dev/null || true"
+```
+
+`pre-remove` stops all services when the worktree is removed.
+
+To create a worktree and immediately attach:
+
+```bash
+wt switch --create feature -x 'tmux attach -t {{ branch | sanitize }}'
+```
+
## 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 3970ccc41..fba3f89d9 100644
--- a/docs/content/tips-patterns.md
+++ b/docs/content/tips-patterns.md
@@ -222,6 +222,44 @@ When I ask you to spawn parallel worktrees, use the agent handoff pattern
from the worktrunk skill.
```
+## Tmux session per worktree
+
+Each worktree gets its own tmux session with a multi-pane layout. Sessions are named after the branch for easy identification.
+
+```toml
+# .config/wt.toml
+[post-create]
+tmux = """
+S="{{ branch | sanitize }}"
+W="{{ worktree_path }}"
+tmux new-session -d -s "$S" -c "$W" -n dev
+
+# Create 4-pane layout: shell | backend / claude | frontend
+tmux split-window -h -t "$S:dev" -c "$W"
+tmux split-window -v -t "$S:dev.0" -c "$W"
+tmux split-window -v -t "$S:dev.2" -c "$W"
+
+# Start services in each pane
+tmux send-keys -t "$S:dev.1" 'npm run backend' Enter
+tmux send-keys -t "$S:dev.2" 'claude' Enter
+tmux send-keys -t "$S:dev.3" 'npm run frontend' Enter
+
+tmux select-pane -t "$S:dev.0"
+echo "✓ Session '$S' — attach with: tmux attach -t $S"
+"""
+
+[pre-remove]
+tmux = "tmux kill-session -t '{{ branch | sanitize }}' 2>/dev/null || true"
+```
+
+`pre-remove` stops all services when the worktree is removed.
+
+To create a worktree and immediately attach:
+
+```bash
+wt switch --create feature -x 'tmux attach -t {{ branch | sanitize }}'
+```
+
## Bare repository layout
An alternative to the default sibling layout (`myproject.feature/`) uses a bare repository with worktrees as subdirectories: