Add a static `display.customLine` config field that renders a user-defined
phrase (max 80 chars) in Claude orange on the project line, joined with
the standard │ separator.
- config.ts: add customLine to HudConfig.display with validation
- colors.ts: add claudeOrange() using 256-color (38;5;208)
- project.ts: append customLine to expanded mode project line
- session-line.ts: append customLine to compact mode parts
- setup.md: add "Custom line" option to Step 4
- configure.md: add Q5 Custom Line to both Flow A and Flow B
* fix: render showSpeed and showDuration in expanded layout
These config options were only implemented in the compact layout
(renderSessionLine in session-line.ts). When using lineLayout: "expanded",
enabling display.showSpeed or display.showDuration had no effect.
This adds both options to renderProjectLine (the expanded layout's
project line), matching the compact layout behavior:
- showSpeed: output token speed (tok/s)
- showDuration: session duration timer
Fixes#221
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* test: add renderProjectLine tests for showSpeed and showDuration
Address Copilot review feedback by adding test coverage for the
new expanded layout rendering of speed and duration:
- duration shown when showDuration is true
- duration omitted when showDuration is false
- speed code path doesn't crash when showSpeed is true
- speed omitted when showSpeed is false
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* test: cover expanded layout speed rendering
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Jarrod Watts <jarrod@cubelabs.xyz>
* fix: detect macOS and show restart hint when HUD initializes without stdin (closes#213)
* fix: prompt user to restart Claude Code after config write for HUD setup
* fix: update assertion to check if output starts with initializing message
* Align restart messaging in docs
---------
Co-authored-by: Jarrod Watts <jarrod@cubelabs.xyz>
* fix: clarify usage time format — show 'resets in' instead of ambiguous elapsed/total
Fixes#240
The format `(2h 43m / 5h)` was confusing because it mimics the common
`(elapsed / total)` pattern, but actually showed time remaining until
reset. Changed to `(resets in 2h 43m)` which is unambiguous.
Before: `Usage █░░░░░░░░░ 7% (2h 43m / 5h)`
After: `Usage █░░░░░░░░░ 7% (resets in 2h 43m)`
* test: cover usage reset wording
---------
Co-authored-by: d 🔹 <258577966+voidborne-d@users.noreply.github.com>
Co-authored-by: Jarrod Watts <jarrod@cubelabs.xyz>
Users running Claude Code with a custom config directory (e.g.
CLAUDE_CONFIG_DIR=~/.claude-work) had the plugin installed to that
directory, but /claude-hud:setup always looked in the hardcoded
~/.claude path, causing it to report the plugin as not installed.
Replace all hardcoded ~/.claude/ references with
${CLAUDE_CONFIG_DIR:-$HOME/.claude} so that setup correctly resolves
the plugin cache, settings.json, and config.json under whatever config
directory Claude Code is using.
Also fix glob-inside-quotes bug in the temp_local_* cleanup commands
(quotes prevented wildcard expansion).
Co-authored-by: dennis <dennis@brevitydata.net>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix: detect terminal width via stderr when stdout is piped
When Claude Code runs the statusLine as a subprocess, stdout is captured
(piped), so process.stdout.columns is undefined. With no terminal width,
long lines aren't wrapped by the HUD — the terminal wraps them silently
instead. Claude Code counts \n characters to determine how many lines to
erase on the next render, so the physical line count diverges from what
Claude Code expects. Over successive renders the cursor drifts upward into
the scrollback buffer, causing the terminal to jump to the top on every
tool execution (https://github.com/jarrodwatts/claude-hud/issues/209).
Fix: fall back to process.stderr.columns before the COLUMNS env var.
When the statusLine subprocess is spawned, only stdout is redirected;
stderr remains connected to the real TTY and returns the correct width.
With accurate width, lines are properly wrapped in the HUD output and
Claude Code's line count stays consistent.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* chore: drop dist artifacts and cover stderr width
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: Jarrod Watts <jarrod@cubelabs.xyz>
* fix: scale progress bars based on terminal width
Resolves#231
Progress bars (coloredBar/quotaBar) were hardcoded to width 10,
causing line wrapping in narrow terminals.
Now bars scale dynamically based on process.stdout.columns:
- Wide terminal (>=100 cols): width 10 (default)
- Medium terminal (60-99 cols): width 6
- Narrow terminal (<60 cols): width 4
Affected files:
- src/render/session-line.ts (context bar + usage bars)
- src/render/lines/identity.ts (context bar in expanded layout)
- src/render/lines/usage.ts (quota bars in expanded layout)
* fix: also check COLUMNS env var as fallback for bar width
For cross-platform compatibility (zsh, macOS, Windows),
getBarWidth() now also checks process.env.COLUMNS when
process.stdout.columns is unavailable (non-TTY, piped output).
* refactor: extract getAdaptiveBarWidth to shared utility
- Remove duplicated getBarWidth() from 3 render files
- Add src/utils/terminal.ts with exported getAdaptiveBarWidth()
- Add Math.floor() for consistency with getTerminalWidth()
- All 3 render files now import from shared utility (DRY)
* test: add unit tests for getAdaptiveBarWidth
Tests cover:
- Narrow terminal (<60 cols) → 4
- Medium terminal (60-99 cols) → 6
- Wide terminal (>=100 cols) → 10
- Boundary values (59, 60, 99, 100)
- Non-TTY/piped output (undefined columns) → 10 (default)
- Fallback to COLUMNS env var
- No terminal info at all → 10 (default)
* style: simplify JSDoc to match project comment style
---------
Co-authored-by: Anna Terek <wabalabudabdab@users.noreply.github.com>
The --extra-cmd feature only rendered extraLabel in compact mode via
renderSessionLine. In the default expanded layout, extraLabel was
collected but never passed to any render function.
Append extraLabel to the project line in expanded mode, consistent
with its placement on the session line in compact mode.
Fixes#242
* feat: show reset time for 7-day usage in text-only mode
- When usageBarEnabled is false, 7d usage now displays reset time,
- consistent with the existing 5h usage text-only behavior.
* test: cover text-mode 7-day reset countdown
---------
Co-authored-by: Jarrod Watts <jarrod@cubelabs.xyz>
* fix: resilient usage display under API rate limiting
The Anthropic usage API rate-limits to ~1 call per 5 minutes. With the
previous 60s cache TTL, 4 out of 5 API calls returned 429, causing the
HUD to permanently display "(429)" instead of actual usage data.
Three-layer fix:
- Increase cache TTL from 60s to 5 minutes to match rate limit window
- Preserve lastGoodData in cache across rate-limited periods so the HUD
always shows the best available data instead of errors
- Exponential backoff (60s→120s→240s→5min cap) with Retry-After header
support for consecutive 429 responses
Also show "syncing..." instead of raw HTTP status on first-run rate limit.
* Update usage-api.ts
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
* fix: harden 429 cache fallback behavior
* test: stabilize usage cache suite after rebase
---------
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Jarrod Watts <jarrod@cubelabs.xyz>
* fix: treat zero-byte lock file as stale to prevent permanent busy state
If the HUD process crashes between fs.openSync(lockPath, 'wx') and
fs.writeFileSync(fd, timestamp), a 0-byte .usage-cache.lock remains.
readLockTimestamp() returns null for unparseable content, and the
existing guard (lockTimestamp != null && expired) never fires, leaving
the cache permanently stuck in 'busy' state.
Add a lockTimestamp === null guard that uses fs.statSync().mtimeMs to
distinguish a crash leftover (old mtime → remove and retry) from an
active writer that is between openSync and writeFileSync (recent mtime
→ return busy). The original != null stale-timestamp path is unchanged.
Closes#202
* test: stabilize stale-lock regression coverage
* test: make usage-api suite self-build for source-only PRs
---------
Co-authored-by: Jarrod Watts <jarrod@cubelabs.xyz>
* fix: use version-based sorting instead of mtime for plugin selection
The statusline command used `ls -td` (sort by modification time) to
select the latest plugin version from the cache directory. When multiple
versions coexist after an upgrade, the older version can have a newer
mtime, causing the statusline to run the wrong version.
This led to a real issue where v0.0.7 (no proxy support) was selected
over v0.0.9, causing persistent 403 errors on the usage API for users
behind a required proxy.
Replace `ls -td | head -1` with `ls -d | sort -V | tail -1` to sort
by version number. Apply the equivalent fix for Windows PowerShell
using `[version]` casting.
Fixes#198
* docs: make setup version lookup portable
* docs: avoid login shell in setup command
---------
Co-authored-by: Jarrod Watts <jarrod@cubelabs.xyz>
* fix(context): scale autocompact buffer by raw usage to avoid inflated percentages at low context
Previously the buffered context percentage applied a flat 22.5% buffer
regardless of actual usage. This caused the HUD to show ~28% context
used immediately after /clear or at session start, when real usage was
only ~5%. The fix scales the buffer linearly: zero buffer at ≤5% raw
usage, ramping to full buffer at ≥50%, matching when autocompact
actually kicks in.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* test: harden autocompact buffer startup coverage
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Jarrod Watts <jarrod@cubelabs.xyz>
* feat(config): add configurable usage cache TTL settings
Add cacheTtlSeconds and failureCacheTtlSeconds to the usage section of
config.json, allowing users to control how often the Anthropic usage API
is fetched (default 60s) and how quickly failures are retried (default 15s).
* docs: document usage cache TTL config options
* refactor(usage): bundle cache TTL params into single CacheTtls object
Replace cacheTtlMs/failureCacheTtlMs pair with a CacheTtls type wherever
they appear together, reducing parameter count in readCacheState, readCache,
waitForFreshCache, and UsageApiDeps.
* chore(build): drop dist changes from pr
---------
Co-authored-by: Jarrod Watts <jarrod@cubelabs.xyz>
* fix(usage): skip API call when using custom provider
Check ANTHROPIC_BASE_URL / ANTHROPIC_API_BASE_URL env vars and skip
OAuth usage API call when user is configured to use a custom provider
(e.g., via cc-switch). This prevents unnecessary API failures when
the user is not using Anthropic's default endpoint.
* test(usage): add tests for custom API endpoint detection
Cover isUsingCustomApiEndpoint behavior via getUsage integration:
- ANTHROPIC_BASE_URL with custom endpoint returns null without fetch
- ANTHROPIC_API_BASE_URL with custom endpoint returns null without fetch
- Empty ANTHROPIC_BASE_URL proceeds normally (falsy check)
- Default endpoint with/without trailing slash proceeds normally
* docs: note that custom API endpoints skip usage display
* fix(usage): tighten custom endpoint detection
---------
Co-authored-by: Jarrod Watts <jarrod@cubelabs.xyz>
PR #174 (67ddceb) accidentally reverted the User-Agent from
'claude-code/2.1' back to 'claude-hud'. Anthropic's /api/oauth/usage
endpoint rejects non-official User-Agent strings with 429.
This was the root cause of issue #173 — not request volume or
failure cache TTL. Same token, same IP:
- User-Agent: claude-hud → 429 (always)
- User-Agent: claude-code/2.1 → 200 with usage data
Restores the fix from PR #168 (ceb1127).
Fixes#173
Co-authored-by: Peter Yan <yanxiaozerg1997@gmail.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* fix(usage-api): change User-Agent to avoid Anthropic 429 rate limiting
Anthropic applies stricter rate limits to non-official User-Agent
strings. The current 'claude-hud/1.0' consistently receives 429
responses while 'claude-code/2.1' succeeds for the same token.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* test(usage-api): cover user-agent constant
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Jarrod Watts <jarrod@cubelabs.xyz>
* feat(config): add showSessionName toggle (default off)
Session name display from #155 is now opt-in via display.showSessionName
config. This addresses user feedback requesting the ability to hide the
session name. Added to setup onboarding and configure command flows.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* test(docs): cover session-name default behavior
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Jarrod Watts <jarrod@cubelabs.xyz>
* fix(usage-api): do not return socket from createConnection in proxy tunnel agent
Node.js _http_agent.js calls `oncreate(null, newSocket)` immediately
when createConnection returns a truthy value, which causes the HTTP
request to be written directly to the raw proxy socket before the
CONNECT handshake completes. Proxies like Clash reject this with
400 Bad Request, surfacing as persistent 403/network errors in the
Usage display.
Return undefined instead so the socket is only delivered via the
async callback after the CONNECT tunnel + TLS handshake succeeds.
Fixes proxy CONNECT failures with Clash and similar HTTP proxies.
* test(usage-api): cover proxy CONNECT request ordering
---------
Co-authored-by: Jarrod Watts <jarrod@cubelabs.xyz>
