Skip to content

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

docs: add Extending Worktrunk page (#2079)

Maximilian Roose2fff694a542
diff --git a/docs/content/extending.md b/docs/content/extending.md
new file mode 100644
index 000000000..1fa0ff341
--- /dev/null
+++ b/docs/content/extending.md
@@ -0,0 +1,133 @@
++++
+title = "Extending Worktrunk"
+description = "Three ways to add custom behavior: hooks for lifecycle automation, aliases for reusable commands, and external subcommands for standalone tools."
+weight = 21
+
+[extra]
+group = "Reference"
++++
+
+Worktrunk has three extension mechanisms.
+
+**[Hooks](#hooks)** run shell commands at lifecycle events — creating a worktree, merging, removing. They're configured in TOML and run automatically.
+
+**[Aliases](#aliases)** define reusable commands invoked via `wt step <name>`. Same template variables as hooks, but triggered manually.
+
+**[External subcommands](#external-subcommands)** are standalone executables. Drop `wt-foo` on `PATH` and it becomes `wt foo`. No configuration needed.
+
+| | Hooks | Aliases | External subcommands |
+|---|---|---|---|
+| **Trigger** | Automatic (lifecycle events) | Manual (`wt step <name>`) | Manual (`wt <name>`) |
+| **Defined in** | TOML config | TOML config | Any executable on `PATH` |
+| **Template variables** | Yes | Yes | No |
+| **Shareable via repo** | `.config/wt.toml` | `.config/wt.toml` | Distribute the binary |
+| **Language** | Shell commands | Shell commands | Any |
+
+## Hooks
+
+Hooks are shell commands that run at key points in the worktree lifecycle. Ten hooks cover five events:
+
+| Event | `pre-` (blocking) | `post-` (background) |
+|-------|-------------------|---------------------|
+| **switch** | `pre-switch` | `post-switch` |
+| **start** | `pre-start` | `post-start` |
+| **commit** | `pre-commit` | `post-commit` |
+| **merge** | `pre-merge` | `post-merge` |
+| **remove** | `pre-remove` | `post-remove` |
+
+`pre-*` hooks block — failure aborts the operation. `post-*` hooks run in the background.
+
+### Configuration
+
+Hooks live in two places:
+
+- **User config** (`~/.config/worktrunk/config.toml`) — personal, applies everywhere, trusted
+- **Project config** (`.config/wt.toml`) — shared with the team, requires [approval](@/hook.md#wt-hook-approvals) on first run
+
+Three formats, from simplest to most expressive:
+
+```toml
+# Single command
+pre-start = "npm ci"
+```
+
+```toml
+# Named commands (concurrent for post-*, serial for pre-*)
+[post-start]
+server = "npm start"
+watcher = "npm run watch"
+```
+
+```toml
+# Pipeline: steps run in order, commands within a step run concurrently
+post-start = [
+ "npm ci",
+ { server = "npm start", build = "npm run build" }
+]
+```
+
+### Template variables
+
+Hook commands are templates. Variables expand at execution time:
+
+```toml
+[post-start]
+server = "npm run dev -- --port {{ branch | hash_port }}"
+env = "echo 'PORT={{ branch | hash_port }}' > .env.local"
+```
+
+Core variables include `branch`, `worktree_path`, `commit`, `repo`, `default_branch`, and context-dependent ones like `target` during merge. Filters like `sanitize`, `hash_port`, and `sanitize_db` transform values for specific uses.
+
+See [`wt hook`](@/hook.md#template-variables) for the full variable and filter reference.
+
+### Common patterns
+
+```toml
+# .config/wt.toml
+
+# Install dependencies when creating a worktree
+[pre-start]
+deps = "npm ci"
+
+# Run tests before merging
+[pre-merge]
+test = "npm test"
+lint = "npm run lint"
+
+# Dev server per worktree on a deterministic port
+[post-start]
+server = "npm run dev -- --port {{ branch | hash_port }}"
+```
+
+See [Tips & Patterns](@/tips-patterns.md) for more recipes: dev server per worktree, database per worktree, tmux sessions, Caddy subdomain routing.
+
+## Aliases
+
+Aliases are custom commands invoked via `wt step <name>`. They share the same template variables and approval model as hooks.
+
+```toml
+# .config/wt.toml
+[aliases]
+deploy = "make deploy BRANCH={{ branch }}"
+open = "open http://localhost:{{ branch | hash_port }}"
+```
+
+{{ terminal(cmd="wt step deploy|||wt step deploy --dry-run|||wt step deploy --var env=staging") }}
+
+When both user and project config define the same alias name, both run — user first, then project. Project-config aliases require approval, same as project hooks.
+
+Alias names that collide with built-in step commands (`commit`, `squash`, `rebase`, etc.) are shadowed by the built-in.
+
+See [`wt step` — Aliases](@/step.md#aliases) for the full reference.
+
+## External subcommands
+
+<span class="badge-experimental"></span>
+
+Any executable named `wt-<name>` on `PATH` becomes available as `wt <name>` — the same pattern git uses for `git-foo`. Built-in commands always take precedence.
+
+{{ terminal(cmd="wt sync origin # runs: wt-sync origin|||wt -C /tmp/repo sync # -C is forwarded as the child's working directory") }}
+
+Arguments pass through verbatim, stdio is inherited, and the child's exit code propagates unchanged. External subcommands don't have access to template variables.
+
+If nothing matches — no built-in, no nested subcommand, no `wt-<name>` on `PATH` — wt prints a "not a wt command" error with a typo suggestion.
diff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.md
index 5990908c7..09fd3dcf4 100644
--- a/docs/content/tips-patterns.md
+++ b/docs/content/tips-patterns.md
@@ -31,14 +31,6 @@ test = "cargo test --features {{ vars.features | default('default') }}"
See [`wt step` aliases](@/step.md#aliases) for scoping, approval, and reference.
-## External subcommands `[experimental]`
-
-Drop a `wt-<name>` binary anywhere on `PATH` and `wt <name>` will run it — mirroring how `git foo` finds `git-foo`. Use this to ship third-party extensions without patching worktrunk itself.
-
-{{ terminal(cmd="wt sync origin # runs: wt-sync origin|||wt -C /tmp/repo sync # `-C` is forwarded as the child's cwd") }}
-
-Built-in commands always take precedence, so an external `wt-switch` cannot shadow `wt switch`. Arguments after the name are passed through verbatim (including `--help`), and the child's exit code is propagated unchanged. If nothing matches — no built-in, no nested subcommand, no `wt-<name>` — wt prints a git-style `'foo' is not a wt command` error with a typo suggestion drawn from the built-in command list.
-
## Per-branch variables
`wt config state vars` holds state per branch, accessible from templates (`{{ vars.key }}`) and the CLI. Some uses:
diff --git a/skills/worktrunk/reference/extending.md b/skills/worktrunk/reference/extending.md
new file mode 100644
index 000000000..3d4556dcc
--- /dev/null
+++ b/skills/worktrunk/reference/extending.md
@@ -0,0 +1,133 @@
+# Extending Worktrunk
+
+Worktrunk has three extension mechanisms.
+
+**[Hooks](#hooks)** run shell commands at lifecycle events — creating a worktree, merging, removing. They're configured in TOML and run automatically.
+
+**[Aliases](#aliases)** define reusable commands invoked via `wt step <name>`. Same template variables as hooks, but triggered manually.
+
+**[External subcommands](#external-subcommands)** are standalone executables. Drop `wt-foo` on `PATH` and it becomes `wt foo`. No configuration needed.
+
+| | Hooks | Aliases | External subcommands |
+|---|---|---|---|
+| **Trigger** | Automatic (lifecycle events) | Manual (`wt step <name>`) | Manual (`wt <name>`) |
+| **Defined in** | TOML config | TOML config | Any executable on `PATH` |
+| **Template variables** | Yes | Yes | No |
+| **Shareable via repo** | `.config/wt.toml` | `.config/wt.toml` | Distribute the binary |
+| **Language** | Shell commands | Shell commands | Any |
+
+## Hooks
+
+Hooks are shell commands that run at key points in the worktree lifecycle. Ten hooks cover five events:
+
+| Event | `pre-` (blocking) | `post-` (background) |
+|-------|-------------------|---------------------|
+| **switch** | `pre-switch` | `post-switch` |
+| **start** | `pre-start` | `post-start` |
+| **commit** | `pre-commit` | `post-commit` |
+| **merge** | `pre-merge` | `post-merge` |
+| **remove** | `pre-remove` | `post-remove` |
+
+`pre-*` hooks block — failure aborts the operation. `post-*` hooks run in the background.
+
+### Configuration
+
+Hooks live in two places:
+
+- **User config** (`~/.config/worktrunk/config.toml`) — personal, applies everywhere, trusted
+- **Project config** (`.config/wt.toml`) — shared with the team, requires [approval](https://worktrunk.dev/hook/#wt-hook-approvals) on first run
+
+Three formats, from simplest to most expressive:
+
+```toml
+# Single command
+pre-start = "npm ci"
+```
+
+```toml
+# Named commands (concurrent for post-*, serial for pre-*)
+[post-start]
+server = "npm start"
+watcher = "npm run watch"
+```
+
+```toml
+# Pipeline: steps run in order, commands within a step run concurrently
+post-start = [
+ "npm ci",
+ { server = "npm start", build = "npm run build" }
+]
+```
+
+### Template variables
+
+Hook commands are templates. Variables expand at execution time:
+
+```toml
+[post-start]
+server = "npm run dev -- --port {{ branch | hash_port }}"
+env = "echo 'PORT={{ branch | hash_port }}' > .env.local"
+```
+
+Core variables include `branch`, `worktree_path`, `commit`, `repo`, `default_branch`, and context-dependent ones like `target` during merge. Filters like `sanitize`, `hash_port`, and `sanitize_db` transform values for specific uses.
+
+See [`wt hook`](https://worktrunk.dev/hook/#template-variables) for the full variable and filter reference.
+
+### Common patterns
+
+```toml
+# .config/wt.toml
+
+# Install dependencies when creating a worktree
+[pre-start]
+deps = "npm ci"
+
+# Run tests before merging
+[pre-merge]
+test = "npm test"
+lint = "npm run lint"
+
+# Dev server per worktree on a deterministic port
+[post-start]
+server = "npm run dev -- --port {{ branch | hash_port }}"
+```
+
+See [Tips & Patterns](https://worktrunk.dev/tips-patterns/) for more recipes: dev server per worktree, database per worktree, tmux sessions, Caddy subdomain routing.
+
+## Aliases
+
+Aliases are custom commands invoked via `wt step <name>`. They share the same template variables and approval model as hooks.
+
+```toml
+# .config/wt.toml
+[aliases]
+deploy = "make deploy BRANCH={{ branch }}"
+open = "open http://localhost:{{ branch | hash_port }}"
+```
+
+```bash
+$ wt step deploy
+$ wt step deploy --dry-run
+$ wt step deploy --var env=staging
+```
+
+When both user and project config define the same alias name, both run — user first, then project. Project-config aliases require approval, same as project hooks.
+
+Alias names that collide with built-in step commands (`commit`, `squash`, `rebase`, etc.) are shadowed by the built-in.
+
+See [`wt step` — Aliases](https://worktrunk.dev/step/#aliases) for the full reference.
+
+## External subcommands
+
+[experimental]
+
+Any executable named `wt-<name>` on `PATH` becomes available as `wt <name>` — the same pattern git uses for `git-foo`. Built-in commands always take precedence.
+
+```bash
+$ wt sync origin # runs: wt-sync origin
+$ wt -C /tmp/repo sync # -C is forwarded as the child's working directory
+```
+
+Arguments pass through verbatim, stdio is inherited, and the child's exit code propagates unchanged. External subcommands don't have access to template variables.
+
+If nothing matches — no built-in, no nested subcommand, no `wt-<name>` on `PATH` — wt prints a "not a wt command" error with a typo suggestion.
diff --git a/skills/worktrunk/reference/tips-patterns.md b/skills/worktrunk/reference/tips-patterns.md
index ae820c81c..64c7a696b 100644
--- a/skills/worktrunk/reference/tips-patterns.md
+++ b/skills/worktrunk/reference/tips-patterns.md
@@ -28,17 +28,6 @@ test = "cargo test --features {{ vars.features | default('default') }}"
See [`wt step` aliases](https://worktrunk.dev/step/#aliases) for scoping, approval, and reference.
-## External subcommands `[experimental]`
-
-Drop a `wt-<name>` binary anywhere on `PATH` and `wt <name>` will run it — mirroring how `git foo` finds `git-foo`. Use this to ship third-party extensions without patching worktrunk itself.
-
-```bash
-$ wt sync origin # runs: wt-sync origin
-$ wt -C /tmp/repo sync # `-C` is forwarded as the child's cwd
-```
-
-Built-in commands always take precedence, so an external `wt-switch` cannot shadow `wt switch`. Arguments after the name are passed through verbatim (including `--help`), and the child's exit code is propagated unchanged. If nothing matches — no built-in, no nested subcommand, no `wt-<name>` — wt prints a git-style `'foo' is not a wt command` error with a typo suggestion drawn from the built-in command list.
-
## Per-branch variables
`wt config state vars` holds state per branch, accessible from templates (`{{ vars.key }}`) and the CLI. Some uses: