Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs: add cmux workspace integration recipe (#1907)
alvistar404bd563a54e
diff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.mdindex 32b363ced..3d8224248 100644--- a/docs/content/tips-patterns.md+++ b/docs/content/tips-patterns.md@@ -270,6 +270,9 @@ Spawn a worktree with an agent CLI running in the background. Examples below use**Zellij** (new pane in current session):{{ terminal(cmd="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.'") }}+**cmux** (new workspace):+{{ terminal(cmd="cmux new-workspace --command __WT_QUOT__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.'__WT_QUOT__") }}+This lets one agent 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 (and other agent CLIs that load it) to execute this pattern. To enable it, request it explicitly ("spawn a parallel worktree for...") or add to your project instructions (`CLAUDE.md` or `AGENTS.md`):@@ -315,6 +318,36 @@ To create a worktree and immediately attach:<span class="cmd">wt switch --create feature -x 'tmux attach -t {{ branch | sanitize }}'</span>{% end %}+## cmux workspace per worktree++Each worktree gets its own [cmux](https://cmux.com) workspace. Switching worktrees switches workspaces; removing a worktree closes its workspace.++**Prerequisites:** [jq](https://jqlang.org) (`brew install jq`)++```toml+# ~/.config/worktrunk/config.toml+[pre-start]+cmux = "cmux new-workspace --name {{ repo | sanitize }}/{{ branch | sanitize }} --cwd {{ worktree_path }}"++[pre-switch]+cmux = """+WS=$(cmux --json list-workspaces 2>/dev/null \\+ | jq -r --arg t '{{ repo | sanitize }}/{{ branch | sanitize }}' \\+ '.workspaces[] | select(.title == $t) | .ref' | head -1)+[ -n "$WS" ] && cmux select-workspace --workspace "$WS" || true+"""++[pre-remove]+cmux = """+WS=$(cmux --json list-workspaces 2>/dev/null \\+ | jq -r --arg t '{{ repo | sanitize }}/{{ branch | sanitize }}' \\+ '.workspaces[] | select(.title == $t) | .ref' | head -1)+[ -n "$WS" ] && cmux close-workspace --workspace "$WS" || true+"""+```++**Why `pre-*` instead of `post-*`?** cmux restricts socket access to processes spawned inside a cmux terminal. `post-*` hooks run as detached background processes, breaking the process ancestry chain. `pre-*` hooks run in the foreground and inherit the terminal's process lineage.+## Xcode DerivedData cleanupClean up Xcode's DerivedData when removing a worktree. Each DerivedData directory contains an `info.plist` recording its project path — grep for the worktree path to find and remove the matching build cache:diff --git a/skills/worktrunk/reference/tips-patterns.md b/skills/worktrunk/reference/tips-patterns.mdindex e5c846819..5020a86cf 100644--- a/skills/worktrunk/reference/tips-patterns.md+++ b/skills/worktrunk/reference/tips-patterns.md@@ -287,6 +287,12 @@ 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.'```+**cmux** (new workspace):+```bash+cmux new-workspace --command "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 agent 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 (and other agent CLIs that load it) to execute this pattern. To enable it, request it explicitly ("spawn a parallel worktree for...") or add to your project instructions (`CLAUDE.md` or `AGENTS.md`):@@ -332,6 +338,36 @@ To create a worktree and immediately attach:$ wt switch --create feature -x 'tmux attach -t {{ branch | sanitize }}'```+## cmux workspace per worktree++Each worktree gets its own [cmux](https://cmux.com) workspace. Switching worktrees switches workspaces; removing a worktree closes its workspace.++**Prerequisites:** [jq](https://jqlang.org) (`brew install jq`)++```toml+# ~/.config/worktrunk/config.toml+[pre-start]+cmux = "cmux new-workspace --name {{ repo | sanitize }}/{{ branch | sanitize }} --cwd {{ worktree_path }}"++[pre-switch]+cmux = """+WS=$(cmux --json list-workspaces 2>/dev/null \\+ | jq -r --arg t '{{ repo | sanitize }}/{{ branch | sanitize }}' \\+ '.workspaces[] | select(.title == $t) | .ref' | head -1)+[ -n "$WS" ] && cmux select-workspace --workspace "$WS" || true+"""++[pre-remove]+cmux = """+WS=$(cmux --json list-workspaces 2>/dev/null \\+ | jq -r --arg t '{{ repo | sanitize }}/{{ branch | sanitize }}' \\+ '.workspaces[] | select(.title == $t) | .ref' | head -1)+[ -n "$WS" ] && cmux close-workspace --workspace "$WS" || true+"""+```++**Why `pre-*` instead of `post-*`?** cmux restricts socket access to processes spawned inside a cmux terminal. `post-*` hooks run as detached background processes, breaking the process ancestry chain. `pre-*` hooks run in the foreground and inherit the terminal's process lineage.+## Xcode DerivedData cleanupClean up Xcode's DerivedData when removing a worktree. Each DerivedData directory contains an `info.plist` recording its project path — grep for the worktree path to find and remove the matching build cache: