Repository navigation
feat(statusline): add Claude Code rate-limit pace segment - #2899
Conversation
## Motivation
Claude Code exposes `rate_limits.{five_hour,seven_day}.{used_percentage,resets_at}` on its statusLine JSON. Without UI for it, users only learn they're over-pacing once Claude throttles them mid-task. We want a single-glance warning that surfaces *before* throttling, and only when continuing at the current pace would actually blow the cap — not whenever raw `u/t > 1`, which fires constantly on early-window bursts.
## Change
A new yellow segment `1.3×pace(10am–3pm)` appears in the `--format=claude-code` statusline when either rate-limit window is meaningfully likely to be hit before reset. For the weekly window it formats as `1.9×pace(Mon–Mon 3pm)`. Only the worse-projected of the two windows is shown; the segment is hidden entirely when both are safe.
The trigger is a Bayesian forecast on `P(final ≥ 100%)`: cumulative consumption modelled as Brownian-with-drift, prior on the long-run rate pulled toward "most windows finish under" (`m₀ = 0.8`), posterior predictive Gaussian. Segment appears only when `P > 50%`. Early-window noise (e.g., 5% used at 3% elapsed → naive `u/t = 1.67` but P(over) = 42%) stays correctly hidden.
The *displayed* number is the naive `u/t` ratio (one decimal), not the Bayesian posterior — the user sees an honest measurement of "what you've actually done over the elapsed window," while the smoothing stays internal where it decides visibility. Window bounds in parentheses locate which 5h or weekly window the pace was measured over.
Adjacent delimiter cleanup in the same file, so the new segment fits the existing line:
- Drop the vestigial `| ` prefix on the model segment — the two-space inter-segment separator already does the job
- Drop the space inside `🌕 42%` → `🌕42%`, matching the other prefix-char segments (`@+1`, `↓1`, `?^|`)
- En-dash inside the parenthetical (`10am–3pm`, not `10am-3pm`) — typographically correct for a range, visually distinct from the ASCII `-3` used for line deletions
## Tests
Eight file snapshot tests cover hidden/well-paced, 5h binding, the `:mm` time branch, 5h at-limit edge, 7d binding (day+time form), both-windows-pick-worse, dirty-worktree combined state, and narrow-width segment drop. Time and timezone are pinned via the existing `WORKTRUNK_TEST_EPOCH` env hook plus a per-subprocess `TZ=UTC`.
23 new unit tests: erf reference-value accuracy, standard-normal CDF, `p_over` boundaries + monotonicity + six Python-prototype calibration points, `format_clock`, `format_window_bounds` for both window kinds, `select_binding_window` selection logic across five scenarios, `format_rate_limit_segment` shape, and `parse_rate_limits` JSON parsing across four cases.
worktrunk-bot
left a comment
There was a problem hiding this comment.
Strong math, thorough tests. Two doc gaps worth fixing before merge:
Stale statusline example. docs/content/claude-code.md:114 (and its skill mirror at skills/worktrunk/reference/claude-code.md:114) shows | Opus 🌔 65%. This PR drops the | prefix from the model segment and the space between emoji and percent (🌔65%), so the inline <code>…</code> example now diverges from real output. test_docs_are_in_sync won't catch it — claude-code.md is a non-command page (category 2 in docs/CLAUDE.md), so the example HTML is authored, not regenerated.
New segment is not mentioned. The Statusline section says "a moon phase gauge appears" when context window data is present, but says nothing about the new yellow <n>×pace(<window>) segment, when it fires, or that the color signals over-pace. A one-line addition (and ideally extending the example HTML to show a 1.4×pace(10am–3pm) segment) keeps the doc in sync with shipped behavior.
Happy to push a commit updating both docs if helpful.
Address review on #2899: the inline statusline example showed the old '| Opus 🌔 65%' form, and the new yellow <n>×pace(<window>) segment wasn't mentioned. Update the example to current output (drop '| ', collapse the moon-percent space, add a 1.4×pace(10am–3pm) segment in amber) and add one sentence describing when it fires. Edit lands in the primary docs/content/claude-code.md; the skill mirror at skills/worktrunk/reference/claude-code.md is auto-synced by test_docs_are_in_sync per the category-2 (non-command-page) workflow.
v0.54.0.
`cargo semver-checks` reports 3 breaking library API changes
(`shell_exec::set_output_log_available` removed,
`SUBPROCESS_TERMINAL_TARGET` removed, `Deprecations::{pre_start,
post_start}` removed) — none of them intentional API, but they force
minor pre-1.0.
Headline user-visible changes:
- New rate-limit pace segment in the Claude Code statusline (#2899,
#2911).
- `wt step prune` streams removals and skips unapproved hooks instead of
prompting mid-scan; default `--min-age` raised 1h → 1d (#2908, #2910,
#2886).
- `-vv` no longer floods stderr — debug routes to `trace.log`, Info
stays on stderr; raw subprocess sink renamed `output.log` →
`subprocess.log`; `RUST_LOG` honored at every verbosity level (#2892,
#2901, #2913).
- Data-safety fixes across merge / remove / prune lifecycle (#2870).
- Legacy shell-wrapper deprecation warning (#2880).
Full CHANGELOG entry in this PR.
worktrunk 0.54.0 Created-by: HarmonybrewBot Commit-by: HarmonybrewBot Merged-by: HarmonybrewBot Description: Created by `brew bump` --- Created with `brew bump-formula-pr`.<details> <summary>release notes</summary> <pre>## Release Notes ### Improved - **Rate-limit pace segment in the Claude Code statusline**: `wt list statusline --format=claude-code` now surfaces a yellow `1.3×pace(10am–3pm)` segment when Claude Code's reported five-hour or seven-day rate-limit window is on track to be hit before its reset. The segment uses a Bayesian forecast on `P(final ≥ 100%)` so early-window bursts (e.g., 5% used at 3% elapsed) don't trigger spurious warnings — only the worse-projected of the two windows is shown, and the segment is hidden entirely when both are safe. The clock format inside the parentheses honors `LC_ALL` / `LC_TIME` / `LANG`: `en_US`/`en_PH`/`en_CA` get 12-hour (`10am–3pm`), everything else (including unset and `C`/`POSIX`) gets 24-hour (`10:00–15:00`). ([#2899](max-sixty/worktrunk#2899), [#2911](max-sixty/worktrunk#2911)) - **`wt step prune` streams removals and never prompts mid-scan**: Prune now bundles integration, removability, and age checks into a single parallel pass and starts removing candidates as soon as they qualify, instead of batching the scan and acting at the end. Dirty / locked / primary worktrees drop out before the age check, so a young + dirty + integrated worktree no longer surfaces as `Skipped (younger than 1d)` — the `(younger than X)` message now fires only when the worktree would actually have been pruned. With `--yes`, every project command is auto-approved as before; without `--yes`, a candidate whose hooks include an unapproved project command is SKIPPED with `(approval required)` rather than aborting the scan with an inline prompt the streaming structure couldn't accommodate. The end-of-run hint enumerates the unapproved hook templates from the invoking worktree's config and emits one copy-pasteable `wt -C <path> remove` line per skipped candidate, annotating candidates whose own `.config/wt.toml` differs from the invoking worktree's. ([#2908](max-sixty/worktrunk#2908), [#2910](max-sixty/worktrunk#2910)) - **`wt step prune` default `--min-age` raised from 1h to 1d**: A worktree just created from the default branch looks "merged" because its branch still points at the same commit; a one-day floor keeps an unattended prune from sweeping it up before its owner starts work. Explicit `--min-age=0s` or any other value is unchanged. ([#2886](max-sixty/worktrunk#2886)) - **Legacy shell-wrapper deprecation warning**: Users who upgrade `wt` without restarting their shell still run the previous release's wrapper, which sets only `WORKTRUNK_DIRECTIVE_FILE` instead of the new split `WORKTRUNK_DIRECTIVE_CD_FILE` / `WORKTRUNK_DIRECTIVE_EXEC_FILE` pair. That fallback used to be silent; `wt` now emits a one-shot per-process warning hinting at `wt config shell install`. bash, zsh, fish, and PowerShell pick up the new wrapper on the next shell restart; nushell is the one shell where users must rerun `wt config shell install nu` because its wrapper is a static file. ([#2880](max-sixty/worktrunk#2880)) - **`-vv` no longer floods stderr; raw subprocess sink renamed to `subprocess.log`**: A `-vv` invocation used to spray ~15K lines of stderr per command, forcing a redirect to a file even though `trace.log` already mirrored most of it. The debug-level `log::*` pipeline now writes to `.git/wt/logs/trace.log` at `-vv`; Info-level records (hook output, template expansions, the `Tracing to …` pointer) stay on stderr at every verbosity level. The companion raw-subprocess-bytes file is renamed from `output.log` to `subprocess.log` — the prior name read as "stuff `wt` printed" but actually held uncapped multi-MB subprocess bodies (`git log -p`, patch-id pipelines). `RUST_LOG` is now honored at every verbosity level: `wt -v` and `wt -vv` previously hardcoded Info / Debug and silently dropped any `RUST_LOG` directive (`RUST_LOG=trace wt -vv` was capped at Debug, `RUST_LOG=worktrunk=trace wt -v` was ignored); all three levels now flow through one builder shape with `RUST_LOG` layered on top of the flag baseline. ([#2892](max-sixty/worktrunk#2892), [#2901](max-sixty/worktrunk#2901), [#2913](max-sixty/worktrunk#2913)) ### Fixed - **Data-safety across the worktree merge / remove / prune lifecycle**: Five TOCTOU and scoping fixes. `wt merge` and `wt remove` revalidate cleanliness and branch integration *after* `pre-remove` hooks run, so a hook (or concurrent process) that dirties the worktree or advances the branch can no longer trash the directory or trigger `git branch -D` against the stale pre-hook decision. The background-removal path does the same revalidation and fails closed for submodule worktrees on the fallback path instead of forcing. `wt step prune` runs its rename-failure fallback `git branch -d` synchronously under the write guard for non-current worktrees (no more race against live integration readers on `.git/config`), scopes hook approval to the worktrees it will actually remove (an unrelated unapproved hook can no longer abort a non-interactive prune), and prunes the stale metadata of detached worktrees whose directory was deleted outside Worktrunk. ([#2870](max-sixty/worktrunk#2870)) ### Documentation - **`-v` / `-vv` help and FAQ**: The `-v` help text is split out from its 150-character parenthetical, and `docs/content/faq.md` gains a "What does `-v` / `-vv` do?" section with a three-level table. ([#2913](max-sixty/worktrunk#2913)) - **Hook docs and `pre-start` docstring**: The `pre_create` field docstring in `HooksConfig` (user-visible via generated JSON schema) read "Commands to execute before worktree creation"; `pre-start` actually runs *after* worktree creation, blocking. Restored the correct wording. The `docs/content/extending.md` overview is reworked to read more cleanly: parallel three-paragraph intro for hooks / aliases / custom subcommands, fewer em-dashes, and the Reference section's table no longer duplicates content covered in prose. ([#2879](max-sixty/worktrunk#2879), [#2912](max-sixty/worktrunk#2912)) ### Internal - **Migrated logging from `env_logger` to `tracing-subscriber`**: A layered subscriber routes records structurally by target and verbosity. Existing `log::*` callers are bridged into `tracing` via `tracing_log::LogTracer`. `[wt-trace]` records emit as typed structured fields with a single formatter rendering the wire shape, so the grammar lives in one place instead of being duplicated across every emit site. - **`UncommittedChanges` error renders dirty files in the canonical gutter**, matching `ConflictingChanges` and the project's `format_with_gutter()` convention. ([#2887](max-sixty/worktrunk#2887)) ## Install worktrunk 0.54.0 ### Install prebuilt binaries via shell script ```sh curl --proto '=https' --tlsv1.2 -LsSf https://github.com/max-sixty/worktrunk/releases/download/v0.54.0/worktrunk-installer.sh | sh && wt config shell install ``` ### Install prebuilt binaries via powershell script ```sh powershell -ExecutionPolicy Bypass -c "irm https://github.com/max-sixty/worktrunk/releases/download/v0.54.0/worktrunk-installer.ps1 | iex"; git-wt config shell install ``` ### Install prebuilt binaries via Homebrew ```sh brew install worktrunk && wt config shell install ``` ## Download worktrunk 0.54.0 | File | Platform | Checksum | |--------|----------|----------| | [worktrunk-aarch64-apple-darwin.tar.xz](https://github.com/max-sixty/worktrunk/releases/download/v0.54.0/worktrunk-aarch64-apple-darwin.tar.xz) | Apple Silicon macOS | [checksum](https://github.com/max-sixty/worktrunk/releases/download/v0.54.0/worktrunk-aarch64-apple-darwin.tar.xz.sha256) | | [worktrunk-x86_64-apple-darwin.tar.xz](https://github.com/max-sixty/worktrunk/releases/download/v0.54.0/worktrunk-x86_64-apple-darwin.tar.xz) | Intel macOS | [checksum](https://github.com/max-sixty/worktrunk/releases/download/v0.54.0/worktrunk-x86_64-apple-darwin.tar.xz.sha256) | | [worktrunk-x86_64-pc-windows-msvc.zip](https://github.com/max-sixty/worktrunk/releases/download/v0.54.0/worktrunk-x86_64-pc-windows-msvc.zip) | x64 Windows | [checksum](https://github.com/max-sixty/worktrunk/releases/download/v0.54.0/worktrunk-x86_64-pc-windows-msvc.zip.sha256) | | [worktrunk-aarch64-unknown-linux-musl.tar.xz](https://github.com/max-sixty/worktrunk/releases/download/v0.54.0/worktrunk-aarch64-unknown-linux-musl.tar.xz) | ARM64 MUSL Linux | [checksum](https://github.com/max-sixty/worktrunk/releases/download/v0.54.0/worktrunk-aarch64-unknown-linux-musl.tar.xz.sha256) | | [worktrunk-x86_64-unknown-linux-musl.tar.xz](https://github.com/max-sixty/worktrunk/releases/download/v0.54.0/worktrunk-x86_64-unknown-linux-musl.tar.xz) | x64 MUSL Linux | [checksum](https://github.com/max-sixty/worktrunk/releases/download/v0.54.0/worktrunk-x86_64-unknown-linux-musl.tar.xz.sha256) | ### Install via Cargo ```sh cargo install worktrunk && wt config shell install ``` ### Install via Winget (Windows) ```sh winget install max-sixty.worktrunk && git-wt config shell install ``` ### Install via AUR (Arch Linux) ```sh paru worktrunk-bin && wt config shell install ``` </pre> <p>View the full release notes at <a href="https://github.com/max-sixty/worktrunk/releases/tag/v0.54.0">https://github.com/max-sixty/worktrunk/releases/tag/v0.54.0</a>.</p> </details> <hr> See merge request: Harmonybrew/homebrew-core!7938
Motivation
Claude Code exposes
rate_limits.{five_hour,seven_day}.{used_percentage,resets_at}on its statusLine JSON. Without UI for it, users only learn they're over-pacing once Claude throttles them mid-task. We want a single-glance warning that surfaces before throttling, and only when continuing at the current pace would actually blow the cap — not whenever rawu/t > 1, which fires constantly on early-window bursts.Change
A new yellow segment
1.3×pace(10am–3pm)appears in the--format=claude-codestatusline when either rate-limit window is meaningfully likely to be hit before reset. For the weekly window it formats as1.9×pace(Mon–Mon 3pm). Only the worse-projected of the two windows is shown; the segment is hidden entirely when both are safe.The trigger is a Bayesian forecast on
P(final ≥ 100%): cumulative consumption modelled as Brownian-with-drift, prior on the long-run rate pulled toward "most windows finish under" (m₀ = 0.8), posterior predictive Gaussian. Segment appears only whenP > 50%. Early-window noise (e.g., 5% used at 3% elapsed → naiveu/t = 1.67but P(over) = 42%) stays correctly hidden.The displayed number is the naive
u/tratio (one decimal), not the Bayesian posterior — the user sees an honest measurement of "what you've actually done over the elapsed window," while the smoothing stays internal where it decides visibility. Window bounds in parentheses locate which 5h or weekly window the pace was measured over.Adjacent delimiter cleanup in the same file, so the new segment fits the existing line:
|prefix on the model segment — the two-space inter-segment separator already does the job🌕 42%→🌕42%, matching the other prefix-char segments (@+1,↓1,?^|)10am–3pm, not10am-3pm) — typographically correct for a range, visually distinct from the ASCII-3used for line deletionsTests
Eight file snapshot tests cover hidden/well-paced, 5h binding, the
:mmtime branch, 5h at-limit edge, 7d binding (day+time form), both-windows-pick-worse, dirty-worktree combined state, and narrow-width segment drop. Time and timezone are pinned via the existingWORKTRUNK_TEST_EPOCHenv hook plus a per-subprocessTZ=UTC.23 new unit tests: erf reference-value accuracy, standard-normal CDF,
p_overboundaries + monotonicity + six Python-prototype calibration points,format_clock,format_window_boundsfor both window kinds,select_binding_windowselection logic across five scenarios,format_rate_limit_segmentshape, andparse_rate_limitsJSON parsing across four cases.