Skip to content

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

feat(plugin): /wt-switch-create — optional repo arg and `--` task delimiter (#2751)

Maximilian Roos52555982a88d
diff --git a/docs/content/claude-code.md b/docs/content/claude-code.md
index 764502d84..033663ca2 100644
--- a/docs/content/claude-code.md
+++ b/docs/content/claude-code.md
@@ -73,7 +73,7 @@ Claude Code agents can run in isolated worktrees (`isolation: "worktree"`). By d
## `/wt-switch-create` command
-`/wt-switch-create <branch> [task...]` starts work in a fresh worktree without leaving the session. It creates (or re-enters) the named worktrunk worktree — sibling layout `<repo>.<branch>/`, not `.claude/worktrees/` — switches the session's working directory into it, then runs the rest of the arguments as the task there. The command rides the same `WorktreeCreate` hook as agent isolation, so the worktree gets worktrunk's naming, hooks, and lifecycle.
+`/wt-switch-create <branch> [<repo>] [-- <task>]` starts work in a fresh worktree without leaving the session. It creates (or re-enters) the named worktrunk worktree — sibling layout `<repo>.<branch>/`, not `.claude/worktrees/` — switches the session's working directory into it, then runs the task there. An optional second token names a different repository to create the worktree in; the task is whatever follows `--` (or, with no `--`, whatever follows the branch). The command rides the same `WorktreeCreate` hook as agent isolation, so the worktree gets worktrunk's naming, hooks, and lifecycle.
On session exit the worktree is offered for removal via the `WorktreeRemove` hook; one with uncommitted changes is kept rather than removed.
diff --git a/skills/worktrunk/reference/claude-code.md b/skills/worktrunk/reference/claude-code.md
index 75228e851..a38d5a590 100644
--- a/skills/worktrunk/reference/claude-code.md
+++ b/skills/worktrunk/reference/claude-code.md
@@ -67,7 +67,7 @@ Claude Code agents can run in isolated worktrees (`isolation: "worktree"`). By d
## `/wt-switch-create` command
-`/wt-switch-create <branch> [task...]` starts work in a fresh worktree without leaving the session. It creates (or re-enters) the named worktrunk worktree — sibling layout `<repo>.<branch>/`, not `.claude/worktrees/` — switches the session's working directory into it, then runs the rest of the arguments as the task there. The command rides the same `WorktreeCreate` hook as agent isolation, so the worktree gets worktrunk's naming, hooks, and lifecycle.
+`/wt-switch-create <branch> [<repo>] [-- <task>]` starts work in a fresh worktree without leaving the session. It creates (or re-enters) the named worktrunk worktree — sibling layout `<repo>.<branch>/`, not `.claude/worktrees/` — switches the session's working directory into it, then runs the task there. An optional second token names a different repository to create the worktree in; the task is whatever follows `--` (or, with no `--`, whatever follows the branch). The command rides the same `WorktreeCreate` hook as agent isolation, so the worktree gets worktrunk's naming, hooks, and lifecycle.
On session exit the worktree is offered for removal via the `WorktreeRemove` hook; one with uncommitted changes is kept rather than removed.
diff --git a/skills/wt-switch-create/SKILL.md b/skills/wt-switch-create/SKILL.md
index b3d3aacb5..16f498f3f 100644
--- a/skills/wt-switch-create/SKILL.md
+++ b/skills/wt-switch-create/SKILL.md
@@ -1,21 +1,40 @@
---
name: wt-switch-create
-description: Create a new worktrunk worktree and switch this session's working directory into it. Use when launching a session that should work in its own worktree (e.g. `/wt-switch-create my-branch <task>`), or mid-session to move work into a fresh branch.
-argument-hint: "<branch-name> [task...]"
+description: Create a new worktrunk worktree (optionally in another repo) and switch this session's working directory into it. Use when launching a session that should work in its own worktree (e.g. `/wt-switch-create my-branch -- <task>`, or `/wt-switch-create my-branch ~/workspace/other-repo -- <task>`), or mid-session to move work into a fresh branch.
+argument-hint: "<branch-name> [<repo>] [-- task...]"
license: MIT OR Apache-2.0
compatibility: Requires the `wt` CLI (https://worktrunk.dev) and this plugin's WorktreeCreate hook
---
-Arguments: `$ARGUMENTS`. The **first whitespace-delimited token** is the branch
-name for the new worktree; everything after it (if any) is the task to perform
-once inside the worktree.
+Arguments: `$ARGUMENTS`. Grammar: `<branch> [<repo>] [-- <task>]`.
+
+- **branch** — required first token; the branch name for the new worktree.
+- **repo** — optional path; create the worktree in this repo instead of the
+ session's current one.
+- **task** — optional; what to do inside the new worktree. No task means enter
+ the worktree and wait.
+
+Without a `--`: a path-shaped second token (absolute, `~`-relative, `./`- or
+`../`-relative, or an existing directory) is the repo, and the task starts
+after it. Otherwise the task starts at the second token.
+
+```
+/wt-switch-create my-feature -- fix the parser bug
+/wt-switch-create my-feature ~/workspace/other-repo -- fix the parser bug
+/wt-switch-create my-feature
+```
## What to do
-1. **First action — before reading any files or running any commands** — call
- `EnterWorktree({name: "<branch-name>"})` with the first token of the
- arguments as the name. This re-roots the session into the new worktree.
+1. **First action — before reading any files or running any commands:**
+ - If a repo was given, `cd` into it first with a `Bash` call (the working
+ directory persists for the rest of the session). `EnterWorktree` has no
+ repo parameter — it creates the worktree wherever the session is rooted.
+ - Then call `EnterWorktree({name: "<branch-name>"})`. This re-roots the
+ session into the new worktree. If a repo was given, confirm the new
+ worktree landed under it; if not, the `cd` didn't take — report it and
+ stop.
- It works because this plugin maps `WorktreeCreate` →
`wt switch --create <name> --no-cd --format=json`, so the new worktree
lands in worktrunk's normal sibling layout (`<repo>.<branch>/`), not under
@@ -23,16 +42,16 @@ once inside the worktree.
- `wt switch --create` is idempotent: if the branch already exists, this
just re-enters its worktree.
- If you are *already* inside an `EnterWorktree`-created worktree (e.g. the
- background harness already isolated this session), **skip this step** —
- `EnterWorktree` refuses to nest. Note that you're reusing the existing
- worktree and continue.
+ background harness isolated this session), **skip `EnterWorktree`** — it
+ refuses to nest. Reuse the existing worktree and continue. But if a repo
+ was given and that worktree belongs to a different repo, you can't honor
+ it — say so and stop rather than running the task in the wrong repo.
- If `EnterWorktree` fails (not a git repo, invalid branch name, etc.),
report the error and stop — do not fall back to working in the original
directory, since that defeats the purpose.
-2. After the cwd switch succeeds, proceed with the task portion of the
- arguments (the text after the branch name) in the new worktree. If there was
- no task text, just confirm the worktree is ready and wait for the next
+2. After the cwd switch succeeds, do the task in the new worktree. If there was
+ no task text, confirm the worktree is ready and wait for the next
instruction.
## Cleanup
@@ -44,5 +63,6 @@ changes won't be auto-removed without confirmation — that's intended.
## Scope
-This command authorizes creating/entering ONE worktree and doing the requested
-task. Commits, pushes, and merges still each require explicit user permission.
+This command authorizes creating/entering ONE worktree — in the named repo, if
+one was given — and doing the requested task. Commits, pushes, and merges still
+each require explicit user permission.