Skip to content

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

Update worktrunk skill to v0.9.3 (#427)

Maximilian Roos5a13a76833ce
diff --git a/.claude-plugin/skills/worktrunk/SKILL.md b/.claude-plugin/skills/worktrunk/SKILL.md
index f0633c15c..0bb72cc92 100644
--- a/.claude-plugin/skills/worktrunk/SKILL.md
+++ b/.claude-plugin/skills/worktrunk/SKILL.md
@@ -3,7 +3,7 @@ name: worktrunk
description: Guidance for Worktrunk, a CLI tool for managing git worktrees. Covers configuration (user config at ~/.config/worktrunk/config.toml and project hooks at .config/wt.toml), usage, and troubleshooting. Use for "setting up LLM", "configuring hooks", "automating tasks", or general worktrunk questions.
---
-<!-- worktrunk-skill-version: 0.6.1 -->
+<!-- worktrunk-skill-version: 0.9.3 -->
# Worktrunk
@@ -12,12 +12,12 @@ Help users work with Worktrunk, a CLI tool for managing git worktrees.
## Available Documentation
- **SKILL.md**: Configuration workflows and common patterns
-- **reference/README.md**: Features, installation, examples, FAQ
-- **reference/*.md**: Detailed configuration and hook specifications
+- **reference/user-config.md**: User config (LLM, worktree paths, command defaults)
+- **reference/project-config.md**: Project config (lifecycle hooks)
+- **reference/hook-types-reference.md**: Detailed hook behavior and timing
+- **reference/shell-integration.md**: Shell integration debugging
-For general usage, consult reference/README.md. For configuration, follow the workflows below.
-
-**For command-specific options**: Run `wt <command> --help` for detailed flags and usage. This skill provides conceptual guidance; the CLI provides authoritative reference.
+For command-specific options, run `wt <command> --help`. For configuration, follow the workflows below.
## Two Types of Configuration
@@ -86,7 +86,7 @@ Most common request. Follow this sequence:
Ask: "Should I add this to your config?"
5. **After approval, apply**
- - Check if config exists: `wt config list`
+ - Check if config exists: `wt config show`
- If not, guide through `wt config create`
- Read, modify, write preserving structure
@@ -185,7 +185,7 @@ Common request for workflow automation. Follow discovery process:
```bash
# View all configuration
-wt config list
+wt config show
# Create initial user config
wt config create
@@ -196,13 +196,11 @@ wt config --help
## Loading Additional Documentation
-Load **reference/README.md** for general features, installation, commands, and examples.
-
Load **reference files** for detailed configuration, hook specifications, and troubleshooting.
Find specific sections with grep:
```bash
-grep -A 20 "## Installation" reference/README.md
grep -A 20 "## LLM Setup" reference/user-config.md
grep -A 30 "### post-create" reference/project-config.md
+grep -A 20 "## Warning Messages" reference/shell-integration.md
```
diff --git a/.claude-plugin/skills/worktrunk/reference/project-config.md b/.claude-plugin/skills/worktrunk/reference/project-config.md
index 1bc2e9c36..537368317 100644
--- a/.claude-plugin/skills/worktrunk/reference/project-config.md
+++ b/.claude-plugin/skills/worktrunk/reference/project-config.md
@@ -499,7 +499,7 @@ post-start = "npm run build" # Slow, background
## Key Commands
```bash
-wt config list # View project config
+wt config show # View project config
cat .config/wt.toml # Read config directly
wt switch --create test-hooks # Test hooks work
```
diff --git a/.claude-plugin/skills/worktrunk/reference/shell-integration.md b/.claude-plugin/skills/worktrunk/reference/shell-integration.md
new file mode 100644
index 000000000..a4323aed0
--- /dev/null
+++ b/.claude-plugin/skills/worktrunk/reference/shell-integration.md
@@ -0,0 +1,204 @@
+# Shell Integration Reference
+
+How Worktrunk's shell integration works and how to debug issues.
+
+## Why Shell Integration Exists
+
+Subprocesses cannot change the parent shell's current directory. When you run
+`wt switch feature`, the `wt` binary runs as a child process and cannot `cd`
+your terminal.
+
+Worktrunk solves this with **directive file passing**:
+
+1. Shell wrapper creates a temp file via `mktemp`
+2. Shell sets `WORKTRUNK_DIRECTIVE_FILE` env var to the temp file path
+3. `wt` binary writes shell commands (like `cd '/path'`) to that file
+4. Shell sources the file after `wt` exits, executing the commands
+5. Shell removes the temp file
+
+This allows `wt switch` to change your terminal's directory.
+
+## Installation
+
+```bash
+# Auto-install for all shells (bash, zsh, fish, PowerShell)
+wt config shell install
+
+# Or manual installation - add to your shell config:
+# bash (~/.bashrc):
+eval "$(wt config shell init bash)"
+
+# zsh (~/.zshrc):
+eval "$(wt config shell init zsh)"
+
+# fish (~/.config/fish/config.fish):
+wt config shell init fish | source
+
+# PowerShell ($PROFILE):
+Invoke-Expression (& wt config shell init powershell | Out-String)
+```
+
+## Checking Status
+
+```bash
+# Show shell integration status
+wt config show
+```
+
+The RUNTIME section shows whether shell integration is active for the current
+session.
+
+## Warning Messages
+
+When shell integration isn't working, `wt switch` shows warnings explaining why.
+
+### "shell integration not installed"
+
+**Meaning**: The shell config file doesn't have the `eval "$(wt config shell init ...)"` line.
+
+**Fix**: Run `wt config shell install` or add the line manually.
+
+### "shell requires restart"
+
+**Meaning**: Shell integration is configured, but the current shell session was
+started before installation. The shell function isn't loaded yet.
+
+**Fix**: Start a new terminal or run `source ~/.bashrc` (or equivalent).
+
+### "ran ./path/to/wt; shell integration wraps wt"
+
+**Meaning**: You invoked the binary with an explicit path (like `./target/debug/wt`
+or `/usr/local/bin/wt`) instead of just `wt`. The shell wrapper only intercepts
+the bare command `wt`.
+
+**Fix**: Use `wt` without a path. For testing dev builds, set `WORKTRUNK_BIN`:
+```bash
+export WORKTRUNK_BIN=./target/debug/wt
+wt switch feature # Now uses your dev build with shell integration
+```
+
+### "ran git wt; running through git prevents cd"
+
+**Meaning**: You ran `git wt` (git alias) instead of `wt`. Git runs worktrunk as
+a subprocess, bypassing the shell wrapper.
+
+**Fix**: Use `wt` directly instead of `git wt` when you need directory switching.
+
+## How the Shell Wrapper Works
+
+The shell wrapper (installed by `wt config shell install`) defines a shell
+function that:
+
+1. Creates a temp file for directives
+2. Sets `WORKTRUNK_DIRECTIVE_FILE` to that path
+3. Runs the real `wt` binary
+4. Sources the directive file (executes `cd` commands)
+5. Cleans up the temp file
+
+Simplified example (actual wrapper handles completions and edge cases):
+```bash
+wt() {
+ local directive_file
+ directive_file="$(mktemp)"
+
+ WORKTRUNK_DIRECTIVE_FILE="$directive_file" command wt "$@" || exit_code=$?
+
+ if [[ -s "$directive_file" ]]; then
+ source "$directive_file"
+ fi
+
+ rm -f "$directive_file"
+ return "$exit_code"
+}
+```
+
+## Debugging Checklist
+
+### 1. Check if wrapper is installed
+
+```bash
+# Should show shell function, not binary path
+type wt
+
+# Expected output (bash/zsh):
+# wt is a function
+# wt () { ... }
+
+# If it shows a path like /usr/local/bin/wt, wrapper isn't loaded
+```
+
+### 2. Check shell config file
+
+```bash
+# bash
+grep -n "wt config shell init" ~/.bashrc
+
+# zsh
+grep -n "wt config shell init" ~/.zshrc
+
+# fish
+grep -n "wt config shell init" ~/.config/fish/config.fish
+```
+
+Should show the `eval` line with line number.
+
+### 3. Check if directive file is set
+
+```bash
+# After running any wt command, this should be unset (temp file deleted)
+echo $WORKTRUNK_DIRECTIVE_FILE
+
+# During wt execution, this would be set to a temp file path
+```
+
+### 4. Test directive file manually
+
+```bash
+# Create a temp file and test
+export WORKTRUNK_DIRECTIVE_FILE=$(mktemp)
+command wt switch feature
+cat $WORKTRUNK_DIRECTIVE_FILE # Should contain: cd '/path/to/worktree'
+source $WORKTRUNK_DIRECTIVE_FILE # Should cd you there
+rm $WORKTRUNK_DIRECTIVE_FILE
+```
+
+## Common Issues
+
+### Shell integration works in terminal but not in IDE terminal
+
+IDE terminals may use different shell configs. Check:
+- VS Code: Settings → Terminal → Integrated → Shell Args
+- The IDE terminal might source a different profile
+
+### Completions not working
+
+Completions are installed alongside shell integration. If they're missing:
+
+```bash
+# Reinstall (forces regeneration)
+wt config shell install
+
+# For zsh, you may need compinit before the wt line:
+autoload -Uz compinit && compinit
+eval "$(wt config shell init zsh)"
+```
+
+### Windows Git Bash issues
+
+Git Bash uses MSYS2, which automatically converts POSIX paths in environment
+variables. The directive file path is handled correctly without manual conversion.
+
+If you see path issues, ensure you're using a recent Git for Windows version.
+
+## Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `WORKTRUNK_DIRECTIVE_FILE` | Set by shell wrapper; path to temp file for directives |
+| `WORKTRUNK_BIN` | Override binary path (for testing dev builds) |
+| `WORKTRUNK_SHELL` | Set by PowerShell wrapper to indicate shell type |
+
+## See Also
+
+- `wt config shell --help` — Shell integration commands
+- `wt config show` — View current configuration and status
diff --git a/.claude-plugin/skills/worktrunk/reference/user-config.md b/.claude-plugin/skills/worktrunk/reference/user-config.md
index 62c2d7835..7bfac87ac 100644
--- a/.claude-plugin/skills/worktrunk/reference/user-config.md
+++ b/.claude-plugin/skills/worktrunk/reference/user-config.md
@@ -78,7 +78,7 @@ Ask: "Should I add this to your config at `~/.config/worktrunk/config.toml`?"
### Step 5: After Approval, Check if Config Exists
```bash
-wt config list
+wt config show
```
If not: guide through `wt config create` first.
@@ -121,7 +121,7 @@ Result: `~/code/myproject/.worktrees/feature-auth`
### Workflow
-1. Show current setting from `wt config list`
+1. Show current setting from `wt config show`
2. Explain the new pattern with concrete example
3. Warn: "Existing worktrees won't move automatically"
4. Propose change
@@ -259,14 +259,14 @@ approved-commands = ["npm install"]
**Check sequence:**
1. Verify command exists: `which llm`
2. Test command directly: `llm "test"`
-3. View config: `wt config list`
+3. View config: `wt config show`
4. Check for template conflicts (both `template` and `template-file` set)
5. If template file is used, verify it exists
### Config Not Loading
**Check sequence:**
-1. View config path: `wt config list` shows location
+1. View config path: `wt config show` shows location
2. Verify file exists: `ls -la ~/.config/worktrunk/config.toml`
3. Check TOML syntax: `cat ~/.config/worktrunk/config.toml`
4. Look for validation errors (path must be relative, not absolute)
@@ -351,7 +351,7 @@ verify = true # Run project hooks
## Key Commands
```bash
-wt config list # View current config
+wt config show # View current config
wt config create # Create initial config file
wt config --help # Show LLM setup guide
```