Hooks
Hooks let you run custom commands in response to worktree lifecycle events.
Configuration
Define hooks in .config/gwt.toml under [hooks.<event>]:
[hooks.post-create]
install = "npm ci"
setup = "cp .env.example .env"
[hooks.pre-merge]
lint = "npm run lint"
test = "cargo test"
[hooks.pre-remove]
cleanup = "rm -rf node_modules"
Each key under the event is a named command. Names are for identification only — the values are the shell commands that run.
Available events
| Event | When it fires | Blocking |
|---|---|---|
post-create | After a worktree is created | Yes |
post-switch | After switching to a worktree | Yes |
pre-remove | Before a worktree is removed | Yes |
pre-merge | Before merge verification starts | Yes |
post-merge | After a successful merge | No |
Blocking events abort the operation if any hook command fails. For example, if a pre-merge hook fails, gwt merge stops before rebasing.
Non-blocking events log a warning on failure but continue the operation.
Built-in hook handlers
In addition to your custom commands, gwt’s internal plugins also respond to hook events:
| Plugin | Event | Action |
|---|---|---|
| Zellij | post-create | Creates a tab for the new worktree |
| Zellij | pre-remove | Closes the worktree’s tab |
| Zellij | post-switch | Switches to the worktree’s tab |
| Gateway | post-switch | Cleans up stale PID files |
| Claude | Various | Keeps the AI agent in sync with worktree state |
Custom hooks run alongside these built-in handlers.
Manually dispatching hooks
gwt hook post-create
gwt hook pre-merge
See hook command for details.