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.mdindex 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 Limitationsdiff --git a/.claude-plugin/README.md b/.claude-plugin/README.mdindex 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 customization2. **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.jsonindex 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.mdindex 0cb150c9d..764502d84 100644--- a/docs/content/claude-code.md+++ b/docs/content/claude-code.md@@ -7,11 +7,12 @@ weight = 23group = "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 issues2. **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.mdindex 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 issues2. **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}' # DiClaude 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.mdnew file mode 100644index 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.