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.mdindex f0633c15c..0bb72cc92 100644--- a/.claude-plugin/skills/worktrunk/SKILL.md+++ b/.claude-plugin/skills/worktrunk/SKILL.md@@ -3,7 +3,7 @@ name: worktrunkdescription: 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 configwt 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.mdgrep -A 20 "## LLM Setup" reference/user-config.mdgrep -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.mdindex 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 configcat .config/wt.toml # Read config directlywt 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.mdnew file mode 100644index 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 statusdiff --git a/.claude-plugin/skills/worktrunk/reference/user-config.md b/.claude-plugin/skills/worktrunk/reference/user-config.mdindex 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 example3. 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 location2. 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 configwt config create # Create initial config filewt config --help # Show LLM setup guide```