
worktree-tools
Open the current git worktree in a target environment: a cmux split pane, a new cmux workspace, or VS Code
Install
/plugin install worktree-tools@powdream-pluginsRun it inside Claude Code after adding the marketplace with /plugin marketplace add powdream/claude-plugins.
Contents
Discovered from sourceSkills 3
worktree-cmux-split
Open the in-progress git worktree as a split pane inside the current cmux workspace (next to the pane Claude Code is running in).
Resolve the worktree path
In priority order:
- Explicit argument — a path, or a branch name (resolve via
git worktree list --porcelain). - The task-specific worktree you've been editing this session.
- If there is no task-specific worktree, open the primary worktree (main checkout) of the project the current task targets — the first entry of
git -C <project> worktree list.
Do NOT fall back to git -C "$PWD" rev-parse --show-toplevel: $PWD may be an unrelated repo. Resolve the target from git worktree list instead — the primary worktree is the project root (main checkout), and task-specific worktrees are the linked worktrees it lists.
Capture the target pane FIRST (before any prompt)
The target is the pane the user is looking at when they invoke. Capture it as the very first action — before asking the direction — so the answer prompt can't shift focus away from it:
CMUX=/Applications/cmux.app/Contents/Resources/bin/cmux
read -r FWIN FW FS < <("$CMUX" identify | python3 -c 'import json,sys;d=json.load(sys.stdin)["focused"];print(d["window_ref"],d["workspace_ref"],d["surface_ref"])')
echo "target: window=$FWIN workspace=$FW surface=$FS ($("$CMUX" tree | grep "$FS " | grep -oE '\"[^\"]+\"' | head -1))"
Capture the window ref too ($FWIN): every later cmux call must carry full --window/--workspace context (see "Open the split").
Use identify.focused (real-time focus = what the user is looking at). Do NOT use $CMUX_SURFACE_ID / $CMUX_WORKSPACE_ID / identify.caller: under Remote Control + multiple sessions the Bash env can point to a different session's pane — that mis-targeting is what previously sent a cd into another running agent. Capturing FW/FS up front pins the target, so later focus drift (e.g. while the user answers the direction prompt) doesn't matter.
Echo the captured workspace/surface (with its title) so the user can sanity-check the target.
Ask the split direction (required)
Use AskUserQuestion with these two options (concrete results, so 가로/세로 wording is never ambiguous):
- 좌우 나란히 (오른쪽에 새 pane) → cmux direction
right - 위아래 (아래에 새 pane) → cmux direction
down
Open the split
new-split has no --cwd, so split the captured focused pane ($FW/$FS from above), then cd the new pane into the worktree. Every call carries full --window/--workspace context:
ref=$("$CMUX" new-split <right|down> --window "$FWIN" --workspace "$FW" --surface "$FS" --focus true | grep -oE 'surface:[0-9]+' | tail -1)
if [ -n "$ref" ]; then
"$CMUX" send --window "$FWIN" --workspace "$FW" --surface "$ref" "cd '<worktree-path>' && clear\n" # \n = Enter; goes to the NEW blank split
else
echo "ABORT: new-split returned no surface ref — not sending cd."
fi
Full context is required, not optional: the Bash caller env ($CMUX_*) belongs to a different, stale session, so cmux send/read-screen with a bare --surface short ref — or even a UUID — resolves in the wrong scope and fails with invalid_params: Surface is not a terminal. Always pass --window "$FWIN" --workspace "$FW" alongside --surface.
Never fall back to cmux send without the captured target (or to $CMUX_SURFACE_ID): if the split failed, that would inject the cd into the focused pane, which may be a running agent. The cd only ever goes to the freshly created split; abort if no new ref.
Echo the targeted workspace/surface, the new surface ref, the worktree path, and the direction. If the worktree path doesn't exist, stop and say so.
Related
- worktree-cmux-workspace — same worktree, but as its own new workspace.
worktree-cmux-workspace
Open the in-progress git worktree as its own new cmux workspace (a fresh terminal whose cwd is the worktree).
Resolve the worktree path
In priority order:
- Explicit argument — a path, or a branch name (resolve via
git worktree list --porcelain). - The task-specific worktree you've been editing this session.
- If there is no task-specific worktree, open the primary worktree (main checkout) of the project the current task targets — the first entry of
git -C <project> worktree list.
Do NOT fall back to git -C "$PWD" rev-parse --show-toplevel: $PWD may be an unrelated repo. Resolve the target from git worktree list instead — the primary worktree is the project root (main checkout), and task-specific worktrees are the linked worktrees it lists.
Open
Use the named form so the workspace gets a meaningful title. (The bare cmux "<path>" form sets the cwd correctly too, but names the workspace generically like "Terminal 7", which clashes with the user's named workspaces.)
CMUX=/Applications/cmux.app/Contents/Resources/bin/cmux
"$CMUX" new-workspace --cwd "<worktree-path>" --name "<name>" --focus true
<name>: the branch for a task-specific worktree (e.g.feature/my-task), or the project dir basename for the primary worktree.cmuxbinary:/Applications/cmux.app/Contents/Resources/bin/cmux(absolute path if not on PATH). It launches the cmux app if it isn't running, and creates the workspace in the caller's window.--cwdsets the shell cwd to the worktree directly (verified:pwdlands in the worktree), so no follow-upcdis needed. Unlikesend,new-workspacedoes not need explicit--window/--surfacecontext — the caller's window ref is correct even though its surface/workspace env is a stale other session.
Echo the resolved path and the workspace name. If the path doesn't exist, say so rather than opening the wrong directory.
Related
- worktree-cmux-split — same worktree, but as a split pane in the current workspace.
worktree-vscode
Open the in-progress git worktree as a folder in VS Code.
Resolve the worktree path
In priority order:
- Explicit argument — a path, or a branch name (resolve via
git worktree list --porcelain). - The task-specific worktree you've been editing this session.
- If there is no task-specific worktree, open the primary worktree (main checkout) of the project the current task targets — the first entry of
git -C <project> worktree list.
Do NOT fall back to git -C "$PWD" rev-parse --show-toplevel: $PWD may be an unrelated repo. Resolve the target from git worktree list instead — the primary worktree is the project root (main checkout), and task-specific worktrees are the linked worktrees it lists.
Open
code "<worktree-path>"
Echo the resolved path. If the path doesn't exist or isn't a git worktree, say so instead of guessing.
Sponsors
Details
- Marketplace
- powdream/claude-plugins
- Source
- plugins/worktree-tools
- Category
- Community