Skip to content

aidenlx/zotlit / .agents/skills/worktrunk

worktrunk

Verified

Guidance 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.

FileKindSize
SKILL.mdskill md11.2 KB
reference/claude-code.mdmarkdown7.0 KB
reference/code-signing.mdmarkdown4.9 KB
reference/config.mdmarkdown49.9 KB
reference/extending.mdmarkdown12.0 KB
reference/faq.mdmarkdown20.4 KB
reference/hook.mdmarkdown20.4 KB
reference/list.mdmarkdown30.6 KB
reference/llm-commits.mdmarkdown8.2 KB
reference/merge.mdmarkdown7.0 KB
reference/remove.mdmarkdown7.4 KB
reference/shell-integration.mdmarkdown8.3 KB
reference/step.mdmarkdown30.8 KB
reference/switch.mdmarkdown13.3 KB
reference/tips-patterns.mdmarkdown20.5 KB
reference/troubleshooting.mdmarkdown6.4 KB
reference/worktrunk.mdmarkdown8.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
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 implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall