@sooneocean/claude-hud 0.1.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "claude-hud",
+  "owner": {
+    "name": "Jarrod Watts",
+    "email": "jarrodwattsyt@gmail.com"
+  },
+  "metadata": {
+    "description": "Real-time statusline HUD for Claude Code - context health, tool activity, agent tracking, and todo progress",
+    "version": "0.0.10"
+  },
+  "plugins": [
+    {
+      "name": "claude-hud",
+      "source": "./",
+      "description": "Real-time statusline showing context usage, active tools, running agents, and todo progress. Always visible below your input, zero config required.",
+      "category": "monitoring",
+      "tags": ["hud", "statusline", "monitoring", "context", "tools", "agents", "todos"]
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "claude-hud",
+  "description": "Real-time statusline HUD for Claude Code - context health, tool activity, agent tracking, and todo progress",
+  "version": "0.0.10",
+  "author": {
+    "name": "Jarrod Watts",
+    "url": "https://github.com/jarrodwatts"
+  },
+  "commands": [
+    "./commands/setup.md",
+    "./commands/configure.md",
+    "./commands/health.md",
+    "./commands/export.md",
+    "./commands/theme.md"
+  ],
+  "homepage": "https://github.com/jarrodwatts/claude-hud",
+  "repository": "https://github.com/jarrodwatts/claude-hud",
+  "license": "MIT",
+  "keywords": ["hud", "monitoring", "statusline", "context", "tools", "agents", "todos", "claude-code"]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jarrod Watts
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,379 @@
+# Claude HUD
+
+A Claude Code plugin that shows what's happening — context usage, active tools, running agents, and todo progress. Always visible below your input.
+
+[![License](https://img.shields.io/github/license/jarrodwatts/claude-hud?v=2)](LICENSE)
+[![Stars](https://img.shields.io/github/stars/jarrodwatts/claude-hud)](https://github.com/jarrodwatts/claude-hud/stargazers)
+
+![Claude HUD in action](claude-hud-preview-5-2.png)
+
+## Install
+
+Inside a Claude Code instance, run the following commands:
+
+**Step 1: Add the marketplace**
+```
+/plugin marketplace add jarrodwatts/claude-hud
+```
+
+**Step 2: Install the plugin**
+
+<details>
+<summary><strong>⚠️ Linux users: Click here first</strong></summary>
+
+On Linux, `/tmp` is often a separate filesystem (tmpfs), which causes plugin installation to fail with:
+```
+EXDEV: cross-device link not permitted
+```
+
+**Fix**: Set TMPDIR before installing:
+```bash
+mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude
+```
+
+Then run the install command below in that session. This is a [Claude Code platform limitation](https://github.com/anthropics/claude-code/issues/14799).
+
+</details>
+
+```
+/plugin install claude-hud
+```
+
+**Step 3: Configure the statusline**
+```
+/claude-hud:setup
+```
+
+Done! Restart Claude Code to load the new statusLine config, then the HUD will appear.
+
+---
+
+## What is Claude HUD?
+
+Claude HUD gives you better insights into what's happening in your Claude Code session.
+
+| What You See | Why It Matters |
+|--------------|----------------|
+| **Project path** | Know which project you're in (configurable 1-3 directory levels) |
+| **Context health** | Know exactly how full your context window is before it's too late |
+| **Tool activity** | Watch Claude read, edit, and search files as it happens |
+| **Agent tracking** | See which subagents are running and what they're doing |
+| **Todo progress** | Track task completion in real-time |
+
+## What You See
+
+### Default (2 lines)
+```
+[Opus | Max] │ my-project git:(main*)
+Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h)
+```
+- **Line 1** — Model, plan name (or `Bedrock`), project path, git branch
+- **Line 2** — Context bar (green → yellow → red) and usage rate limits
+
+### Optional lines (enable via `/claude-hud:configure`)
+```
+◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2        ← Tools activity
+◐ explore [haiku]: Finding auth code (2m 15s)    ← Agent status
+▸ Fix authentication bug (2/5)                   ← Todo progress
+```
+
+---
+
+## How It Works
+
+Claude HUD uses Claude Code's native **statusline API** — no separate window, no tmux required, works in any terminal.
+
+```
+Claude Code → stdin JSON → claude-hud → stdout → displayed in your terminal
+           ↘ transcript JSONL (tools, agents, todos)
+```
+
+**Key features:**
+- Native token data from Claude Code (not estimated)
+- Scales with Claude Code's reported context window size, including newer 1M-context sessions
+- Parses the transcript for tool/agent activity
+- Updates every ~300ms
+
+---
+
+## Configuration
+
+Customize your HUD anytime:
+
+```
+/claude-hud:configure
+```
+
+The guided flow handles layout and display toggles. Advanced overrides such as
+custom colors and thresholds are preserved there, but you set them by editing the config file directly:
+
+- **First time setup**: Choose a preset (Full/Essential/Minimal), then fine-tune individual elements
+- **Customize anytime**: Toggle items on/off, adjust git display style, switch layouts
+- **Preview before saving**: See exactly how your HUD will look before committing changes
+
+### Presets
+
+| Preset | What's Shown |
+|--------|--------------|
+| **Full** | Everything enabled — tools, agents, todos, git, usage, duration |
+| **Essential** | Activity lines + git status, minimal info clutter |
+| **Minimal** | Core only — just model name and context bar |
+
+After choosing a preset, you can turn individual elements on or off.
+
+### Manual Configuration
+
+Edit `~/.claude/plugins/claude-hud/config.json` directly for advanced settings such as `colors.*`,
+`pathLevels`, and threshold overrides. Running `/claude-hud:configure` preserves those manual settings.
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `lineLayout` | string | `expanded` | Layout: `expanded` (multi-line) or `compact` (single line) |
+| `pathLevels` | 1-3 | 1 | Directory levels to show in project path |
+| `elementOrder` | string[] | `["project","context","usage","environment","tools","agents","todos"]` | Expanded-mode element order. Omit entries to hide them in expanded mode. |
+| `gitStatus.enabled` | boolean | true | Show git branch in HUD |
+| `gitStatus.showDirty` | boolean | true | Show `*` for uncommitted changes |
+| `gitStatus.showAheadBehind` | boolean | false | Show `↑N ↓N` for ahead/behind remote |
+| `gitStatus.showFileStats` | boolean | false | Show file change counts `!M +A ✘D ?U` |
+| `display.showModel` | boolean | true | Show model name `[Opus]` |
+| `display.showContextBar` | boolean | true | Show visual context bar `████░░░░░░` |
+| `display.contextValue` | `percent` \| `tokens` \| `remaining` | `percent` | Context display format (`45%`, `45k/200k`, or `55%` remaining) |
+| `display.showConfigCounts` | boolean | false | Show CLAUDE.md, rules, MCPs, hooks counts |
+| `display.showDuration` | boolean | false | Show session duration `⏱️ 5m` |
+| `display.showSpeed` | boolean | false | Show output token speed `out: 42.1 tok/s` |
+| `display.showUsage` | boolean | true | Show usage limits (Pro/Max/Team only) |
+| `display.usageBarEnabled` | boolean | true | Display usage as visual bar instead of text |
+| `display.sevenDayThreshold` | 0-100 | 80 | Show 7-day usage when >= threshold (0 = always) |
+| `display.showTokenBreakdown` | boolean | true | Show token details at high context (85%+) |
+| `display.showTools` | boolean | false | Show tools activity line |
+| `display.showAgents` | boolean | false | Show agents activity line |
+| `display.showTodos` | boolean | false | Show todos progress line |
+| `display.showSessionName` | boolean | false | Show session slug or custom title from `/rename` |
+| `usage.cacheTtlSeconds` | number | 60 | How long (seconds) to cache a successful usage API response |
+| `usage.failureCacheTtlSeconds` | number | 15 | How long (seconds) to cache a failed usage API response before retrying |
+| `colors.context` | color name | `green` | Base color for the context bar and context percentage |
+| `colors.usage` | color name | `brightBlue` | Base color for usage bars and percentages below warning thresholds |
+| `colors.warning` | color name | `yellow` | Warning color for context thresholds and usage warning text |
+| `colors.usageWarning` | color name | `brightMagenta` | Warning color for usage bars and percentages near their threshold |
+| `colors.critical` | color name | `red` | Critical color for limit-reached states and critical thresholds |
+
+Supported color names: `red`, `green`, `yellow`, `magenta`, `cyan`, `brightBlue`, `brightMagenta`.
+
+### Usage Limits (Pro/Max/Team)
+
+Usage display is **enabled by default** for Claude Pro, Max, and Team subscribers. It shows your rate limit consumption on line 2 alongside the context bar.
+
+The 7-day percentage appears when above the `display.sevenDayThreshold` (default 80%):
+
+```
+Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h) | ██████████ 85% (2d / 7d)
+```
+
+To disable, set `display.showUsage` to `false`.
+
+**Requirements:**
+- Claude Pro, Max, or Team subscription (not available for API users)
+- OAuth credentials from Claude Code (created automatically when you log in)
+
+**Troubleshooting:** If usage doesn't appear:
+- Ensure you're logged in with a Pro/Max/Team account (not API key)
+- Check `display.showUsage` is not set to `false` in config
+- API users see no usage display (they have pay-per-token, not rate limits)
+- AWS Bedrock models display `Bedrock` and hide usage limits (usage is managed in AWS)
+- Non-default `ANTHROPIC_BASE_URL` / `ANTHROPIC_API_BASE_URL` settings skip usage display, because the Anthropic OAuth usage API may not apply
+- If you are behind a proxy, set `HTTPS_PROXY` (or `HTTP_PROXY`/`ALL_PROXY`) and optional `NO_PROXY`
+- For high-latency environments, increase usage API timeout with `CLAUDE_HUD_USAGE_TIMEOUT_MS` (milliseconds)
+
+### Example Configuration
+
+```json
+{
+  "lineLayout": "expanded",
+  "pathLevels": 2,
+  "elementOrder": ["project", "tools", "context", "usage", "environment", "agents", "todos"],
+  "gitStatus": {
+    "enabled": true,
+    "showDirty": true,
+    "showAheadBehind": true,
+    "showFileStats": true
+  },
+  "display": {
+    "showTools": true,
+    "showAgents": true,
+    "showTodos": true,
+    "showConfigCounts": true,
+    "showDuration": true
+  },
+  "colors": {
+    "context": "cyan",
+    "usage": "cyan",
+    "warning": "yellow",
+    "usageWarning": "magenta",
+    "critical": "red"
+  },
+  "usage": {
+    "cacheTtlSeconds": 120,
+    "failureCacheTtlSeconds": 30
+  }
+}
+```
+
+### Display Examples
+
+**1 level (default):** `[Opus] │ my-project git:(main)`
+
+**2 levels:** `[Opus] │ apps/my-project git:(main)`
+
+**3 levels:** `[Opus] │ dev/apps/my-project git:(main)`
+
+**With dirty indicator:** `[Opus] │ my-project git:(main*)`
+
+**With ahead/behind:** `[Opus] │ my-project git:(main ↑2 ↓1)`
+
+**With file stats:** `[Opus] │ my-project git:(main* !3 +1 ?2)`
+- `!` = modified files, `+` = added/staged, `✘` = deleted, `?` = untracked
+- Counts of 0 are omitted for cleaner display
+
+### Troubleshooting
+
+**Config not applying?**
+- Check for JSON syntax errors: invalid JSON silently falls back to defaults
+- Ensure valid values: `pathLevels` must be 1, 2, or 3; `lineLayout` must be `expanded` or `compact`
+- Delete config and run `/claude-hud:configure` to regenerate
+
+**Git status missing?**
+- Verify you're in a git repository
+- Check `gitStatus.enabled` is not `false` in config
+
+**Tool/agent/todo lines missing?**
+- These are hidden by default — enable with `showTools`, `showAgents`, `showTodos` in config
+- They also only appear when there's activity to show
+
+**HUD not appearing after setup?**
+- Restart Claude Code so it picks up the new statusLine config
+- On macOS, fully quit Claude Code and run `claude` again in your terminal
+
+---
+
+## Enhanced Features
+
+These features were added in the enhancement fork. All are opt-in and backward-compatible.
+
+### Dashboard Rich Mode
+
+Enable all visual enhancements:
+
+```json
+{
+  "display": {
+    "activityIndicator": true,
+    "treePrefixes": true,
+    "mergeToolsAgents": true,
+    "barStyle": "modern"
+  }
+}
+```
+
+Features:
+- **Activity indicator** (`◉`) — Red when tools running, green when idle
+- **Tree prefixes** (`├─` / `└─`) — Hierarchical connectors for activity lines
+- **Merged tools+agents** — Combined on one line for density
+- **Modern bar chars** (`▰▱`) — Cleaner alternative to `█░`
+- **Todo mini progress bar** (`▪▪▪▪▪`) — Per-item colored squares
+- **Context sparkline** — Mini trend chart of recent context usage
+
+### Alerts
+
+Configurable threshold alerts with visual, bell, and prediction text:
+
+```json
+{
+  "display": { "showAlerts": true },
+  "alerts": {
+    "context": { "warningThreshold": 70, "criticalThreshold": 85 },
+    "usage5h": { "warningThreshold": 70, "criticalThreshold": 90 },
+    "usage7d": { "warningThreshold": 80 }
+  }
+}
+```
+
+### Framework Integration
+
+Monitor AGW combos and Agent Teams worktrees:
+
+```json
+{
+  "display": { "showFrameworks": true },
+  "frameworks": {
+    "agw": { "enabled": true, "endpoint": "http://localhost:3000" },
+    "agentTeams": { "enabled": true }
+  }
+}
+```
+
+### Color Themes
+
+One-key theme switching: Default, Catppuccin Mocha, Dracula, Nord.
+
+```json
+{ "theme": "catppuccin" }
+```
+
+Or use the command: `/claude-hud:theme`
+
+### Cost Estimation
+
+Session cost tracking based on model pricing:
+
+```json
+{ "display": { "showCost": true } }
+```
+
+### Performance
+
+- **File-based cache** with TTL reduces I/O on the 300ms polling cycle
+- **Transcript mtime caching** skips re-parsing when file hasn't changed
+- **Git status caching** (2s TTL) eliminates redundant git commands
+- **Responsive layout** adapts to terminal width without truncating content
+
+### Additional Commands
+
+| Command | Description |
+|---------|-------------|
+| `/claude-hud:health` | Diagnostic health check |
+| `/claude-hud:export` | Export/import/reset config |
+| `/claude-hud:theme` | Switch color theme |
+
+---
+
+## Requirements
+
+- Claude Code v1.0.80+
+- Node.js 18+ or Bun
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/jarrodwatts/claude-hud
+cd claude-hud
+npm ci && npm run build
+npm test
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)
+
+---
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=jarrodwatts/claude-hud&type=Date)](https://star-history.com/#jarrodwatts/claude-hud&Date)