@sooneocean/claude-hud 0.1.0

package/commands/configure.md

@@ -0,0 +1,361 @@
+---
+description: Configure HUD display options (layout, presets, display elements) while preserving advanced manual overrides
+allowed-tools: Read, Write, AskUserQuestion
+---
+
+# Configure Claude HUD
+
+**FIRST**: Use the Read tool to load `~/.claude/plugins/claude-hud/config.json` if it exists.
+
+Store current values and note whether config exists (determines which flow to use).
+
+## Always On (Core Features)
+
+These are always enabled and NOT configurable:
+- Model name `[Opus]`
+- Context bar `████░░░░░░ 45%`
+
+Advanced settings such as `colors.*`, `pathLevels`, `display.usageThreshold`, and
+`display.environmentThreshold` are preserved when saving but are not edited by this guided flow.
+
+---
+
+## Two Flows Based on Config State
+
+### Flow A: New User (no config)
+Questions: **Layout → Preset → Bar Style → Turn Off → Turn On**
+
+### Flow B: Update Config (config exists)
+Questions: **Turn Off → Turn On → Git Style → Color Theme → Layout/Reset → Custom Line** (6 questions max)
+
+---
+
+## Flow A: New User (6 Questions)
+
+### Q1: Layout
+- header: "Layout"
+- question: "Choose your HUD layout:"
+- multiSelect: false
+- options:
+  - "Expanded (Recommended)" - Split into semantic lines (identity, project, environment, usage)
+  - "Compact" - Everything on one line
+  - "Compact + Separators" - One line with separator before activity
+
+### Q2: Preset
+- header: "Preset"
+- question: "Choose a starting configuration:"
+- multiSelect: false
+- options:
+  - "Full" - Everything enabled (Recommended)
+  - "Essential" - Activity + git, minimal info
+  - "Minimal" - Core only (model, context bar)
+
+### Q3: Bar Style
+- header: "Bar Style"
+- question: "Choose progress bar characters:"
+- multiSelect: false
+- options:
+  - "Classic" — █████░░░░░ (default)
+  - "Modern" — ▰▰▰▰▰▱▱▱▱▱
+
+| Option | Config |
+|--------|--------|
+| Classic | `display.barStyle: "classic"` |
+| Modern | `display.barStyle: "modern"` |
+
+### Q4: Turn Off (based on chosen preset)
+- header: "Turn Off"
+- question: "Disable any of these? (enabled by your preset)"
+- multiSelect: true
+- options: **ONLY items that are ON in the chosen preset** (max 4)
+  - "Tools activity" - ◐ Edit: file.ts | ✓ Read ×3
+  - "Agents status" - ◐ explore [haiku]: Finding code
+  - "Todo progress" - ▸ Fix bug (2/5 tasks)
+  - "Project name" - my-project path display
+  - "Git status" - git:(main*) branch indicator
+  - "Config counts" - 2 CLAUDE.md | 4 rules
+  - "Token breakdown" - (in: 45k, cache: 12k)
+  - "Output speed" - out: 42.1 tok/s
+  - "Usage limits" - 5h: 25% | 7d: 10%
+  - "Session duration" - ⏱️ 5m
+  - "Session name" - fix-auth-bug (session slug or custom title)
+  - "Frameworks" — ⟳ AGW: pipeline (3/5) │ ⬡ Teams: fe✓ be◐
+  - "Burn rate" — 1.2k tok/m consumption rate
+  - "Alerts" — ⚠ Context 92% — ~8 calls
+  - "Activity indicator" — ◉ red/green status dot
+  - "Tree prefixes" — ├─ └─ hierarchical connectors
+  - "Merge tools+agents" — Combine on one line
+
+### Q5: Turn On (based on chosen preset)
+- header: "Turn On"
+- question: "Enable any of these? (disabled by your preset)"
+- multiSelect: true
+- options: **ONLY items that are OFF in the chosen preset** (max 4)
+  - (same list as above, filtered to OFF items)
+
+**Note:** If preset has all items ON (Full), Q5 shows "Nothing to enable - Full preset has everything!"
+If preset has all items OFF (Minimal), Q4 shows "Nothing to disable - Minimal preset is already minimal!"
+
+### Q6: Custom Line (optional)
+- header: "Custom Line"
+- question: "Add a custom phrase to display in the HUD? (e.g. a motto, max 80 chars)"
+- multiSelect: false
+- options:
+  - "Skip" - No custom line
+  - "Enter custom text" - Ask user for their phrase via AskUserQuestion (free text input)
+
+If user chooses "Enter custom text", use AskUserQuestion to get their text. Save as `display.customLine` in config.
+
+---
+
+## Flow B: Update Config (6 Questions)
+
+### Q1: Turn Off
+- header: "Turn Off"
+- question: "What do you want to DISABLE? (currently enabled)"
+- multiSelect: true
+- options: **ONLY items currently ON** (max 4, prioritize Activity first)
+  - "Tools activity" - ◐ Edit: file.ts | ✓ Read ×3
+  - "Agents status" - ◐ explore [haiku]: Finding code
+  - "Todo progress" - ▸ Fix bug (2/5 tasks)
+  - "Project name" - my-project path display
+  - "Git status" - git:(main*) branch indicator
+  - "Session name" - fix-auth-bug (session slug or custom title)
+  - "Usage bar style" - ██░░ 25% visual bar (only if usageBarEnabled is true)
+
+If more than 4 items ON, show Activity items (Tools, Agents, Todos, Project, Git) first.
+Info items (Counts, Tokens, Usage, Speed, Duration) can be turned off via "Reset to Minimal" in Q5.
+
+### Q2: Turn On
+- header: "Turn On"
+- question: "What do you want to ENABLE? (currently disabled)"
+- multiSelect: true
+- options: **ONLY items currently OFF** (max 4)
+  - "Config counts" - 2 CLAUDE.md | 4 rules
+  - "Token breakdown" - (in: 45k, cache: 12k)
+  - "Output speed" - out: 42.1 tok/s
+  - "Usage limits" - 5h: 25% | 7d: 10%
+  - "Usage bar style" - ██░░ 25% visual bar (only if usageBarEnabled is false)
+  - "Session name" - fix-auth-bug (session slug or custom title)
+  - "Session duration" - ⏱️ 5m
+  - "Frameworks" — ⟳ AGW: pipeline (3/5) │ ⬡ Teams: fe✓ be◐
+  - "Burn rate" — 1.2k tok/m consumption rate
+  - "Alerts" — ⚠ Context 92% — ~8 calls
+  - "Activity indicator" — ◉ red/green status dot
+  - "Tree prefixes" — ├─ └─ hierarchical connectors
+  - "Merge tools+agents" — Combine on one line
+
+### Q3: Git Style (only if Git is currently enabled)
+- header: "Git Style"
+- question: "How much git info to show?"
+- multiSelect: false
+- options:
+  - "Branch only" - git:(main)
+  - "Branch + dirty" - git:(main*) shows uncommitted changes
+  - "Full details" - git:(main* ↑2 ↓1) includes ahead/behind
+  - "File stats" - git:(main* !2 +1 ?3) Starship-compatible format
+
+**Skip Q3 if Git is OFF** - proceed to Q4.
+
+### Q4: Color Theme
+- header: "Color Theme"
+- question: "Apply a color theme?"
+- multiSelect: false
+- options:
+  - "Keep current" — No change
+  - "Default" — Green/Blue/Yellow/Red
+  - "Catppuccin Mocha" — Pastel dark theme
+  - "Dracula" — Purple-accented dark theme
+  - "Nord" — Cool blue-toned theme
+
+### Q5: Layout/Reset
+- header: "Layout/Reset"
+- question: "Change layout or reset to preset?"
+- multiSelect: false
+- options:
+  - "Keep current" - No layout/preset changes (current: Expanded/Compact/Compact + Separators)
+  - "Switch to Expanded" - Split into semantic lines (if not current)
+  - "Switch to Compact" - Everything on one line (if not current)
+  - "Reset to Full" - Enable everything
+  - "Reset to Essential" - Activity + git only
+
+### Q6: Custom Line (optional)
+- header: "Custom Line"
+- question: "Update your custom phrase? (currently: '{current customLine or none}')"
+- multiSelect: false
+- options:
+  - "Keep current" - No change (skip if no customLine set)
+  - "Enter custom text" - Set or update custom phrase (max 80 chars)
+  - "Remove" - Clear the custom line (only show if customLine is currently set)
+
+If user chooses "Enter custom text", use AskUserQuestion to get their text. Save as `display.customLine` in config.
+If user chooses "Remove", set `display.customLine` to `""` in config.
+
+---
+
+## Preset Definitions
+
+**Full** (everything ON):
+- Activity: Tools ON, Agents ON, Todos ON
+- Info: Counts ON, Tokens ON, Usage ON, Duration ON, Session Name ON
+- Git: ON (with dirty indicator, no ahead/behind)
+- New features: showFrameworks: true, showBurnRate: true, showAlerts: true, activityIndicator: true, treePrefixes: true, mergeToolsAgents: true
+
+**Essential** (activity + git):
+- Activity: Tools ON, Agents ON, Todos ON
+- Info: Counts OFF, Tokens OFF, Usage OFF, Duration ON, Session Name OFF
+- Git: ON (with dirty indicator)
+- New features: showFrameworks: false, showBurnRate: false, showAlerts: true, activityIndicator: true, treePrefixes: true, mergeToolsAgents: true
+
+**Minimal** (core only — this is the default):
+- Activity: Tools OFF, Agents OFF, Todos OFF
+- Info: Counts OFF, Tokens OFF, Usage OFF, Duration OFF, Session Name OFF
+- Git: ON (with dirty indicator)
+- New features: showFrameworks: false, showBurnRate: false, showAlerts: true, activityIndicator: true, treePrefixes: false, mergeToolsAgents: false
+
+---
+
+## Layout Mapping
+
+| Option | Config |
+|--------|--------|
+| Expanded | `lineLayout: "expanded", showSeparators: false` |
+| Compact | `lineLayout: "compact", showSeparators: false` |
+| Compact + Separators | `lineLayout: "compact", showSeparators: true` |
+
+---
+
+## Git Style Mapping
+
+| Option | Config |
+|--------|--------|
+| Branch only | `gitStatus: { enabled: true, showDirty: false, showAheadBehind: false, showFileStats: false }` |
+| Branch + dirty | `gitStatus: { enabled: true, showDirty: true, showAheadBehind: false, showFileStats: false }` |
+| Full details | `gitStatus: { enabled: true, showDirty: true, showAheadBehind: true, showFileStats: false }` |
+| File stats | `gitStatus: { enabled: true, showDirty: true, showAheadBehind: false, showFileStats: true }` |
+
+---
+
+## Element Mapping
+
+| Element | Config Key |
+|---------|------------|
+| Tools activity | `display.showTools` |
+| Agents status | `display.showAgents` |
+| Todo progress | `display.showTodos` |
+| Project name | `display.showProject` |
+| Git status | `gitStatus.enabled` |
+| Config counts | `display.showConfigCounts` |
+| Token breakdown | `display.showTokenBreakdown` |
+| Output speed | `display.showSpeed` |
+| Usage limits | `display.showUsage` |
+| Usage bar style | `display.usageBarEnabled` |
+| Session name | `display.showSessionName` |
+| Session duration | `display.showDuration` |
+| Custom line | `display.customLine` |
+| Frameworks status | `display.showFrameworks` |
+| Burn rate | `display.showBurnRate` |
+| Alerts | `display.showAlerts` |
+| Activity indicator | `display.activityIndicator` |
+| Tree prefixes | `display.treePrefixes` |
+| Merge tools+agents | `display.mergeToolsAgents` |
+
+**Always true (not configurable):**
+- `display.showModel: true`
+- `display.showContextBar: true`
+
+---
+
+## Usage Style Mapping
+
+| Option | Config |
+|--------|--------|
+| Bar style | `display.usageBarEnabled: true` — Shows `██░░ 25% (1h 30m / 5h)` |
+| Text style | `display.usageBarEnabled: false` — Shows `5h: 25% (1h 30m)` |
+
+**Note**: Usage style only applies when `display.showUsage: true`. When 7d usage >= 80%, it also shows with the same style.
+
+---
+
+## Processing Logic
+
+### For New Users (Flow A):
+1. Apply chosen preset as base
+2. Apply bar style selection
+3. Apply Turn Off selections (set those items to OFF)
+4. Apply Turn On selections (set those items to ON)
+5. Apply chosen layout
+
+### For Returning Users (Flow B):
+1. Start from current config
+2. Apply Turn Off selections (set to OFF, including usageBarEnabled if selected)
+3. Apply Turn On selections (set to ON, including usageBarEnabled if selected)
+4. Apply Git Style selection (if shown)
+5. Apply Color Theme selection (if not "Keep current")
+6. If "Reset to [preset]" selected, override with preset values
+7. If layout change selected, apply it
+
+---
+
+## Before Writing - Validate & Preview
+
+**GUARDS - Do NOT write config if:**
+- User cancels (Esc) → say "Configuration cancelled."
+- No changes from current config → say "No changes needed - config unchanged."
+
+**Show preview before saving:**
+
+1. **Summary of changes:**
+```
+Layout: Compact → Expanded
+Git style: Branch + dirty
+Changes:
+  - Usage limits: OFF → ON
+  - Config counts: ON → OFF
+```
+
+2. **Preview of HUD (Expanded layout):**
+```
+[Opus | Pro] │ my-project git:(main*)
+Context ████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h)
+◐ Edit: file.ts | ✓ Read ×3
+▸ Fix auth bug (2/5)
+```
+
+**Preview (Expanded, Full preset):**
+```
+◉ [Opus 4.6 | Max] │ my-project git:(main*)
+Context ▰▰▰▰▰▱▱▱▱▱ 45% │ 1.2k tok/m │ Usage ▰▰▱▱▱▱▱▱▱▱ 25% (resets in 1h 30m)
+├─ ⟳ AGW: review-loop (3/5) │ ⬡ Teams: fe✓ be◐
+├─ ◐ Edit: auth.ts │ ✓ Read ×3 │ ◐ explore [haiku] (2m)
+└─ ▸ Fix auth bug (2/5) │ ▪▪▪▪▪
+```
+
+**Preview of HUD (Compact layout):**
+```
+[Opus | Pro] ████░░░░░ 45% | my-project git:(main*) | 5h: 25% | ⏱️ 5m
+◐ Edit: file.ts | ✓ Read ×3
+▸ Fix auth bug (2/5)
+```
+
+3. **Confirm**: "Save these changes?"
+
+---
+
+## Write Configuration
+
+Write to `~/.claude/plugins/claude-hud/config.json`.
+
+Merge with existing config, preserving:
+- `pathLevels` (not in configure flow)
+- `display.usageThreshold` (advanced config)
+- `display.environmentThreshold` (advanced config)
+- `colors` (advanced manual palette overrides)
+
+**Migration note**: Old configs with `layout: "default"` or `layout: "separators"` are automatically migrated to the new `lineLayout` + `showSeparators` format on load.
+
+---
+
+## After Writing
+
+Say: "Configuration saved! The HUD will reflect your changes immediately."

package/commands/export.md

@@ -0,0 +1,43 @@
+---
+description: Export or import Claude HUD configuration
+allowed-tools: Bash, Read, Write, AskUserQuestion
+---
+
+# Claude HUD Config Export/Import
+
+## Step 1: Choose Action
+
+Use AskUserQuestion:
+- header: "Config Management"
+- question: "What would you like to do?"
+- options:
+  - "Export config" — Copy current config to clipboard or display
+  - "Import config" — Paste a config to apply
+  - "Reset to defaults" — Clear all custom config
+
+## Export Flow
+
+1. Read `~/.claude/plugins/claude-hud/config.json`
+2. Display the JSON content
+3. If `pbcopy` available (macOS), offer to copy to clipboard:
+   ```bash
+   cat ~/.claude/plugins/claude-hud/config.json | pbcopy
+   ```
+4. Say "Config copied to clipboard!" or display it for manual copy
+
+## Import Flow
+
+1. Use AskUserQuestion to get the JSON string (free text input)
+2. Validate it's valid JSON
+3. Show preview of what will change
+4. Confirm before writing
+5. Write to `~/.claude/plugins/claude-hud/config.json`
+
+## Reset Flow
+
+1. Confirm: "This will remove all custom config. The HUD will use default settings. Continue?"
+2. If confirmed, delete the config file:
+   ```bash
+   rm ~/.claude/plugins/claude-hud/config.json
+   ```
+3. Say "Config reset to defaults. The HUD will use default settings."

package/commands/health.md

@@ -0,0 +1,61 @@
+---
+description: Run a diagnostic health check on Claude HUD
+allowed-tools: Bash, Read, AskUserQuestion
+---
+
+# Claude HUD Health Check
+
+Run a comprehensive diagnostic to verify the HUD is working correctly.
+
+## Step 1: Check Plugin Installation
+
+Run:
+```bash
+CLAUDE_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
+echo "Plugin cache: $(ls -d "$CLAUDE_DIR/plugins/cache/claude-hud" 2>/dev/null && echo 'YES' || echo 'NO')"
+echo "Config file: $(ls "$CLAUDE_DIR/plugins/claude-hud/config.json" 2>/dev/null && echo 'YES' || echo 'NO')"
+echo "Cache dir: $(ls -d "$CLAUDE_DIR/plugins/claude-hud/.cache" 2>/dev/null && echo 'YES' || echo 'NO')"
+echo "History file: $(ls "$CLAUDE_DIR/plugins/claude-hud/session-history.json" 2>/dev/null && echo 'YES' || echo 'NO')"
+echo "Node: $(node --version 2>/dev/null || echo 'NOT FOUND')"
+echo "Bun: $(bun --version 2>/dev/null || echo 'NOT FOUND')"
+echo "Platform: $(uname -s)"
+echo "Terminal: ${COLUMNS:-unknown} cols"
+```
+
+## Step 2: Validate Config
+
+Read `~/.claude/plugins/claude-hud/config.json` if it exists.
+
+Check:
+- Is it valid JSON?
+- Are all field names recognized?
+- Is the theme valid (default/catppuccin/dracula/nord)?
+- Are threshold values in range (0-100)?
+
+Report any issues found.
+
+## Step 3: Check StatusLine Config
+
+Read `~/.claude/settings.json` and check if `statusLine` is configured.
+
+Report:
+- statusLine type and command
+- Whether the command path exists
+
+## Step 4: Test HUD Output
+
+Run the statusLine command with sample data:
+```bash
+echo '{"model":{"display_name":"Test"},"context_window":{"current_usage":{"input_tokens":50000},"context_window_size":200000}}' | <statusLine command> 2>/dev/null
+```
+
+Check if output is non-empty.
+
+## Step 5: Report
+
+Present results using AskUserQuestion:
+- header: "Health Check Results"
+- question: Show all results with ✓/✘ indicators
+- options: "Everything looks good!" / "I need help with an issue"
+
+If user needs help, ask what's wrong and debug.