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.tomlindex 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.tomlindex 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.mdindex 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 pexclude = [] # 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.mdindex 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.mdindex 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 filesdiff --git a/docs/content/step.md b/docs/content/step.mdindex 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-### PerformanceReflink 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` iThe `.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 stdfeature/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.mdindex 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.jsonindex 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.mdindex 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 documentationReference files are synced from [worktrunk.dev](https://worktrunk.dev) documentation:@@ -24,224 +24,77 @@ Reference files are synced from [worktrunk.dev](https://worktrunk.dev) documentaFor 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 createwt 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 sessionsWorktrunk 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 handoffsWhen 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.mdindex 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 pexclude = [] # 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.mdindex 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.mdindex 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 filesdiff --git a/plugins/worktrunk/skills/worktrunk/reference/shell-integration.md b/plugins/worktrunk/skills/worktrunk/reference/shell-integration.mdindex 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).## Installationdiff --git a/plugins/worktrunk/skills/worktrunk/reference/step.md b/plugins/worktrunk/skills/worktrunk/reference/step.mdindex 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-### PerformanceReflink 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` iThe `.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.mdindex 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`:```bashgit 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.mdindex 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'); dodone```-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.mdindex 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 documentationReference files are synced from [worktrunk.dev](https://worktrunk.dev) documentation:@@ -24,224 +24,77 @@ Reference files are synced from [worktrunk.dev](https://worktrunk.dev) documentaFor 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 createwt 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 sessionsWorktrunk 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 handoffsWhen 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.mdindex 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 pexclude = [] # 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.mdindex 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.mdindex 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 filesdiff --git a/skills/worktrunk/reference/shell-integration.md b/skills/worktrunk/reference/shell-integration.mdindex 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).## Installationdiff --git a/skills/worktrunk/reference/step.md b/skills/worktrunk/reference/step.mdindex 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-### PerformanceReflink 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` iThe `.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.mdindex 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`:```bashgit 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.mdindex 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'); dodone```-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.rsindex 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 hinthide = 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.rsindex 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 pexclude = [] # 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.## Aliasesdiff --git a/src/cli/step.rs b/src/cli/step.rsindex 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-## PerformanceReflink 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` iThe `.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.snapindex 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 [2m~/.config/worktrunk/config.toml[0m with the following content:[107m [0m [2m# [step.copy-ignored][0m[107m [0m [2m# exclude = [] # Additional excludes (e.g., [".cache/", ".turbo/"])[0m[107m [0m [2m#[0m-[107m [0m [2m# 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.[0m+[107m [0m [2m# 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.[0m[107m [0m [2m#[0m[107m [0m [2m# ### Aliases[0m[107m [0m [2m#[0m@@ -444,14 +445,14 @@ Creates [2m~/.config/worktrunk/config.toml[0m with the following content:[107m [0m [2m#[0m[107m [0m [2m# #### Appending to the prompt [experimental][0m[107m [0m [2m#[0m-[107m [0m [2m# `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:[0m+[107m [0m [2m# `template-append` adds personal conventions to the commit and squash prompts without restating the whole template:[0m[107m [0m [2m#[0m[107m [0m [2m# [commit.generation][0m[107m [0m [2m# template-append = """[0m[107m [0m [2m# - Explain the rationale in the body, not just the change[0m[107m [0m [2m# """[0m[107m [0m [2m#[0m-[107m [0m [2m# 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>`.[0m+[107m [0m [2m# How the fragment renders, and the project-config counterpart: the LLM commits guide (https://worktrunk.dev/llm-commits/#appending-to-the-prompt).[0m[107m [0m [2m#[0m[107m [0m [2m# ## Hooks[0m[107m [0m [2m#[0m@@ -492,8 +493,7 @@ With [2m--project[0m, creates [2m.config/wt.toml[0m in the current repositor[107m [0m [2m#[0m[107m [0m [2m# ## Commit-message append [experimental][0m[107m [0m [2m#[0m-[107m [0m [2m# 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-[107m [0m as project-defined hooks.[0m+[107m [0m [2m# `template-append` adds project-wide conventions to the LLM commit and squash prompts, shared so every teammate's LLM sees the same style guide:[0m[107m [0m [2m#[0m[107m [0m [2m# [commit.generation][0m[107m [0m [2m# template-append = """[0m@@ -501,7 +501,8 @@ With [2m--project[0m, creates [2m.config/wt.toml[0m in the current repositor[107m [0m [2m# - Reference the relevant issue ID in the body[0m[107m [0m [2m# """[0m[107m [0m [2m#[0m-[107m [0m [2m# 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.[0m+[107m [0m [2m# 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+[107m [0m (https://worktrunk.dev/llm-commits/#appending-to-the-prompt).[0m[107m [0m [2m#[0m[107m [0m [2m# ## Copy-ignored excludes[0m[107m [0m [2m#[0m@@ -510,7 +511,7 @@ With [2m--project[0m, creates [2m.config/wt.toml[0m in the current repositor[107m [0m [2m# [step.copy-ignored][0m[107m [0m [2m# exclude = [".cache/", ".turbo/"][0m[107m [0m [2m#[0m-[107m [0m [2m# 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.[0m+[107m [0m [2m# 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.[0m[107m [0m [2m#[0m[107m [0m [2m# ## Aliases[0m[107m [0m [2m#[0mdiff --git a/tests/snapshots/integration__integration_tests__help__help_config_long.snap b/tests/snapshots/integration__integration_tests__help__help_config_long.snapindex 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 [2mwt remove[0m. Override on command line as needed[107m [0m [2m[36m[step.copy-ignored][0m[107m [0m [2mexclude = [] [0m[2m# Additional excludes (e.g., [".cache/", ".turbo/"])[0m-Built-in excludes always apply: VCS metadata directories ([2m.bzr/[0m, [2m.hg/[0m, [2m.jj/[0m, [2m.pijul/[0m, [2m.sl/[0m, [2m.svn/[0m) and tool-state directories ([2m.conductor/[0m, [2m.entire/[0m, [2m.worktrees/[0m). User config and project config exclusions are combined.+Built-in excludes (VCS metadata and tool-state directories) always apply; the [2mwt step copy-ignored[0m docs list them. User config and project config exclusions are combined.[32mAliases[0m@@ -488,14 +489,14 @@ Default template:[1mAppending to the prompt [experimental][0m-[2mtemplate-append[0m 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' [2m{{ user_guidance }}[0m slot — a [2m<user-guidance>[0m block right after [2m<style>[0m. It applies to both commit and squash. Use it for personal preferences without restating the whole template:+[2mtemplate-append[0m adds personal conventions to the commit and squash prompts without restating the whole template:[107m [0m [2m[36m[commit.generation][0m[107m [0m [2mtemplate-append = [0m[2m[32m""[0m[2m[32m"[0m[107m [0m [2m[32m- Explain the rationale in the body, not just the change[0m[107m [0m [2m[32m"[0m[2m[32m""[0m-The project config has a [2mtemplate-append[0m of its own; it renders into a separate [2m<project-guidance>[0m block right after [2m<user-guidance>[0m.+How the fragment renders, and the project-config counterpart: the LLM commits guide.[1m[32mHooks[0m@@ -531,7 +532,7 @@ Name the forge explicitly for SSH aliases or self-hosted instances, where it can[1m[32mCommit-message append [experimental][0m-Project-wide commit-message conventions appended to the LLM commit and squash prompts inside a [2m<project-guidance>[0m block, after the main template's [2m<style>[0m section (and after any user [2m<user-guidance>[0m). Rendered as a minijinja template with the same variables as the main commit template ([2m{{ branch }}[0m, [2m{{ git_diff }}[0m, etc.), so it can reference them directly. The first time the fragment changes, [2mwt[0m prompts the user to approve it — the same one-shot gate as project-defined hooks.+[2mtemplate-append[0m adds project-wide conventions to the LLM commit and squash prompts, shared so every teammate's LLM sees the same style guide:[107m [0m [2m[36m[commit.generation][0m[107m [0m [2mtemplate-append = [0m[2m[32m""[0m[2m[32m"[0m@@ -539,7 +540,7 @@ Project-wide commit-message conventions appended to the LLM commit and squash pr[107m [0m [2m[32m- Reference the relevant issue ID in the body[0m[107m [0m [2m[32m"[0m[2m[32m""[0m-Only [2mtemplate-append[0m 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 [2m[commit.generation] template-append[0m of its own; it renders into a separate [2m<user-guidance>[0m block immediately before this one.+The first time the fragment is used (and whenever it changes), [2mwt[0m prompts the user to approve it — the same one-shot gate as project-defined hooks. Only [2mtemplate-append[0m 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.[1m[32mCopy-ignored excludes[0m@@ -548,7 +549,7 @@ Additional excludes for [2mwt step copy-ignored[0m:[107m [0m [2m[36m[step.copy-ignored][0m[107m [0m [2mexclude = [[0m[2m[32m".cache/"[0m[2m, [0m[2m[32m".turbo/"[0m[2m][0m-Built-in excludes always apply: VCS metadata directories ([2m.bzr/[0m, [2m.hg/[0m, [2m.jj/[0m, [2m.pijul/[0m, [2m.sl/[0m, [2m.svn/[0m) and tool-state directories ([2m.conductor/[0m, [2m.entire/[0m, [2m.worktrees/[0m). User config and project config exclusions are combined.+Built-in excludes (VCS metadata and tool-state directories) always apply; the [2mwt step copy-ignored[0m docs list them. User config and project config exclusions are combined.[1m[32mAliases[0mdiff --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.snapindex 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: [1m[36mwt config state ci-status[0m [36m[OPTIONS][0m [36m[COMMAND][1mDeprecated[0m — the CI status cache is now part of [2mwt config state cache[0m. This subcommand still works but prints a deprecation notice.-Caches GitHub/GitLab CI status for display in [2mwt list[0m.--Requires [2mgh[0m (GitHub) or [2mglab[0m (GitLab) CLI, authenticated. Platform auto-detects from the remote URL; set [2mforge.platform = "github"[0m (or [2m"gitlab"[0m) in [2m.config/wt.toml[0m for SSH host aliases or self-hosted instances. For GitHub Enterprise or self-hosted GitLab, also set [2mforge.hostname[0m.--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.--[1m[32mStatus values[0m-- Status Meaning- ───────── ───────────────────────────────────────- [2mpassed[0m All checks passed- [2mrunning[0m Checks in progress- [2mfailed[0m Checks failed- [2mconflicts[0m PR has merge conflicts- [2mno-ci[0m No checks configured- [2merror[0m Fetch error (rate limit, network, auth)--See [2mwt list[0m CI status for display symbols and colors.+Status values, display symbols, and fetch behavior: [2mwt list[0m CI status.Without a subcommand, runs [2mget[0m for the current branch. Use [2mclear[0m to reset cache for a branch or [2mclear --all[0m 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.snapindex 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:[1m[32mWhat gets copied[0m-All gitignored files are copied by default, except for built-in excluded directories: VCS metadata ([2m.bzr/[0m, [2m.hg/[0m, [2m.jj/[0m, [2m.pijul/[0m, [2m.sl/[0m, [2m.svn/[0m) and tool-state ([2m.conductor/[0m, [2m.entire/[0m, [2m.worktrees/[0m). Tracked files are never touched.+All gitignored files are copied by default, except for built-in excluded directories: VCS metadata ([2m.bzr/[0m, [2m.hg/[0m, [2m.jj/[0m, [2m.pijul/[0m, [2m.sl/[0m, [2m.svn/[0m), tool-state ([2m.conductor/[0m, [2m.entire/[0m, [2m.worktrees/[0m), and nested worktrees. Tracked files are never touched. Discovery handles nested [2m.gitignore[0m files, global excludes, and [2m.git/info/exclude[0m. Existing files in the destination are skipped, so re-running is safe; [2m--force[0m overwrites them.To limit what gets copied further, create [2m.worktreeinclude[0m with gitignore-style patterns. Files must be [1mboth[0m gitignored [1mand[0m in [2m.worktreeinclude[0m:@@ -126,14 +127,6 @@ Without [2m.worktreeinclude[0m, the command is a no-op (it reports that nothinGenerated assets Images, ML models, binaries too large for gitEnvironment files [2m.env[0m (if not generated per-worktree)-[1m[32mFeatures[0m--- Uses copy-on-write (reflink) when available for space-efficient copies-- Handles nested [2m.gitignore[0m files, global excludes, and [2m.git/info/exclude[0m-- Skips existing files by default (safe to re-run)-- [2m--force[0m overwrites existing files in the destination-- Always skips built-in excluded directories — VCS metadata ([2m.bzr/[0m, [2m.hg/[0m, [2m.jj/[0m, [2m.pijul/[0m, [2m.sl/[0m, [2m.svn/[0m) and tool-state ([2m.conductor/[0m, [2m.entire/[0m, [2m.worktrees/[0m) — and nested worktrees-[1m[32mPerformance[0mReflink copies share disk blocks until modified — no data is actually copied. For a 14GB [2mtarget/[0m directory:@@ -175,7 +168,7 @@ Virtual environments contain absolute paths and can't be copied. Use [2muv syncThe [2m.worktreeinclude[0m 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 [2m.worktreeinclude[0m. Pass [2m--require-include[0m to match Claude Code (copy nothing without [2m.worktreeinclude[0m)-- worktrunk uses copy-on-write for large directories like [2mtarget/[0m — potentially 30x faster on macOS, 6x on Linux+- worktrunk uses copy-on-write for large directories like [2mtarget/[0m (see Performance above)- worktrunk runs as a configurable hook in the worktree lifecycle----- stderr -----