Skip to content

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

docs(hook): clarify when pre-start/post-start fire (#2360)

Worktrunk Bot3a9d6402cb9a
diff --git a/docs/content/hook.md b/docs/content/hook.md
index de437f287..d09ddd278 100644
--- a/docs/content/hook.md
+++ b/docs/content/hook.md
@@ -31,8 +31,8 @@ The most common starting point is `post-start` — it runs background tasks (dev
|------|---------|
| `pre-switch` | Runs before branch resolution or worktree creation. `{{ branch }}` is the destination as typed (before resolution) |
| `post-switch` | Triggers on all switch results: creating, switching to existing, or staying on current |
-| `pre-start` | Tasks that must complete before `post-start`/`--execute`: dependency install, env file generation |
-| `post-start` | Dev servers, long builds, file watchers, copying caches |
+| `pre-start` | Runs once when a new worktree is created, blocking `post-start`/`--execute` until complete: dependency install, env file generation |
+| `post-start` | Runs once when a new worktree is created, in the background: dev servers, long builds, file watchers, copying caches |
| `pre-commit` | Formatters, linters, type checking — runs during `wt merge` before the squash commit |
| `post-commit` | CI triggers, notifications, background linting |
| `pre-merge` | Tests, security scans, build verification — runs after rebase, before merge to target |
diff --git a/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.md
index 935079d72..7aa977770 100644
--- a/skills/worktrunk/reference/hook.md
+++ b/skills/worktrunk/reference/hook.md
@@ -22,8 +22,8 @@ The most common starting point is `post-start` — it runs background tasks (dev
|------|---------|
| `pre-switch` | Runs before branch resolution or worktree creation. `{{ branch }}` is the destination as typed (before resolution) |
| `post-switch` | Triggers on all switch results: creating, switching to existing, or staying on current |
-| `pre-start` | Tasks that must complete before `post-start`/`--execute`: dependency install, env file generation |
-| `post-start` | Dev servers, long builds, file watchers, copying caches |
+| `pre-start` | Runs once when a new worktree is created, blocking `post-start`/`--execute` until complete: dependency install, env file generation |
+| `post-start` | Runs once when a new worktree is created, in the background: dev servers, long builds, file watchers, copying caches |
| `pre-commit` | Formatters, linters, type checking — runs during `wt merge` before the squash commit |
| `post-commit` | CI triggers, notifications, background linting |
| `pre-merge` | Tests, security scans, build verification — runs after rebase, before merge to target |
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index e1576fd7d..a3fb00efa 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -1163,8 +1163,8 @@ The most common starting point is `post-start` — it runs background tasks (dev
|------|---------|
| `pre-switch` | Runs before branch resolution or worktree creation. `{{ branch }}` is the destination as typed (before resolution) |
| `post-switch` | Triggers on all switch results: creating, switching to existing, or staying on current |
-| `pre-start` | Tasks that must complete before `post-start`/`--execute`: dependency install, env file generation |
-| `post-start` | Dev servers, long builds, file watchers, copying caches |
+| `pre-start` | Runs once when a new worktree is created, blocking `post-start`/`--execute` until complete: dependency install, env file generation |
+| `post-start` | Runs once when a new worktree is created, in the background: dev servers, long builds, file watchers, copying caches |
| `pre-commit` | Formatters, linters, type checking — runs during `wt merge` before the squash commit |
| `post-commit` | CI triggers, notifications, background linting |
| `pre-merge` | Tests, security scans, build verification — runs after rebase, before merge to target |