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.mdindex 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.mdindex 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-opahdiff --git a/docs/content/llm-commits.md b/docs/content/llm-commits.mdindex 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.-## UsageThese 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 templatesdiff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.mdindex 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.mdindex 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.mdindex 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-opahdiff --git a/skills/worktrunk/reference/llm-commits.md b/skills/worktrunk/reference/llm-commits.mdindex 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.-## UsageThese 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 templatesdiff --git a/skills/worktrunk/reference/tips-patterns.md b/skills/worktrunk/reference/tips-patterns.mdindex 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:```bashtail -f "$(wt config state logs get --hook=user:post-start:server)"diff --git a/src/cli/mod.rs b/src/cli/mod.rsindex 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