Skip to content

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

docs(hook): drop pre-start vs post-start section (#2326)

Maximilian Roos0be0a28eae5a
diff --git a/README.md b/README.md
index 11c3bca9d..0528c5ad6 100644
--- a/README.md
+++ b/README.md
@@ -198,7 +198,7 @@ wt switch -x claude -c feature-b -- 'Fix the pagination bug'
wt switch -x claude -c feature-c -- 'Write tests for the API'
```
-The `-x` flag runs a command after switching; arguments after `--` are passed to it. Configure [post-start hooks](https://worktrunk.dev/hook/#pre-start-vs-post-start) to automate setup (install deps, start dev servers).
+The `-x` flag runs a command after switching; arguments after `--` are passed to it. Configure [post-start hooks](https://worktrunk.dev/hook/#hook-types) to automate setup (install deps, start dev servers).
## Next steps
diff --git a/docs/content/hook.md b/docs/content/hook.md
index 93ccb7736..fb5484291 100644
--- a/docs/content/hook.md
+++ b/docs/content/hook.md
@@ -25,7 +25,7 @@ Hooks are shell commands that run at key points in the worktree lifecycle — au
`pre-*` hooks block — failure aborts the operation. `post-*` hooks run in the background with output logged (use [`wt config state logs`](@/config.md#wt-config-state-logs) to find and manage log files). Use `-v` to see expanded command details for background hooks.
-The most common starting point is `post-start` — it runs background tasks (dev servers, file copying, builds) when creating a worktree.
+The most common starting point is `post-start` — it runs background tasks (dev servers, file copying, builds) without blocking worktree creation. Prefer `post-start` over `pre-start` unless a later step needs the work completed first.
| Hook | Purpose |
|------|---------|
@@ -299,17 +299,6 @@ Pipelines matter when there's a dependency chain — typically setup steps that
# Designing Effective Hooks
-## pre-start vs post-start
-
-Both run when creating a worktree. The difference:
-
-| Hook | Execution | Best for |
-|------|-----------|----------|
-| `pre-start` | Blocks until complete | Tasks the developer needs before working (dependency install) |
-| `post-start` | Background, parallel | Long-running tasks that don't block worktree creation |
-
-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. For finer control over execution order within `post-start`, see [Pipeline ordering](#pipeline-ordering).
-
## Copying untracked files
Git worktrees share the repository but not untracked files. [`wt step copy-ignored`](@/step.md#wt-step-copy-ignored) copies gitignored files between worktrees:
diff --git a/docs/content/worktrunk.md b/docs/content/worktrunk.md
index be03f99ba..d6704f5d0 100644
--- a/docs/content/worktrunk.md
+++ b/docs/content/worktrunk.md
@@ -192,7 +192,7 @@ For parallel agents, create multiple worktrees and launch an agent in each:
{{ terminal(cmd="wt switch -x claude -c feature-a -- 'Add user authentication'|||wt switch -x claude -c feature-b -- 'Fix the pagination bug'|||wt switch -x claude -c feature-c -- 'Write tests for the API'") }}
-The `-x` flag runs a command after switching; arguments after `--` are passed to it. Configure [post-start hooks](@/hook.md#pre-start-vs-post-start) to automate setup (install deps, start dev servers).
+The `-x` flag runs a command after switching; arguments after `--` are passed to it. Configure [post-start hooks](@/hook.md#hook-types) to automate setup (install deps, start dev servers).
## Next steps
diff --git a/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.md
index 7c02fe17e..c2a1e2735 100644
--- a/skills/worktrunk/reference/hook.md
+++ b/skills/worktrunk/reference/hook.md
@@ -16,7 +16,7 @@ Hooks are shell commands that run at key points in the worktree lifecycle — au
`pre-*` hooks block — failure aborts the operation. `post-*` hooks run in the background with output logged (use [`wt config state logs`](https://worktrunk.dev/config/#wt-config-state-logs) to find and manage log files). Use `-v` to see expanded command details for background hooks.
-The most common starting point is `post-start` — it runs background tasks (dev servers, file copying, builds) when creating a worktree.
+The most common starting point is `post-start` — it runs background tasks (dev servers, file copying, builds) without blocking worktree creation. Prefer `post-start` over `pre-start` unless a later step needs the work completed first.
| Hook | Purpose |
|------|---------|
@@ -298,17 +298,6 @@ Pipelines matter when there's a dependency chain — typically setup steps that
# Designing Effective Hooks
-## pre-start vs post-start
-
-Both run when creating a worktree. The difference:
-
-| Hook | Execution | Best for |
-|------|-----------|----------|
-| `pre-start` | Blocks until complete | Tasks the developer needs before working (dependency install) |
-| `post-start` | Background, parallel | Long-running tasks that don't block worktree creation |
-
-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. For finer control over execution order within `post-start`, see [Pipeline ordering](#pipeline-ordering).
-
## Copying untracked files
Git worktrees share the repository but not untracked files. [`wt step copy-ignored`](https://worktrunk.dev/step/#wt-step-copy-ignored) copies gitignored files between worktrees:
diff --git a/skills/worktrunk/reference/worktrunk.md b/skills/worktrunk/reference/worktrunk.md
index 2d43f4809..7ba962ed8 100644
--- a/skills/worktrunk/reference/worktrunk.md
+++ b/skills/worktrunk/reference/worktrunk.md
@@ -174,7 +174,7 @@ wt switch -x claude -c feature-b -- 'Fix the pagination bug'
wt switch -x claude -c feature-c -- 'Write tests for the API'
```
-The `-x` flag runs a command after switching; arguments after `--` are passed to it. Configure [post-start hooks](https://worktrunk.dev/hook/#pre-start-vs-post-start) to automate setup (install deps, start dev servers).
+The `-x` flag runs a command after switching; arguments after `--` are passed to it. Configure [post-start hooks](https://worktrunk.dev/hook/#hook-types) to automate setup (install deps, start dev servers).
## Next steps
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 5b2a0026b..5f8f5efc0 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -1157,7 +1157,7 @@ $ wt step push
`pre-*` hooks block — failure aborts the operation. `post-*` hooks run in the background with output logged (use [`wt config state logs`](@/config.md#wt-config-state-logs) to find and manage log files). Use `-v` to see expanded command details for background hooks.
-The most common starting point is `post-start` — it runs background tasks (dev servers, file copying, builds) when creating a worktree.
+The most common starting point is `post-start` — it runs background tasks (dev servers, file copying, builds) without blocking worktree creation. Prefer `post-start` over `pre-start` unless a later step needs the work completed first.
| Hook | Purpose |
|------|---------|
@@ -1439,17 +1439,6 @@ Pipelines matter when there's a dependency chain — typically setup steps that
# Designing Effective Hooks
-## pre-start vs post-start
-
-Both run when creating a worktree. The difference:
-
-| Hook | Execution | Best for |
-|------|-----------|----------|
-| `pre-start` | Blocks until complete | Tasks the developer needs before working (dependency install) |
-| `post-start` | Background, parallel | Long-running tasks that don't block worktree creation |
-
-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. For finer control over execution order within `post-start`, see [Pipeline ordering](#pipeline-ordering).
-
## Copying untracked files
Git worktrees share the repository but not untracked files. [`wt step copy-ignored`](@/step.md#wt-step-copy-ignored) copies gitignored files between worktrees: