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: 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>
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(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 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>
* feat: add showProject config to hide project name from statusline
Adds `display.showProject` (default: true) to control whether the
project path is displayed. When set to false, the project name and
its associated git info are hidden from both compact and expanded
layouts.
* fix: keep git status visible when project name is hidden
---------
Co-authored-by: Jarrod Watts <jarrod@cubelabs.xyz>
* fix: display reset time in days when >= 24 hours
The 7-day usage window reset countdown shows raw hours (e.g., "151h 59m")
which is hard to read. Format as days + hours when >= 24h (e.g., "6d 7h").
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* test: cover day-based usage reset formatting
---------
Co-authored-by: KwCCCC <KwCCCC@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Jarrod Watts <jarrod@cubelabs.xyz>
* feat: show session name in statusline
Reads the session slug (auto-generated) and custom title (set via
/rename) from the transcript JSONL and displays it in dim text after
the project/git info on both expanded and compact layouts.
Custom title takes priority over auto-generated slug when both exist.
* test: add session name coverage and harden integration spawn
---------
Co-authored-by: Jarrod Watts <jarrod@cubelabs.xyz>
New default: model+project on line 1, context+usage bars combined on line 2.
All optional features (tools, agents, todos) hidden by default with
setup onboarding step to enable them.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat: add usageBarEnabled config option for quota display style
Add configurable display style for usage limits:
- usageBarEnabled: true → visual bar (██░░ 25%)
- usageBarEnabled: false → text format (5h: 25%)
Changes:
- config.ts: Add usageBarEnabled option (default: true)
- colors.ts: Add quotaBar() and getQuotaColor() with blue color scheme
- usage.ts, session-line.ts: Conditional rendering based on config
Closes#84
* fix: add clamp guard to coloredBar for consistency
Apply the same safeWidth/safePercent guards from quotaBar to coloredBar
to prevent RangeError on malformed input values.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* chore: revert dist files to main
Remove build artifacts from PR diff. CI will rebuild dist/ after merge.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* test: add usageBarEnabled: false to baseContext
Ensures existing tests continue to check text format behavior.
The new bar format is opt-in via config.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Aster Kim <aster@spoonlabs.com>
Co-authored-by: Jarrod Watts <jarrod@cubelabs.xyz>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
* feat(layout): add expanded multi-line layout mode
Split the overloaded session line into semantic lines for better readability:
- Identity line: model, plan, context bar, duration
- Project line: path, git status
- Environment line: config counts (CLAUDE.md, rules, MCPs, hooks)
- Usage line: rate limits with reset times
New config options:
- `lineLayout`: 'compact' | 'expanded' (default: expanded for new users)
- `showSeparators`: boolean (orthogonal to layout)
- `usageThreshold`: show usage line only when >= N%
- `environmentThreshold`: show env line only when counts >= N
Backward compatible: old `layout` config is automatically migrated.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix: address code review feedback
- Fix usage threshold to use max(5h, 7d) so high 7d usage isn't hidden
when 5h is null
- Update stale comment in session-line.ts (now compact layout only)
- Remove non-null assertions in identity.ts by hoisting planName
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix: apply thresholds to compact layout for consistency
- Add environmentThreshold gating to config counts in compact mode
- Add usageThreshold with max(5h, 7d) logic to usage in compact mode
- Remove non-null assertion for planName (same fix as identity.ts)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* test: update tests for new lineLayout config schema
- Update config.test.js to validate lineLayout instead of layout
- Update render.test.js to use lineLayout and showSeparators
- Update index.test.js mock config with new schema
- Update integration test expected output for expanded default
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
- Remove ~160 lines of DEFAULT_CONFIG assertion tests that only verify
constants equal themselves (no bug-catching value)
- Add 2 tests for layout: 'separators' path (was 40% branch coverage)
Net: 102 tests (was 123), same meaningful coverage, less maintenance.
Based on distinguished-reviewer analysis of test suite quality.
* fix: use percentage-based autocompact buffer with config toggle
- Change hardcoded 45k buffer to 22.5% of context window
- Scales correctly for enterprise windows (>200k)
- Add `display.autocompactBuffer` config option ('enabled' | 'disabled')
- Default 'enabled' preserves current behavior (buffered %)
- 'disabled' shows raw % for users with autocompact off
Fixes#48, #16
Related: #4, #30, #43, #49
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* test: add autocompactBuffer tests for renderSessionLine
Address review feedback:
- Add tests verifying autocompactBuffer: 'enabled' uses buffered %
- Add tests verifying autocompactBuffer: 'disabled' uses raw %
- Add autocompactBuffer check to loadConfig test
- Update baseContext() to include autocompactBuffer
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* docs: add clickable GitHub URLs to CHANGELOG credits
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* feat: add debug log for autocompactBuffer mode
When DEBUG=claude-hud is set and autocompactBuffer='disabled',
logs both raw and buffered percentages to help troubleshoot mismatches.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
* feat: display last 3 path segments first in session line
Shows the last 3 segments of the working directory path at the
beginning of the session line for quick project identification.
Before: [Opus 4.5] ████░░░░░░ 19% | my-project git:(main) | ...
After: dev/apps/my-project git:(main) | [Opus 4.5] ████░░░░░░ 19% | ...
This helps distinguish between projects with similar names in
different locations and puts the most relevant info first.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* feat: configurable path levels (1-3) and git status toggle
- Add config system at ~/.claude/plugins/claude-hud/config.json
- Default path display to 1 level (was hardcoded at 3)
- Add pathLevels option: 1, 2, or 3 directory segments
- Add gitStatus.enabled toggle to show/hide git branch
- Add interactive CLI: npx claude-hud-configure
- Add comprehensive tests for config and path levels
- Update README with configuration documentation
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix: handle cross-platform path separators
- Split paths by both / and \ for Windows compatibility
- Always output forward slashes for consistent display
- Add tests for Windows paths, UNC paths, and mixed separators
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* feat: show existing config when reconfiguring
- Display current values when config file exists
- Prompt user that Enter keeps current values
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* feat: interactive CLI with arrow-key selection
- Add @inquirer/prompts for better UX
- Arrow keys to select path levels
- Visual feedback with checkmarks
- Cleaner, more compact output
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* feat: add dirty indicator and ahead/behind git status
- Add gitStatus.showDirty option (default: true)
- Add gitStatus.showAheadBehind option (default: false)
- Update getGitStatus to return isDirty, ahead, behind
- Update CLI to configure new options with preview
- Add tests for dirty and ahead/behind display
- Update README with new options
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* feat: add configurable display options for all HUD elements
- Add display configuration object with 8 boolean options:
- showModel: Toggle model name display [Opus]
- showContextBar: Toggle visual context bar ████░░░░░░
- showConfigCounts: Toggle CLAUDE.md, rules, MCPs, hooks counts
- showDuration: Toggle session duration display
- showTokenBreakdown: Toggle token details at high context (85%+)
- showTools: Toggle tools activity line
- showAgents: Toggle agents activity line
- showTodos: Toggle todos progress line
- All options default to true for backward compatibility
- Enhanced CLI preview with colors matching actual HUD output
- Added 5 new tests for display configuration (87 total)
- Updated README with complete configuration reference
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* feat: add configurable layout options (default, condensed, separators)
- Add layout config option with three styles:
- default: All info on first line (original behavior)
- condensed: Model/context top, project bottom
- separators: Condensed with visual separator lines
- Create project-line.ts for rendering project path in split layouts
- Add renderSessionLineMinimal for condensed/separators layouts
- Interactive CLI preview shows selected layout style
- All 87 tests pass
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* feat: add interactive HUD preview and folder icon
- Add live preview that updates as config options are selected
- Show initial preview on startup based on existing/default config
- Add folder icon (📁) in front of project path
- Extract preview generation to separate module for reuse
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* docs: update README with folder icon and live preview
- Add folder icon (📁) to all path examples
- Document live preview feature in interactive CLI section
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* feat: add menu-based navigation to configure CLI
- Replace linear flow with main menu loop
- Show current values in menu (layout, path levels, git status, etc.)
- Users can edit any section and return to menu
- Preview updates after each section change
- Save & Exit or Exit without saving options
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix: update tests for folder icon and config structure
- Update integration test expected output with folder icon
- Make config test environment-independent (validates structure, not specific values)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* test: add comprehensive config loading tests
Add 23 new tests for config system validation:
- DEFAULT_CONFIG structure (layout, gitStatus, 8 display options)
- Layout validation (default, condensed, separators)
- PathLevels validation (1, 2, or 3)
- Git status configuration defaults
- Display configuration (booleans, defaults to true, count)
- loadConfig behavior (complete fields, valid values)
- getConfigPath structure tests
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* feat: add usage API, config enhancements, and bug fixes
This PR combines and enhances the config system from PR #32 with new features
and bug fixes addressing the owner's review feedback.
## New Features
- Usage API integration showing 5h/7d limits for Pro/Max/Team users
- Interactive `/claude-hud:configure` skill for in-Claude-Code configuration
- Hybrid showUsage toggle (env var + config for privacy control)
## Bug Fixes (addressing #32 review feedback)
- Fix git status spacing: `main*↑2↓1` → `main* ↑2 ↓1`
- Fix root path rendering: show `/` instead of empty folder icon
- Fix Windows path normalization in truncatePath
- Fix duplicate dependencies key in package.json
- Fix multiSelect for mutually exclusive options in configure skill
## Credits
- Config system, layouts, path levels, git toggle, CLI by @Tsopic (PR #32)
- Usage API, configure skill, bug fixes by @melon-hub
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Co-Authored-By: Tsopic <Tsopic@users.noreply.github.com>
* fix: move configure command to correct location
- Move configure.md from .claude-plugin/skills/ to commands/
- Remove skills array from plugin.json (commands are auto-discovered)
Commands must be in the commands/ directory at plugin root,
not inside .claude-plugin/. This matches the existing setup.md pattern.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix: layout order, remove condensed, redesign configure flow
Render fixes (per PR feedback):
- Fix element order: model first, project second
- Remove condensed layout (only default/separators remain)
- Separators: single line below header only when activity exists
- Delete project-line.ts (no longer needed)
- Remove renderSessionLineMinimal() function
Configure skill redesign:
- Context-aware tab order (returning users start on Turn Off)
- Explicit Turn Off/Turn On questions (no toggle ambiguity)
- Git Style question for dirty/ahead-behind options
- Combined Layout/Reset tab for returning users
- Duration now toggleable
- Guards against empty submissions
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* docs: rename 'Returning User' to 'Update Config' in configure flow
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* test: fix tests for new element order and removed function
- Update render-basic.txt expected output (model first, project second)
- Remove renderSessionLineMinimal import and test (function was deleted)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* docs: update documentation for usage API, config flow, and troubleshooting
- Remove stale CLAUDE_HUD_SHOW_USAGE env var references (now config-based)
- Add usage API data sources to CLAUDE.md
- Add new source files to file structure (config.ts, git.ts, usage-api.ts)
- Update README with usage limits section and requirements
- Add troubleshooting sections for config, git, and usage issues
- Standardize output examples across all documentation files
- Remove condensed layout references (only default/separators now)
- Update configure skill reference (npx CLI → /claude-hud:configure)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix: remove dist/ from PR and update outdated comment
- Reset dist/ to main branch (dist will be built by CI after merge)
- Update comment: "requires env var opt-in AND config" → "shown when enabled in config"
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* chore: remove internal design doc from release
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* chore: remove CLI and runtime dependency
- Remove src/bin/configure.ts and src/bin/preview.ts
- Remove @inquirer/prompts dependency (plugins don't run npm install)
- Remove bin field from package.json
- Users configure via /claude-hud:configure skill instead
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* chore: bump version to 0.0.4
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix: use file-based cache for usage API
HUD runs as a new process every ~300ms, so in-memory cache was useless.
Now caches to ~/.claude/plugins/claude-hud/.usage-cache.json.
This reduces API calls from ~10,800/hour to max 60/hour.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix: use consistent homeDir/now in getUsage
Avoids potential divergence if deps functions are non-deterministic.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* test: add real tests for usage API file cache
- Test credential parsing with mock HOME directory
- Test cache TTL behavior (success and failure)
- Test apiUnavailable flag handling
- Replace placeholder assert.ok(true) with actual assertions
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Martin Kask <martin@industrial.ninja>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: melon-hub <melon-hub@users.noreply.github.com>
Co-authored-by: Tsopic <Tsopic@users.noreply.github.com>
Co-authored-by: Jarrod Watts <jarrod@cubelabs.xyz>
Claude Code natively displays "X% left to autocompact" making the HUD's
COMPACT warning redundant. The context bar already turns red at high
usage to visually indicate critical state.
Closes#26🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
feat: display project folder name in session line
- Add project folder name with 📁 emoji at start of session line
- Use path.basename() for cross-platform compatibility
- Add tests for POSIX/Windows paths and edge cases
Co-authored-by: Tsopic <39419095+Tsopic@users.noreply.github.com>
Adds AUTOCOMPACT_BUFFER (45k tokens) to match /context output.
This accounts for the reserved space Claude Code uses for autocompact.
Changes:
- Add src/constants.ts with AUTOCOMPACT_BUFFER export
- Update getContextPercent to include buffer in calculation
- Add edge case guard for invalid context window sizes
- Update tests to use realistic 200k context sizes
Closes#4🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: melon-hub <melon-hub@users.noreply.github.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
