Skip to content

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.md
index 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.md
index 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.md
index 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 dependenc
To 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 variables
diff --git a/docs/src/content/docs/list.md b/docs/src/content/docs/list.md
index 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.toml
diff --git a/plugins/worktrunk/skills/worktrunk/reference/claude-code.md b/plugins/worktrunk/skills/worktrunk/reference/claude-code.md
index 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.md
index 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.md
index 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 dependenc
To 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 variables
diff --git a/plugins/worktrunk/skills/worktrunk/reference/list.md b/plugins/worktrunk/skills/worktrunk/reference/list.md
index 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.toml
diff --git a/skills/worktrunk/reference/claude-code.md b/skills/worktrunk/reference/claude-code.md
index 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.md
index 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.md
index 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 dependenc
To 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 variables
diff --git a/skills/worktrunk/reference/list.md b/skills/worktrunk/reference/list.md
index 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.toml
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 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 dependenc
To 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 variables
diff --git a/tests/snapshots/integration__integration_tests__help__help_list_long.snap b/tests/snapshots/integration__integration_tests__help__help_list_long.snap
index 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 commit.generation command β€” the same LLM that generates com
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, 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, and {{ git.branch.* }}, from branch.<name>.* in Git config:
  # ~/.config/worktrunk/config.toml
  [list.custom-columns.Ticket]
diff --git a/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap b/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap
index 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.
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, 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, and {{ git.branch.* }}, from branch.<name>.* in
+Git config:
  # ~/.config/worktrunk/config.toml
  [list.custom-columns.Ticket]