Skip to content

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

feat(plugin): ship the wt-switch-create skill in the Claude Code plugin (#2737)

Maximilian Roos5a07bc09bdc4
diff --git a/.claude-plugin/CLAUDE.md b/.claude-plugin/CLAUDE.md
index 351783758..d0c761d66 100644
--- a/.claude-plugin/CLAUDE.md
+++ b/.claude-plugin/CLAUDE.md
@@ -2,19 +2,21 @@
## Directory Layout
-Skills are at the repo root (`skills/worktrunk/`) — the standard plugin location.
-Hooks remain in `.claude-plugin/hooks/` for now.
+Skills are at the repo root (`skills/`) — the standard plugin location. Hooks
+remain in `.claude-plugin/hooks/` for now.
```
-worktrunk.skills/ ← plugin root
+worktrunk/ ← plugin root (repo root)
├── .claude-plugin/
-│ ├── plugin.json ← manifest
-│ └── hooks/hooks.json ← activity tracking hooks
+│ ├── plugin.json ← manifest (lists every skill dir)
+│ └── hooks/hooks.json ← activity tracking + WorktreeCreate/Remove hooks
└── skills/
- └── worktrunk/ ← main skill + reference docs
+ ├── worktrunk/ ← config/hook guidance skill + reference docs
+ └── wt-switch-create/ ← /wt-switch-create slash command
```
-Paths in `plugin.json` and `marketplace.json` resolve from the plugin root (repo root).
+Paths in `plugin.json` and `marketplace.json` resolve from the plugin root (repo
+root). Each skill directory must be listed in `plugin.json`'s `skills` array.
## Known Limitations
diff --git a/.claude-plugin/README.md b/.claude-plugin/README.md
index 7105d62ab..98937bbeb 100644
--- a/.claude-plugin/README.md
+++ b/.claude-plugin/README.md
@@ -6,6 +6,7 @@ Git worktree management CLI integration with activity tracking.
1. **Configuration skill** — Guides LLM-powered commit message setup, project hooks (pre-start, pre-merge), and worktree path customization
2. **Activity tracking** — Shows which branches have active Claude sessions via indicators in `wt list`
+3. **`/wt-switch-create` command** — Creates a worktrunk worktree and moves the current Claude session into it
## Examples
@@ -22,3 +23,7 @@ The configuration skill guides through configuring an AI tool (Claude Code, Code
**Add pre-start hooks to run npm install automatically**
The skill configures `.config/wt.toml` with project hooks. Pre-start hooks run when creating worktrees, pre-merge hooks validate before merging.
+
+**Start work in a fresh worktree**
+
+`/wt-switch-create fix-auth Investigate the 5-minute session timeout` creates a `fix-auth` worktree in worktrunk's normal sibling layout (`<repo>.fix-auth/`), switches the session into it, and starts the task there. On session exit the worktree is offered for removal — a worktree with uncommitted changes is kept rather than removed.
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 3ebb17394..88b68f0e2 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -6,6 +6,7 @@
},
"hooks": "./.claude-plugin/hooks/hooks.json",
"skills": [
- "./skills/worktrunk"
+ "./skills/worktrunk",
+ "./skills/wt-switch-create"
]
}
diff --git a/docs/content/claude-code.md b/docs/content/claude-code.md
index 0cb150c9d..764502d84 100644
--- a/docs/content/claude-code.md
+++ b/docs/content/claude-code.md
@@ -7,11 +7,12 @@ weight = 23
group = "Reference"
+++
-The worktrunk Claude Code plugin provides three features:
+The worktrunk Claude Code plugin provides four features:
1. **Configuration skill** — Documentation Claude Code can read, so it can help set up LLM commits, hooks, and troubleshoot issues
2. **Worktree isolation** — When Claude Code agents create isolated worktrees, the plugin routes creation and removal through `wt` instead of raw `git`
3. **Activity tracking** — Status markers in `wt list` showing which worktrees have active Claude sessions (🤖 working, 💬 waiting)
+4. **`/wt-switch-create` command** — Creates a worktrunk worktree and moves the current Claude session into it
## Installation
@@ -70,6 +71,12 @@ Set status markers manually for any workflow:
Claude Code agents can run in isolated worktrees (`isolation: "worktree"`). By default, Claude Code creates these with `git worktree add`. The plugin's `WorktreeCreate` and `WorktreeRemove` hooks route this through `wt switch --create` and `wt remove` instead, so worktrees created by agents get worktrunk's naming conventions, hooks, and lifecycle management.
+## `/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.
+
+On session exit the worktree is offered for removal via the `WorktreeRemove` hook; one with uncommitted changes is kept rather than removed.
+
## Statusline
`wt list statusline --format=claude-code` outputs a single-line status for the Claude Code statusline. When the CI status cache is stale, this fetches from the network — typically 1–2 seconds — making it suitable for async statuslines but too slow for synchronous shell prompts. If a faster version would be helpful, please [open an issue](https://github.com/max-sixty/worktrunk/issues).
diff --git a/skills/worktrunk/reference/claude-code.md b/skills/worktrunk/reference/claude-code.md
index 02aefb599..75228e851 100644
--- a/skills/worktrunk/reference/claude-code.md
+++ b/skills/worktrunk/reference/claude-code.md
@@ -1,10 +1,11 @@
# Claude Code Integration
-The worktrunk Claude Code plugin provides three features:
+The worktrunk Claude Code plugin provides four features:
1. **Configuration skill** — Documentation Claude Code can read, so it can help set up LLM commits, hooks, and troubleshoot issues
2. **Worktree isolation** — When Claude Code agents create isolated worktrees, the plugin routes creation and removal through `wt` instead of raw `git`
3. **Activity tracking** — Status markers in `wt list` showing which worktrees have active Claude sessions (🤖 working, 💬 waiting)
+4. **`/wt-switch-create` command** — Creates a worktrunk worktree and moves the current Claude session into it
## Installation
@@ -64,6 +65,12 @@ $ git config worktrunk.state.feature.marker '{"marker":"💬","set_at":0}' # Di
Claude Code agents can run in isolated worktrees (`isolation: "worktree"`). By default, Claude Code creates these with `git worktree add`. The plugin's `WorktreeCreate` and `WorktreeRemove` hooks route this through `wt switch --create` and `wt remove` instead, so worktrees created by agents get worktrunk's naming conventions, hooks, and lifecycle management.
+## `/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.
+
+On session exit the worktree is offered for removal via the `WorktreeRemove` hook; one with uncommitted changes is kept rather than removed.
+
## Statusline
`wt list statusline --format=claude-code` outputs a single-line status for the Claude Code statusline. When the CI status cache is stale, this fetches from the network — typically 1–2 seconds — making it suitable for async statuslines but too slow for synchronous shell prompts. If a faster version would be helpful, please [open an issue](https://github.com/max-sixty/worktrunk/issues).
diff --git a/skills/wt-switch-create/SKILL.md b/skills/wt-switch-create/SKILL.md
new file mode 100644
index 000000000..63c0eaeb5
--- /dev/null
+++ b/skills/wt-switch-create/SKILL.md
@@ -0,0 +1,48 @@
+---
+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...]"
+license: MIT OR Apache-2.0
+compatibility: Requires the worktrunk 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.
+
+## 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.
+
+ - 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
+ `.claude/worktrees/`.
+ - `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.
+ - 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
+ instruction.
+
+## Cleanup
+
+Don't remove the worktree yourself. `ExitWorktree({action: "remove"})` (if the
+user asks to leave) or the session-exit prompt routes through this plugin's
+`WorktreeRemove` hook → `wt remove -D --foreground`. A worktree with uncommitted
+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.