Worktree lifecycle: a runOnWorktreeRemove hook for tearing down per-worktree resources

[Xentox-Phil]

What we're trying to do

Each T3 worktree in our repo gets its own disposable dev resources:

• a local Postgres database (a template copy of a golden DB)
• its own SST stage on AWS (queues + a Lambda), so parallel worktrees running sst dev don't collide

Setup works well: a post-checkout hook provisions both when the worktree is created (runOnWorktreeCreate would work too).

Teardown is the gap. We want these resources to go away together with the worktree, so stale AWS stages and databases don't pile up.

What we do today

We tear down in a t3.json script with "runOnSettle": true. It runs sst remove --stage <hash> and drops the DB.

That's close, but settle isn't the same as "worktree is gone":

• Threads also settle after N days of inactivity. If you un-settle and continue in the same worktree, the database is gone, and nothing re-provisions it, because there is no hook on un-settle.
• Automatic worktree cleanup (storageCleanup.worktreeOnMerge) calls git worktree remove directly. Git has no hook for worktree removal, so there's no way to run cleanup at the moment the worktree actually disappears.

Question / idea

What's the intended way to model this lifecycle in T3?

A runOnWorktreeRemove script in t3.json would solve it cleanly:

• the counterpart to runOnWorktreeCreate
• runs in the worktree right before T3 removes it (merge cleanup, thread delete, after-days cleanup)
• setup ↔ teardown would then be symmetric, and settle/un-settle wouldn't need to touch external resources at all

Alternatively, a runOnUnsettle hook would let us re-provision after a settle-time teardown.

Happy to hear if there's a better pattern we're missing.

Version: 0.0.45-nightly.20260930.2481

[adamcooper]

+1 for a runOnWorktreeRemove hook. Our Rails worktrees use shared database, search, and caching servers, with separate databases, search indices, cache allocations, and local configuration for each worktree.

On settle, we only stop the application processes so the thread can resume with its data intact. When the worktree is removed, we want to clean up its resources and configuration while leaving the shared servers running.

A hook before removal would let us automate that cleanup, including when T3 removes worktrees automatically.

[t3dotgg]

Note

🤖 GPT-6.1 Terra [1m] responding on behalf of Theo

Closing as a duplicate of the earlier pre-removal project-action proposal. It covers teardown inside the worktree before manual or automatic removal. #14804