Skip to content

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

docs: consolidate duplicated explanations and trim slop (#3494)

Maximilian Roos568b6de85f81
diff --git a/dev/config.example.toml b/dev/config.example.toml
index 6d4772b62..b22a62a25 100644
--- a/dev/config.example.toml
+++ b/dev/config.example.toml
@@ -221,7 +221,7 @@
# [step.copy-ignored]
# exclude = [] # Additional excludes (e.g., [".cache/", ".turbo/"])
#
-# Built-in excludes always apply: VCS metadata directories (`.bzr/`, `.hg/`, `.jj/`, `.pijul/`, `.sl/`, `.svn/`) and tool-state directories (`.conductor/`, `.entire/`, `.worktrees/`). User config and project config exclusions are combined.
+# Built-in excludes (VCS metadata and tool-state directories) always apply; the `wt step copy-ignored` docs (https://worktrunk.dev/step/#wt-step-copy-ignored) list them. User config and project config exclusions are combined.
#
# ### Aliases
#
@@ -378,14 +378,14 @@
#
# #### Appending to the prompt [experimental]
#
-# `template-append` adds to the prompt instead of replacing it. The value is rendered as its own minijinja template (same variables) and injected into the default templates' `{{ user_guidance }}` slot — a `<user-guidance>` block right after `<style>`. It applies to both commit and squash. Use it for personal preferences without restating the whole template:
+# `template-append` adds personal conventions to the commit and squash prompts without restating the whole template:
#
# [commit.generation]
# template-append = """
# - Explain the rationale in the body, not just the change
# """
#
-# The project config (https://worktrunk.dev/config/#project-configuration) has a `template-append` of its own; it renders into a separate `<project-guidance>` block right after `<user-guidance>`.
+# How the fragment renders, and the project-config counterpart: the LLM commits guide (https://worktrunk.dev/llm-commits/#appending-to-the-prompt).
#
# ## Hooks
#
diff --git a/dev/wt.example.toml b/dev/wt.example.toml
index 4091239b7..af1e8541b 100644
--- a/dev/wt.example.toml
+++ b/dev/wt.example.toml
@@ -29,7 +29,7 @@
#
# ## Commit-message append [experimental]
#
-# Project-wide commit-message conventions appended to the LLM commit and squash prompts inside a `<project-guidance>` block, after the main template's `<style>` section (and after any user `<user-guidance>`). Rendered as a minijinja (https://docs.rs/minijinja/) template with the same variables as the main commit template (`{{ branch }}`, `{{ git_diff }}`, etc.), so it can reference them directly. The first time the fragment changes, `wt` prompts the user to approve it — the same one-shot gate as project-defined hooks.
+# `template-append` adds project-wide conventions to the LLM commit and squash prompts, shared so every teammate's LLM sees the same style guide:
#
# [commit.generation]
# template-append = """
@@ -37,7 +37,7 @@
# - Reference the relevant issue ID in the body
# """
#
-# Only `template-append` is honored from the project file. The LLM command and the main prompt template stay in user config (https://worktrunk.dev/config/) — they describe per-developer environment (which CLI is installed, which agent the developer prefers). User config has a `[commit.generation] template-append` of its own; it renders into a separate `<user-guidance>` block immediately before this one.
+# The first time the fragment is used (and whenever it changes), `wt` prompts the user to approve it — the same one-shot gate as project-defined hooks. Only `template-append` is honored from the project file; the LLM command and the main prompt template stay in user config (https://worktrunk.dev/config/), since they describe per-developer environment (which CLI is installed, which agent the developer prefers). How the fragment renders: the LLM commits guide (https://worktrunk.dev/llm-commits/#appending-to-the-prompt).
#
# ## Copy-ignored excludes
#
@@ -46,7 +46,7 @@
# [step.copy-ignored]
# exclude = [".cache/", ".turbo/"]
#
-# Built-in excludes always apply: VCS metadata directories (`.bzr/`, `.hg/`, `.jj/`, `.pijul/`, `.sl/`, `.svn/`) and tool-state directories (`.conductor/`, `.entire/`, `.worktrees/`). User config and project config exclusions are combined.
+# Built-in excludes (VCS metadata and tool-state directories) always apply; the `wt step copy-ignored` docs (https://worktrunk.dev/step/#wt-step-copy-ignored) list them. User config and project config exclusions are combined.
#
# ## Aliases
#
diff --git a/docs/content/config.md b/docs/content/config.md
index c99f2c056..d041cef33 100644
--- a/docs/content/config.md
+++ b/docs/content/config.md
@@ -325,7 +325,7 @@ pager = "delta --paging=never" # Example: override git's core.pager for diff p
exclude = [] # Additional excludes (e.g., [".cache/", ".turbo/"])
```
-Built-in excludes always apply: VCS metadata directories (`.bzr/`, `.hg/`, `.jj/`, `.pijul/`, `.sl/`, `.svn/`) and tool-state directories (`.conductor/`, `.entire/`, `.worktrees/`). User config and project config exclusions are combined.
+Built-in excludes (VCS metadata and tool-state directories) always apply; [the `wt step copy-ignored` docs](@/step.md#wt-step-copy-ignored) list them. User config and project config exclusions are combined.
### Aliases
@@ -494,7 +494,7 @@ squash-template = """
<span class="badge-experimental"></span>
-`template-append` adds to the prompt instead of replacing it. The value is rendered as its own minijinja template (same variables) and injected into the default templates' `{{ user_guidance }}` slot — a `<user-guidance>` block right after `<style>`. It applies to both commit and squash. Use it for personal preferences without restating the whole template:
+`template-append` adds personal conventions to the commit and squash prompts without restating the whole template:
```toml
[commit.generation]
@@ -503,7 +503,7 @@ template-append = """
"""
```
-The [project config](@/config.md#project-configuration) has a `template-append` of its own; it renders into a separate `<project-guidance>` block right after `<user-guidance>`.
+How the fragment renders, and the project-config counterpart: [the LLM commits guide](@/llm-commits.md#appending-to-the-prompt).
## Hooks
@@ -549,7 +549,7 @@ hostname = "github.example.com" # Example: API host (GHE / self-hosted GitLab)
<span class="badge-experimental"></span>
-Project-wide commit-message conventions appended to the LLM commit and squash prompts inside a `<project-guidance>` block, after the main template's `<style>` section (and after any user `<user-guidance>`). Rendered as a [minijinja](https://docs.rs/minijinja/) template with the same variables as the main commit template (`{{ branch }}`, `{{ git_diff }}`, etc.), so it can reference them directly. The first time the fragment changes, `wt` prompts the user to approve it — the same one-shot gate as project-defined hooks.
+`template-append` adds project-wide conventions to the LLM commit and squash prompts, shared so every teammate's LLM sees the same style guide:
```toml
[commit.generation]
@@ -559,7 +559,7 @@ template-append = """
"""
```
-Only `template-append` is honored from the project file. The LLM command and the main prompt template stay in [user config](@/config.md) — they describe per-developer environment (which CLI is installed, which agent the developer prefers). User config has a `[commit.generation] template-append` of its own; it renders into a separate `<user-guidance>` block immediately before this one.
+The first time the fragment is used (and whenever it changes), `wt` prompts the user to approve it — the same one-shot gate as project-defined hooks. Only `template-append` is honored from the project file; the LLM command and the main prompt template stay in [user config](@/config.md), since they describe per-developer environment (which CLI is installed, which agent the developer prefers). How the fragment renders: [the LLM commits guide](@/llm-commits.md#appending-to-the-prompt).
## Copy-ignored excludes
@@ -570,7 +570,7 @@ Additional excludes for `wt step copy-ignored`:
exclude = [".cache/", ".turbo/"]
```
-Built-in excludes always apply: VCS metadata directories (`.bzr/`, `.hg/`, `.jj/`, `.pijul/`, `.sl/`, `.svn/`) and tool-state directories (`.conductor/`, `.entire/`, `.worktrees/`). User config and project config exclusions are combined.
+Built-in excludes (VCS metadata and tool-state directories) always apply; [the `wt step copy-ignored` docs](@/step.md#wt-step-copy-ignored) list them. User config and project config exclusions are combined.
## Aliases
@@ -1191,26 +1191,7 @@ CI status cache.
**Deprecated** — the CI status cache is now part of [`wt config state cache`](@/config.md#wt-config-state-cache). This subcommand still works but prints a deprecation notice.
-Caches GitHub/GitLab CI status for display in [`wt list`](@/list.md#ci-status).
-
-Requires `gh` (GitHub) or `glab` (GitLab) CLI, authenticated. Platform auto-detects from the remote URL; set `forge.platform = "github"` (or `"gitlab"`) in `.config/wt.toml` for SSH host aliases or self-hosted instances. For GitHub Enterprise or self-hosted GitLab, also set `forge.hostname`.
-
-Checks open PRs/MRs first, then branch pipelines for branches with upstream. Local-only branches (no remote tracking) show blank.
-
-Results cache for 30-60 seconds. Indicators dim when local changes haven't been pushed.
-
-### Status values
-
-| Status | Meaning |
-|--------|---------|
-| `passed` | All checks passed |
-| `running` | Checks in progress |
-| `failed` | Checks failed |
-| `conflicts` | PR has merge conflicts |
-| `no-ci` | No checks configured |
-| `error` | Fetch error (rate limit, network, auth) |
-
-See [`wt list` CI status](@/list.md#ci-status) for display symbols and colors.
+Status values, display symbols, and fetch behavior: [`wt list` CI status](@/list.md#ci-status).
Without a subcommand, runs `get` for the current branch. Use `clear` to reset cache for a branch or `clear --all` to reset all.
diff --git a/docs/content/extending.md b/docs/content/extending.md
index 772fac056..b3fa96983 100644
--- a/docs/content/extending.md
+++ b/docs/content/extending.md
@@ -27,17 +27,7 @@ Hooks and aliases live in the same TOML config and share the [template engine](@
## Hooks
-Ten hooks cover five lifecycle events:
-
-| Event | `pre-` (blocking) | `post-` (background) |
-|-------|-------------------|---------------------|
-| **switch** | `pre-switch` | `post-switch` |
-| **start** | `pre-start` | `post-start` |
-| **commit** | `pre-commit` | `post-commit` |
-| **merge** | `pre-merge` | `post-merge` |
-| **remove** | `pre-remove` | `post-remove` |
-
-`pre-*` hooks block: failure aborts the operation. `post-*` hooks run in the background.
+Ten hooks cover five lifecycle events — switch, start, commit, merge, remove — each with a blocking `pre-` variant (failure aborts the operation) and a background `post-` variant. [`wt hook`](@/hook.md#hook-types) maps each hook to its timing and typical uses.
```toml
[pre-start]
diff --git a/docs/content/faq.md b/docs/content/faq.md
index 0346f5119..d7f187728 100644
--- a/docs/content/faq.md
+++ b/docs/content/faq.md
@@ -99,12 +99,7 @@ Three verbosity levels. Each is a superset of the previous one.
At `-vv`, debug-level records (command lines, in-process spans, bounded subprocess preview) route to `trace.log` instead of stderr — so the terminal stays readable while the deep trace lands on disk. A one-line pointer on stderr shows where the files went.
-The `-vv` files have distinct audiences:
-
-- **`trace.log`** — the human trace (bounded ~1K lines, gistable): each command's start (`$ git status`) and finish (`✓ git status [wt] 12.3ms`, `✗` on failure), spans, and milestones.
-- **`trace.jsonl`** — the same records as one JSON object per line, for machines (`jq`, chrome://tracing). `wt config state logs profile` reads it.
-- **`subprocess.log`** — raw uncapped stdout/stderr of every subprocess `wt` spawns (multi-MB possible, e.g. full `git log -p` output). The deep-dive escape hatch.
-- **`diagnostic.md`** — markdown bug-report bundle that leads with the performance report (subprocess time by command type, slowest calls, repeated calls — the same rendering `wt config state logs profile` produces from `trace.jsonl`) and inlines `trace.log`. `wt` prints a `gh gist create` command pointing at it.
+The `-vv` files have distinct audiences: `trace.log` is the human trace (bounded, gistable), `trace.jsonl` the same records for machines, `subprocess.log` the raw uncapped subprocess output, and `diagnostic.md` a bug-report bundle. Each is described in [`wt config state logs`](@/config.md#wt-config-state-logs).
`RUST_LOG` overrides the flag baseline when set (`RUST_LOG=debug wt -v` lifts `-v` to debug-on-stderr).
@@ -198,8 +193,7 @@ Use `-D` to force-delete branches with unmerged changes. Use `--no-delete-branch
### Other cleanup
-- `wt remove` — in addition to the target worktree, runs a background internal sweep: deletes `.git/wt/trash/` entries older than 24 hours (eventual cleanup for directories orphaned when a previous background removal was interrupted), and terminates (`SIGTERM` then `SIGKILL`) `git fsmonitor--daemon` processes whose worktree no longer exists
-- `wt remove` — terminates the removed worktree's `git fsmonitor--daemon` process. Git starts this per-worktree filesystem-watch daemon when `core.fsmonitor=true`; once its worktree is gone it would leak. Removal sends `git fsmonitor--daemon stop`, then resolves that daemon's PID from its IPC socket and force-terminates it (SIGTERM, then SIGKILL) if it didn't exit. The signal only ever targets the daemon whose socket resolves to the worktree being removed.
+- `wt remove` — besides the target worktree, two cleanup mechanisms run. The removed worktree's own `git fsmonitor--daemon` (git's per-worktree filesystem watcher under `core.fsmonitor=true`, which would leak once its worktree is gone) is sent `git fsmonitor--daemon stop`, then force-terminated (`SIGTERM`, then `SIGKILL`) via the PID resolved from its IPC socket if it didn't exit. A background sweep then deletes `.git/wt/trash/` entries older than 24 hours (directories orphaned when a previous background removal was interrupted) and terminates fsmonitor daemons whose worktree no longer exists (orphans from `git worktree remove`, `rm -rf`, or a crashed `wt`)
- `wt config state clear` — removes all worktrunk data from `.git/` (config keys, caches, markers, hints, variables, logs, stale trash)
- `wt config shell install` — when migrating an integration to a new location, removes the worktrunk-managed file left at the old one: fish `conf.d/wt.fish` (now `functions/wt.fish`) and nushell wrappers stranded under `<config-dir>/vendor/autoload` (now `<data-dir>/vendor/autoload`)
- `wt config shell uninstall` — removes shell integration from rc files
diff --git a/docs/content/step.md b/docs/content/step.md
index 5ba08da6e..8f05a6078 100644
--- a/docs/content/step.md
+++ b/docs/content/step.md
@@ -375,7 +375,7 @@ copy = "wt step copy-ignored"
### What gets copied
-All gitignored files are copied by default, except for built-in excluded directories: VCS metadata (`.bzr/`, `.hg/`, `.jj/`, `.pijul/`, `.sl/`, `.svn/`) and tool-state (`.conductor/`, `.entire/`, `.worktrees/`). Tracked files are never touched.
+All gitignored files are copied by default, except for built-in excluded directories: VCS metadata (`.bzr/`, `.hg/`, `.jj/`, `.pijul/`, `.sl/`, `.svn/`), tool-state (`.conductor/`, `.entire/`, `.worktrees/`), and nested worktrees. Tracked files are never touched. Discovery handles nested `.gitignore` files, global excludes, and `.git/info/exclude`. Existing files in the destination are skipped, so re-running is safe; `--force` overwrites them.
To limit what gets copied further, create `.worktreeinclude` with gitignore-style patterns. Files must be **both** gitignored **and** in `.worktreeinclude`:
@@ -410,14 +410,6 @@ Without `.worktreeinclude`, the command is a no-op (it reports that nothing was
| Generated assets | Images, ML models, binaries too large for git |
| Environment files | `.env` (if not generated per-worktree) |
-### Features
-
-- Uses copy-on-write (reflink) when available for space-efficient copies
-- Handles nested `.gitignore` files, global excludes, and `.git/info/exclude`
-- Skips existing files by default (safe to re-run)
-- `--force` overwrites existing files in the destination
-- Always skips built-in excluded directories — VCS metadata (`.bzr/`, `.hg/`, `.jj/`, `.pijul/`, `.sl/`, `.svn/`) and tool-state (`.conductor/`, `.entire/`, `.worktrees/`) — and nested worktrees
-
### Performance
Reflink copies share disk blocks until modified — no data is actually copied. For a 14GB `target/` directory:
@@ -461,7 +453,7 @@ Virtual environments contain absolute paths and can't be copied. Use `uv sync` i
The `.worktreeinclude` pattern is shared with [Claude Code on desktop](https://code.claude.com/docs/en/desktop), which copies matching files when creating worktrees. Differences:
- worktrunk copies all gitignored files by default; Claude Code requires `.worktreeinclude`. Pass `--require-include` to match Claude Code (copy nothing without `.worktreeinclude`)
-- worktrunk uses copy-on-write for large directories like `target/` — potentially 30x faster on macOS, 6x on Linux
+- worktrunk uses copy-on-write for large directories like `target/` (see Performance above)
- worktrunk runs as a configurable hook in the worktree lifecycle
### Command reference
@@ -570,8 +562,6 @@ List the available template variables with `-v` (alongside the expansion, on std
feature/auth-oauth2
{% end %}
-Note: This command is experimental and may change in future versions.
-
### Command reference
{% terminal() %}
@@ -649,8 +639,6 @@ Pull updates in worktrees with upstreams (skips others):
{{ terminal(cmd="git fetch --prune && wt step for-each -- sh -c '[ __WT_QUOT__$(git rev-parse @{u} 2>/dev/null)__WT_QUOT__ ] || exit 0; git pull --autostash'") }}
-Note: This command is experimental and may change in future versions.
-
### Command reference
{% terminal() %}
@@ -915,8 +903,6 @@ refuses), unless `--commit` is passed.
- **Target blocked** (without `--clobber`) — use `--clobber` to backup blocker
- **Detached HEAD** — no branch to compute expected path
-Note: This command is experimental and may change in future versions.
-
### Command reference
{% terminal() %}
@@ -1017,8 +1003,6 @@ Run a dev server, torn down automatically when the worktree goes away:
server = "wt step tether -- npm run dev -- --port {{ branch | hash_port }}"
```
-Note: This command is experimental and may change in future versions.
-
### Command reference
{% terminal() %}
diff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.md
index b7ac9efa3..f304ec7f5 100644
--- a/docs/content/tips-patterns.md
+++ b/docs/content/tips-patterns.md
@@ -225,7 +225,7 @@ Structured output for dashboards, statuslines, and scripts. See [`wt list`](@/li
## Reuse `default-branch`
-Worktrunk maintains useful state. Default branch [detection](@/config.md#wt-config-state-default-branch), for instance, means scripts work on any repo — no need to hardcode `main` or `master`:
+Default branch [detection](@/config.md#wt-config-state-default-branch) means scripts work on any repo — no need to hardcode `main` or `master`:
{{ terminal(cmd="git rebase $(wt config state default-branch)") }}
@@ -395,8 +395,6 @@ clean-derived = """
"""
```
-This precisely targets only the DerivedData for the removed worktree, leaving caches for other worktrees and the main repository intact.
-
## Subdomain routing with Caddy
<!-- Hand-tested 2026-03-07 -->
diff --git a/docs/static/.well-known/agent-skills/index.json b/docs/static/.well-known/agent-skills/index.json
index b879b4362..c5645fa75 100644
--- a/docs/static/.well-known/agent-skills/index.json
+++ b/docs/static/.well-known/agent-skills/index.json
@@ -6,7 +6,7 @@
"type": "skill-md",
"description": "Guidance for Worktrunk (the `wt` CLI) — git worktree management, hooks, and config. Load when editing .config/wt.toml or ~/.config/worktrunk/config.toml; adding, modifying, or debugging hooks (post-merge, post-start, pre-commit, pre-merge, post-switch, etc.); configuring commit message generation or command aliases; or troubleshooting wt behavior. Also answers general worktrunk/wt questions.",
"url": "./worktrunk/SKILL.md",
- "digest": "sha256:2a41c53d60232fd8d8a4973474f63dde4b5339738f2a728eac309a0162947f35"
+ "digest": "sha256:0a217b6b0a30588569bf97d5ad828d07aaf8241c67e2855ef461233098ec8c53"
}
]
}
diff --git a/plugins/worktrunk/skills/worktrunk/SKILL.md b/plugins/worktrunk/skills/worktrunk/SKILL.md
index ab68bcf99..3c538ccf4 100644
--- a/plugins/worktrunk/skills/worktrunk/SKILL.md
+++ b/plugins/worktrunk/skills/worktrunk/SKILL.md
@@ -9,7 +9,7 @@ compatibility: Requires the `wt` CLI (https://worktrunk.dev)
Help users work with Worktrunk, a CLI tool for managing git worktrees.
-## Available Documentation
+## Available documentation
Reference files are synced from [worktrunk.dev](https://worktrunk.dev) documentation:
@@ -24,224 +24,77 @@ Reference files are synced from [worktrunk.dev](https://worktrunk.dev) documenta
For command-specific options, run `wt <command> --help`. For configuration, follow the workflows below.
-## Two Types of Configuration
-
-Worktrunk uses two separate config files with different scopes and behaviors:
-
-### User Config (`~/.config/worktrunk/config.toml`)
-- **Scope**: Personal preferences for the individual developer
-- **Location**: `~/.config/worktrunk/config.toml` (never checked into git)
-- **Contains**: LLM integration, worktree path templates, command settings, user hooks, approved commands
-- **Permission model**: Always propose changes and get consent before editing
-- **See**: `reference/config.md` for detailed guidance
-
-### Project Config (`.config/wt.toml`)
-- **Scope**: Team-wide automation shared by all developers
-- **Location**: `<repo>/.config/wt.toml` (checked into git)
-- **Contains**: Hooks for worktree lifecycle (pre-start, pre-merge, etc.)
-- **Permission model**: Proactive (create directly, changes are reversible via git)
-- **See**: `reference/hook.md` for detailed guidance
-
-## Determining Which Config to Use
-
-When a user asks for configuration help, determine which type based on:
+## Two types of configuration
-**User config indicators**:
-- "set up LLM" or "configure commit generation"
-- "change where worktrees are created"
-- "customize commit message templates"
-- Affects only their environment
+Worktrunk uses two config files with different scopes and permission models:
-**Project config indicators**:
-- "set up hooks for this project"
-- "automate npm install"
-- "run tests before merge"
-- Affects the entire team
+**User config** (`~/.config/worktrunk/config.toml`, never checked into git) holds personal preferences: LLM integration, worktree path templates, command settings, user hooks. Treat it conservatively — propose changes and get consent before editing, never install tools on the user's behalf, and preserve the file's existing structure and comments. See `reference/config.md`.
-**Both configs may be needed**: For example, setting up commit message generation requires user config, but automating quality checks requires project config.
-
-## Core Workflows
+**Project config** (`<repo>/.config/wt.toml`, checked into git) holds team-wide automation: hooks for the worktree lifecycle (pre-start, pre-merge, etc.). Edit proactively — changes are versioned and reversible via git. Comment why each hook exists, and warn the user before adding destructive commands (`rm -rf`, `DROP TABLE`), network fetches piped to shells, or `sudo`. See `reference/hook.md`.
-### Setting Up Commit Message Generation (User Config)
+Some requests span both: commit-message generation is user config, while the team's quality checks are project config.
-Most common request. See `reference/llm-commits.md` for supported tools and exact command syntax.
+## Core workflows
-1. **Detect available tools**
- ```bash
- which claude codex llm aichat 2>/dev/null
- ```
-
-2. **If none installed, recommend Claude Code** (already available in Claude Code sessions)
+### Setting up commit message generation (user config)
-3. **Propose config change** — Get the exact command from `reference/llm-commits.md`
- ```toml
- [commit.generation]
- command = "..." # see reference/llm-commits.md for tool-specific commands
- ```
- Ask: "Should I add this to your config?"
-
-4. **After approval, apply**
- - Check if config exists: `wt config show`
- - If not, guide through `wt config create`
- - Read, modify, write preserving structure
+Detect which tools are installed (`which claude codex llm aichat`); if none, recommend Claude Code. Take the exact command for the chosen tool from `reference/llm-commits.md`, propose the `[commit.generation]` change, and apply it after approval (`wt config create` first if no config exists). To verify, `wt step commit --dry-run` renders the prompt, runs the LLM, and prints the message without committing.
-5. **Suggest testing**
- ```bash
- wt step commit --show-prompt | head # verify prompt builds
- wt merge # in a repo with uncommitted changes
- ```
+### Configuring project hooks
-### Setting Up Project Hooks (Project Config)
+Pick the hook type by when the command should run and whether it may block (10 types: 5 events × pre/post — full reference in `reference/hook.md`):
-Common request for workflow automation. Follow discovery process:
+- Dependencies and env files a later step needs → `pre-start` (blocks creation)
+- Dev servers, long builds, cache copying → `post-start` (background)
+- Formatters, linters, type checks → `pre-commit`
+- Tests that must pass before merging → `pre-merge`
+- CI triggers, notifications → `post-commit`
+- Deployment → `post-merge`
+- Setup before branch resolution / terminal-IDE updates → `pre-switch` / `post-switch`
+- Cleanup before/after removal (save artifacts; stop servers, remove containers) → `pre-remove` / `post-remove`
-1. **Detect project type**
- ```bash
- ls package.json Cargo.toml pyproject.toml
- ```
+Derive the commands from the project itself (`package.json` scripts, `Cargo.toml`, `pyproject.toml`) and verify they run before adding them.
-2. **Identify available commands**
- - For npm: Read `package.json` scripts
- - For Rust: Common cargo commands
- - For Python: Check pyproject.toml
+When a new hook must wait for an existing one, convert the entry to a pipeline; independent commands in a named table run concurrently:
-3. **Design appropriate hooks** (10 hook types: 5 events × pre/post — see `reference/hook.md`)
- - Dependencies (fast, must complete) → `pre-start`
- - Tests/linting (must pass) → `pre-commit` or `pre-merge`
- - Long builds, dev servers → `post-start`
- - Setup before branch resolution → `pre-switch`
- - Terminal/IDE updates → `post-switch`
- - After-commit triggers (CI, notifications) → `post-commit`
- - Deployment → `post-merge`
- - Cleanup before removal → `pre-remove`
- - Cleanup after removal (stop servers, remove containers) → `post-remove`
+```toml
+# Pipeline: install completes before migrate starts
+[[pre-start]]
+install = "npm install"
-4. **Validate commands work**
- ```bash
- npm run lint # verify exists
- which cargo # verify tool exists
- ```
+[[pre-start]]
+migrate = "npm run db:migrate"
-5. **Create `.config/wt.toml`**
- ```toml
- # Install dependencies when creating worktrees
- pre-start = "npm install"
-
- # Validate code quality before committing
- [pre-commit]
- lint = "npm run lint"
- typecheck = "npm run typecheck"
-
- # Run tests before merging
- pre-merge = "npm test"
- ```
-
-6. **Add comments explaining choices**
-
-7. **Suggest testing**
- ```bash
- wt switch --create test-hooks
- ```
-
-**See `reference/hook.md` for complete details.**
-
-### Adding Hooks to Existing Config
-
-When users want to add automation to an existing project:
-
-1. **Read existing config**: `cat .config/wt.toml`
-
-2. **Determine hook type** - When should this run? (10 types: 5 events × pre/post)
- - Creating worktree (blocking) → `pre-start`
- - Creating worktree (background) → `post-start`
- - Before/after a switch → `pre-switch` / `post-switch`
- - Before committing → `pre-commit`
- - After committing (CI, notifications) → `post-commit`
- - Before merging → `pre-merge`
- - After merging → `post-merge`
- - Before/after removal → `pre-remove` / `post-remove`
-
-3. **Handle format conversion if needed**
-
- Single command to a pipeline of dependent steps:
- ```toml
- # Before
- pre-start = "npm install"
-
- # After (adding db:migrate, which needs install to finish first)
- [[pre-start]]
- install = "npm install"
-
- [[pre-start]]
- migrate = "npm run db:migrate"
- ```
-
- For independent commands, a named table runs them concurrently:
- ```toml
- [pre-start]
- install = "npm install"
- env = "cp .env.example .env"
- ```
-
-4. **Preserve existing structure and comments**
-
-### Validation Before Adding Commands
-
-Before adding hooks, validate:
-
-```bash
-# Verify command exists
-which npm
-which cargo
-
-# For npm, verify script exists
-npm run lint --dry-run
-
-# For shell commands, check syntax
-bash -n -c "if [ true ]; then echo ok; fi"
+# Concurrent: independent commands in one table
+[pre-start]
+install = "npm install"
+env = "cp .env.example .env"
```
-**Dangerous patterns** — Warn users before creating hooks with:
-- Destructive commands: `rm -rf`, `DROP TABLE`
-- External dependencies: `curl http://...`
-- Privilege escalation: `sudo`
-
-## Permission Models
-
-### User Config: Conservative
-- **Never edit without consent** - Always show proposed change and wait for approval
-- **Never install tools** - Provide commands for users to run themselves
-- **Preserve structure** - Keep existing comments and organization
-- **Validate first** - Ensure TOML is valid before writing
+Test with `wt switch --create test-hooks`.
-### Project Config: Proactive
-- **Create directly** - Changes are versioned, easily reversible
-- **Validate commands** - Check commands exist before adding
-- **Explain choices** - Add comments documenting why hooks exist
-- **Warn on danger** - Flag destructive operations before adding
+## Common tasks reference
-## Common Tasks Reference
-
-### User Config Tasks
+### User config tasks
- Set up commit message generation → `reference/llm-commits.md`
- Customize worktree paths → `reference/config.md#worktree-path-template`
- Custom commit templates → `reference/llm-commits.md#prompt-templates`
- Configure command defaults → `reference/config.md#command-config`
- Set up personal hooks → `reference/config.md#hooks`
-### Project Config Tasks
+### Project config tasks
- Set up hooks for new project → `reference/hook.md`
- Add hook to existing config → `reference/hook.md#hook-forms`
- Use template variables → `reference/hook.md#template-variables`
- Add dev server URL to list → `reference/config.md#dev-server-url`
-### Aliases & Multi-Worktree Tasks
+### Aliases & multi-worktree tasks
- Create a `wt` alias → `reference/extending.md#aliases`
- Run a command in every worktree → `reference/step.md#wt-step-for-each`
- Rebase every worktree (up-style) → `reference/extending.md#recipe-rebase-every-worktree-onto-its-upstream`
- Defer a template variable to a nested `wt` command → `reference/extending.md#deferring-expansion-to-a-nested-wt-command`
-## Key Commands
+## Key commands
```bash
# View all configuration
@@ -254,18 +107,7 @@ wt config create
wt config --help
```
-## Loading Additional Documentation
-
-Load **reference files** for detailed configuration, hook specifications, and troubleshooting.
-
-Find specific sections with grep:
-```bash
-grep -A 20 "## Setup" reference/llm-commits.md
-grep -A 30 "### pre-start" reference/hook.md
-grep -A 20 "## Warning Messages" reference/shell-integration.md
-```
-
-## Hook Approvals in Non-Interactive Sessions
+## Hook approvals in non-interactive sessions
Worktrunk never runs a project's hooks or aliases until the user has explicitly approved them. The commands in `.config/wt.toml` are arbitrary shell code shipped in a repository the user may have just cloned, so on first run Worktrunk shows each command and waits for the user to approve it — an untrusted `.config/wt.toml` cannot silently execute anything. Approvals are stored per-project in `~/.config/worktrunk/approvals.toml` and re-prompted whenever a command template changes, so a hook can't be swapped for a different command after it was approved.
@@ -285,7 +127,7 @@ The resolution is for the user to make the trust decision themselves:
**When invoked as an agent, stop and escalate to the user.** Approving a project's hooks is a security decision about whether this repository should be trusted to run arbitrary commands on the user's machine — that decision belongs to the user, not the agent. Tell the user to run `wt config approvals add` and let them review the commands. Do not run `--yes` on the user's behalf: it skips the approval gate for that invocation, so reaching for it to unblock a command defeats the protection. `--yes` exists for CI/CD pipelines that already control their own hook contents; it is not a shortcut for an interactive agent to silence an approval prompt.
-## Advanced: Agent Handoffs
+## Advanced: agent handoffs
When the user requests spawning a worktree with an agent in a background session ("spawn a worktree for...", "hand off to another agent"), use the appropriate pattern for their terminal multiplexer. Substitute `<agent-cli>` with the CLI you are running as: `claude` for Claude Code, `'opencode run'` for OpenCode.
diff --git a/plugins/worktrunk/skills/worktrunk/reference/config.md b/plugins/worktrunk/skills/worktrunk/reference/config.md
index d8751415e..96a21dd55 100644
--- a/plugins/worktrunk/skills/worktrunk/reference/config.md
+++ b/plugins/worktrunk/skills/worktrunk/reference/config.md
@@ -322,7 +322,7 @@ pager = "delta --paging=never" # Example: override git's core.pager for diff p
exclude = [] # Additional excludes (e.g., [".cache/", ".turbo/"])
```
-Built-in excludes always apply: VCS metadata directories (`.bzr/`, `.hg/`, `.jj/`, `.pijul/`, `.sl/`, `.svn/`) and tool-state directories (`.conductor/`, `.entire/`, `.worktrees/`). User config and project config exclusions are combined.
+Built-in excludes (VCS metadata and tool-state directories) always apply; [the `wt step copy-ignored` docs](https://worktrunk.dev/step/#wt-step-copy-ignored) list them. User config and project config exclusions are combined.
### Aliases
@@ -489,7 +489,7 @@ squash-template = """
#### Appending to the prompt [experimental]
-`template-append` adds to the prompt instead of replacing it. The value is rendered as its own minijinja template (same variables) and injected into the default templates' `{{ user_guidance }}` slot — a `<user-guidance>` block right after `<style>`. It applies to both commit and squash. Use it for personal preferences without restating the whole template:
+`template-append` adds personal conventions to the commit and squash prompts without restating the whole template:
```toml
[commit.generation]
@@ -498,7 +498,7 @@ template-append = """
"""
```
-The [project config](https://worktrunk.dev/config/#project-configuration) has a `template-append` of its own; it renders into a separate `<project-guidance>` block right after `<user-guidance>`.
+How the fragment renders, and the project-config counterpart: [the LLM commits guide](https://worktrunk.dev/llm-commits/#appending-to-the-prompt).
## Hooks
@@ -542,7 +542,7 @@ hostname = "github.example.com" # Example: API host (GHE / self-hosted GitLab)
## Commit-message append [experimental]
-Project-wide commit-message conventions appended to the LLM commit and squash prompts inside a `<project-guidance>` block, after the main template's `<style>` section (and after any user `<user-guidance>`). Rendered as a [minijinja](https://docs.rs/minijinja/) template with the same variables as the main commit template (`{{ branch }}`, `{{ git_diff }}`, etc.), so it can reference them directly. The first time the fragment changes, `wt` prompts the user to approve it — the same one-shot gate as project-defined hooks.
+`template-append` adds project-wide conventions to the LLM commit and squash prompts, shared so every teammate's LLM sees the same style guide:
```toml
[commit.generation]
@@ -552,7 +552,7 @@ template-append = """
"""
```
-Only `template-append` is honored from the project file. The LLM command and the main prompt template stay in [user config](https://worktrunk.dev/config/) — they describe per-developer environment (which CLI is installed, which agent the developer prefers). User config has a `[commit.generation] template-append` of its own; it renders into a separate `<user-guidance>` block immediately before this one.
+The first time the fragment is used (and whenever it changes), `wt` prompts the user to approve it — the same one-shot gate as project-defined hooks. Only `template-append` is honored from the project file; the LLM command and the main prompt template stay in [user config](https://worktrunk.dev/config/), since they describe per-developer environment (which CLI is installed, which agent the developer prefers). How the fragment renders: [the LLM commits guide](https://worktrunk.dev/llm-commits/#appending-to-the-prompt).
## Copy-ignored excludes
@@ -563,7 +563,7 @@ Additional excludes for `wt step copy-ignored`:
exclude = [".cache/", ".turbo/"]
```
-Built-in excludes always apply: VCS metadata directories (`.bzr/`, `.hg/`, `.jj/`, `.pijul/`, `.sl/`, `.svn/`) and tool-state directories (`.conductor/`, `.entire/`, `.worktrees/`). User config and project config exclusions are combined.
+Built-in excludes (VCS metadata and tool-state directories) always apply; [the `wt step copy-ignored` docs](https://worktrunk.dev/step/#wt-step-copy-ignored) list them. User config and project config exclusions are combined.
## Aliases
@@ -1240,26 +1240,7 @@ CI status cache.
**Deprecated** — the CI status cache is now part of [`wt config state cache`](https://worktrunk.dev/config/#wt-config-state-cache). This subcommand still works but prints a deprecation notice.
-Caches GitHub/GitLab CI status for display in [`wt list`](https://worktrunk.dev/list/#ci-status).
-
-Requires `gh` (GitHub) or `glab` (GitLab) CLI, authenticated. Platform auto-detects from the remote URL; set `forge.platform = "github"` (or `"gitlab"`) in `.config/wt.toml` for SSH host aliases or self-hosted instances. For GitHub Enterprise or self-hosted GitLab, also set `forge.hostname`.
-
-Checks open PRs/MRs first, then branch pipelines for branches with upstream. Local-only branches (no remote tracking) show blank.
-
-Results cache for 30-60 seconds. Indicators dim when local changes haven't been pushed.
-
-### Status values
-
-| Status | Meaning |
-|--------|---------|
-| `passed` | All checks passed |
-| `running` | Checks in progress |
-| `failed` | Checks failed |
-| `conflicts` | PR has merge conflicts |
-| `no-ci` | No checks configured |
-| `error` | Fetch error (rate limit, network, auth) |
-
-See [`wt list` CI status](https://worktrunk.dev/list/#ci-status) for display symbols and colors.
+Status values, display symbols, and fetch behavior: [`wt list` CI status](https://worktrunk.dev/list/#ci-status).
Without a subcommand, runs `get` for the current branch. Use `clear` to reset cache for a branch or `clear --all` to reset all.
diff --git a/plugins/worktrunk/skills/worktrunk/reference/extending.md b/plugins/worktrunk/skills/worktrunk/reference/extending.md
index 091080eed..61f91e592 100644
--- a/plugins/worktrunk/skills/worktrunk/reference/extending.md
+++ b/plugins/worktrunk/skills/worktrunk/reference/extending.md
@@ -20,17 +20,7 @@ Hooks and aliases live in the same TOML config and share the [template engine](h
## Hooks
-Ten hooks cover five lifecycle events:
-
-| Event | `pre-` (blocking) | `post-` (background) |
-|-------|-------------------|---------------------|
-| **switch** | `pre-switch` | `post-switch` |
-| **start** | `pre-start` | `post-start` |
-| **commit** | `pre-commit` | `post-commit` |
-| **merge** | `pre-merge` | `post-merge` |
-| **remove** | `pre-remove` | `post-remove` |
-
-`pre-*` hooks block: failure aborts the operation. `post-*` hooks run in the background.
+Ten hooks cover five lifecycle events — switch, start, commit, merge, remove — each with a blocking `pre-` variant (failure aborts the operation) and a background `post-` variant. [`wt hook`](https://worktrunk.dev/hook/#hook-types) maps each hook to its timing and typical uses.
```toml
[pre-start]
diff --git a/plugins/worktrunk/skills/worktrunk/reference/faq.md b/plugins/worktrunk/skills/worktrunk/reference/faq.md
index 070caf402..aa412f05a 100644
--- a/plugins/worktrunk/skills/worktrunk/reference/faq.md
+++ b/plugins/worktrunk/skills/worktrunk/reference/faq.md
@@ -92,12 +92,7 @@ Three verbosity levels. Each is a superset of the previous one.
At `-vv`, debug-level records (command lines, in-process spans, bounded subprocess preview) route to `trace.log` instead of stderr — so the terminal stays readable while the deep trace lands on disk. A one-line pointer on stderr shows where the files went.
-The `-vv` files have distinct audiences:
-
-- **`trace.log`** — the human trace (bounded ~1K lines, gistable): each command's start (`$ git status`) and finish (`✓ git status [wt] 12.3ms`, `✗` on failure), spans, and milestones.
-- **`trace.jsonl`** — the same records as one JSON object per line, for machines (`jq`, chrome://tracing). `wt config state logs profile` reads it.
-- **`subprocess.log`** — raw uncapped stdout/stderr of every subprocess `wt` spawns (multi-MB possible, e.g. full `git log -p` output). The deep-dive escape hatch.
-- **`diagnostic.md`** — markdown bug-report bundle that leads with the performance report (subprocess time by command type, slowest calls, repeated calls — the same rendering `wt config state logs profile` produces from `trace.jsonl`) and inlines `trace.log`. `wt` prints a `gh gist create` command pointing at it.
+The `-vv` files have distinct audiences: `trace.log` is the human trace (bounded, gistable), `trace.jsonl` the same records for machines, `subprocess.log` the raw uncapped subprocess output, and `diagnostic.md` a bug-report bundle. Each is described in [`wt config state logs`](https://worktrunk.dev/config/#wt-config-state-logs).
`RUST_LOG` overrides the flag baseline when set (`RUST_LOG=debug wt -v` lifts `-v` to debug-on-stderr).
@@ -193,8 +188,7 @@ Use `-D` to force-delete branches with unmerged changes. Use `--no-delete-branch
### Other cleanup
-- `wt remove` — in addition to the target worktree, runs a background internal sweep: deletes `.git/wt/trash/` entries older than 24 hours (eventual cleanup for directories orphaned when a previous background removal was interrupted), and terminates (`SIGTERM` then `SIGKILL`) `git fsmonitor--daemon` processes whose worktree no longer exists
-- `wt remove` — terminates the removed worktree's `git fsmonitor--daemon` process. Git starts this per-worktree filesystem-watch daemon when `core.fsmonitor=true`; once its worktree is gone it would leak. Removal sends `git fsmonitor--daemon stop`, then resolves that daemon's PID from its IPC socket and force-terminates it (SIGTERM, then SIGKILL) if it didn't exit. The signal only ever targets the daemon whose socket resolves to the worktree being removed.
+- `wt remove` — besides the target worktree, two cleanup mechanisms run. The removed worktree's own `git fsmonitor--daemon` (git's per-worktree filesystem watcher under `core.fsmonitor=true`, which would leak once its worktree is gone) is sent `git fsmonitor--daemon stop`, then force-terminated (`SIGTERM`, then `SIGKILL`) via the PID resolved from its IPC socket if it didn't exit. A background sweep then deletes `.git/wt/trash/` entries older than 24 hours (directories orphaned when a previous background removal was interrupted) and terminates fsmonitor daemons whose worktree no longer exists (orphans from `git worktree remove`, `rm -rf`, or a crashed `wt`)
- `wt config state clear` — removes all worktrunk data from `.git/` (config keys, caches, markers, hints, variables, logs, stale trash)
- `wt config shell install` — when migrating an integration to a new location, removes the worktrunk-managed file left at the old one: fish `conf.d/wt.fish` (now `functions/wt.fish`) and nushell wrappers stranded under `<config-dir>/vendor/autoload` (now `<data-dir>/vendor/autoload`)
- `wt config shell uninstall` — removes shell integration from rc files
diff --git a/plugins/worktrunk/skills/worktrunk/reference/shell-integration.md b/plugins/worktrunk/skills/worktrunk/reference/shell-integration.md
index b7039915e..9e1e51031 100644
--- a/plugins/worktrunk/skills/worktrunk/reference/shell-integration.md
+++ b/plugins/worktrunk/skills/worktrunk/reference/shell-integration.md
@@ -8,18 +8,13 @@ Subprocesses cannot change the parent shell's current directory. When
`wt switch feature` runs, the `wt` binary runs as a child process and cannot
`cd` the terminal.
-Worktrunk solves this with **split directive file passing**:
-
-1. Shell wrapper creates two temp files via `mktemp` (one for cd, one for exec)
-2. Shell sets `WORKTRUNK_DIRECTIVE_CD_FILE` and `WORKTRUNK_DIRECTIVE_EXEC_FILE`
-3. `wt` binary writes a raw path to the CD file (no shell escaping needed)
-4. `wt` writes shell commands to the EXEC file (only for `--execute`)
-5. Shell reads the CD file with `cd -- "$(< file)"` — no shell parsing
-6. Shell sources the EXEC file if non-empty
-7. Shell removes both temp files
-
-The split design eliminates shell injection from cd directives — the CD file
-holds a raw path that is never parsed as shell.
+Worktrunk solves this with **split directive file passing**: the shell wrapper
+creates two temp files, `wt` writes a raw path to one (cd) and shell commands
+to the other (`--execute` payloads), and the wrapper applies both after `wt`
+exits. The split design eliminates shell injection from cd directives — the CD
+file holds a raw path that is never parsed as shell. The wrapper's steps and a
+simplified implementation: [How the Shell Wrapper
+Works](#how-the-shell-wrapper-works).
## Installation
diff --git a/plugins/worktrunk/skills/worktrunk/reference/step.md b/plugins/worktrunk/skills/worktrunk/reference/step.md
index 98772bfb3..85d72b08e 100644
--- a/plugins/worktrunk/skills/worktrunk/reference/step.md
+++ b/plugins/worktrunk/skills/worktrunk/reference/step.md
@@ -386,7 +386,7 @@ copy = "wt step copy-ignored"
### What gets copied
-All gitignored files are copied by default, except for built-in excluded directories: VCS metadata (`.bzr/`, `.hg/`, `.jj/`, `.pijul/`, `.sl/`, `.svn/`) and tool-state (`.conductor/`, `.entire/`, `.worktrees/`). Tracked files are never touched.
+All gitignored files are copied by default, except for built-in excluded directories: VCS metadata (`.bzr/`, `.hg/`, `.jj/`, `.pijul/`, `.sl/`, `.svn/`), tool-state (`.conductor/`, `.entire/`, `.worktrees/`), and nested worktrees. Tracked files are never touched. Discovery handles nested `.gitignore` files, global excludes, and `.git/info/exclude`. Existing files in the destination are skipped, so re-running is safe; `--force` overwrites them.
To limit what gets copied further, create `.worktreeinclude` with gitignore-style patterns. Files must be **both** gitignored **and** in `.worktreeinclude`:
@@ -421,14 +421,6 @@ Without `.worktreeinclude`, the command is a no-op (it reports that nothing was
| Generated assets | Images, ML models, binaries too large for git |
| Environment files | `.env` (if not generated per-worktree) |
-### Features
-
-- Uses copy-on-write (reflink) when available for space-efficient copies
-- Handles nested `.gitignore` files, global excludes, and `.git/info/exclude`
-- Skips existing files by default (safe to re-run)
-- `--force` overwrites existing files in the destination
-- Always skips built-in excluded directories — VCS metadata (`.bzr/`, `.hg/`, `.jj/`, `.pijul/`, `.sl/`, `.svn/`) and tool-state (`.conductor/`, `.entire/`, `.worktrees/`) — and nested worktrees
-
### Performance
Reflink copies share disk blocks until modified — no data is actually copied. For a 14GB `target/` directory:
@@ -472,7 +464,7 @@ Virtual environments contain absolute paths and can't be copied. Use `uv sync` i
The `.worktreeinclude` pattern is shared with [Claude Code on desktop](https://code.claude.com/docs/en/desktop), which copies matching files when creating worktrees. Differences:
- worktrunk copies all gitignored files by default; Claude Code requires `.worktreeinclude`. Pass `--require-include` to match Claude Code (copy nothing without `.worktreeinclude`)
-- worktrunk uses copy-on-write for large directories like `target/` — potentially 30x faster on macOS, 6x on Linux
+- worktrunk uses copy-on-write for large directories like `target/` (see Performance above)
- worktrunk runs as a configurable hook in the worktree lifecycle
### Command reference
@@ -587,8 +579,6 @@ $ wt step eval -v '{{ branch }}'
feature/auth-oauth2
```
-Note: This command is experimental and may change in future versions.
-
### Command reference
```
@@ -676,8 +666,6 @@ Pull updates in worktrees with upstreams (skips others):
$ git fetch --prune && wt step for-each -- sh -c '[ "$(git rev-parse @{u} 2>/dev/null)" ] || exit 0; git pull --autostash'
```
-Note: This command is experimental and may change in future versions.
-
### Command reference
```
@@ -960,8 +948,6 @@ refuses), unless `--commit` is passed.
- **Target blocked** (without `--clobber`) — use `--clobber` to backup blocker
- **Detached HEAD** — no branch to compute expected path
-Note: This command is experimental and may change in future versions.
-
### Command reference
```
@@ -1068,8 +1054,6 @@ Run a dev server, torn down automatically when the worktree goes away:
server = "wt step tether -- npm run dev -- --port {{ branch | hash_port }}"
```
-Note: This command is experimental and may change in future versions.
-
### Command reference
```
diff --git a/plugins/worktrunk/skills/worktrunk/reference/tips-patterns.md b/plugins/worktrunk/skills/worktrunk/reference/tips-patterns.md
index 80e0780dd..5390975a6 100644
--- a/plugins/worktrunk/skills/worktrunk/reference/tips-patterns.md
+++ b/plugins/worktrunk/skills/worktrunk/reference/tips-patterns.md
@@ -228,7 +228,7 @@ Structured output for dashboards, statuslines, and scripts. See [`wt list`](http
## Reuse `default-branch`
-Worktrunk maintains useful state. Default branch [detection](https://worktrunk.dev/config/#wt-config-state-default-branch), for instance, means scripts work on any repo — no need to hardcode `main` or `master`:
+Default branch [detection](https://worktrunk.dev/config/#wt-config-state-default-branch) means scripts work on any repo — no need to hardcode `main` or `master`:
```bash
git rebase $(wt config state default-branch)
@@ -412,8 +412,6 @@ clean-derived = """
"""
```
-This precisely targets only the DerivedData for the removed worktree, leaving caches for other worktrees and the main repository intact.
-
## Subdomain routing with Caddy
<!-- Hand-tested 2026-03-07 -->
diff --git a/plugins/worktrunk/skills/worktrunk/reference/troubleshooting.md b/plugins/worktrunk/skills/worktrunk/reference/troubleshooting.md
index 6b30ab3b5..bbb015973 100644
--- a/plugins/worktrunk/skills/worktrunk/reference/troubleshooting.md
+++ b/plugins/worktrunk/skills/worktrunk/reference/troubleshooting.md
@@ -115,9 +115,7 @@ for pid in $(pgrep -f 'git fsmonitor--daemon'); do
done
```
-Sockets listed as bare `fsmonitor--daemon.ipc` (no resolved path) belong to deleted worktrees. `wt remove` reaps these as part of its internal sweep: after the primary removal output, it sends `SIGTERM` (then `SIGKILL` after a short bounded wait) to every `git fsmonitor--daemon` whose socket no longer resolves to a live worktree. That covers daemons orphaned by `wt remove` itself and by paths that bypass it (plain `git worktree remove`, manual `rm -rf`, or a crashed `wt`).
-
-`wt remove` also force-terminates the removed worktree's own daemon as part of the synchronous teardown — it sends `git fsmonitor--daemon stop`, then resolves the daemon's PID from its IPC socket and SIGTERM/SIGKILLs it if it didn't exit. So removing a worktree never leaves a daemon behind, even one that has stopped answering its IPC.
+Sockets listed as bare `fsmonitor--daemon.ipc` (no resolved path) belong to deleted worktrees. Any `wt remove` cleans these up: it terminates the removed worktree's own daemon and sweeps daemons whose worktree no longer exists, including ones orphaned by `git worktree remove` or `rm -rf` (mechanism details: [What can Worktrunk delete?](https://worktrunk.dev/faq/#what-can-worktrunk-delete)).
The residual case both paths deliberately leave is a wedged daemon on a *live* worktree that is never removed: `git status` in that worktree blocks on the unresponsive IPC, but the daemon still serves a real worktree, so reaping it implicitly is out of scope. Terminate it manually: kill the daemon whose socket path matches the worktree, or `pkill -9 -f 'git fsmonitor--daemon'` and let the next `wt list` respawn the live ones. Disabling fsmonitor globally (`git config --global core.fsmonitor false`) avoids the class of problem entirely at the cost of some `git status` speed on large repos.
diff --git a/skills/worktrunk/SKILL.md b/skills/worktrunk/SKILL.md
index ab68bcf99..3c538ccf4 100644
--- a/skills/worktrunk/SKILL.md
+++ b/skills/worktrunk/SKILL.md
@@ -9,7 +9,7 @@ compatibility: Requires the `wt` CLI (https://worktrunk.dev)
Help users work with Worktrunk, a CLI tool for managing git worktrees.
-## Available Documentation
+## Available documentation
Reference files are synced from [worktrunk.dev](https://worktrunk.dev) documentation:
@@ -24,224 +24,77 @@ Reference files are synced from [worktrunk.dev](https://worktrunk.dev) documenta
For command-specific options, run `wt <command> --help`. For configuration, follow the workflows below.
-## Two Types of Configuration
-
-Worktrunk uses two separate config files with different scopes and behaviors:
-
-### User Config (`~/.config/worktrunk/config.toml`)
-- **Scope**: Personal preferences for the individual developer
-- **Location**: `~/.config/worktrunk/config.toml` (never checked into git)
-- **Contains**: LLM integration, worktree path templates, command settings, user hooks, approved commands
-- **Permission model**: Always propose changes and get consent before editing
-- **See**: `reference/config.md` for detailed guidance
-
-### Project Config (`.config/wt.toml`)
-- **Scope**: Team-wide automation shared by all developers
-- **Location**: `<repo>/.config/wt.toml` (checked into git)
-- **Contains**: Hooks for worktree lifecycle (pre-start, pre-merge, etc.)
-- **Permission model**: Proactive (create directly, changes are reversible via git)
-- **See**: `reference/hook.md` for detailed guidance
-
-## Determining Which Config to Use
-
-When a user asks for configuration help, determine which type based on:
+## Two types of configuration
-**User config indicators**:
-- "set up LLM" or "configure commit generation"
-- "change where worktrees are created"
-- "customize commit message templates"
-- Affects only their environment
+Worktrunk uses two config files with different scopes and permission models:
-**Project config indicators**:
-- "set up hooks for this project"
-- "automate npm install"
-- "run tests before merge"
-- Affects the entire team
+**User config** (`~/.config/worktrunk/config.toml`, never checked into git) holds personal preferences: LLM integration, worktree path templates, command settings, user hooks. Treat it conservatively — propose changes and get consent before editing, never install tools on the user's behalf, and preserve the file's existing structure and comments. See `reference/config.md`.
-**Both configs may be needed**: For example, setting up commit message generation requires user config, but automating quality checks requires project config.
-
-## Core Workflows
+**Project config** (`<repo>/.config/wt.toml`, checked into git) holds team-wide automation: hooks for the worktree lifecycle (pre-start, pre-merge, etc.). Edit proactively — changes are versioned and reversible via git. Comment why each hook exists, and warn the user before adding destructive commands (`rm -rf`, `DROP TABLE`), network fetches piped to shells, or `sudo`. See `reference/hook.md`.
-### Setting Up Commit Message Generation (User Config)
+Some requests span both: commit-message generation is user config, while the team's quality checks are project config.
-Most common request. See `reference/llm-commits.md` for supported tools and exact command syntax.
+## Core workflows
-1. **Detect available tools**
- ```bash
- which claude codex llm aichat 2>/dev/null
- ```
-
-2. **If none installed, recommend Claude Code** (already available in Claude Code sessions)
+### Setting up commit message generation (user config)
-3. **Propose config change** — Get the exact command from `reference/llm-commits.md`
- ```toml
- [commit.generation]
- command = "..." # see reference/llm-commits.md for tool-specific commands
- ```
- Ask: "Should I add this to your config?"
-
-4. **After approval, apply**
- - Check if config exists: `wt config show`
- - If not, guide through `wt config create`
- - Read, modify, write preserving structure
+Detect which tools are installed (`which claude codex llm aichat`); if none, recommend Claude Code. Take the exact command for the chosen tool from `reference/llm-commits.md`, propose the `[commit.generation]` change, and apply it after approval (`wt config create` first if no config exists). To verify, `wt step commit --dry-run` renders the prompt, runs the LLM, and prints the message without committing.
-5. **Suggest testing**
- ```bash
- wt step commit --show-prompt | head # verify prompt builds
- wt merge # in a repo with uncommitted changes
- ```
+### Configuring project hooks
-### Setting Up Project Hooks (Project Config)
+Pick the hook type by when the command should run and whether it may block (10 types: 5 events × pre/post — full reference in `reference/hook.md`):
-Common request for workflow automation. Follow discovery process:
+- Dependencies and env files a later step needs → `pre-start` (blocks creation)
+- Dev servers, long builds, cache copying → `post-start` (background)
+- Formatters, linters, type checks → `pre-commit`
+- Tests that must pass before merging → `pre-merge`
+- CI triggers, notifications → `post-commit`
+- Deployment → `post-merge`
+- Setup before branch resolution / terminal-IDE updates → `pre-switch` / `post-switch`
+- Cleanup before/after removal (save artifacts; stop servers, remove containers) → `pre-remove` / `post-remove`
-1. **Detect project type**
- ```bash
- ls package.json Cargo.toml pyproject.toml
- ```
+Derive the commands from the project itself (`package.json` scripts, `Cargo.toml`, `pyproject.toml`) and verify they run before adding them.
-2. **Identify available commands**
- - For npm: Read `package.json` scripts
- - For Rust: Common cargo commands
- - For Python: Check pyproject.toml
+When a new hook must wait for an existing one, convert the entry to a pipeline; independent commands in a named table run concurrently:
-3. **Design appropriate hooks** (10 hook types: 5 events × pre/post — see `reference/hook.md`)
- - Dependencies (fast, must complete) → `pre-start`
- - Tests/linting (must pass) → `pre-commit` or `pre-merge`
- - Long builds, dev servers → `post-start`
- - Setup before branch resolution → `pre-switch`
- - Terminal/IDE updates → `post-switch`
- - After-commit triggers (CI, notifications) → `post-commit`
- - Deployment → `post-merge`
- - Cleanup before removal → `pre-remove`
- - Cleanup after removal (stop servers, remove containers) → `post-remove`
+```toml
+# Pipeline: install completes before migrate starts
+[[pre-start]]
+install = "npm install"
-4. **Validate commands work**
- ```bash
- npm run lint # verify exists
- which cargo # verify tool exists
- ```
+[[pre-start]]
+migrate = "npm run db:migrate"
-5. **Create `.config/wt.toml`**
- ```toml
- # Install dependencies when creating worktrees
- pre-start = "npm install"
-
- # Validate code quality before committing
- [pre-commit]
- lint = "npm run lint"
- typecheck = "npm run typecheck"
-
- # Run tests before merging
- pre-merge = "npm test"
- ```
-
-6. **Add comments explaining choices**
-
-7. **Suggest testing**
- ```bash
- wt switch --create test-hooks
- ```
-
-**See `reference/hook.md` for complete details.**
-
-### Adding Hooks to Existing Config
-
-When users want to add automation to an existing project:
-
-1. **Read existing config**: `cat .config/wt.toml`
-
-2. **Determine hook type** - When should this run? (10 types: 5 events × pre/post)
- - Creating worktree (blocking) → `pre-start`
- - Creating worktree (background) → `post-start`
- - Before/after a switch → `pre-switch` / `post-switch`
- - Before committing → `pre-commit`
- - After committing (CI, notifications) → `post-commit`
- - Before merging → `pre-merge`
- - After merging → `post-merge`
- - Before/after removal → `pre-remove` / `post-remove`
-
-3. **Handle format conversion if needed**
-
- Single command to a pipeline of dependent steps:
- ```toml
- # Before
- pre-start = "npm install"
-
- # After (adding db:migrate, which needs install to finish first)
- [[pre-start]]
- install = "npm install"
-
- [[pre-start]]
- migrate = "npm run db:migrate"
- ```
-
- For independent commands, a named table runs them concurrently:
- ```toml
- [pre-start]
- install = "npm install"
- env = "cp .env.example .env"
- ```
-
-4. **Preserve existing structure and comments**
-
-### Validation Before Adding Commands
-
-Before adding hooks, validate:
-
-```bash
-# Verify command exists
-which npm
-which cargo
-
-# For npm, verify script exists
-npm run lint --dry-run
-
-# For shell commands, check syntax
-bash -n -c "if [ true ]; then echo ok; fi"
+# Concurrent: independent commands in one table
+[pre-start]
+install = "npm install"
+env = "cp .env.example .env"
```
-**Dangerous patterns** — Warn users before creating hooks with:
-- Destructive commands: `rm -rf`, `DROP TABLE`
-- External dependencies: `curl http://...`
-- Privilege escalation: `sudo`
-
-## Permission Models
-
-### User Config: Conservative
-- **Never edit without consent** - Always show proposed change and wait for approval
-- **Never install tools** - Provide commands for users to run themselves
-- **Preserve structure** - Keep existing comments and organization
-- **Validate first** - Ensure TOML is valid before writing
+Test with `wt switch --create test-hooks`.
-### Project Config: Proactive
-- **Create directly** - Changes are versioned, easily reversible
-- **Validate commands** - Check commands exist before adding
-- **Explain choices** - Add comments documenting why hooks exist
-- **Warn on danger** - Flag destructive operations before adding
+## Common tasks reference
-## Common Tasks Reference
-
-### User Config Tasks
+### User config tasks
- Set up commit message generation → `reference/llm-commits.md`
- Customize worktree paths → `reference/config.md#worktree-path-template`
- Custom commit templates → `reference/llm-commits.md#prompt-templates`
- Configure command defaults → `reference/config.md#command-config`
- Set up personal hooks → `reference/config.md#hooks`
-### Project Config Tasks
+### Project config tasks
- Set up hooks for new project → `reference/hook.md`
- Add hook to existing config → `reference/hook.md#hook-forms`
- Use template variables → `reference/hook.md#template-variables`
- Add dev server URL to list → `reference/config.md#dev-server-url`
-### Aliases & Multi-Worktree Tasks
+### Aliases & multi-worktree tasks
- Create a `wt` alias → `reference/extending.md#aliases`
- Run a command in every worktree → `reference/step.md#wt-step-for-each`
- Rebase every worktree (up-style) → `reference/extending.md#recipe-rebase-every-worktree-onto-its-upstream`
- Defer a template variable to a nested `wt` command → `reference/extending.md#deferring-expansion-to-a-nested-wt-command`
-## Key Commands
+## Key commands
```bash
# View all configuration
@@ -254,18 +107,7 @@ wt config create
wt config --help
```
-## Loading Additional Documentation
-
-Load **reference files** for detailed configuration, hook specifications, and troubleshooting.
-
-Find specific sections with grep:
-```bash
-grep -A 20 "## Setup" reference/llm-commits.md
-grep -A 30 "### pre-start" reference/hook.md
-grep -A 20 "## Warning Messages" reference/shell-integration.md
-```
-
-## Hook Approvals in Non-Interactive Sessions
+## Hook approvals in non-interactive sessions
Worktrunk never runs a project's hooks or aliases until the user has explicitly approved them. The commands in `.config/wt.toml` are arbitrary shell code shipped in a repository the user may have just cloned, so on first run Worktrunk shows each command and waits for the user to approve it — an untrusted `.config/wt.toml` cannot silently execute anything. Approvals are stored per-project in `~/.config/worktrunk/approvals.toml` and re-prompted whenever a command template changes, so a hook can't be swapped for a different command after it was approved.
@@ -285,7 +127,7 @@ The resolution is for the user to make the trust decision themselves:
**When invoked as an agent, stop and escalate to the user.** Approving a project's hooks is a security decision about whether this repository should be trusted to run arbitrary commands on the user's machine — that decision belongs to the user, not the agent. Tell the user to run `wt config approvals add` and let them review the commands. Do not run `--yes` on the user's behalf: it skips the approval gate for that invocation, so reaching for it to unblock a command defeats the protection. `--yes` exists for CI/CD pipelines that already control their own hook contents; it is not a shortcut for an interactive agent to silence an approval prompt.
-## Advanced: Agent Handoffs
+## Advanced: agent handoffs
When the user requests spawning a worktree with an agent in a background session ("spawn a worktree for...", "hand off to another agent"), use the appropriate pattern for their terminal multiplexer. Substitute `<agent-cli>` with the CLI you are running as: `claude` for Claude Code, `'opencode run'` for OpenCode.
diff --git a/skills/worktrunk/reference/config.md b/skills/worktrunk/reference/config.md
index d8751415e..96a21dd55 100644
--- a/skills/worktrunk/reference/config.md
+++ b/skills/worktrunk/reference/config.md
@@ -322,7 +322,7 @@ pager = "delta --paging=never" # Example: override git's core.pager for diff p
exclude = [] # Additional excludes (e.g., [".cache/", ".turbo/"])
```
-Built-in excludes always apply: VCS metadata directories (`.bzr/`, `.hg/`, `.jj/`, `.pijul/`, `.sl/`, `.svn/`) and tool-state directories (`.conductor/`, `.entire/`, `.worktrees/`). User config and project config exclusions are combined.
+Built-in excludes (VCS metadata and tool-state directories) always apply; [the `wt step copy-ignored` docs](https://worktrunk.dev/step/#wt-step-copy-ignored) list them. User config and project config exclusions are combined.
### Aliases
@@ -489,7 +489,7 @@ squash-template = """
#### Appending to the prompt [experimental]
-`template-append` adds to the prompt instead of replacing it. The value is rendered as its own minijinja template (same variables) and injected into the default templates' `{{ user_guidance }}` slot — a `<user-guidance>` block right after `<style>`. It applies to both commit and squash. Use it for personal preferences without restating the whole template:
+`template-append` adds personal conventions to the commit and squash prompts without restating the whole template:
```toml
[commit.generation]
@@ -498,7 +498,7 @@ template-append = """
"""
```
-The [project config](https://worktrunk.dev/config/#project-configuration) has a `template-append` of its own; it renders into a separate `<project-guidance>` block right after `<user-guidance>`.
+How the fragment renders, and the project-config counterpart: [the LLM commits guide](https://worktrunk.dev/llm-commits/#appending-to-the-prompt).
## Hooks
@@ -542,7 +542,7 @@ hostname = "github.example.com" # Example: API host (GHE / self-hosted GitLab)
## Commit-message append [experimental]
-Project-wide commit-message conventions appended to the LLM commit and squash prompts inside a `<project-guidance>` block, after the main template's `<style>` section (and after any user `<user-guidance>`). Rendered as a [minijinja](https://docs.rs/minijinja/) template with the same variables as the main commit template (`{{ branch }}`, `{{ git_diff }}`, etc.), so it can reference them directly. The first time the fragment changes, `wt` prompts the user to approve it — the same one-shot gate as project-defined hooks.
+`template-append` adds project-wide conventions to the LLM commit and squash prompts, shared so every teammate's LLM sees the same style guide:
```toml
[commit.generation]
@@ -552,7 +552,7 @@ template-append = """
"""
```
-Only `template-append` is honored from the project file. The LLM command and the main prompt template stay in [user config](https://worktrunk.dev/config/) — they describe per-developer environment (which CLI is installed, which agent the developer prefers). User config has a `[commit.generation] template-append` of its own; it renders into a separate `<user-guidance>` block immediately before this one.
+The first time the fragment is used (and whenever it changes), `wt` prompts the user to approve it — the same one-shot gate as project-defined hooks. Only `template-append` is honored from the project file; the LLM command and the main prompt template stay in [user config](https://worktrunk.dev/config/), since they describe per-developer environment (which CLI is installed, which agent the developer prefers). How the fragment renders: [the LLM commits guide](https://worktrunk.dev/llm-commits/#appending-to-the-prompt).
## Copy-ignored excludes
@@ -563,7 +563,7 @@ Additional excludes for `wt step copy-ignored`:
exclude = [".cache/", ".turbo/"]
```
-Built-in excludes always apply: VCS metadata directories (`.bzr/`, `.hg/`, `.jj/`, `.pijul/`, `.sl/`, `.svn/`) and tool-state directories (`.conductor/`, `.entire/`, `.worktrees/`). User config and project config exclusions are combined.
+Built-in excludes (VCS metadata and tool-state directories) always apply; [the `wt step copy-ignored` docs](https://worktrunk.dev/step/#wt-step-copy-ignored) list them. User config and project config exclusions are combined.
## Aliases
@@ -1240,26 +1240,7 @@ CI status cache.
**Deprecated** — the CI status cache is now part of [`wt config state cache`](https://worktrunk.dev/config/#wt-config-state-cache). This subcommand still works but prints a deprecation notice.
-Caches GitHub/GitLab CI status for display in [`wt list`](https://worktrunk.dev/list/#ci-status).
-
-Requires `gh` (GitHub) or `glab` (GitLab) CLI, authenticated. Platform auto-detects from the remote URL; set `forge.platform = "github"` (or `"gitlab"`) in `.config/wt.toml` for SSH host aliases or self-hosted instances. For GitHub Enterprise or self-hosted GitLab, also set `forge.hostname`.
-
-Checks open PRs/MRs first, then branch pipelines for branches with upstream. Local-only branches (no remote tracking) show blank.
-
-Results cache for 30-60 seconds. Indicators dim when local changes haven't been pushed.
-
-### Status values
-
-| Status | Meaning |
-|--------|---------|
-| `passed` | All checks passed |
-| `running` | Checks in progress |
-| `failed` | Checks failed |
-| `conflicts` | PR has merge conflicts |
-| `no-ci` | No checks configured |
-| `error` | Fetch error (rate limit, network, auth) |
-
-See [`wt list` CI status](https://worktrunk.dev/list/#ci-status) for display symbols and colors.
+Status values, display symbols, and fetch behavior: [`wt list` CI status](https://worktrunk.dev/list/#ci-status).
Without a subcommand, runs `get` for the current branch. Use `clear` to reset cache for a branch or `clear --all` to reset all.
diff --git a/skills/worktrunk/reference/extending.md b/skills/worktrunk/reference/extending.md
index 091080eed..61f91e592 100644
--- a/skills/worktrunk/reference/extending.md
+++ b/skills/worktrunk/reference/extending.md
@@ -20,17 +20,7 @@ Hooks and aliases live in the same TOML config and share the [template engine](h
## Hooks
-Ten hooks cover five lifecycle events:
-
-| Event | `pre-` (blocking) | `post-` (background) |
-|-------|-------------------|---------------------|
-| **switch** | `pre-switch` | `post-switch` |
-| **start** | `pre-start` | `post-start` |
-| **commit** | `pre-commit` | `post-commit` |
-| **merge** | `pre-merge` | `post-merge` |
-| **remove** | `pre-remove` | `post-remove` |
-
-`pre-*` hooks block: failure aborts the operation. `post-*` hooks run in the background.
+Ten hooks cover five lifecycle events — switch, start, commit, merge, remove — each with a blocking `pre-` variant (failure aborts the operation) and a background `post-` variant. [`wt hook`](https://worktrunk.dev/hook/#hook-types) maps each hook to its timing and typical uses.
```toml
[pre-start]
diff --git a/skills/worktrunk/reference/faq.md b/skills/worktrunk/reference/faq.md
index 070caf402..aa412f05a 100644
--- a/skills/worktrunk/reference/faq.md
+++ b/skills/worktrunk/reference/faq.md
@@ -92,12 +92,7 @@ Three verbosity levels. Each is a superset of the previous one.
At `-vv`, debug-level records (command lines, in-process spans, bounded subprocess preview) route to `trace.log` instead of stderr — so the terminal stays readable while the deep trace lands on disk. A one-line pointer on stderr shows where the files went.
-The `-vv` files have distinct audiences:
-
-- **`trace.log`** — the human trace (bounded ~1K lines, gistable): each command's start (`$ git status`) and finish (`✓ git status [wt] 12.3ms`, `✗` on failure), spans, and milestones.
-- **`trace.jsonl`** — the same records as one JSON object per line, for machines (`jq`, chrome://tracing). `wt config state logs profile` reads it.
-- **`subprocess.log`** — raw uncapped stdout/stderr of every subprocess `wt` spawns (multi-MB possible, e.g. full `git log -p` output). The deep-dive escape hatch.
-- **`diagnostic.md`** — markdown bug-report bundle that leads with the performance report (subprocess time by command type, slowest calls, repeated calls — the same rendering `wt config state logs profile` produces from `trace.jsonl`) and inlines `trace.log`. `wt` prints a `gh gist create` command pointing at it.
+The `-vv` files have distinct audiences: `trace.log` is the human trace (bounded, gistable), `trace.jsonl` the same records for machines, `subprocess.log` the raw uncapped subprocess output, and `diagnostic.md` a bug-report bundle. Each is described in [`wt config state logs`](https://worktrunk.dev/config/#wt-config-state-logs).
`RUST_LOG` overrides the flag baseline when set (`RUST_LOG=debug wt -v` lifts `-v` to debug-on-stderr).
@@ -193,8 +188,7 @@ Use `-D` to force-delete branches with unmerged changes. Use `--no-delete-branch
### Other cleanup
-- `wt remove` — in addition to the target worktree, runs a background internal sweep: deletes `.git/wt/trash/` entries older than 24 hours (eventual cleanup for directories orphaned when a previous background removal was interrupted), and terminates (`SIGTERM` then `SIGKILL`) `git fsmonitor--daemon` processes whose worktree no longer exists
-- `wt remove` — terminates the removed worktree's `git fsmonitor--daemon` process. Git starts this per-worktree filesystem-watch daemon when `core.fsmonitor=true`; once its worktree is gone it would leak. Removal sends `git fsmonitor--daemon stop`, then resolves that daemon's PID from its IPC socket and force-terminates it (SIGTERM, then SIGKILL) if it didn't exit. The signal only ever targets the daemon whose socket resolves to the worktree being removed.
+- `wt remove` — besides the target worktree, two cleanup mechanisms run. The removed worktree's own `git fsmonitor--daemon` (git's per-worktree filesystem watcher under `core.fsmonitor=true`, which would leak once its worktree is gone) is sent `git fsmonitor--daemon stop`, then force-terminated (`SIGTERM`, then `SIGKILL`) via the PID resolved from its IPC socket if it didn't exit. A background sweep then deletes `.git/wt/trash/` entries older than 24 hours (directories orphaned when a previous background removal was interrupted) and terminates fsmonitor daemons whose worktree no longer exists (orphans from `git worktree remove`, `rm -rf`, or a crashed `wt`)
- `wt config state clear` — removes all worktrunk data from `.git/` (config keys, caches, markers, hints, variables, logs, stale trash)
- `wt config shell install` — when migrating an integration to a new location, removes the worktrunk-managed file left at the old one: fish `conf.d/wt.fish` (now `functions/wt.fish`) and nushell wrappers stranded under `<config-dir>/vendor/autoload` (now `<data-dir>/vendor/autoload`)
- `wt config shell uninstall` — removes shell integration from rc files
diff --git a/skills/worktrunk/reference/shell-integration.md b/skills/worktrunk/reference/shell-integration.md
index b7039915e..9e1e51031 100644
--- a/skills/worktrunk/reference/shell-integration.md
+++ b/skills/worktrunk/reference/shell-integration.md
@@ -8,18 +8,13 @@ Subprocesses cannot change the parent shell's current directory. When
`wt switch feature` runs, the `wt` binary runs as a child process and cannot
`cd` the terminal.
-Worktrunk solves this with **split directive file passing**:
-
-1. Shell wrapper creates two temp files via `mktemp` (one for cd, one for exec)
-2. Shell sets `WORKTRUNK_DIRECTIVE_CD_FILE` and `WORKTRUNK_DIRECTIVE_EXEC_FILE`
-3. `wt` binary writes a raw path to the CD file (no shell escaping needed)
-4. `wt` writes shell commands to the EXEC file (only for `--execute`)
-5. Shell reads the CD file with `cd -- "$(< file)"` — no shell parsing
-6. Shell sources the EXEC file if non-empty
-7. Shell removes both temp files
-
-The split design eliminates shell injection from cd directives — the CD file
-holds a raw path that is never parsed as shell.
+Worktrunk solves this with **split directive file passing**: the shell wrapper
+creates two temp files, `wt` writes a raw path to one (cd) and shell commands
+to the other (`--execute` payloads), and the wrapper applies both after `wt`
+exits. The split design eliminates shell injection from cd directives — the CD
+file holds a raw path that is never parsed as shell. The wrapper's steps and a
+simplified implementation: [How the Shell Wrapper
+Works](#how-the-shell-wrapper-works).
## Installation
diff --git a/skills/worktrunk/reference/step.md b/skills/worktrunk/reference/step.md
index 98772bfb3..85d72b08e 100644
--- a/skills/worktrunk/reference/step.md
+++ b/skills/worktrunk/reference/step.md
@@ -386,7 +386,7 @@ copy = "wt step copy-ignored"
### What gets copied
-All gitignored files are copied by default, except for built-in excluded directories: VCS metadata (`.bzr/`, `.hg/`, `.jj/`, `.pijul/`, `.sl/`, `.svn/`) and tool-state (`.conductor/`, `.entire/`, `.worktrees/`). Tracked files are never touched.
+All gitignored files are copied by default, except for built-in excluded directories: VCS metadata (`.bzr/`, `.hg/`, `.jj/`, `.pijul/`, `.sl/`, `.svn/`), tool-state (`.conductor/`, `.entire/`, `.worktrees/`), and nested worktrees. Tracked files are never touched. Discovery handles nested `.gitignore` files, global excludes, and `.git/info/exclude`. Existing files in the destination are skipped, so re-running is safe; `--force` overwrites them.
To limit what gets copied further, create `.worktreeinclude` with gitignore-style patterns. Files must be **both** gitignored **and** in `.worktreeinclude`:
@@ -421,14 +421,6 @@ Without `.worktreeinclude`, the command is a no-op (it reports that nothing was
| Generated assets | Images, ML models, binaries too large for git |
| Environment files | `.env` (if not generated per-worktree) |
-### Features
-
-- Uses copy-on-write (reflink) when available for space-efficient copies
-- Handles nested `.gitignore` files, global excludes, and `.git/info/exclude`
-- Skips existing files by default (safe to re-run)
-- `--force` overwrites existing files in the destination
-- Always skips built-in excluded directories — VCS metadata (`.bzr/`, `.hg/`, `.jj/`, `.pijul/`, `.sl/`, `.svn/`) and tool-state (`.conductor/`, `.entire/`, `.worktrees/`) — and nested worktrees
-
### Performance
Reflink copies share disk blocks until modified — no data is actually copied. For a 14GB `target/` directory:
@@ -472,7 +464,7 @@ Virtual environments contain absolute paths and can't be copied. Use `uv sync` i
The `.worktreeinclude` pattern is shared with [Claude Code on desktop](https://code.claude.com/docs/en/desktop), which copies matching files when creating worktrees. Differences:
- worktrunk copies all gitignored files by default; Claude Code requires `.worktreeinclude`. Pass `--require-include` to match Claude Code (copy nothing without `.worktreeinclude`)
-- worktrunk uses copy-on-write for large directories like `target/` — potentially 30x faster on macOS, 6x on Linux
+- worktrunk uses copy-on-write for large directories like `target/` (see Performance above)
- worktrunk runs as a configurable hook in the worktree lifecycle
### Command reference
@@ -587,8 +579,6 @@ $ wt step eval -v '{{ branch }}'
feature/auth-oauth2
```
-Note: This command is experimental and may change in future versions.
-
### Command reference
```
@@ -676,8 +666,6 @@ Pull updates in worktrees with upstreams (skips others):
$ git fetch --prune && wt step for-each -- sh -c '[ "$(git rev-parse @{u} 2>/dev/null)" ] || exit 0; git pull --autostash'
```
-Note: This command is experimental and may change in future versions.
-
### Command reference
```
@@ -960,8 +948,6 @@ refuses), unless `--commit` is passed.
- **Target blocked** (without `--clobber`) — use `--clobber` to backup blocker
- **Detached HEAD** — no branch to compute expected path
-Note: This command is experimental and may change in future versions.
-
### Command reference
```
@@ -1068,8 +1054,6 @@ Run a dev server, torn down automatically when the worktree goes away:
server = "wt step tether -- npm run dev -- --port {{ branch | hash_port }}"
```
-Note: This command is experimental and may change in future versions.
-
### Command reference
```
diff --git a/skills/worktrunk/reference/tips-patterns.md b/skills/worktrunk/reference/tips-patterns.md
index 80e0780dd..5390975a6 100644
--- a/skills/worktrunk/reference/tips-patterns.md
+++ b/skills/worktrunk/reference/tips-patterns.md
@@ -228,7 +228,7 @@ Structured output for dashboards, statuslines, and scripts. See [`wt list`](http
## Reuse `default-branch`
-Worktrunk maintains useful state. Default branch [detection](https://worktrunk.dev/config/#wt-config-state-default-branch), for instance, means scripts work on any repo — no need to hardcode `main` or `master`:
+Default branch [detection](https://worktrunk.dev/config/#wt-config-state-default-branch) means scripts work on any repo — no need to hardcode `main` or `master`:
```bash
git rebase $(wt config state default-branch)
@@ -412,8 +412,6 @@ clean-derived = """
"""
```
-This precisely targets only the DerivedData for the removed worktree, leaving caches for other worktrees and the main repository intact.
-
## Subdomain routing with Caddy
<!-- Hand-tested 2026-03-07 -->
diff --git a/skills/worktrunk/reference/troubleshooting.md b/skills/worktrunk/reference/troubleshooting.md
index 6b30ab3b5..bbb015973 100644
--- a/skills/worktrunk/reference/troubleshooting.md
+++ b/skills/worktrunk/reference/troubleshooting.md
@@ -115,9 +115,7 @@ for pid in $(pgrep -f 'git fsmonitor--daemon'); do
done
```
-Sockets listed as bare `fsmonitor--daemon.ipc` (no resolved path) belong to deleted worktrees. `wt remove` reaps these as part of its internal sweep: after the primary removal output, it sends `SIGTERM` (then `SIGKILL` after a short bounded wait) to every `git fsmonitor--daemon` whose socket no longer resolves to a live worktree. That covers daemons orphaned by `wt remove` itself and by paths that bypass it (plain `git worktree remove`, manual `rm -rf`, or a crashed `wt`).
-
-`wt remove` also force-terminates the removed worktree's own daemon as part of the synchronous teardown — it sends `git fsmonitor--daemon stop`, then resolves the daemon's PID from its IPC socket and SIGTERM/SIGKILLs it if it didn't exit. So removing a worktree never leaves a daemon behind, even one that has stopped answering its IPC.
+Sockets listed as bare `fsmonitor--daemon.ipc` (no resolved path) belong to deleted worktrees. Any `wt remove` cleans these up: it terminates the removed worktree's own daemon and sweeps daemons whose worktree no longer exists, including ones orphaned by `git worktree remove` or `rm -rf` (mechanism details: [What can Worktrunk delete?](https://worktrunk.dev/faq/#what-can-worktrunk-delete)).
The residual case both paths deliberately leave is a wedged daemon on a *live* worktree that is never removed: `git status` in that worktree blocks on the unresponsive IPC, but the daemon still serves a real worktree, so reaping it implicitly is out of scope. Terminate it manually: kill the daemon whose socket path matches the worktree, or `pkill -9 -f 'git fsmonitor--daemon'` and let the next `wt list` respawn the live ones. Disabling fsmonitor globally (`git config --global core.fsmonitor false`) avoids the class of problem entirely at the cost of some `git status` speed on large repos.
diff --git a/src/cli/config.rs b/src/cli/config.rs
index cab117af4..635fd6aae 100644
--- a/src/cli/config.rs
+++ b/src/cli/config.rs
@@ -969,26 +969,7 @@ $ wt config state hints clear NAME # re-show specific hint
hide = true,
after_long_help = r#"**Deprecated** — the CI status cache is now part of [`wt config state cache`](@/config.md#wt-config-state-cache). This subcommand still works but prints a deprecation notice.
-Caches GitHub/GitLab CI status for display in [`wt list`](@/list.md#ci-status).
-
-Requires `gh` (GitHub) or `glab` (GitLab) CLI, authenticated. Platform auto-detects from the remote URL; set `forge.platform = "github"` (or `"gitlab"`) in `.config/wt.toml` for SSH host aliases or self-hosted instances. For GitHub Enterprise or self-hosted GitLab, also set `forge.hostname`.
-
-Checks open PRs/MRs first, then branch pipelines for branches with upstream. Local-only branches (no remote tracking) show blank.
-
-Results cache for 30-60 seconds. Indicators dim when local changes haven't been pushed.
-
-## Status values
-
-| Status | Meaning |
-|--------|---------|
-| `passed` | All checks passed |
-| `running` | Checks in progress |
-| `failed` | Checks failed |
-| `conflicts` | PR has merge conflicts |
-| `no-ci` | No checks configured |
-| `error` | Fetch error (rate limit, network, auth) |
-
-See [`wt list` CI status](@/list.md#ci-status) for display symbols and colors.
+Status values, display symbols, and fetch behavior: [`wt list` CI status](@/list.md#ci-status).
Without a subcommand, runs `get` for the current branch. Use `clear` to reset cache for a branch or `clear --all` to reset all."#
)]
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 9f252d2dc..d33ce6a6c 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -2173,7 +2173,7 @@ pager = "delta --paging=never" # Example: override git's core.pager for diff p
exclude = [] # Additional excludes (e.g., [".cache/", ".turbo/"])
```
-Built-in excludes always apply: VCS metadata directories (`.bzr/`, `.hg/`, `.jj/`, `.pijul/`, `.sl/`, `.svn/`) and tool-state directories (`.conductor/`, `.entire/`, `.worktrees/`). User config and project config exclusions are combined.
+Built-in excludes (VCS metadata and tool-state directories) always apply; [the `wt step copy-ignored` docs](@/step.md#wt-step-copy-ignored) list them. User config and project config exclusions are combined.
### Aliases
@@ -2340,7 +2340,7 @@ squash-template = """
#### Appending to the prompt [experimental]
-`template-append` adds to the prompt instead of replacing it. The value is rendered as its own minijinja template (same variables) and injected into the default templates' `{{ user_guidance }}` slot — a `<user-guidance>` block right after `<style>`. It applies to both commit and squash. Use it for personal preferences without restating the whole template:
+`template-append` adds personal conventions to the commit and squash prompts without restating the whole template:
```toml
[commit.generation]
@@ -2349,7 +2349,7 @@ template-append = """
"""
```
-The [project config](@/config.md#project-configuration) has a `template-append` of its own; it renders into a separate `<project-guidance>` block right after `<user-guidance>`.
+How the fragment renders, and the project-config counterpart: [the LLM commits guide](@/llm-commits.md#appending-to-the-prompt).
## Hooks
@@ -2393,7 +2393,7 @@ hostname = "github.example.com" # Example: API host (GHE / self-hosted GitLab)
## Commit-message append [experimental]
-Project-wide commit-message conventions appended to the LLM commit and squash prompts inside a `<project-guidance>` block, after the main template's `<style>` section (and after any user `<user-guidance>`). Rendered as a [minijinja](https://docs.rs/minijinja/) template with the same variables as the main commit template (`{{ branch }}`, `{{ git_diff }}`, etc.), so it can reference them directly. The first time the fragment changes, `wt` prompts the user to approve it — the same one-shot gate as project-defined hooks.
+`template-append` adds project-wide conventions to the LLM commit and squash prompts, shared so every teammate's LLM sees the same style guide:
```toml
[commit.generation]
@@ -2403,7 +2403,7 @@ template-append = """
"""
```
-Only `template-append` is honored from the project file. The LLM command and the main prompt template stay in [user config](@/config.md) — they describe per-developer environment (which CLI is installed, which agent the developer prefers). User config has a `[commit.generation] template-append` of its own; it renders into a separate `<user-guidance>` block immediately before this one.
+The first time the fragment is used (and whenever it changes), `wt` prompts the user to approve it — the same one-shot gate as project-defined hooks. Only `template-append` is honored from the project file; the LLM command and the main prompt template stay in [user config](@/config.md), since they describe per-developer environment (which CLI is installed, which agent the developer prefers). How the fragment renders: [the LLM commits guide](@/llm-commits.md#appending-to-the-prompt).
## Copy-ignored excludes
@@ -2414,7 +2414,7 @@ Additional excludes for `wt step copy-ignored`:
exclude = [".cache/", ".turbo/"]
```
-Built-in excludes always apply: VCS metadata directories (`.bzr/`, `.hg/`, `.jj/`, `.pijul/`, `.sl/`, `.svn/`) and tool-state directories (`.conductor/`, `.entire/`, `.worktrees/`). User config and project config exclusions are combined.
+Built-in excludes (VCS metadata and tool-state directories) always apply; [the `wt step copy-ignored` docs](@/step.md#wt-step-copy-ignored) list them. User config and project config exclusions are combined.
## Aliases
diff --git a/src/cli/step.rs b/src/cli/step.rs
index 737e45c63..084cb8db2 100644
--- a/src/cli/step.rs
+++ b/src/cli/step.rs
@@ -287,7 +287,7 @@ copy = "wt step copy-ignored"
## What gets copied
-All gitignored files are copied by default, except for built-in excluded directories: VCS metadata (`.bzr/`, `.hg/`, `.jj/`, `.pijul/`, `.sl/`, `.svn/`) and tool-state (`.conductor/`, `.entire/`, `.worktrees/`). Tracked files are never touched.
+All gitignored files are copied by default, except for built-in excluded directories: VCS metadata (`.bzr/`, `.hg/`, `.jj/`, `.pijul/`, `.sl/`, `.svn/`), tool-state (`.conductor/`, `.entire/`, `.worktrees/`), and nested worktrees. Tracked files are never touched. Discovery handles nested `.gitignore` files, global excludes, and `.git/info/exclude`. Existing files in the destination are skipped, so re-running is safe; `--force` overwrites them.
To limit what gets copied further, create `.worktreeinclude` with gitignore-style patterns. Files must be **both** gitignored **and** in `.worktreeinclude`:
@@ -322,14 +322,6 @@ Without `.worktreeinclude`, the command is a no-op (it reports that nothing was
| Generated assets | Images, ML models, binaries too large for git |
| Environment files | `.env` (if not generated per-worktree) |
-## Features
-
-- Uses copy-on-write (reflink) when available for space-efficient copies
-- Handles nested `.gitignore` files, global excludes, and `.git/info/exclude`
-- Skips existing files by default (safe to re-run)
-- `--force` overwrites existing files in the destination
-- Always skips built-in excluded directories — VCS metadata (`.bzr/`, `.hg/`, `.jj/`, `.pijul/`, `.sl/`, `.svn/`) and tool-state (`.conductor/`, `.entire/`, `.worktrees/`) — and nested worktrees
-
## Performance
Reflink copies share disk blocks until modified — no data is actually copied. For a 14GB `target/` directory:
@@ -373,7 +365,7 @@ Virtual environments contain absolute paths and can't be copied. Use `uv sync` i
The `.worktreeinclude` pattern is shared with [Claude Code on desktop](https://code.claude.com/docs/en/desktop), which copies matching files when creating worktrees. Differences:
- worktrunk copies all gitignored files by default; Claude Code requires `.worktreeinclude`. Pass `--require-include` to match Claude Code (copy nothing without `.worktreeinclude`)
-- worktrunk uses copy-on-write for large directories like `target/` — potentially 30x faster on macOS, 6x on Linux
+- worktrunk uses copy-on-write for large directories like `target/` (see Performance above)
- worktrunk runs as a configurable hook in the worktree lifecycle
"#)]
CopyIgnored {
@@ -457,8 +449,6 @@ $ wt step eval -v '{{ branch }}'
feature/auth-oauth2
```
-
-Note: This command is experimental and may change in future versions.
"#
)]
Eval {
@@ -511,8 +501,6 @@ Pull updates in worktrees with upstreams (skips others):
```console
$ git fetch --prune && wt step for-each -- sh -c '[ "$(git rev-parse @{u} 2>/dev/null)" ] || exit 0; git pull --autostash'
```
-
-Note: This command is experimental and may change in future versions.
"#
)]
ForEach {
@@ -695,8 +683,6 @@ refuses), unless `--commit` is passed.
- **Locked** — unlock with `git worktree unlock`
- **Target blocked** (without `--clobber`) — use `--clobber` to backup blocker
- **Detached HEAD** — no branch to compute expected path
-
-Note: This command is experimental and may change in future versions.
"#)]
Relocate {
/// Worktrees to relocate (defaults to all mismatched)
@@ -770,8 +756,6 @@ Run a dev server, torn down automatically when the worktree goes away:
[post-start]
server = "wt step tether -- npm run dev -- --port {{ branch | hash_port }}"
```
-
-Note: This command is experimental and may change in future versions.
"#)]
Tether {
/// Command to run (after `--`, run directly, no shell)
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_create.snap b/tests/snapshots/integration__integration_tests__help__help_config_create.snap
index a9b32c087..258786968 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_create.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_create.snap
@@ -25,6 +25,7 @@ info:
WORKTRUNK_TEST_GEMINI_INSTALLED: "0"
WORKTRUNK_TEST_NUSHELL_ENV: "0"
WORKTRUNK_TEST_OPENCODE_INSTALLED: "0"
+ WORKTRUNK_TEST_PARENT_SHELL: ""
WORKTRUNK_TEST_POWERSHELL_ENV: "0"
WORKTRUNK_TEST_POWERSHELL_INSTALLED: "0"
WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
@@ -287,7 +288,7 @@ Creates ~/.config/worktrunk/config.toml with the following content:
  # [step.copy-ignored]
  # exclude = [] # Additional excludes (e.g., [".cache/", ".turbo/"])
  #
-  # Built-in excludes always apply: VCS metadata directories (`.bzr/`, `.hg/`, `.jj/`, `.pijul/`, `.sl/`, `.svn/`) and tool-state directories (`.conductor/`, `.entire/`, `.worktrees/`). User config and project config exclusions are combined.
+  # Built-in excludes (VCS metadata and tool-state directories) always apply; the `wt step copy-ignored` docs (https://worktrunk.dev/step/#wt-step-copy-ignored) list them. User config and project config exclusions are combined.
  #
  # ### Aliases
  #
@@ -444,14 +445,14 @@ Creates ~/.config/worktrunk/config.toml with the following content:
  #
  # #### Appending to the prompt [experimental]
  #
-  # `template-append` adds to the prompt instead of replacing it. The value is rendered as its own minijinja template (same variables) and injected into the default templates' `{{ user_guidance }}` slot — a `<user-guidance>` block right after `<style>`. It applies to both commit and squash. Use it for personal preferences without restating the whole template:
+  # `template-append` adds personal conventions to the commit and squash prompts without restating the whole template:
  #
  # [commit.generation]
  # template-append = """
  # - Explain the rationale in the body, not just the change
  # """
  #
-  # The project config (https://worktrunk.dev/config/#project-configuration) has a `template-append` of its own; it renders into a separate `<project-guidance>` block right after `<user-guidance>`.
+  # How the fragment renders, and the project-config counterpart: the LLM commits guide (https://worktrunk.dev/llm-commits/#appending-to-the-prompt).
  #
  # ## Hooks
  #
@@ -492,8 +493,7 @@ With --project, creates .config/wt.toml in the current repositor
  #
  # ## Commit-message append [experimental]
  #
-  # Project-wide commit-message conventions appended to the LLM commit and squash prompts inside a `<project-guidance>` block, after the main template's `<style>` section (and after any user `<user-guidance>`). Rendered as a minijinja (https://docs.rs/minijinja/) template with the same variables as the main commit template (`{{ branch }}`, `{{ git_diff }}`, etc.), so it can reference them directly. The first time the fragment changes, `wt` prompts the user to approve it — the same one-shot gate
-  as project-defined hooks.
+  # `template-append` adds project-wide conventions to the LLM commit and squash prompts, shared so every teammate's LLM sees the same style guide:
  #
  # [commit.generation]
  # template-append = """
@@ -501,7 +501,8 @@ With --project, creates .config/wt.toml in the current repositor
  # - Reference the relevant issue ID in the body
  # """
  #
-  # Only `template-append` is honored from the project file. The LLM command and the main prompt template stay in user config (https://worktrunk.dev/config/) — they describe per-developer environment (which CLI is installed, which agent the developer prefers). User config has a `[commit.generation] template-append` of its own; it renders into a separate `<user-guidance>` block immediately before this one.
+  # The first time the fragment is used (and whenever it changes), `wt` prompts the user to approve it — the same one-shot gate as project-defined hooks. Only `template-append` is honored from the project file; the LLM command and the main prompt template stay in user config (https://worktrunk.dev/config/), since they describe per-developer environment (which CLI is installed, which agent the developer prefers). How the fragment renders: the LLM commits guide
+  (https://worktrunk.dev/llm-commits/#appending-to-the-prompt).
  #
  # ## Copy-ignored excludes
  #
@@ -510,7 +511,7 @@ With --project, creates .config/wt.toml in the current repositor
  # [step.copy-ignored]
  # exclude = [".cache/", ".turbo/"]
  #
-  # Built-in excludes always apply: VCS metadata directories (`.bzr/`, `.hg/`, `.jj/`, `.pijul/`, `.sl/`, `.svn/`) and tool-state directories (`.conductor/`, `.entire/`, `.worktrees/`). User config and project config exclusions are combined.
+  # Built-in excludes (VCS metadata and tool-state directories) always apply; the `wt step copy-ignored` docs (https://worktrunk.dev/step/#wt-step-copy-ignored) list them. User config and project config exclusions are combined.
  #
  # ## Aliases
  #
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_long.snap b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
index 6aaf3a911..5bd691784 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
@@ -24,6 +24,7 @@ info:
WORKTRUNK_TEST_GEMINI_INSTALLED: "0"
WORKTRUNK_TEST_NUSHELL_ENV: "0"
WORKTRUNK_TEST_OPENCODE_INSTALLED: "0"
+ WORKTRUNK_TEST_PARENT_SHELL: ""
WORKTRUNK_TEST_POWERSHELL_ENV: "0"
WORKTRUNK_TEST_POWERSHELL_INSTALLED: "0"
WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
@@ -335,7 +336,7 @@ Persistent flag values for wt remove. Override on command line as needed
  [step.copy-ignored]
  exclude = [] # Additional excludes (e.g., [".cache/", ".turbo/"])
-Built-in excludes always apply: VCS metadata directories (.bzr/, .hg/, .jj/, .pijul/, .sl/, .svn/) and tool-state directories (.conductor/, .entire/, .worktrees/). User config and project config exclusions are combined.
+Built-in excludes (VCS metadata and tool-state directories) always apply; the wt step copy-ignored docs list them. User config and project config exclusions are combined.
Aliases
@@ -488,14 +489,14 @@ Default template:
Appending to the prompt [experimental]
-template-append adds to the prompt instead of replacing it. The value is rendered as its own minijinja template (same variables) and injected into the default templates' {{ user_guidance }} slot — a <user-guidance> block right after <style>. It applies to both commit and squash. Use it for personal preferences without restating the whole template:
+template-append adds personal conventions to the commit and squash prompts without restating the whole template:
  [commit.generation]
  template-append = """
  - Explain the rationale in the body, not just the change
  """
-The project config has a template-append of its own; it renders into a separate <project-guidance> block right after <user-guidance>.
+How the fragment renders, and the project-config counterpart: the LLM commits guide.
Hooks
@@ -531,7 +532,7 @@ Name the forge explicitly for SSH aliases or self-hosted instances, where it can
Commit-message append [experimental]
-Project-wide commit-message conventions appended to the LLM commit and squash prompts inside a <project-guidance> block, after the main template's <style> section (and after any user <user-guidance>). Rendered as a minijinja template with the same variables as the main commit template ({{ branch }}, {{ git_diff }}, etc.), so it can reference them directly. The first time the fragment changes, wt prompts the user to approve it — the same one-shot gate as project-defined hooks.
+template-append adds project-wide conventions to the LLM commit and squash prompts, shared so every teammate's LLM sees the same style guide:
  [commit.generation]
  template-append = """
@@ -539,7 +540,7 @@ Project-wide commit-message conventions appended to the LLM commit and squash pr
  - Reference the relevant issue ID in the body
  """
-Only template-append is honored from the project file. The LLM command and the main prompt template stay in user config — they describe per-developer environment (which CLI is installed, which agent the developer prefers). User config has a [commit.generation] template-append of its own; it renders into a separate <user-guidance> block immediately before this one.
+The first time the fragment is used (and whenever it changes), wt prompts the user to approve it — the same one-shot gate as project-defined hooks. Only template-append is honored from the project file; the LLM command and the main prompt template stay in user config, since they describe per-developer environment (which CLI is installed, which agent the developer prefers). How the fragment renders: the LLM commits guide.
Copy-ignored excludes
@@ -548,7 +549,7 @@ Additional excludes for wt step copy-ignored:
  [step.copy-ignored]
  exclude = [".cache/", ".turbo/"]
-Built-in excludes always apply: VCS metadata directories (.bzr/, .hg/, .jj/, .pijul/, .sl/, .svn/) and tool-state directories (.conductor/, .entire/, .worktrees/). User config and project config exclusions are combined.
+Built-in excludes (VCS metadata and tool-state directories) always apply; the wt step copy-ignored docs list them. User config and project config exclusions are combined.
Aliases
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_state_ci_status.snap b/tests/snapshots/integration__integration_tests__help__help_config_state_ci_status.snap
index 6a96cdc30..043861d3c 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_state_ci_status.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_state_ci_status.snap
@@ -26,6 +26,7 @@ info:
WORKTRUNK_TEST_GEMINI_INSTALLED: "0"
WORKTRUNK_TEST_NUSHELL_ENV: "0"
WORKTRUNK_TEST_OPENCODE_INSTALLED: "0"
+ WORKTRUNK_TEST_PARENT_SHELL: ""
WORKTRUNK_TEST_POWERSHELL_ENV: "0"
WORKTRUNK_TEST_POWERSHELL_INSTALLED: "0"
WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
@@ -68,26 +69,7 @@ Usage: wt config state ci-status [OPTIONS] [COMMAND]
Deprecated — the CI status cache is now part of wt config state cache. This subcommand still works but prints a deprecation notice.
-Caches GitHub/GitLab CI status for display in wt list.
-
-Requires gh (GitHub) or glab (GitLab) CLI, authenticated. Platform auto-detects from the remote URL; set forge.platform = "github" (or "gitlab") in .config/wt.toml for SSH host aliases or self-hosted instances. For GitHub Enterprise or self-hosted GitLab, also set forge.hostname.
-
-Checks open PRs/MRs first, then branch pipelines for branches with upstream. Local-only branches (no remote tracking) show blank.
-
-Results cache for 30-60 seconds. Indicators dim when local changes haven't been pushed.
-
-Status values
-
- Status Meaning
- ───────── ───────────────────────────────────────
- passed All checks passed
- running Checks in progress
- failed Checks failed
- conflicts PR has merge conflicts
- no-ci No checks configured
- error Fetch error (rate limit, network, auth)
-
-See wt list CI status for display symbols and colors.
+Status values, display symbols, and fetch behavior: wt list CI status.
Without a subcommand, runs get for the current branch. Use clear to reset cache for a branch or clear --all to reset all.
diff --git a/tests/snapshots/integration__integration_tests__help__help_step_copy_ignored.snap b/tests/snapshots/integration__integration_tests__help__help_step_copy_ignored.snap
index e92d231c7..6a05aa5f7 100644
--- a/tests/snapshots/integration__integration_tests__help__help_step_copy_ignored.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_step_copy_ignored.snap
@@ -25,6 +25,7 @@ info:
WORKTRUNK_TEST_GEMINI_INSTALLED: "0"
WORKTRUNK_TEST_NUSHELL_ENV: "0"
WORKTRUNK_TEST_OPENCODE_INSTALLED: "0"
+ WORKTRUNK_TEST_PARENT_SHELL: ""
WORKTRUNK_TEST_POWERSHELL_ENV: "0"
WORKTRUNK_TEST_POWERSHELL_INSTALLED: "0"
WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
@@ -97,7 +98,7 @@ Add to the project config:
What gets copied
-All gitignored files are copied by default, except for built-in excluded directories: VCS metadata (.bzr/, .hg/, .jj/, .pijul/, .sl/, .svn/) and tool-state (.conductor/, .entire/, .worktrees/). Tracked files are never touched.
+All gitignored files are copied by default, except for built-in excluded directories: VCS metadata (.bzr/, .hg/, .jj/, .pijul/, .sl/, .svn/), tool-state (.conductor/, .entire/, .worktrees/), and nested worktrees. Tracked files are never touched. Discovery handles nested .gitignore files, global excludes, and .git/info/exclude. Existing files in the destination are skipped, so re-running is safe; --force overwrites them.
To limit what gets copied further, create .worktreeinclude with gitignore-style patterns. Files must be both gitignored and in .worktreeinclude:
@@ -126,14 +127,6 @@ Without .worktreeinclude, the command is a no-op (it reports that nothin
Generated assets Images, ML models, binaries too large for git
Environment files .env (if not generated per-worktree)
-Features
-
-- Uses copy-on-write (reflink) when available for space-efficient copies
-- Handles nested .gitignore files, global excludes, and .git/info/exclude
-- Skips existing files by default (safe to re-run)
-- --force overwrites existing files in the destination
-- Always skips built-in excluded directories — VCS metadata (.bzr/, .hg/, .jj/, .pijul/, .sl/, .svn/) and tool-state (.conductor/, .entire/, .worktrees/) — and nested worktrees
-
Performance
Reflink copies share disk blocks until modified — no data is actually copied. For a 14GB target/ directory:
@@ -175,7 +168,7 @@ Virtual environments contain absolute paths and can't be copied. Use uv sync
The .worktreeinclude pattern is shared with Claude Code on desktop, which copies matching files when creating worktrees. Differences:
- worktrunk copies all gitignored files by default; Claude Code requires .worktreeinclude. Pass --require-include to match Claude Code (copy nothing without .worktreeinclude)
-- worktrunk uses copy-on-write for large directories like target/ — potentially 30x faster on macOS, 6x on Linux
+- worktrunk uses copy-on-write for large directories like target/ (see Performance above)
- worktrunk runs as a configurable hook in the worktree lifecycle
----- stderr -----