* 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>
* 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>
* 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>
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>
Document the showFileStats configuration option added in PR #71:
- Add option to Options table with description
- Add file stats display example with symbol legend
- Add showFileStats to example configuration
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Failed or interrupted plugin installations can leave inconsistent state:
- Cache exists but not in registry (orphaned)
- Registry entry exists but no cache (stale)
- temp_local_* files left from interrupted installs
New Step 0 in setup.md:
- Detects cache/registry mismatch
- Finds leftover temp files
- Provides cleanup commands for macOS/Linux/Windows
- Includes EXDEV check for Linux (consolidated from Step 1)
Also consolidates EXDEV detection into Step 0 instead of buried in Step 1.
Fixes#59, #62, #60
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Adds a star history chart section at the bottom of the README using
star-history.com's SVG API.
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>
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>
The previous installation command didn't work because Claude Code
plugins require a marketplace manifest. This adds the marketplace.json
and updates install instructions to the correct two-step flow:
1. /plugin marketplace add jarrodwatts/claude-hud
2. /plugin install claude-hud@claude-hud
Also commits dist/ for plugin distribution since users can't run
npm build when installing via marketplace.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
