Repository hooks

skills/worktree/reference/hooks.md · view on GitHub (opens in a new tab)

How a repository tells wt to give each worktree its own environment. Read this when setting a repository up (wt init) or debugging a hook.

Where they live

<root>/.claude/worktree/, in the root checkout. Hooks always run from there, never from a tree’s own copy, so they work whether the directory is committed or ignored, and teardown still works for a tree whose directory is gone. Every hook is optional; a repository without any still gets trees, names, slots and claims.

wt init writes commented stubs. wt init --local also adds the directory to .git/info/exclude, so it stays personal without touching .gitignore.

A hook must be executable; wt reports a non-executable hook as an error rather than skipping it.

The slot

Every tree holds a small integer, WT_SLOT, unique among the project’s trees. It is the only isolation wt provides: hooks turn it into real resources.

ResourceFrom the slot
Test databasesa suffix: TEST_ENV_NUMBER=$WT_SLOT
Portsan offset: $((10000 + WT_SLOT * 100))
Docker Composea project: COMPOSE_PROJECT_NAME=$WT_PROJECT-wt$WT_SLOT
Redisa database index

slot_min reserves low numbers — for example when the root checkout already uses test environment 1, start at 2.

Warm slots. With warm_slots = N, up to N idle slots keep their resources after their tree is removed (WT_TEARDOWN_MODE=release), and a new tree prefers one of them (WT_SLOT_WARM=1) — so setup can skip building databases that already exist. Beyond N, teardown is asked to destroy.

setup

Runs after wt new or wt adopt creates or registers a tree, and again on wt setup. cwd is the tree.

VariableValue
WT_NAME, WT_BRANCH, WT_PATHthe tree
WT_ROOT, WT_PROJECT, WT_GIT_COMMON_DIRthe root checkout, its directory name, the shared .git
WT_SLOTthe slot
WT_SLOT_WARM1 if the slot’s resources survived from an earlier tree
WT_ENV_OUTa file to append KEY=VALUE lines to

Lines in WT_ENV_OUT are stored in the registry and become the environment of every wt exec in the tree, and of its teardown. Values are taken literally (no quoting or expansion); export prefixes and # comments are allowed; WT_* names are reserved.

Exit non-zero and the tree is kept but marked broken, with the log path in its error. Output goes to a log under ~/.claude/wt/logs/; -v streams it as well.

teardown

Runs twice per removal: first with WT_DRY_RUN=1 while wt builds the plan, then with WT_DRY_RUN=0 when the user applies it. cwd is the tree, or the root checkout when the tree’s directory is gone. It sees everything setup saw, everything setup wrote, and:

VariableValue
WT_TEARDOWN_MODErelease (keep resources, the slot stays warm) or destroy
WT_DRY_RUN1: print what you would do and change nothing

Exiting non-zero means “not sure”, and nothing is removed: the dry run blocks the plan; a failed real run leaves the tree broken so wt rm can be retried. Use that whenever the hook cannot see what exists — a database server that is down, a failed authentication query — rather than reporting “nothing to clean”.

wt slots purge N also calls teardown, in destroy mode, for a slot no tree owns; then WT_NAME, WT_BRANCH and WT_PATH are empty and nothing from setup is available.

inventory

Optional. Prints the slot numbers that have resources in reality, one per line. wt status compares that with the registry:

Settings

config.toml. All optional; unknown keys and wrong types are errors.

KeyDefaultMeaning
slot_min, slot_max1, 999the slot range
warm_slots0idle slots that keep their resources
worktrees_dir".claude/worktrees"where new trees go, relative to the root
remote"origin"
base""start point for new branches; empty means <remote>/HEAD
fetchtruefetch the base before branching from it
branch_typesfeature, bug, chore, …leading branch segments dropped from tree names
default_type"feature"prefix for branches made from a description
story_branch"{type}/sc-{id}-{slug}"branch for a story that has none
slug_max, name_max50, 60length caps
unmanaged["agent-*"]trees under worktrees_dir that wt ignores

Writing good hooks