Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

docs: document post-start/pre-remove cleanup pattern (#646)

Maximilian Roos5819e3f9e166
diff --git a/.claude-plugin/skills/worktrunk/reference/hook.md b/.claude-plugin/skills/worktrunk/reference/hook.md
index 84eddea34..88edce442 100644
--- a/.claude-plugin/skills/worktrunk/reference/hook.md
+++ b/.claude-plugin/skills/worktrunk/reference/hook.md
@@ -276,6 +276,8 @@ Both run when creating a worktree. The difference:
Many tasks work well in `post-start` — they'll likely be ready by the time they're needed, especially when the fallback is recompiling. If unsure, prefer `post-start` for faster worktree creation.
+Background processes spawned by `post-start` outlive the worktree — pair them with `pre-remove` hooks to clean up. See [Dev servers](#dev-servers) and [Databases](#databases) for examples.
+
### Copying untracked files
Git worktrees share the repository but not untracked files (dependencies, caches, `.env`). Use [`wt step copy-ignored`](https://worktrunk.dev/step/#wt-step-copy-ignored) to copy gitignored files:
@@ -294,6 +296,9 @@ Run a dev server per worktree on a deterministic port using `hash_port`:
```toml
[post-start]
server = "npm run dev -- --port {{ branch | hash_port }}"
+
+[pre-remove]
+server = "lsof -ti :{{ branch | hash_port }} | xargs kill 2>/dev/null || true"
```
The port is stable across machines and restarts — `feature-api` always gets the same port. Show it in `wt list`:
diff --git a/docs/content/hook.md b/docs/content/hook.md
index 0ab56a9f3..72c194f3e 100644
--- a/docs/content/hook.md
+++ b/docs/content/hook.md
@@ -284,6 +284,8 @@ Both run when creating a worktree. The difference:
Many tasks work well in `post-start` — they'll likely be ready by the time they're needed, especially when the fallback is recompiling. If unsure, prefer `post-start` for faster worktree creation.
+Background processes spawned by `post-start` outlive the worktree — pair them with `pre-remove` hooks to clean up. See [Dev servers](#dev-servers) and [Databases](#databases) for examples.
+
### Copying untracked files
Git worktrees share the repository but not untracked files (dependencies, caches, `.env`). Use [`wt step copy-ignored`](@/step.md#wt-step-copy-ignored) to copy gitignored files:
@@ -302,6 +304,9 @@ Run a dev server per worktree on a deterministic port using `hash_port`:
```toml
[post-start]
server = "npm run dev -- --port {{ branch | hash_port }}"
+
+[pre-remove]
+server = "lsof -ti :{{ branch | hash_port }} | xargs kill 2>/dev/null || true"
```
The port is stable across machines and restarts — `feature-api` always gets the same port. Show it in `wt list`:
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index dd8c04b5d..252c1e1bc 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -1272,6 +1272,8 @@ Both run when creating a worktree. The difference:
Many tasks work well in `post-start` — they'll likely be ready by the time they're needed, especially when the fallback is recompiling. If unsure, prefer `post-start` for faster worktree creation.
+Background processes spawned by `post-start` outlive the worktree — pair them with `pre-remove` hooks to clean up. See [Dev servers](#dev-servers) and [Databases](#databases) for examples.
+
### Copying untracked files
Git worktrees share the repository but not untracked files (dependencies, caches, `.env`). Use [`wt step copy-ignored`](@/step.md#wt-step-copy-ignored) to copy gitignored files:
@@ -1290,6 +1292,9 @@ Run a dev server per worktree on a deterministic port using `hash_port`:
```toml
[post-start]
server = "npm run dev -- --port {{ branch | hash_port }}"
+
+[pre-remove]
+server = "lsof -ti :{{ branch | hash_port }} | xargs kill 2>/dev/null || true"
```
The port is stable across machines and restarts — `feature-api` always gets the same port. Show it in `wt list`: