Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

docs: writing-prose cleanup (claude-code, hook, llm-commits, tips-patterns) (#2922)

Maximilian Roos3be40ad36ff3
diff --git a/docs/content/claude-code.md b/docs/content/claude-code.md
index 0c45c564a..2f740dc2c 100644
--- a/docs/content/claude-code.md
+++ b/docs/content/claude-code.md
@@ -52,7 +52,7 @@ Gemini loads the extension natively from the repository, so there is no `wt` wra
## Configuration skill
-The plugin includes a skill — documentation the agent can read — covering Worktrunk's configuration system. After installation, the agent can help with:
+With the `/worktrunk` skill, the agent can help with:
- Setting up LLM-generated commit messages
- Adding project hooks (pre-start, pre-merge, pre-commit)
diff --git a/docs/content/hook.md b/docs/content/hook.md
index 48d1ecbae..54fbeb3f0 100644
--- a/docs/content/hook.md
+++ b/docs/content/hook.md
@@ -40,7 +40,7 @@ The most common creation hook is `post-start` — it runs background tasks (dev
| `pre-remove` | Cleanup before worktree deletion: saving test artifacts, backing up state. Runs in the worktree being removed |
| `post-remove` | Stopping dev servers, removing containers, notifying external systems. Template variables reference the removed worktree |
-During `wt merge`, hooks run in this order: pre-commit → post-commit → pre-merge → pre-remove → post-remove + post-merge. As usual, post-* hooks run in the background. See [`wt merge`](@/merge.md#pipeline) for the complete pipeline.
+During `wt merge`, hooks run in this order: pre-commit → post-commit → pre-merge → pre-remove → post-remove + post-merge. See [`wt merge`](@/merge.md#pipeline) for the complete pipeline.
# Security
@@ -129,12 +129,12 @@ Hooks can use template variables that expand at runtime:
| | `{{ commit }}` | Branch HEAD SHA |
| | `{{ short_commit }}` | Branch HEAD SHA, abbreviated per `core.abbrev` |
| | `{{ upstream }}` | Branch upstream (if tracking a remote) |
-| operation | `{{ base }}` | Base branch name |
+| operation | `{{ base }}` | Base branch name (switch/create only) |
| | `{{ base_worktree_path }}` | Base worktree path |
| | `{{ target }}` | Target branch name |
-| | `{{ target_worktree_path }}` | Target worktree path |
-| | `{{ pr_number }}` | PR/MR number (when creating via `pr:N` / `mr:N`) |
-| | `{{ pr_url }}` | PR/MR web URL (when creating via `pr:N` / `mr:N`) |
+| | `{{ target_worktree_path }}` | Target worktree path (when target has a worktree) |
+| | `{{ pr_number }}` | PR/MR number (post-switch, pre-start, post-start; when creating via `pr:N` / `mr:N`) |
+| | `{{ pr_url }}` | PR/MR web URL (post-switch, pre-start, post-start; when creating via `pr:N` / `mr:N`) |
| repo | `{{ repo }}` | Repository directory name |
| | `{{ repo_path }}` | Absolute path to repository root |
| | `{{ owner }}` | Primary remote owner path (may include subgroups) |
@@ -157,9 +157,14 @@ Bare variables (`branch`, `worktree_path`, `commit`) refer to the branch the ope
| merge | feature being merged | = bare vars | merge target |
| remove | branch being removed | = bare vars | where you end up |
-Pre and post hooks share the same perspective — `{{ branch | hash_port }}` produces the same port in `post-start` and `post-remove`. `cwd` is the worktree root where the hook command runs. It differs from `worktree_path` in three cases: pre-switch, where the hook runs in the source but `worktree_path` is the destination; post-remove, where the active worktree is gone so the hook runs in primary; and post-merge with removal, same — the active worktree is gone, so the hook runs in target.
+All hooks share the same perspective — `{{ branch | hash_port }}` produces the same port in `post-start` and `post-remove`.
-Some variables are conditional: `upstream` requires remote tracking; `base` only appears in switch/create hooks; `target_worktree_path` requires the target to have a worktree; `pr_number`/`pr_url` are populated for `post-switch`, `pre-start`, and `post-start` hooks when creating via `pr:N` or `mr:N`; `vars` keys may not exist. Undefined variables error — use conditionals or defaults for optional behavior:
+`cwd` is the worktree root where the hook command runs. It equals `worktree_path` except in three cases:
+
+- `pre-switch`: hook runs in the source worktree; `worktree_path` is the destination
+- `post-remove` and `post-merge` with removal: the active worktree is gone, so the hook runs in primary or target, respectively
+
+Undefined variables error — use conditionals or defaults for optional behavior:
```toml
[pre-start]
@@ -191,7 +196,7 @@ Templates support Jinja2 filters for transforming values:
| `basename` | `{{ repo_path \| basename }}` | Keep only the last path component (`/a/b/c` → `c`) |
| `codename(n)` | `{{ branch \| codename(2) }}` | Deterministic friendly words |
-The `sanitize` filter makes branch names safe for filesystem paths. The `sanitize_db` filter produces database-safe identifiers — lowercase alphanumeric and underscores, no leading digits, with a 3-character hash suffix to avoid collisions and reserved words. The `sanitize_hash` filter produces a filesystem-safe name and appends a 3-character hash suffix when sanitization changed the input, so distinct originals never collide — already-safe names pass through unchanged. The `codename(n)` filter produces deterministic friendly names from an input string: `codename(1)` returns a noun, `codename(2)` returns `adjective-noun`, and higher counts add more adjectives. The pool is large (~1.26M combinations for `codename(2)`), so it usually stands alone as a worktree leaf:
+The `sanitize_db` filter produces database-safe identifiers — lowercase alphanumeric and underscores, no leading digits, with a 3-character hash suffix to avoid collisions and reserved words. The `sanitize_hash` filter produces a filesystem-safe name and appends a 3-character hash suffix when sanitization changed the input, so distinct originals never collide — already-safe names pass through unchanged. The `codename(n)` filter produces deterministic friendly names from an input string: `codename(1)` returns a noun, `codename(2)` returns `adjective-noun`, and higher counts add more adjectives. The pool is large (~1.26M combinations for `codename(2)`), so it usually stands alone as a worktree leaf:
```toml
# Friendly branch-derived worktree names, e.g. myproject.malleable-opah
diff --git a/docs/content/llm-commits.md b/docs/content/llm-commits.md
index 14f9c573e..0edfd5c75 100644
--- a/docs/content/llm-commits.md
+++ b/docs/content/llm-commits.md
@@ -51,10 +51,6 @@ command = "llm -m claude-haiku-4.5"
command = "aichat -m claude:claude-haiku-4.5"
```
-## How it works
-
-When worktrunk needs a commit message, it builds a prompt from a template and pipes it to the configured command via shell (`sh -c`). Environment variables can be set inline in the command string.
-
## Usage
These examples assume a feature worktree with changes to commit.
@@ -147,7 +143,7 @@ Summaries are cached and regenerated only when the diff changes.
## Prompt templates
-Worktrunk uses [minijinja](https://docs.rs/minijinja/) templates (Jinja2-like syntax) to build prompts. There are sensible defaults, but templates are fully customizable.
+Worktrunk uses [minijinja](https://docs.rs/minijinja/) templates (Jinja2-like syntax) to build prompts.
### Custom templates
diff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.md
index 6ce19f077..0e4ec178e 100644
--- a/docs/content/tips-patterns.md
+++ b/docs/content/tips-patterns.md
@@ -57,7 +57,7 @@ server = "wt step tether -- npm run dev -- --port {{ branch | hash_port }}"
url = "http://localhost:{{ branch | hash_port }}"
```
-[`wt step tether`](@/step.md#wt-step-tether) runs the server in its own process group and tears the whole group down when the worktree is removed, so no `pre-remove` hook is needed. This matters because `npm run dev` spawns an esbuild process that does not listen on the dev-server port and reparents away when the top process exits, so a port- or parent-based kill leaks it; across enough worktree churn those leaks accumulate. See the [`wt step tether`](@/step.md#wt-step-tether) docs for the full rationale and platform behavior.
+[`wt step tether`](@/step.md#wt-step-tether) runs the server in its own process group and tears the whole group down when the worktree is removed, so no `pre-remove` hook is needed. See the [`wt step tether`](@/step.md#wt-step-tether) docs for the full rationale and platform behavior.
The URL column in `wt list` shows each worktree's dev server:
@@ -76,7 +76,7 @@ The URL column in `wt list` shows each worktree's dev server:
<!-- END AUTO-GENERATED -->
-Ports are deterministic: `fix-auth` always gets port 16460, regardless of which machine or when. The URL dims if the server isn't running.
+`fix-auth` always gets port 16460, on any machine. The URL dims if the server isn't running.
## Database per worktree
@@ -409,7 +409,7 @@ url = "http://{{ branch | sanitize }}.{{ repo }}.localhost:8080"
## Monitor hook logs
-Follow background hook output in real-time:
+Follow background hook output:
{{ terminal(cmd="tail -f __WT_QUOT__$(wt config state logs get --hook=user:post-start:server)__WT_QUOT__") }}
diff --git a/skills/worktrunk/reference/claude-code.md b/skills/worktrunk/reference/claude-code.md
index 668d26435..0adcae17d 100644
--- a/skills/worktrunk/reference/claude-code.md
+++ b/skills/worktrunk/reference/claude-code.md
@@ -58,7 +58,7 @@ Gemini loads the extension natively from the repository, so there is no `wt` wra
## Configuration skill
-The plugin includes a skill — documentation the agent can read — covering Worktrunk's configuration system. After installation, the agent can help with:
+With the `/worktrunk` skill, the agent can help with:
- Setting up LLM-generated commit messages
- Adding project hooks (pre-start, pre-merge, pre-commit)
diff --git a/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.md
index 792765753..2184e3029 100644
--- a/skills/worktrunk/reference/hook.md
+++ b/skills/worktrunk/reference/hook.md
@@ -31,7 +31,7 @@ The most common creation hook is `post-start` — it runs background tasks (dev
| `pre-remove` | Cleanup before worktree deletion: saving test artifacts, backing up state. Runs in the worktree being removed |
| `post-remove` | Stopping dev servers, removing containers, notifying external systems. Template variables reference the removed worktree |
-During `wt merge`, hooks run in this order: pre-commit → post-commit → pre-merge → pre-remove → post-remove + post-merge. As usual, post-* hooks run in the background. See [`wt merge`](https://worktrunk.dev/merge/#pipeline) for the complete pipeline.
+During `wt merge`, hooks run in this order: pre-commit → post-commit → pre-merge → pre-remove → post-remove + post-merge. See [`wt merge`](https://worktrunk.dev/merge/#pipeline) for the complete pipeline.
# Security
@@ -120,12 +120,12 @@ Hooks can use template variables that expand at runtime:
| | `{{ commit }}` | Branch HEAD SHA |
| | `{{ short_commit }}` | Branch HEAD SHA, abbreviated per `core.abbrev` |
| | `{{ upstream }}` | Branch upstream (if tracking a remote) |
-| operation | `{{ base }}` | Base branch name |
+| operation | `{{ base }}` | Base branch name (switch/create only) |
| | `{{ base_worktree_path }}` | Base worktree path |
| | `{{ target }}` | Target branch name |
-| | `{{ target_worktree_path }}` | Target worktree path |
-| | `{{ pr_number }}` | PR/MR number (when creating via `pr:N` / `mr:N`) |
-| | `{{ pr_url }}` | PR/MR web URL (when creating via `pr:N` / `mr:N`) |
+| | `{{ target_worktree_path }}` | Target worktree path (when target has a worktree) |
+| | `{{ pr_number }}` | PR/MR number (post-switch, pre-start, post-start; when creating via `pr:N` / `mr:N`) |
+| | `{{ pr_url }}` | PR/MR web URL (post-switch, pre-start, post-start; when creating via `pr:N` / `mr:N`) |
| repo | `{{ repo }}` | Repository directory name |
| | `{{ repo_path }}` | Absolute path to repository root |
| | `{{ owner }}` | Primary remote owner path (may include subgroups) |
@@ -148,9 +148,14 @@ Bare variables (`branch`, `worktree_path`, `commit`) refer to the branch the ope
| merge | feature being merged | = bare vars | merge target |
| remove | branch being removed | = bare vars | where you end up |
-Pre and post hooks share the same perspective — `{{ branch | hash_port }}` produces the same port in `post-start` and `post-remove`. `cwd` is the worktree root where the hook command runs. It differs from `worktree_path` in three cases: pre-switch, where the hook runs in the source but `worktree_path` is the destination; post-remove, where the active worktree is gone so the hook runs in primary; and post-merge with removal, same — the active worktree is gone, so the hook runs in target.
+All hooks share the same perspective — `{{ branch | hash_port }}` produces the same port in `post-start` and `post-remove`.
-Some variables are conditional: `upstream` requires remote tracking; `base` only appears in switch/create hooks; `target_worktree_path` requires the target to have a worktree; `pr_number`/`pr_url` are populated for `post-switch`, `pre-start`, and `post-start` hooks when creating via `pr:N` or `mr:N`; `vars` keys may not exist. Undefined variables error — use conditionals or defaults for optional behavior:
+`cwd` is the worktree root where the hook command runs. It equals `worktree_path` except in three cases:
+
+- `pre-switch`: hook runs in the source worktree; `worktree_path` is the destination
+- `post-remove` and `post-merge` with removal: the active worktree is gone, so the hook runs in primary or target, respectively
+
+Undefined variables error — use conditionals or defaults for optional behavior:
```toml
[pre-start]
@@ -182,7 +187,7 @@ Templates support Jinja2 filters for transforming values:
| `basename` | `{{ repo_path \| basename }}` | Keep only the last path component (`/a/b/c` → `c`) |
| `codename(n)` | `{{ branch \| codename(2) }}` | Deterministic friendly words |
-The `sanitize` filter makes branch names safe for filesystem paths. The `sanitize_db` filter produces database-safe identifiers — lowercase alphanumeric and underscores, no leading digits, with a 3-character hash suffix to avoid collisions and reserved words. The `sanitize_hash` filter produces a filesystem-safe name and appends a 3-character hash suffix when sanitization changed the input, so distinct originals never collide — already-safe names pass through unchanged. The `codename(n)` filter produces deterministic friendly names from an input string: `codename(1)` returns a noun, `codename(2)` returns `adjective-noun`, and higher counts add more adjectives. The pool is large (~1.26M combinations for `codename(2)`), so it usually stands alone as a worktree leaf:
+The `sanitize_db` filter produces database-safe identifiers — lowercase alphanumeric and underscores, no leading digits, with a 3-character hash suffix to avoid collisions and reserved words. The `sanitize_hash` filter produces a filesystem-safe name and appends a 3-character hash suffix when sanitization changed the input, so distinct originals never collide — already-safe names pass through unchanged. The `codename(n)` filter produces deterministic friendly names from an input string: `codename(1)` returns a noun, `codename(2)` returns `adjective-noun`, and higher counts add more adjectives. The pool is large (~1.26M combinations for `codename(2)`), so it usually stands alone as a worktree leaf:
```toml
# Friendly branch-derived worktree names, e.g. myproject.malleable-opah
diff --git a/skills/worktrunk/reference/llm-commits.md b/skills/worktrunk/reference/llm-commits.md
index 14f60e327..5f1f8dae8 100644
--- a/skills/worktrunk/reference/llm-commits.md
+++ b/skills/worktrunk/reference/llm-commits.md
@@ -37,10 +37,6 @@ command = "llm -m claude-haiku-4.5"
command = "aichat -m claude:claude-haiku-4.5"
```
-## How it works
-
-When worktrunk needs a commit message, it builds a prompt from a template and pipes it to the configured command via shell (`sh -c`). Environment variables can be set inline in the command string.
-
## Usage
These examples assume a feature worktree with changes to commit.
@@ -121,7 +117,7 @@ Summaries are cached and regenerated only when the diff changes.
## Prompt templates
-Worktrunk uses [minijinja](https://docs.rs/minijinja/) templates (Jinja2-like syntax) to build prompts. There are sensible defaults, but templates are fully customizable.
+Worktrunk uses [minijinja](https://docs.rs/minijinja/) templates (Jinja2-like syntax) to build prompts.
### Custom templates
diff --git a/skills/worktrunk/reference/tips-patterns.md b/skills/worktrunk/reference/tips-patterns.md
index ed9433bb0..90c6cccab 100644
--- a/skills/worktrunk/reference/tips-patterns.md
+++ b/skills/worktrunk/reference/tips-patterns.md
@@ -54,7 +54,7 @@ server = "wt step tether -- npm run dev -- --port {{ branch | hash_port }}"
url = "http://localhost:{{ branch | hash_port }}"
```
-[`wt step tether`](https://worktrunk.dev/step/#wt-step-tether) runs the server in its own process group and tears the whole group down when the worktree is removed, so no `pre-remove` hook is needed. This matters because `npm run dev` spawns an esbuild process that does not listen on the dev-server port and reparents away when the top process exits, so a port- or parent-based kill leaks it; across enough worktree churn those leaks accumulate. See the [`wt step tether`](https://worktrunk.dev/step/#wt-step-tether) docs for the full rationale and platform behavior.
+[`wt step tether`](https://worktrunk.dev/step/#wt-step-tether) runs the server in its own process group and tears the whole group down when the worktree is removed, so no `pre-remove` hook is needed. See the [`wt step tether`](https://worktrunk.dev/step/#wt-step-tether) docs for the full rationale and platform behavior.
The URL column in `wt list` shows each worktree's dev server:
@@ -69,7 +69,7 @@ $ wt list
<span class=d>○</span> <span class=d>Showing 4 worktrees, 2 with changes, 2 ahead, 2 columns hidden</span>
```
-Ports are deterministic: `fix-auth` always gets port 16460, regardless of which machine or when. The URL dims if the server isn't running.
+`fix-auth` always gets port 16460, on any machine. The URL dims if the server isn't running.
## Database per worktree
@@ -426,7 +426,7 @@ url = "http://{{ branch | sanitize }}.{{ repo }}.localhost:8080"
## Monitor hook logs
-Follow background hook output in real-time:
+Follow background hook output:
```bash
tail -f "$(wt config state logs get --hook=user:post-start:server)"
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index ef93efeb9..4d0b9449f 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -1252,7 +1252,7 @@ The most common creation hook is `post-start` — it runs background tasks (dev
| `pre-remove` | Cleanup before worktree deletion: saving test artifacts, backing up state. Runs in the worktree being removed |
| `post-remove` | Stopping dev servers, removing containers, notifying external systems. Template variables reference the removed worktree |
-During `wt merge`, hooks run in this order: pre-commit → post-commit → pre-merge → pre-remove → post-remove + post-merge. As usual, post-* hooks run in the background. See [`wt merge`](@/merge.md#pipeline) for the complete pipeline.
+During `wt merge`, hooks run in this order: pre-commit → post-commit → pre-merge → pre-remove → post-remove + post-merge. See [`wt merge`](@/merge.md#pipeline) for the complete pipeline.
# Security
@@ -1341,12 +1341,12 @@ Hooks can use template variables that expand at runtime:
| | `{{ commit }}` | Branch HEAD SHA |
| | `{{ short_commit }}` | Branch HEAD SHA, abbreviated per `core.abbrev` |
| | `{{ upstream }}` | Branch upstream (if tracking a remote) |
-| operation | `{{ base }}` | Base branch name |
+| operation | `{{ base }}` | Base branch name (switch/create only) |
| | `{{ base_worktree_path }}` | Base worktree path |
| | `{{ target }}` | Target branch name |
-| | `{{ target_worktree_path }}` | Target worktree path |
-| | `{{ pr_number }}` | PR/MR number (when creating via `pr:N` / `mr:N`) |
-| | `{{ pr_url }}` | PR/MR web URL (when creating via `pr:N` / `mr:N`) |
+| | `{{ target_worktree_path }}` | Target worktree path (when target has a worktree) |
+| | `{{ pr_number }}` | PR/MR number (post-switch, pre-start, post-start; when creating via `pr:N` / `mr:N`) |
+| | `{{ pr_url }}` | PR/MR web URL (post-switch, pre-start, post-start; when creating via `pr:N` / `mr:N`) |
| repo | `{{ repo }}` | Repository directory name |
| | `{{ repo_path }}` | Absolute path to repository root |
| | `{{ owner }}` | Primary remote owner path (may include subgroups) |
@@ -1369,9 +1369,14 @@ Bare variables (`branch`, `worktree_path`, `commit`) refer to the branch the ope
| merge | feature being merged | = bare vars | merge target |
| remove | branch being removed | = bare vars | where you end up |
-Pre and post hooks share the same perspective — `{{ branch | hash_port }}` produces the same port in `post-start` and `post-remove`. `cwd` is the worktree root where the hook command runs. It differs from `worktree_path` in three cases: pre-switch, where the hook runs in the source but `worktree_path` is the destination; post-remove, where the active worktree is gone so the hook runs in primary; and post-merge with removal, same — the active worktree is gone, so the hook runs in target.
+All hooks share the same perspective — `{{ branch | hash_port }}` produces the same port in `post-start` and `post-remove`.
-Some variables are conditional: `upstream` requires remote tracking; `base` only appears in switch/create hooks; `target_worktree_path` requires the target to have a worktree; `pr_number`/`pr_url` are populated for `post-switch`, `pre-start`, and `post-start` hooks when creating via `pr:N` or `mr:N`; `vars` keys may not exist. Undefined variables error — use conditionals or defaults for optional behavior:
+`cwd` is the worktree root where the hook command runs. It equals `worktree_path` except in three cases:
+
+- `pre-switch`: hook runs in the source worktree; `worktree_path` is the destination
+- `post-remove` and `post-merge` with removal: the active worktree is gone, so the hook runs in primary or target, respectively
+
+Undefined variables error — use conditionals or defaults for optional behavior:
```toml
[pre-start]
@@ -1403,7 +1408,7 @@ Templates support Jinja2 filters for transforming values:
| `basename` | `{{ repo_path \| basename }}` | Keep only the last path component (`/a/b/c` → `c`) |
| `codename(n)` | `{{ branch \| codename(2) }}` | Deterministic friendly words |
-The `sanitize` filter makes branch names safe for filesystem paths. The `sanitize_db` filter produces database-safe identifiers — lowercase alphanumeric and underscores, no leading digits, with a 3-character hash suffix to avoid collisions and reserved words. The `sanitize_hash` filter produces a filesystem-safe name and appends a 3-character hash suffix when sanitization changed the input, so distinct originals never collide — already-safe names pass through unchanged. The `codename(n)` filter produces deterministic friendly names from an input string: `codename(1)` returns a noun, `codename(2)` returns `adjective-noun`, and higher counts add more adjectives. The pool is large (~1.26M combinations for `codename(2)`), so it usually stands alone as a worktree leaf:
+The `sanitize_db` filter produces database-safe identifiers — lowercase alphanumeric and underscores, no leading digits, with a 3-character hash suffix to avoid collisions and reserved words. The `sanitize_hash` filter produces a filesystem-safe name and appends a 3-character hash suffix when sanitization changed the input, so distinct originals never collide — already-safe names pass through unchanged. The `codename(n)` filter produces deterministic friendly names from an input string: `codename(1)` returns a noun, `codename(2)` returns `adjective-noun`, and higher counts add more adjectives. The pool is large (~1.26M combinations for `codename(2)`), so it usually stands alone as a worktree leaf:
```toml
# Friendly branch-derived worktree names, e.g. myproject.malleable-opah