Skip to content

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.md
index 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:
```bash
llm install llm-anthropic
llm 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 Commands
diff --git a/.claude-plugin/skills/worktrunk/reference/hook-types-reference.md b/.claude-plugin/skills/worktrunk/reference/hook-types-reference.md
index 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 Merge
Full sequence when running `wt merge`:
@@ -161,7 +211,8 @@ Full sequence when running `wt merge`:
7. Merge branch into target
8. Push to remote
9. **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 execution
Named 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 Build
diff --git a/.claude-plugin/skills/worktrunk/reference/project-config.md b/.claude-plugin/skills/worktrunk/reference/project-config.md
index 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 Type
Ask: 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`: Sequential
Named 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 types
4. Test command manually in terminal
### Hook Failing
@@ -451,6 +504,23 @@ cat .config/wt.toml # Read config directly
wt 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.md
index 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-anthropic
llm 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