Skip to content

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

feat(statusline): show used % instead of pace above 90% of the rate limit (#3057)

Maximilian Roos8f44e986365d
diff --git a/docs/content/claude-code.md b/docs/content/claude-code.md
index 7f58af1f0..b2c2ec82d 100644
--- a/docs/content/claude-code.md
+++ b/docs/content/claude-code.md
@@ -111,7 +111,7 @@ On session exit the worktree is offered for removal via the `WorktreeRemove` hoo
<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>
-When Claude Code provides context window usage via stdin JSON, a moon phase gauge appears (πŸŒ•β†’πŸŒ‘ as context fills). A yellow `<n>Γ—(<window>)` segment appears when Claude's 5-hour or weekly rate limit is on track to be hit before reset β€” `1.4Γ—(10am–3pm)` reads as 1.4Γ— the pace that would exactly fill that window.
+When Claude Code provides context window usage via stdin JSON, a moon phase gauge appears (πŸŒ•β†’πŸŒ‘ as context fills). A yellow `<n>Γ—(<window>)` segment appears when Claude's 5-hour or weekly rate limit is on track to be hit before reset β€” `1.4Γ—(10am–3pm)` reads as 1.4Γ— the pace that would exactly fill that window. Above 90% used it shows usage instead of pace β€” `93%(10am–3pm)` β€” near the cap, how much is left matters more than how fast it's going.
<figure class="demo">
<picture>
diff --git a/skills/worktrunk/reference/claude-code.md b/skills/worktrunk/reference/claude-code.md
index 45f41a26a..b26761841 100644
--- a/skills/worktrunk/reference/claude-code.md
+++ b/skills/worktrunk/reference/claude-code.md
@@ -113,7 +113,7 @@ On session exit the worktree is offered for removal via the `WorktreeRemove` hoo
<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>
-When Claude Code provides context window usage via stdin JSON, a moon phase gauge appears (πŸŒ•β†’πŸŒ‘ as context fills). A yellow `<n>Γ—(<window>)` segment appears when Claude's 5-hour or weekly rate limit is on track to be hit before reset β€” `1.4Γ—(10am–3pm)` reads as 1.4Γ— the pace that would exactly fill that window.
+When Claude Code provides context window usage via stdin JSON, a moon phase gauge appears (πŸŒ•β†’πŸŒ‘ as context fills). A yellow `<n>Γ—(<window>)` segment appears when Claude's 5-hour or weekly rate limit is on track to be hit before reset β€” `1.4Γ—(10am–3pm)` reads as 1.4Γ— the pace that would exactly fill that window. Above 90% used it shows usage instead of pace β€” `93%(10am–3pm)` β€” near the cap, how much is left matters more than how fast it's going.
Add to `~/.claude/settings.json`:
diff --git a/src/cli/list.rs b/src/cli/list.rs
index f12046f9d..f46d7b201 100644
--- a/src/cli/list.rs
+++ b/src/cli/list.rs
@@ -22,7 +22,7 @@ pub enum ListSubcommand {
- `.rate_limits.{five_hour,seven_day}.used_percentage` β€” rate-limit window usage (0–100)
- `.rate_limits.{five_hour,seven_day}.resets_at` β€” window reset time (Unix epoch seconds)
-The pace segment appears only when usage is likely to hit a rate limit before its window resets, and shows the higher-risk window: `2.9Γ—(Tue–Tue 5pm)` reads as 2.9Γ— the pace that would exactly fill that window. "Likely" is a Bayesian forecast; early-window bursts don't trigger it. With `-vv`, each window's inputs and projection are logged to `.git/wt/logs/trace.log`.
+The pace segment appears only when usage is likely to hit a rate limit before its window resets, and shows the higher-risk window: `2.9Γ—(Tue–Tue 5pm)` reads as 2.9Γ— the pace that would exactly fill that window. Above 90% used it shows usage instead of pace β€” `93%(Tue–Tue 5pm)` β€” near the cap, how much is left matters more than how fast it's going. "Likely" is a Bayesian forecast; early-window bursts don't trigger it. With `-vv`, each window's inputs and projection are logged to `.git/wt/logs/trace.log`.
"#)]
Statusline {
/// Output format (table, json, claude-code)
diff --git a/src/commands/statusline.rs b/src/commands/statusline.rs
index 9956ae6fc..d9be84c2d 100644
--- a/src/commands/statusline.rs
+++ b/src/commands/statusline.rs
@@ -227,6 +227,13 @@ const SEVEN_DAY_SECS: i64 = 7 * 86400;
/// Show the rate-limit segment when P(over) crosses this threshold.
const RATE_LIMIT_P_THRESHOLD: f64 = 0.50;
+/// Above this usage (in percent), display used % instead of pace.
+///
+/// Close to the cap, proximity beats velocity: pace answers "will the limit
+/// be hit?", but once usage is nearly there that's all but settled, and "how
+/// much is left?" becomes the actionable number.
+const RATE_LIMIT_NEAR_CAP_PCT: f64 = 90.0;
+
/// Extract any present rate-limit windows from the Claude Code JSON.
///
/// Both windows are independently optional: subscribers see `rate_limits`
@@ -492,6 +499,10 @@ fn select_binding_window(
/// posterior `m₁` is only used by [`p_over`] to decide whether to show β€”
/// for the *displayed* number, the raw measurement is more honest, more
/// transparent, and tracks bursts naturally.
+///
+/// Above [`RATE_LIMIT_NEAR_CAP_PCT`] used, the shape becomes
+/// `<used>%(<window_bounds>)` β€” e.g. `93%(10am–3pm)` β€” showing how close
+/// the limit is rather than how fast it's being approached.
fn format_rate_limit_segment(readings: &[RateLimitReading], now_unix: i64) -> Option<String> {
let r = select_binding_window(readings, now_unix)?;
let u = r.used_percentage / 100.0;
@@ -500,7 +511,11 @@ fn format_rate_limit_segment(readings: &[RateLimitReading], now_unix: i64) -> Op
// returns a reading whose `P(over) β‰₯ 0.5`, which requires `t > 0`.
let elapsed = (now_unix - (r.resets_at - r.window_secs)) as f64 / r.window_secs as f64;
let t = elapsed.clamp(0.001, 1.0);
- let pace = u / t;
+ let reading = if r.used_percentage > RATE_LIMIT_NEAR_CAP_PCT {
+ format!("{:.0}%", r.used_percentage)
+ } else {
+ format!("{:.1}Γ—", u / t)
+ };
let bounds = format_window_bounds(
r.resets_at,
r.window_secs,
@@ -511,7 +526,7 @@ fn format_rate_limit_segment(readings: &[RateLimitReading], now_unix: i64) -> Op
// the warning. Unlike informational segments where color picks out one
// sub-glyph (`@+1` green, `?` cyan), here the entire string is the
// "you should look at this" signal.
- Some(color_print::cformat!("<yellow>{pace:.1}Γ—({bounds})</>"))
+ Some(color_print::cformat!("<yellow>{reading}({bounds})</>"))
}
/// Format context usage as a moon phase gauge.
@@ -1395,6 +1410,30 @@ mod tests {
);
}
+ #[test]
+ fn test_format_rate_limit_segment_near_cap_shows_used_pct() {
+ let now = 1_700_000_000_i64;
+ // Above 90% used the displayed number switches from pace to used %:
+ // remaining headroom, not speed, is the actionable quantity there.
+ let r = make_reading(95.0, 0.60, &FIVE_HOUR_PRIORS, now, FIVE_HOUR_SECS);
+ let out =
+ format_rate_limit_segment(std::slice::from_ref(&r), now).expect("should be visible");
+ let visible = out.ansi_strip();
+ assert!(
+ visible.starts_with("95%(") && visible.ends_with(')'),
+ "unexpected format: {visible:?}"
+ );
+ // Exactly 90% stays on the pace form β€” the switch is strictly above.
+ let r = make_reading(90.0, 0.60, &FIVE_HOUR_PRIORS, now, FIVE_HOUR_SECS);
+ let out =
+ format_rate_limit_segment(std::slice::from_ref(&r), now).expect("should be visible");
+ let visible = out.ansi_strip();
+ assert!(
+ visible.starts_with("1.5Γ—("),
+ "unexpected format: {visible:?}"
+ );
+ }
+
#[test]
fn test_format_rate_limit_segment_hidden() {
let now = 1_700_000_000_i64;
diff --git a/tests/snapshots/integration__integration_tests__statusline__rate_limit_5h_at_limit.snap b/tests/snapshots/integration__integration_tests__statusline__rate_limit_5h_at_limit.snap
index b1c81d179..a4e6c1e0d 100644
--- a/tests/snapshots/integration__integration_tests__statusline__rate_limit_5h_at_limit.snap
+++ b/tests/snapshots/integration__integration_tests__statusline__rate_limit_5h_at_limit.snap
@@ -2,4 +2,4 @@
source: tests/integration_tests/statusline.rs
expression: out
---
-[PATH] main ^| Opus πŸŒ• 42% 1.7Γ—(10am–3pm)
+[PATH] main ^| Opus πŸŒ• 42% 100%(10am–3pm)
diff --git a/tests/snapshots/integration__integration_tests__statusline__rate_limit_5h_with_minutes.snap b/tests/snapshots/integration__integration_tests__statusline__rate_limit_5h_with_minutes.snap
index fc69aa06d..d3ba196fc 100644
--- a/tests/snapshots/integration__integration_tests__statusline__rate_limit_5h_with_minutes.snap
+++ b/tests/snapshots/integration__integration_tests__statusline__rate_limit_5h_with_minutes.snap
@@ -2,4 +2,4 @@
source: tests/integration_tests/statusline.rs
expression: out
---
-[PATH] main ^| Opus πŸŒ• 42% 1.1Γ—(8:30am–1:30pm)
+[PATH] main ^| Opus πŸŒ• 42% 95%(8:30am–1:30pm)