Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs: simplify logging and integration guidance (#4576)
Maximilian Roos423960b2afd1
diff --git a/docs/src/content/docs/claude-code.md b/docs/src/content/docs/claude-code.mdindex 9f3926aae..7ad0684a9 100644--- a/docs/src/content/docs/claude-code.md+++ b/docs/src/content/docs/claude-code.md@@ -126,7 +126,7 @@ $ git config worktrunk.state.feature.marker '{"marker":"π¬","set_at":0}' # Di### Agent CLIs without a plugin-Activity tracking is not plugin-specific. The plugins above only call `wt` on their host's session events, and the marker itself is plain git config β so any CLI that can run a command on session lifecycle events drives the same π€/π¬ markers with no worktrunk plugin:+For other agent CLIs, configure these commands to run on session events:| Host event | Command ||---|---|@@ -152,7 +152,7 @@ Claude Code asks for confirmation before a session enters an existing worktree b<code>~/w/myproject.feature-auth !π€ @<span style='color:#0a0'>+42</span> <span style='color:#a00'>-8</span> <span style='color:#0a0'>β3</span> <span style='color:#0a0'>β‘1</span> <span style='color:#0a0'>#3035</span> Opus π 65% <span style='color:#a70'>1.4Γ(10amβ3pm)</span></code>-Worktree state comes from the same cells [`wt list`](/list/) renders; Claude Code's stdin JSON adds the model, the `π 65%` context gauge, and the rate-limit pace notice. [`wt list statusline`](/list/#wt-list-statusline) documents every segment, how the links behave, and the JSON fields behind them.+The statusline shows worktree status, model, context usage, and rate-limit pace. See [`wt list statusline`](/list/#wt-list-statusline) for details.<figure class="demo"><picture>diff --git a/docs/src/content/docs/faq.md b/docs/src/content/docs/faq.mdindex 08b7f2195..93070c18f 100644--- a/docs/src/content/docs/faq.md+++ b/docs/src/content/docs/faq.md@@ -97,9 +97,7 @@ Three verbosity levels. Each is a superset of the previous one.| `-v` | + Info: hook output, alias template variable resolution | β | Debugging hooks/aliases || `-vv` | Same as `-v` | + `trace.log`, `trace.jsonl`, `subprocess.log`, `diagnostic.md` | Filing a bug |-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` 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/#wt-config-state-logs).+With `-vv`, stderr shows the log directory. See [`wt config state logs`](/config/#wt-config-state-logs) for the file formats.`RUST_LOG` overrides the flag baseline when set (`RUST_LOG=debug wt -v` lifts `-v` to debug-on-stderr).diff --git a/docs/src/content/docs/hook.md b/docs/src/content/docs/hook.mdindex f5f566d3e..d34db87cf 100644--- a/docs/src/content/docs/hook.md+++ b/docs/src/content/docs/hook.md@@ -117,7 +117,7 @@ Most hooks don't need `[[hook]]` blocks. Reach for them when there's a dependencTo run a specific hook when user and project both define the same name, use `user:name` or `project:name` syntax.-A `pre-*` hook blocks the command, so both sources run as one pipeline: user commands first, and a failure there skips the project's. A `post-*` hook runs in the background, where each source is its own detached pipeline β they start together, neither waits for the other, and a failure in one leaves the other running. Order within a source is still yours to set with `[[hook]]` blocks; across `post-*` sources there is none. Two `post-*` hooks that write the same file, or run `git` in the same worktree, will race, so put commands that depend on each other in one source.+For `pre-*` hooks, a user-hook failure skips project hooks. For `post-*` hooks, a failure in one source does not stop the other. Concurrent hooks can race when writing the same file or running Git in the same worktree. Commands that depend on each other should use ordered `[[hook]]` blocks within one source.## Template variablesdiff --git a/docs/src/content/docs/list.md b/docs/src/content/docs/list.mdindex 802475784..f5ddd6d93 100644--- a/docs/src/content/docs/list.md+++ b/docs/src/content/docs/list.md@@ -138,7 +138,7 @@ Reuses the [`commit.generation`](/config/#commit) command β the same LLM that<span class="badge-experimental"></span>-Each `[list.custom-columns]` entry in user config adds a column: the key is the header, the template renders each row's cell. Templates read two per-branch namespaces β `{{ vars.* }}`, stored with [`wt config state vars set`](/config/#wt-config-state-vars), and `{{ git.branch.* }}`, the branch's own git config under `branch.<name>.*` (a `jira` key you set yourself, or the git-native `description`) β useful for tracking what each of many (often agent-driven) branches is for:+Each `[list.custom-columns]` entry in user config adds a column. Its key sets the header; its template renders each row's cell. Templates read `{{ vars.* }}`, set with [`wt config state vars set`](/config/#wt-config-state-vars), and `{{ git.branch.* }}`, from `branch.<name>.*` in Git config:```toml# ~/.config/worktrunk/config.tomldiff --git a/plugins/worktrunk/skills/worktrunk/reference/claude-code.md b/plugins/worktrunk/skills/worktrunk/reference/claude-code.mdindex 452b81dec..ac51c7f44 100644--- a/plugins/worktrunk/skills/worktrunk/reference/claude-code.md+++ b/plugins/worktrunk/skills/worktrunk/reference/claude-code.md@@ -118,7 +118,7 @@ $ git config worktrunk.state.feature.marker '{"marker":"π¬","set_at":0}' # Di### Agent CLIs without a plugin-Activity tracking is not plugin-specific. The plugins above only call `wt` on their host's session events, and the marker itself is plain git config β so any CLI that can run a command on session lifecycle events drives the same π€/π¬ markers with no worktrunk plugin:+For other agent CLIs, configure these commands to run on session events:| Host event | Command ||---|---|@@ -144,7 +144,7 @@ Claude Code asks for confirmation before a session enters an existing worktree b<code>~/w/myproject.feature-auth !π€ @<span style='color:#0a0'>+42</span> <span style='color:#a00'>-8</span> <span style='color:#0a0'>β3</span> <span style='color:#0a0'>β‘1</span> <span style='color:#0a0'>#3035</span> Opus π 65% <span style='color:#a70'>1.4Γ(10amβ3pm)</span></code>-Worktree state comes from the same cells [`wt list`](https://worktrunk.dev/list/) renders; Claude Code's stdin JSON adds the model, the `π 65%` context gauge, and the rate-limit pace notice. [`wt list statusline`](https://worktrunk.dev/list/#wt-list-statusline) documents every segment, how the links behave, and the JSON fields behind them.+The statusline shows worktree status, model, context usage, and rate-limit pace. See [`wt list statusline`](https://worktrunk.dev/list/#wt-list-statusline) for details.Add to `~/.claude/settings.json`:diff --git a/plugins/worktrunk/skills/worktrunk/reference/faq.md b/plugins/worktrunk/skills/worktrunk/reference/faq.mdindex a10528385..76543bf91 100644--- a/plugins/worktrunk/skills/worktrunk/reference/faq.md+++ b/plugins/worktrunk/skills/worktrunk/reference/faq.md@@ -93,9 +93,7 @@ Three verbosity levels. Each is a superset of the previous one.| `-v` | + Info: hook output, alias template variable resolution | β | Debugging hooks/aliases || `-vv` | Same as `-v` | + `trace.log`, `trace.jsonl`, `subprocess.log`, `diagnostic.md` | Filing a bug |-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` 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).+With `-vv`, stderr shows the log directory. See [`wt config state logs`](https://worktrunk.dev/config/#wt-config-state-logs) for the file formats.`RUST_LOG` overrides the flag baseline when set (`RUST_LOG=debug wt -v` lifts `-v` to debug-on-stderr).diff --git a/plugins/worktrunk/skills/worktrunk/reference/hook.md b/plugins/worktrunk/skills/worktrunk/reference/hook.mdindex a88ad9cf7..878c66878 100644--- a/plugins/worktrunk/skills/worktrunk/reference/hook.md+++ b/plugins/worktrunk/skills/worktrunk/reference/hook.md@@ -111,7 +111,7 @@ Most hooks don't need `[[hook]]` blocks. Reach for them when there's a dependencTo run a specific hook when user and project both define the same name, use `user:name` or `project:name` syntax.-A `pre-*` hook blocks the command, so both sources run as one pipeline: user commands first, and a failure there skips the project's. A `post-*` hook runs in the background, where each source is its own detached pipeline β they start together, neither waits for the other, and a failure in one leaves the other running. Order within a source is still yours to set with `[[hook]]` blocks; across `post-*` sources there is none. Two `post-*` hooks that write the same file, or run `git` in the same worktree, will race, so put commands that depend on each other in one source.+For `pre-*` hooks, a user-hook failure skips project hooks. For `post-*` hooks, a failure in one source does not stop the other. Concurrent hooks can race when writing the same file or running Git in the same worktree. Commands that depend on each other should use ordered `[[hook]]` blocks within one source.## Template variablesdiff --git a/plugins/worktrunk/skills/worktrunk/reference/list.md b/plugins/worktrunk/skills/worktrunk/reference/list.mdindex c2e71bd45..fa43721d8 100644--- a/plugins/worktrunk/skills/worktrunk/reference/list.md+++ b/plugins/worktrunk/skills/worktrunk/reference/list.md@@ -122,7 +122,7 @@ Reuses the [`commit.generation`](https://worktrunk.dev/config/#commit) command### Custom columns [experimental]-Each `[list.custom-columns]` entry in user config adds a column: the key is the header, the template renders each row's cell. Templates read two per-branch namespaces β `{{ vars.* }}`, stored with [`wt config state vars set`](https://worktrunk.dev/config/#wt-config-state-vars), and `{{ git.branch.* }}`, the branch's own git config under `branch.<name>.*` (a `jira` key you set yourself, or the git-native `description`) β useful for tracking what each of many (often agent-driven) branches is for:+Each `[list.custom-columns]` entry in user config adds a column. Its key sets the header; its template renders each row's cell. Templates read `{{ vars.* }}`, set with [`wt config state vars set`](https://worktrunk.dev/config/#wt-config-state-vars), and `{{ git.branch.* }}`, from `branch.<name>.*` in Git config:```toml# ~/.config/worktrunk/config.tomldiff --git a/skills/worktrunk/reference/claude-code.md b/skills/worktrunk/reference/claude-code.mdindex 452b81dec..ac51c7f44 100644--- a/skills/worktrunk/reference/claude-code.md+++ b/skills/worktrunk/reference/claude-code.md@@ -118,7 +118,7 @@ $ git config worktrunk.state.feature.marker '{"marker":"π¬","set_at":0}' # Di### Agent CLIs without a plugin-Activity tracking is not plugin-specific. The plugins above only call `wt` on their host's session events, and the marker itself is plain git config β so any CLI that can run a command on session lifecycle events drives the same π€/π¬ markers with no worktrunk plugin:+For other agent CLIs, configure these commands to run on session events:| Host event | Command ||---|---|@@ -144,7 +144,7 @@ Claude Code asks for confirmation before a session enters an existing worktree b<code>~/w/myproject.feature-auth !π€ @<span style='color:#0a0'>+42</span> <span style='color:#a00'>-8</span> <span style='color:#0a0'>β3</span> <span style='color:#0a0'>β‘1</span> <span style='color:#0a0'>#3035</span> Opus π 65% <span style='color:#a70'>1.4Γ(10amβ3pm)</span></code>-Worktree state comes from the same cells [`wt list`](https://worktrunk.dev/list/) renders; Claude Code's stdin JSON adds the model, the `π 65%` context gauge, and the rate-limit pace notice. [`wt list statusline`](https://worktrunk.dev/list/#wt-list-statusline) documents every segment, how the links behave, and the JSON fields behind them.+The statusline shows worktree status, model, context usage, and rate-limit pace. See [`wt list statusline`](https://worktrunk.dev/list/#wt-list-statusline) for details.Add to `~/.claude/settings.json`:diff --git a/skills/worktrunk/reference/faq.md b/skills/worktrunk/reference/faq.mdindex a10528385..76543bf91 100644--- a/skills/worktrunk/reference/faq.md+++ b/skills/worktrunk/reference/faq.md@@ -93,9 +93,7 @@ Three verbosity levels. Each is a superset of the previous one.| `-v` | + Info: hook output, alias template variable resolution | β | Debugging hooks/aliases || `-vv` | Same as `-v` | + `trace.log`, `trace.jsonl`, `subprocess.log`, `diagnostic.md` | Filing a bug |-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` 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).+With `-vv`, stderr shows the log directory. See [`wt config state logs`](https://worktrunk.dev/config/#wt-config-state-logs) for the file formats.`RUST_LOG` overrides the flag baseline when set (`RUST_LOG=debug wt -v` lifts `-v` to debug-on-stderr).diff --git a/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.mdindex a88ad9cf7..878c66878 100644--- a/skills/worktrunk/reference/hook.md+++ b/skills/worktrunk/reference/hook.md@@ -111,7 +111,7 @@ Most hooks don't need `[[hook]]` blocks. Reach for them when there's a dependencTo run a specific hook when user and project both define the same name, use `user:name` or `project:name` syntax.-A `pre-*` hook blocks the command, so both sources run as one pipeline: user commands first, and a failure there skips the project's. A `post-*` hook runs in the background, where each source is its own detached pipeline β they start together, neither waits for the other, and a failure in one leaves the other running. Order within a source is still yours to set with `[[hook]]` blocks; across `post-*` sources there is none. Two `post-*` hooks that write the same file, or run `git` in the same worktree, will race, so put commands that depend on each other in one source.+For `pre-*` hooks, a user-hook failure skips project hooks. For `post-*` hooks, a failure in one source does not stop the other. Concurrent hooks can race when writing the same file or running Git in the same worktree. Commands that depend on each other should use ordered `[[hook]]` blocks within one source.## Template variablesdiff --git a/skills/worktrunk/reference/list.md b/skills/worktrunk/reference/list.mdindex c2e71bd45..fa43721d8 100644--- a/skills/worktrunk/reference/list.md+++ b/skills/worktrunk/reference/list.md@@ -122,7 +122,7 @@ Reuses the [`commit.generation`](https://worktrunk.dev/config/#commit) command### Custom columns [experimental]-Each `[list.custom-columns]` entry in user config adds a column: the key is the header, the template renders each row's cell. Templates read two per-branch namespaces β `{{ vars.* }}`, stored with [`wt config state vars set`](https://worktrunk.dev/config/#wt-config-state-vars), and `{{ git.branch.* }}`, the branch's own git config under `branch.<name>.*` (a `jira` key you set yourself, or the git-native `description`) β useful for tracking what each of many (often agent-driven) branches is for:+Each `[list.custom-columns]` entry in user config adds a column. Its key sets the header; its template renders each row's cell. Templates read `{{ vars.* }}`, set with [`wt config state vars set`](https://worktrunk.dev/config/#wt-config-state-vars), and `{{ git.branch.* }}`, from `branch.<name>.*` in Git config:```toml# ~/.config/worktrunk/config.tomldiff --git a/src/cli/mod.rs b/src/cli/mod.rsindex 799e8d211..eeb66b9e3 100644--- a/src/cli/mod.rs+++ b/src/cli/mod.rs@@ -937,7 +937,7 @@ Reuses the [`commit.generation`](/config/#commit) command β the same LLM that### Custom columns [experimental]-Each `[list.custom-columns]` entry in user config adds a column: the key is the header, the template renders each row's cell. Templates read two per-branch namespaces β `{{ vars.* }}`, stored with [`wt config state vars set`](/config/#wt-config-state-vars), and `{{ git.branch.* }}`, the branch's own git config under `branch.<name>.*` (a `jira` key you set yourself, or the git-native `description`) β useful for tracking what each of many (often agent-driven) branches is for:+Each `[list.custom-columns]` entry in user config adds a column. Its key sets the header; its template renders each row's cell. Templates read `{{ vars.* }}`, set with [`wt config state vars set`](/config/#wt-config-state-vars), and `{{ git.branch.* }}`, from `branch.<name>.*` in Git config:```toml# ~/.config/worktrunk/config.toml@@ -1744,7 +1744,7 @@ Most hooks don't need `[[hook]]` blocks. Reach for them when there's a dependencTo run a specific hook when user and project both define the same name, use `user:name` or `project:name` syntax.-A `pre-*` hook blocks the command, so both sources run as one pipeline: user commands first, and a failure there skips the project's. A `post-*` hook runs in the background, where each source is its own detached pipeline β they start together, neither waits for the other, and a failure in one leaves the other running. Order within a source is still yours to set with `[[hook]]` blocks; across `post-*` sources there is none. Two `post-*` hooks that write the same file, or run `git` in the same worktree, will race, so put commands that depend on each other in one source.+For `pre-*` hooks, a user-hook failure skips project hooks. For `post-*` hooks, a failure in one source does not stop the other. Concurrent hooks can race when writing the same file or running Git in the same worktree. Commands that depend on each other should use ordered `[[hook]]` blocks within one source.## Template variablesdiff --git a/tests/snapshots/integration__integration_tests__help__help_list_long.snap b/tests/snapshots/integration__integration_tests__help__help_list_long.snapindex e0e099920..b90a0fbe7 100644--- a/tests/snapshots/integration__integration_tests__help__help_list_long.snap+++ b/tests/snapshots/integration__integration_tests__help__help_list_long.snap@@ -202,7 +202,7 @@ Reuses the [2mcommit.generation[0m command β the same LLM that generates com[32mCustom columns [experimental][0m-Each [2m[list.custom-columns][0m entry in user config adds a column: the key is the header, the template renders each row's cell. Templates read two per-branch namespaces β [2m{{ vars.* }}[0m, stored with [2mwt config state vars set[0m, and [2m{{ git.branch.* }}[0m, the branch's own git config under [2mbranch.<name>.*[0m (a [2mjira[0m key you set yourself, or the git-native [2mdescription[0m) β useful for tracking what each of many (often agent-driven) branches is for:+Each [2m[list.custom-columns][0m entry in user config adds a column. Its key sets the header; its template renders each row's cell. Templates read [2m{{ vars.* }}[0m, set with [2mwt config state vars set[0m, and [2m{{ git.branch.* }}[0m, from [2mbranch.<name>.*[0m in Git config:[107m [0m [2m# ~/.config/worktrunk/config.toml[0m[107m [0m [2m[36m[list.custom-columns.Ticket][0mdiff --git a/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap b/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snapindex 4ab7ec7ee..cb68cfada 100644--- a/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap+++ b/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap@@ -237,12 +237,10 @@ are cached until the branch's diff changes.[32mCustom columns [experimental][0m-Each [2m[list.custom-columns][0m entry in user config adds a column: the key is the-header, the template renders each row's cell. Templates read two per-branch-namespaces β [2m{{ vars.* }}[0m, stored with [2mwt config state vars set[0m, and [2m{{-[2mgit.branch.* }}[0m, the branch's own git config under [2mbranch.<name>.*[0m (a [2mjira[0m key-you set yourself, or the git-native [2mdescription[0m) β useful for tracking what each- of many (often agent-driven) branches is for:+Each [2m[list.custom-columns][0m entry in user config adds a column. Its key sets the+header; its template renders each row's cell. Templates read [2m{{ vars.* }}[0m, set+with [2mwt config state vars set[0m, and [2m{{ git.branch.* }}[0m, from [2mbranch.<name>.*[0m in+Git config:[107m [0m [2m# ~/.config/worktrunk/config.toml[0m[107m [0m [2m[36m[list.custom-columns.Ticket][0m