The macOS/Linux awk-based version sorting command uses '"'"' to nest
single quotes inside bash -c '...'. After JSON encoding/decoding in
settings.json, this quoting breaks on Windows Git Bash, causing a
silent syntax error that prevents the HUD statusline from starting.
Replace awk with sort -V (GNU version sort, included with Git for
Windows) in the Windows + Git Bash section, which avoids nested
single quotes entirely.
Fixes#326
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Claude Code runs the statusLine command as a subprocess with piped
stdout/stderr, so process.stdout.columns is unavailable. Without an
explicit COLUMNS value, getTerminalWidth() falls back to the
UNKNOWN_TERMINAL_WIDTH constant and width-dependent layout (line
combining, wrapping) cannot use the real terminal dimensions.
Fix: inject COLUMNS into the generated statusLine command on all
platforms:
- macOS/Linux/WSL: `stty size </dev/tty` reads from the controlling
terminal (works even when stdout is piped)
- Windows PowerShell: `[Console]::WindowWidth` reads the console
buffer width
Both subtract 4 columns to account for Claude Code's PromptInputFooter
padding (paddingX={2}, i.e. 2 columns on each side).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Parse assistant message usage fields from the transcript JSONL to
accumulate input, output, cache creation and cache read tokens across
the entire session. Display the total as a new HUD line controlled by
the `display.showSessionTokens` config option (default: false).
Changes:
- types.ts: add SessionTokenUsage interface
- transcript.ts: accumulate usage from assistant messages
- config.ts: add showSessionTokens option
- render/lines/session-tokens.ts: new render component
- render/index.ts & session-line.ts: integrate into both layouts
- commands/configure.md: add Session tokens to configure flow
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
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: 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>
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: 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>
* 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>
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>
The Bash tool on Windows uses Git Bash as its interpreter, so `uname -s`
returns MINGW even when the user launched Claude Code from PowerShell.
This caused setup to generate bash commands that fail in PowerShell.
Fix: Instruct Claude to use the Platform value from its environment
context (darwin/linux/win32) instead of running uname. This correctly
identifies the user's actual platform regardless of the Bash tool's
environment.
- darwin → bash commands (macOS)
- linux → bash commands (all distros: Ubuntu, NixOS, Arch, etc.)
- win32 → PowerShell commands (works on PowerShell, cmd.exe, Git Bash)
Fixes#90
Co-authored-by: Claude Opus 4.5 <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>
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>
* fix: detect EXDEV cross-device error on Linux installation
When plugin path is not found during setup on Linux, check if /tmp and
~/.claude are on different filesystems. If so, provide the TMPDIR
workaround to users.
Fixes#52
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(setup): dynamic platform and runtime detection
- Detect macOS/Linux/Windows and generate appropriate command
- Use absolute runtime path (fixes PATH issues with mise/nvm)
- Prefer bun when available for faster startup
- Add user verification step with debugging if setup fails
- Keep dynamic plugin path lookup for automatic updates
Addresses: #5, #11, PR #19, PR #22🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix: address review feedback for robust cross-platform support
- Use `command -v` instead of `which` (POSIX compliant)
- Add runtime path validation step
- Add Windows bun support with proper detection
- Use `Join-Path` for Windows path handling
- Add WSL-specific guidance
- Add PowerShell execution policy troubleshooting
- Add expected execution time (1 second)
- Include asdf in version manager list
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix: address minor review feedback
- Add placeholder substitution note at top
- Use basename for more robust bun detection
- Clarify GitHub star prompt
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix: harden edge case handling
- Add plugin path validation for both platforms
- Windows: explicit error if neither bun nor node found
- Windows: quote runtime path to handle spaces in paths
- Windows: use full cmdlet names (Sort-Object, Get-ChildItem) for clarity
- Add note that Step 2 test catches broken binaries
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix(setup): address code review feedback
- Fix MINGW/MSYS/CYGWIN detection: Git Bash users now handled correctly
- Add quotes around runtime path to handle spaces in paths
- Add Windows-specific settings.json path guidance
- Clarify Step 3 JSON merge edge cases (missing file, invalid JSON)
- Document bun's native TypeScript support
- Add auto-update documentation note
- Add symlink troubleshooting for version managers
- Add stale config detection in debugging section
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* docs(setup): address additional code review feedback
- Add explicit Git Bash/MSYS2/Cygwin user guidance
- Change test timeout from "1 second" to "a few seconds"
- Add readlink -f as alternative to realpath
- Add note about re-running setup if HUD stops working
- Check gh CLI availability before star suggestion
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Uses time-sorted ls to find latest version - no external scripts needed.
Works on all macOS/Linux versions.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- setup.md now explicitly instructs to use the variable, not resolve it
- Version updated to 0.0.1 for initial release
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Jarrod Watts