[Feature]: Run a project action before worktree removal (runOnWorktreeRemove), for resources outside the worktree

[mateosayas]

Before submitting

• I searched existing issues and did not find an open issue covering this exact behavior.
• I am describing a concrete problem or use case, not just a vague idea.

Area

apps/server

Problem or use case

runOnWorktreeCreate can start resources that live outside the worktree, for example a per-worktree Postgres container (docker compose -p <slug> up). There is no matching hook for removal.

When a thread is deleted in the UI, T3 Code removes the worktree directory, but the container and its volume stay. They accumulate until Docker consumes most of the machine's RAM and disk.

The teardown needs state that lives in the worktree (in our case a .dev/workspace.env holding the compose project name). Once the directory is gone, that state is gone too, so a cleanup after the fact cannot work reliably.

Proposed solution

Add an optional project action flag, runOnWorktreeRemove, that:

• runs in the worktree before git worktree remove
• receives T3CODE_WORKTREE_PATH / T3CODE_PROJECT_ROOT, like the create action
• applies to every removal path: manual thread delete, archive/settle cleanup, and the Storage cleanup rules

Smallest useful scope

Run the flagged action before git worktree remove on manual thread delete. The other removal paths can follow.

Alternatives considered

• A teardown script that runs our teardown and then removes the worktree: works, but the UI delete and archive buttons skip it.
• Cleanup after removal: the state the teardown needs is gone with the worktree directory.

Examples or references

• Project scripts: add worktree deletion lifecycle hooks #425 and feat(worktrees): run actions before removal #9337 both implemented this. feat(worktrees): run actions before removal #9337 was closed so V2 can land first; this Discussion records the request so it can be part of the V2 design.
• Related: Configurable custom actions when a task is settled (e.g. clean build artifacts) #12522, Workspace providers: pluggable create/remove commands (rift, CoW clones, Worktrunk), with support for non-git directories and cleanup on settle #11266, [Feature]: Clean up worktrees for settled threads without deleting history #6856.

Contribution

• I would be open to helping implement this.

[yakobe]

@t3dotgg & @juliusmarminge is there a chance we could get a hook like this?

I'm trying to migrate from Orca to T3 Code. Without a hook like this, we can't clean up, and eventually the environment will just crash.

[bacaxnot]

Same need here, and the same Orca migration. Our setup creates a per-worktree Postgres database on a shared server, so removal has to drop it, stop dev servers started in the worktree, and delete the branch. Orca runs scripts.archive from orca.yaml before it removes a worktree, and we point it at the same script's teardown. Under T3 we remove worktrees from a terminal first, and anything T3 removes (manual delete, cleanup policies) leaves the database behind. Like the original post, we need the hook to run before removal, in the worktree, because the teardown reads state from it.

[djgilcrease]

NOTE: This comment was left by gpt-6.1-sol high on behalf of Dj Gilcrease.

I built a runnable prototype for this use case as an external Worktree Environments plugin, released as v0.1.0. The plugin proposal update has screenshots, a failure/retry recording, configuration examples and verification limits.

Its worktree.removing hook runs before the checkout, untracked files or submodules are removed, so teardown can still read .dev/workspace.env and stop a per-worktree Compose stack or drop a project-owned database. It is connected to T3's manual removal and storage-cleanup paths, including thread-deletion cleanup. Setup and cleanup scripts stay versioned in your project; commands receive T3CODE_WORKTREE_PATH, T3CODE_PROJECT_ROOT and a stable worktree ID. Private env values and secret references can be configured separately.

If teardown fails, the checkout is kept and its owning thread is restored/unsettled with a visible failure notice. Fix the script and retry removal. Required cleanup goes in the pre-removal hook; after-removal notifications are best effort. The cleanup recipe is recorded before setup so changing the project's recipe later does not silently replace cleanup ownership.

This requires the proposed plugin-host fork and is not available in stock T3 Code. It is an optional script runner, not a built-in Docker/Postgres integration; scripts must be idempotent, and deletion outside T3 cannot trigger hooks. The UI demo uses a synthetic external resource.

It also gives this feature need an external implementation to try while the plugin proposal is discussed: users can publish and maintain their own environment workflows without putting each integration into T3's core. Design feedback on the shared lifecycle boundary can go to the linked update.