Extending Worktrunk

Worktrunk has three extension mechanisms.

Hooks are shell commands that run automatically at lifecycle events (switching, starting, committing, merging, removing). Defined in TOML.

Aliases are reusable shell commands invoked as wt <name>. Defined in TOML.

Custom subcommands are standalone executables invoked as wt <name>. Drop wt-foo on PATH and it becomes wt foo.

Hooks and aliases live in the same TOML config and share the template engine. User config is trusted; project config requires approval on first run. When both define the same name, both run (user first).

Hooks

Ten hooks cover five lifecycle events:

pre-* hooks block: failure aborts the operation. post-* hooks run in the background.

[pre-start]
deps = "npm ci"

[post-start]
server = "npm run dev -- --port {{ branch | hash_port }}"

[pre-merge]
test = "npm test"

See wt hook for the full reference and built-in recipes (dev server per worktree, database per worktree, progressive validation). Tips & Patterns has more.

Aliases

Aliases are configured under [aliases]:

[aliases]
deploy = "fly deploy --config=fly.{{ env }}.toml --app=myapp-{{ branch }}"
open = "open http://localhost:{{ branch | hash_port }}"
since-main = "git log --oneline {{ default_branch }}..HEAD"

wt deploy --env=staging
wt open

wt <name> resolves to a built-in first, then an alias, then a custom subcommand.

Templates

Aliases use the same template engine as hooks: variables, filters, functions, and --KEY=VALUE smart routing (bind if the template references KEY, else forward to {{ args }}). For example, wt deploy --env=staging sets {{ env }}.

Alias templates add {{ args }} for positional CLI arguments. Operation-context variables (target, base, pr_number) aren't auto-populated, but can still be bound with --KEY=VALUE.

Positional arguments

{{ args }} renders as a space-joined, shell-escaped string, ready to splice into a command:

[aliases]
s = "wt switch {{ args }}"

wt s some-branch
wt s feature/api
wt s 'has a space'

For indexing ({{ args[0] }}), looping, and counting, see Passing values.

Tokens after -- forward unconditionally, bypassing any binding. Writing wt deploy -- --branch=foo forwards the literal --branch=foo to {{ args }} even though the template references {{ branch }}.

Inspecting and previewing

• wt config alias show <name> prints the template.
• wt config alias dry-run <name> [-- args...] prints the rendered command.

wt config alias show deploy
wt config alias dry-run deploy
wt config alias dry-run deploy -- --env=staging

Multi-step pipelines

[[aliases.NAME]] defines a pipeline using the same [[block]] semantics as hooks: blocks run in order, keys within a block run concurrently, and a step failure aborts the remainder.

[[aliases.release]]
test = "cargo test"

[[aliases.release]]
build = "cargo build --release"
package = "cargo package --no-verify"

[[aliases.release]]
publish = "cargo publish {{ args }}"

Every step sees the same {{ args }} and bound variables. wt release -- --dry-run forwards --dry-run to publish without affecting earlier steps.

Changing directory

wt switch, wt merge (when it leaves the removed source), and wt remove of the current worktree change the parent shell's directory even when invoked from an alias; the Worktrunk shell integration propagates the change through. Other shell state doesn't persist: the alias runs in a subshell, so cd, export, and similar commands only affect that subshell.

Deferring expansion to a nested wt command

Alias templates render once at dispatch, using the alias-invocation worktree's context. A nested wt command in the alias body (for example wt switch --execute '…') therefore receives already-rendered text, so a variable like {{ worktree_path }} inside the inner command's template resolves to the outer worktree rather than the one wt switch is targeting. Wrap the inner template in {% raw %}…{% endraw %} so it passes through unrendered and the inner wt command expands it in its own context:

[aliases]
echo-target = "wt switch {{ args }} --no-cd --execute 'echo {% raw %}{{ worktree_path }}{% endraw %}'"

wt echo-target other now prints the path of the other worktree, not the worktree the alias was invoked from.

Recipe: rebase every worktree onto its upstream

[aliases]
up = '''
git fetch --all --prune && wt step for-each -- sh -c '
  git rev-parse --verify @{u} >/dev/null 2>&1 || exit 0
  g=$(git rev-parse --git-dir)
  test -d "$g/rebase-merge" -o -d "$g/rebase-apply" && exit 0
  git rebase @{u} --no-autostash || git rebase --abort
''''

wt up fetches all remotes, then iterates every worktree: skip if no upstream, skip if mid-rebase, otherwise rebase and auto-abort on conflict.

Recipe: move or copy in-progress changes to a new worktree

wt switch --create lands you in a clean worktree. To carry staged, unstaged, and untracked changes along, pair it with git stash:

# .config/wt.toml
[aliases]
move-changes = '''
if git diff --quiet HEAD && test -z "$(git ls-files --others --exclude-standard)"; then
  wt switch --create {{ to }} --execute="{{ args }}"
else
  git stash push --include-untracked --quiet
  wt switch --create {{ to }} --execute="git stash pop --index; {{ args }}"
fi
'''

Run with wt move-changes --to=feature-xyz. The guard skips the stash when nothing is in flight; otherwise git stash push captures everything and --execute pops it in the new worktree with the staged/unstaged split intact. Anything after -- runs in the new worktree after pop. For example, wt move-changes --to=feature-xyz -- claude opens Claude there.

To copy instead of move, add git stash apply --index --quiet right after the push.

Recipe: tail a specific hook log

wt config state logs --format=json emits structured entries (branch, source, hook_type, name, path). Pipe through jq to resolve one entry, then wrap in an alias for quick access:

[aliases]
hook-log = '''
tail -f "$(wt config state logs --format=json | jq -r --arg name "{{ name | sanitize_hash }}" --arg kind "{{ kind }}" '
  .hook_output[]
  | select(.branch == "{{ branch | sanitize_hash }}" and .hook_type == $kind and .name == $name)
  | .path
' | head -1)"
'''

Run with wt hook-log --kind=post-start --name=server to tail the log for the server hook on the current branch. --kind picks the hook type; the branch is pulled from the current worktree via {{ branch }}. sanitize_hash rewrites branch and name to filesystem-safe forms with a hash suffix that keeps distinct originals unique (the same transformation Worktrunk applies on disk), so the alias resolves the right log even when either contains characters like /.

Custom subcommands

Any executable named wt-<name> on PATH becomes available as wt <name>, the same pattern git uses for git-foo. Built-in commands and aliases take precedence.

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.

Examples

• worktrunk-sync: rebases stacked worktree branches in the dependency order inferred from git history. Install with cargo install worktrunk-sync, then run as wt sync.

Reference: hooks vs. aliases

Aside from the differences below, hooks and aliases behave the same.