aidenlx/zotlit / .agents/skills/worktrunk
worktrunk
VerifiedGuidance for Worktrunk (the `wt` CLI) — git worktree management, hooks, and config. Load when working out which worktree a `wt` command will act on, or reaching for the global `-C <path>` to target one; editing .config/wt.toml or ~/.config/worktrunk/config.toml; adding, modifying, or debugging hooks (post-merge, post-start, pre-commit, pre-merge, post-switch, etc.); configuring commit message generation or command aliases; or troubleshooting wt behavior. Also answers general worktrunk/wt questions.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.2 KB |
| reference/claude-code.md | markdown | 7.0 KB |
| reference/code-signing.md | markdown | 4.9 KB |
| reference/config.md | markdown | 49.9 KB |
| reference/extending.md | markdown | 12.0 KB |
| reference/faq.md | markdown | 20.4 KB |
| reference/hook.md | markdown | 20.4 KB |
| reference/list.md | markdown | 30.6 KB |
| reference/llm-commits.md | markdown | 8.2 KB |
| reference/merge.md | markdown | 7.0 KB |
| reference/remove.md | markdown | 7.4 KB |
| reference/shell-integration.md | markdown | 8.3 KB |
| reference/step.md | markdown | 30.8 KB |
| reference/switch.md | markdown | 13.3 KB |
| reference/tips-patterns.md | markdown | 20.5 KB |
| reference/troubleshooting.md | markdown | 6.4 KB |
| reference/worktrunk.md | markdown | 8.1 KB |
reference/troubleshooting.md
View on GitHub# Troubleshooting
Claude-specific troubleshooting guidance for common worktrunk issues.
## Commit message generation
### Command not found
Check if the configured tool is installed:
```bash
wt config show # shows the configured command
which claude # or: which codex, which llm, which aichat
```
If empty, install one of the supported tools. See [LLM commits docs](https://worktrunk.dev/llm-commits/) for setup instructions.
### Command returns an error
Test the configured command directly by piping a prompt to it. See `reference/llm-commits.md` for the exact command syntax for each tool.
```bash
echo "say hello" | <your-configured-command>
```
Common issues:
- **API key not set**: Each tool has its own auth mechanism
- **Model not available**: Check model name with the tool's help
- **Network issues**: Check internet connectivity
### Config not loading
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)
### Template config errors
Only inline `template` and `squash-template` values are supported. If the
config still uses the retired `template-file` or `squash-template-file` keys,
paste each file's contents into the corresponding inline setting.
## Hooks
### Hook not running
Check sequence:
1. Verify `.config/wt.toml` exists: `ls -la .config/wt.toml`
2. Check TOML syntax (use `wt hook show` to see parsed config)
3. Verify hook type spelling matches one of the ten types
4. Test command manually in the worktree
### Hook failing
Debug steps:
1. Run the command manually in the worktree to see errors
2. Check for missing dependencies (npm packages, system tools)
3. Verify template variables expand correctly with `wt hook show --expanded` (shows each command with its variables substituted)
4. For background hooks, check `.git/wt/logs/` for output
### Slow blocking hooks
Move long-running commands to background:
```toml
# Before — blocks for minutes
pre-start = "npm run build"
# After — fast setup, build in background
pre-start = "npm install"
post-start = "npm run build"
```
## Aliases
### Inspecting an alias
- `wt config alias show <name>` prints the raw template.
- `wt config alias dry-run <name> [-- args...]` prints the rendered command without running it.
### A `for-each` or `--execute` alias uses the same value in every worktree
The alias body rendered once at dispatch, baking the variable to the invoking worktree's value before the nested `wt` command iterated. See `reference/extending.md#nesting-templates` for how to pass the template through unrendered.
## List
### `wt list` times out after 120s
The timeout warning names the tasks that didn't finish:
```
Listing worktrees timed out after 120s (170 results received); blocked tasks:
<branch>: working-tree-diff, working-tree-conflicts
```
Both tasks run `git status --porcelain` first. When the named worktree has `core.fsmonitor=true` and its `git fsmonitor--daemon` is wedged, `git status` blocks until the IPC attempt fails (several minutes), and the 120s drain deadline fires first.
Confirm by running `git status` in the affected worktree:
```bash
cd <worktree>
time git --no-optional-locks status --porcelain
# error: could not read IPC response → hung daemon
```
List running daemons with their IPC socket (identifies which worktree each serves):
```bash
for pid in $(pgrep -f 'git fsmonitor--daemon'); do
sock=$(lsof -p $pid 2>/dev/null | grep 'fsmonitor--daemon.ipc' | awk '{print $NF}' | head -1)
printf "%6d %s\n" "$pid" "$sock"
done
```
Sockets listed as bare `fsmonitor--daemon.ipc` (no resolved path) belong to deleted worktrees. Any `wt remove` cleans these up: it terminates the removed worktree's own daemon and sweeps daemons whose worktree no longer exists, including ones orphaned by `git worktree remove` or `rm -rf` (mechanism details: [What can Worktrunk delete?](https://worktrunk.dev/faq/#what-can-worktrunk-delete)).
The residual case both paths deliberately leave is a wedged daemon on a *live* worktree that is never removed: `git status` in that worktree blocks on the unresponsive IPC, but the daemon still serves a real worktree, so reaping it implicitly is out of scope. Terminate it manually: kill the daemon whose socket path matches the worktree, or `pkill -9 -f 'git fsmonitor--daemon'` and let the next `wt list` respawn the live ones.
## PowerShell on Windows
### PowerShell profiles not created
On Windows, `wt config shell install` creates PowerShell profiles automatically when running from cmd.exe or PowerShell. It creates both:
- `Documents/PowerShell/Microsoft.PowerShell_profile.ps1` (PowerShell 7+/pwsh)
- `Documents/WindowsPowerShell/Microsoft.PowerShell_profile.ps1` (Windows PowerShell 5.1)
**If running from Git Bash or MSYS2**, PowerShell is skipped because the `SHELL` environment variable is set. To create PowerShell profiles explicitly:
```bash
wt config shell install powershell
```
### Wrong PowerShell variant configured
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_CD_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:
- `SHELL` not set → Windows-native shell → create both PowerShell profiles
- `SHELL` set (e.g., `/usr/bin/bash`) → Git Bash/MSYS2 → skip PowerShell
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |