Skip to content

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

docs: add PowerShell diagnostic guidance to skill references (#993)

Maximilian Roos9ed9ed2e96b2
diff --git a/.claude-plugin/skills/worktrunk/reference/shell-integration.md b/.claude-plugin/skills/worktrunk/reference/shell-integration.md
index 6c3dc2526..b2628261b 100644
--- a/.claude-plugin/skills/worktrunk/reference/shell-integration.md
+++ b/.claude-plugin/skills/worktrunk/reference/shell-integration.md
@@ -152,6 +152,23 @@ type wt
# If it shows a path like /usr/local/bin/wt, wrapper isn't loaded
```
+### 1b. Check if wrapper is installed (PowerShell)
+
+```powershell
+# PowerShell: should show Function, not just Application
+Get-Command wt -All
+
+# Expected output when wrapper is loaded:
+# CommandType Name Source
+# ----------- ---- ------
+# Function wt
+# Application wt C:\Users\...\wt.exe
+
+# If only Application appears, wrapper isn't loaded (restart shell)
+# If Function appears but integration is still "not active", check the body:
+(Get-Command wt -CommandType Function).ScriptBlock | Select-String WORKTRUNK
+```
+
### 2. Check shell config file
```bash
diff --git a/.claude-plugin/skills/worktrunk/reference/troubleshooting.md b/.claude-plugin/skills/worktrunk/reference/troubleshooting.md
index a791f26ba..4062dec5c 100644
--- a/.claude-plugin/skills/worktrunk/reference/troubleshooting.md
+++ b/.claude-plugin/skills/worktrunk/reference/troubleshooting.md
@@ -92,6 +92,25 @@ wt config shell install powershell
Both profile files are created when installing from a Windows-native shell. This ensures shell integration works regardless of which PowerShell variant the user opens later. The profile files are small and harmless if unused.
+### Shell integration configured but not active
+
+When `wt config show` shows the profile line is configured but shell integration
+is "not active", ask the user to run these diagnostics in the same PowerShell
+session:
+
+1. `Get-Command git-wt -All` — shows whether the wrapper Function is loaded
+ alongside the Application (exe). If only Application appears, the profile
+ didn't define the function (restart shell, or profile load failed).
+
+2. `(Get-Command git-wt -CommandType Function).ScriptBlock | Select-String
+ WORKTRUNK` — verifies the wrapper function body sets
+ `WORKTRUNK_DIRECTIVE_FILE`. If this doesn't appear, the function is
+ incomplete or corrupted.
+
+3. `Get-Command git-wt -CommandType Application | Select-Object Source` — shows
+ what the wrapper resolves as `$wtBin`. If empty, the wrapper can't find the
+ binary and will fail silently.
+
### Detection logic
Worktrunk detects Windows-native shells (cmd/PowerShell) by checking if the `SHELL` environment variable is **not** set: