Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
Update worktrunk skill with new hooks and features (#294)
Maximilian Roose50cbd484ccc
diff --git a/.claude-plugin/skills/worktrunk/SKILL.md b/.claude-plugin/skills/worktrunk/SKILL.mdindex a5abd071d..7c778bb2c 100644--- a/.claude-plugin/skills/worktrunk/SKILL.md+++ b/.claude-plugin/skills/worktrunk/SKILL.md@@ -22,7 +22,7 @@ Worktrunk uses two separate config files with different scopes and behaviors:### User Config (`~/.config/worktrunk/config.toml`)- **Scope**: Personal preferences for the individual developer- **Location**: `~/.config/worktrunk/config.toml` (never checked into git)-- **Contains**: LLM integration, worktree path templates, approved commands+- **Contains**: LLM integration, worktree path templates, command settings, user hooks, approved commands- **Permission model**: Always propose changes and get consent before editing- **See**: `reference/user-config.md` for detailed guidance@@ -71,7 +71,7 @@ Most common request. Follow this sequence:```bashllm install llm-anthropicllm keys set anthropic- llm models default claude-haiku-4-5-20251001+ llm models default claude-haiku-4.5```4. **Propose config change**@@ -108,10 +108,13 @@ Common request for workflow automation. Follow discovery process:- For Rust: Common cargo commands- For Python: Check pyproject.toml-3. **Design appropriate hooks**+3. **Design appropriate hooks** (7 hook types available)- Dependencies (fast, must complete) → `post-create`- Tests/linting (must pass) → `pre-commit` or `pre-merge`- - Long builds → `post-start`+ - Long builds, dev servers → `post-start`+ - Terminal/IDE updates → `post-switch`+ - Deployment → `post-merge`+ - Cleanup tasks → `pre-remove`4. **Validate commands work**```bash@@ -162,6 +165,8 @@ Common request for workflow automation. Follow discovery process:- Set up LLM integration → `reference/user-config.md#llm-setup`- Customize worktree paths → `reference/user-config.md#worktree-paths`- Custom commit templates → `reference/user-config.md#templates`+- Configure command defaults → `reference/user-config.md#command-settings`+- Set up personal hooks → `reference/user-config.md#user-hooks`- Troubleshoot LLM issues → `reference/user-config.md#troubleshooting`### Project Config Tasks@@ -169,6 +174,7 @@ Common request for workflow automation. Follow discovery process:- Add hook to existing config → `reference/project-config.md#add-hook`- Use template variables → `reference/project-config.md#variables`- Convert command formats → `reference/project-config.md#formats`+- Add dev server URL to list → `reference/project-config.md#dev-server-url`- Troubleshoot hook execution → `reference/project-config.md#troubleshooting`## Key Commandsdiff --git a/.claude-plugin/skills/worktrunk/reference/hook-types-reference.md b/.claude-plugin/skills/worktrunk/reference/hook-types-reference.mdindex c3e8f5669..6ae6b8b57 100644--- a/.claude-plugin/skills/worktrunk/reference/hook-types-reference.md+++ b/.claude-plugin/skills/worktrunk/reference/hook-types-reference.md@@ -1,18 +1,20 @@# Hook Types Reference-Detailed behavior and use cases for all five Worktrunk hook types.+Detailed behavior and use cases for all seven Worktrunk hook types.## Hook Type Comparison| Hook | When | Blocking? | Fail-Fast? | Variables | Execution ||------|------|-----------|------------|-----------|-----------|| `post-create` | After creating worktree | Yes | No | Basic | Sequential |-| `post-start` | When switching to worktree | No | No | Basic | Parallel |+| `post-start` | After creating worktree | No (background) | No | Basic | Parallel |+| `post-switch` | After every switch | No (background) | No | Basic | Parallel || `pre-commit` | Before committing during merge | Yes | Yes | Basic + Merge | Sequential || `pre-merge` | Before merging to target | Yes | Yes | Basic + Merge | Sequential || `post-merge` | After successful merge | Yes | No | Basic + Merge | Sequential |+| `pre-remove` | Before worktree removed | Yes | Yes | Basic | Sequential |-**Basic variables**: `{{ repo }}`, `{{ branch }}` (raw), `{{ worktree }}`, `{{ repo_root }}`+**Basic variables**: `{{ repo }}`, `{{ branch }}`, `{{ worktree }}`, `{{ worktree_name }}`, `{{ repo_root }}`, `{{ default_branch }}`, `{{ commit }}`, `{{ short_commit }}`, `{{ remote }}`, `{{ remote_url }}`, `{{ upstream }}`**Merge variables**: Basic + `{{ target }}`**Filters**: `{{ branch | sanitize }}` (replace `/` `\` with `-`), `{{ branch | hash_port }}` (port 10000-19999)@@ -70,6 +72,29 @@ sync = "git pull origin main"**What happens**: User runs `wt switch --create feature-x`. After creation completes, all three commands start immediately in parallel in background. User can work while they run. Check `.git/wt-logs/` for output.+### post-switch++**When it runs**: After every switch operation (creating new, switching to existing, or switching to current).++**Behavior**:+- Runs in background, doesn't block user+- Multiple commands run in parallel+- Output logged to `.git/wt-logs/`+- Triggers on all switch results++**Use cases**:+- Renaming terminal tabs+- Updating tmux window names+- IDE notifications+- Any per-switch automation++**Example**:+```toml+post-switch = "echo 'Switched to {{ branch }}'"+```++**What happens**: Every time the user runs `wt switch`, this fires in the background. Unlike post-start, it runs on every switch, not just when creating new worktrees.+### pre-commit**When it runs**: Before committing changes during `wt merge`.@@ -148,6 +173,31 @@ notify = "./scripts/notify-slack.sh"**What happens**: User runs `wt merge`. After merge succeeds and push completes, commands run in main worktree. Then cleanup happens (branch deletion, worktree removal).+### pre-remove++**When it runs**: Before worktree removal during `wt remove`.++**Behavior**:+- Blocks until all commands complete+- Commands run sequentially+- ANY failure aborts the removal (fail-fast)+- Exit code 0 required from all commands++**Use cases**:+- Cleanup tasks (temp files, caches)+- Saving state before removal+- Notifying external systems+- Stopping services++**Example**:+```toml+[pre-remove]+cleanup = "rm -rf /tmp/cache/{{ branch }}"+stop = "docker-compose down"+```++**What happens**: User runs `wt remove`. Before the worktree is removed, commands run. If any fails, removal is aborted.+## Execution Order During MergeFull sequence when running `wt merge`:@@ -161,7 +211,8 @@ Full sequence when running `wt merge`:7. Merge branch into target8. Push to remote9. **Run `post-merge`** (best-effort)-10. Clean up (delete branch, remove worktree)+10. **Run `pre-remove`** (fail-fast, if cleanup enabled)+11. Clean up (delete branch, remove worktree)## Format Variants@@ -183,9 +234,11 @@ services = "docker-compose up -d"Behavior:- `post-create`: Sequential execution- `post-start`: Parallel execution+- `post-switch`: Parallel execution- `pre-commit`: Sequential execution- `pre-merge`: Sequential execution- `post-merge`: Sequential execution+- `pre-remove`: Sequential executionNamed commands appear in output with their labels, making it easier to identify which command succeeded or failed.@@ -201,7 +254,14 @@ Available:- `{{ repo }}` - Repository name (e.g., "my-project")- `{{ branch }}` - Branch name (e.g., "feature-auth")- `{{ worktree }}` - Absolute path to worktree+- `{{ worktree_name }}` - Worktree directory name (e.g., "my-project.feature-auth")- `{{ repo_root }}` - Absolute path to repository root+- `{{ default_branch }}` - Default branch name (e.g., "main")+- `{{ commit }}` - Full HEAD commit SHA+- `{{ short_commit }}` - Short HEAD commit SHA (7 chars)+- `{{ remote }}` - Primary remote name (e.g., "origin")+- `{{ remote_url }}` - Remote URL (e.g., "[email protected]:user/repo.git")+- `{{ upstream }}` - Upstream tracking branch (e.g., "origin/feature")### Merge Variables (Merge Hooks Only)@@ -230,6 +290,31 @@ fi"""```+### JSON Context++Hooks also receive context as JSON on stdin, enabling hooks in any language:++```python+import json, sys+ctx = json.load(sys.stdin)+print(f"Setting up {ctx['repo']} on branch {ctx['branch']}")+```++The JSON includes all template variables plus `hook_type` and `hook_name`. This enables repository-specific behavior in user hooks:++```toml+# ~/.config/worktrunk/config.toml+[post-switch]+notify = """+python3 -c '+import json, sys+ctx = json.load(sys.stdin)+if "work-project" in ctx.get("repo", ""):+ print(f"Switched to work project: {ctx[\"branch\"]}")+'+"""+```+## Common Patterns### Fast Dependencies + Slow Builddiff --git a/.claude-plugin/skills/worktrunk/reference/project-config.md b/.claude-plugin/skills/worktrunk/reference/project-config.mdindex ab63cce35..5657141e7 100644--- a/.claude-plugin/skills/worktrunk/reference/project-config.md+++ b/.claude-plugin/skills/worktrunk/reference/project-config.md@@ -133,11 +133,13 @@ cat .config/wt.toml### Step 2: Determine Appropriate Hook TypeAsk: When should this run?-- Creating worktree → `post-create`-- Switching to worktree → `post-start`+- Creating worktree (blocking) → `post-create`+- Creating worktree (background) → `post-start`+- Every switch operation → `post-switch`- Before committing → `pre-commit`- Before merging → `pre-merge`- After merging → `post-merge`+- Before worktree removal → `pre-remove`### Step 3: Handle Format Conversion if Needed@@ -188,7 +190,14 @@ Available in all hook types:- `{{ repo }}` - Repository name (e.g., "my-project")- `{{ branch }}` - Raw branch name (e.g., "feature/auth")- `{{ worktree }}` - Absolute path to worktree+- `{{ worktree_name }}` - Worktree directory name (e.g., "my-project.feature-auth")- `{{ repo_root }}` - Absolute path to repository root+- `{{ default_branch }}` - Default branch name (e.g., "main")+- `{{ commit }}` - Full HEAD commit SHA+- `{{ short_commit }}` - Short HEAD commit SHA (7 chars)+- `{{ remote }}` - Primary remote name (e.g., "origin")+- `{{ remote_url }}` - Remote URL (e.g., "[email protected]:user/repo.git")+- `{{ upstream }}` - Upstream tracking branch (e.g., "origin/feature")### Filters@@ -254,15 +263,17 @@ services = "docker-compose up -d"Behavior:- `post-create`: Sequential- `post-start`: Parallel+- `post-switch`: Parallel- `pre-commit`: Sequential- `pre-merge`: Sequential- `post-merge`: Sequential+- `pre-remove`: SequentialNamed commands appear in output with their labels, which helps identify which command succeeded or failed.## Hook Types-Five hook types with different timing and behavior:+Seven hook types with different timing and behavior:### post-create@@ -308,6 +319,26 @@ services = "docker-compose up -d"</example>+### post-switch++**When**: After every switch operation (background)+**Blocking**: No (runs in background)+**Fail-fast**: No+**Execution**: Parallel++**Use for**:+- Renaming terminal tabs+- Updating tmux window names+- IDE notifications++<example type="post-switch">++```toml+post-switch = "echo 'Switched to {{ branch }}'"+```++</example>+### pre-commit**When**: Before committing during merge@@ -370,6 +401,28 @@ post-merge = "npm run deploy"</example>+### pre-remove++**When**: Before worktree removal during `wt remove`+**Blocking**: Yes+**Fail-fast**: Yes (any failure aborts removal)+**Execution**: Sequential++**Use for**:+- Cleanup tasks (temp files, caches)+- Saving state+- Notifying external systems+- Stopping services++<example type="pre-remove">++```toml+[pre-remove]+cleanup = "rm -rf /tmp/cache/{{ branch }}"+```++</example>+See `hook-types-reference.md` for complete behavioral details.## Validation & Safety@@ -413,7 +466,7 @@ Reject obviously dangerous commands:Check sequence:1. Verify `.config/wt.toml` exists: `ls -la .config/wt.toml`2. Check TOML syntax: `cat .config/wt.toml`-3. Verify hook name spelling matches one of the five types+3. Verify hook name spelling matches one of the seven types4. Test command manually in terminal### Hook Failing@@ -451,6 +504,23 @@ cat .config/wt.toml # Read config directlywt switch --create test-hooks # Test hooks work```+## Dev Server URL++Add a URL column to `wt list` showing dev server links per worktree:++```toml+[list]+url = "http://localhost:{{ branch | hash_port }}"+```++URLs are dimmed when the port isn't listening. The template supports all variables plus filters.++Example with subdomain:+```toml+[list]+url = "http://{{ branch }}.lvh.me:3000"+```+## Config File Location- **Always at**: `<repo>/.config/wt.toml` (checked into git)diff --git a/.claude-plugin/skills/worktrunk/reference/user-config.md b/.claude-plugin/skills/worktrunk/reference/user-config.mdindex 3f922d02a..8cd11164f 100644--- a/.claude-plugin/skills/worktrunk/reference/user-config.md+++ b/.claude-plugin/skills/worktrunk/reference/user-config.md@@ -49,7 +49,7 @@ For Claude (via llm):llm install llm-anthropicllm keys set anthropic# User pastes API key from: https://console.anthropic.com/settings/keys-llm models default claude-haiku-4-5-20251001+llm models default claude-haiku-4.5```For OpenAI (via llm):@@ -212,6 +212,29 @@ worktree-path = "../{{ main_worktree }}.{{ branch | sanitize }}"command = "llm"args = ["-m", "claude-haiku-4.5"]+# Command Settings (configure default flags)+[list]+full = true # --full+branches = true # --branches+remotes = true # --remotes++[commit]+stage = "all" # "all", "tracked", or "none"++[merge]+squash = true # Squash commits (default: true)+commit = true # Commit uncommitted changes (default: true)+rebase = true # Rebase onto target (default: true)+remove = true # Remove worktree after merge (default: true)+verify = true # Run hooks (default: true)++# User Hooks (run for all repositories, no approval required)+[post-create]+setup = "echo 'Setting up worktree...'"++[pre-merge]+notify = "notify-send 'Merging {{ branch }}'"+# Optional: Custom prompt template (inline, Jinja2 syntax)template = "..."@@ -253,6 +276,78 @@ approved-commands = ["npm install"]- Approved commands are auto-populated when using `wt switch --execute "cmd" --force`- Manual editing is possible but discouraged (use the tool's approval system)+## User Hooks++Personal hooks that run for all repositories. These don't require approval and run before project hooks.++```toml+[post-create]+setup = "echo 'Setting up worktree...'"++[pre-merge]+notify = "notify-send 'Merging {{ branch }}'"+```++User hooks support the same hook types and template variables as project hooks. Use `--no-verify` to skip.++**Key differences from project hooks:**++| Aspect | User hooks | Project hooks |+|--------|------------|--------------|+| Location | `~/.config/worktrunk/config.toml` | `.config/wt.toml` |+| Scope | All repositories | Single repository |+| Approval | Not required | Required |+| Execution order | First | After user hooks |++**Filtering by repository:**++User hooks receive JSON context on stdin, enabling repository-specific behavior:++```toml+[post-switch]+notify = """+python3 -c '+import json, sys+ctx = json.load(sys.stdin)+if "work-project" in ctx.get("repo", ""):+ print(f"Switched to work project: {ctx[\"branch\"]}")+'+"""+```++## Command Settings++Configure default flag values for commands. These apply unless explicitly overridden.++### `[list]` section++```toml+[list]+full = false # Show CI and main-diffstat columns (--full)+branches = false # Include branches without worktrees (--branches)+remotes = false # Include remote branches (--remotes)+```++### `[commit]` section++Shared by `wt step commit`, `wt step squash`, and `wt merge`:++```toml+[commit]+stage = "all" # What to stage: "all", "tracked", or "none"+```++### `[merge]` section++```toml+[merge]+squash = true # Squash commits when merging+commit = true # Commit uncommitted changes (disables squash when false)+rebase = true # Rebase onto target before merging+remove = true # Remove worktree after merge+verify = true # Run project hooks+```+## Key Commands```bash