{"id":35893251,"url":"https://github.com/jarrodwatts/claude-hud","last_synced_at":"2026-01-17T16:17:42.331Z","repository":{"id":331996615,"uuid":"1126473386","full_name":"jarrodwatts/claude-hud","owner":"jarrodwatts","description":"A Claude Code plugin that shows what's happening - context usage, active tools, running agents, and todo progress","archived":false,"fork":false,"pushed_at":"2026-01-12T00:17:12.000Z","size":903,"stargazers_count":1951,"open_issues_count":10,"forks_count":93,"subscribers_count":7,"default_branch":"main","last_synced_at":"2026-01-12T03:22:32.887Z","etag":null,"topics":["anthropic","claude","claude-code","cli","plugin","statusline","typescript"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jarrodwatts.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":"MAINTAINERS.md","copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-02T01:35:07.000Z","updated_at":"2026-01-12T02:30:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jarrodwatts/claude-hud","commit_stats":null,"previous_names":["jarrodwatts/claude-hud"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/jarrodwatts/claude-hud","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jarrodwatts%2Fclaude-hud","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jarrodwatts%2Fclaude-hud/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jarrodwatts%2Fclaude-hud/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jarrodwatts%2Fclaude-hud/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jarrodwatts","download_url":"https://codeload.github.com/jarrodwatts/claude-hud/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jarrodwatts%2Fclaude-hud/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28465784,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-15T18:56:24.589Z","status":"ssl_error","status_checked_at":"2026-01-15T18:56:23.992Z","response_time":62,"last_error":"SSL_read: (null) (tls_retry_write_records failure)","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anthropic","claude","claude-code","cli","plugin","statusline","typescript"],"created_at":"2026-01-09T11:00:36.028Z","updated_at":"2026-01-15T19:00:46.634Z","avatar_url":"https://github.com/jarrodwatts.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","Skills \u0026 Plugins","Claude Plugins","A01_文本生成_文本对话","🤖 AI \u0026 Machine Learning","Productivity Tools","⭐ 精选第三方技能","Ecosystem","Repos","Monitoring and Dashboards"],"sub_categories":["大语言对话模型及数据","Monitoring \u0026 Observability","🏆 明星技能（万星以上）","Quick Setup with cc-safe-setup"],"readme":"# Claude HUD\n\nA Claude Code plugin that shows what's happening — context usage, active tools, running agents, and todo progress. Always visible below your input.\n\n[![License](https://img.shields.io/github/license/jarrodwatts/claude-hud?v=2)](LICENSE)\n[![Stars](https://img.shields.io/github/stars/jarrodwatts/claude-hud)](https://github.com/jarrodwatts/claude-hud/stargazers)\n\n![Claude HUD in action](claude-hud-preview-5-2.png)\n\n## Install\n\nInside a Claude Code instance, run the following commands:\n\n**Step 1: Add the marketplace**\n```\n/plugin marketplace add jarrodwatts/claude-hud\n```\n\n**Step 2: Install the plugin**\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e⚠️ Linux users: Click here first\u003c/strong\u003e\u003c/summary\u003e\n\nOn Linux, `/tmp` is often a separate filesystem (tmpfs), which causes plugin installation to fail with:\n```\nEXDEV: cross-device link not permitted\n```\n\n**Fix**: Set TMPDIR before installing:\n```bash\nmkdir -p ~/.cache/tmp \u0026\u0026 TMPDIR=~/.cache/tmp claude\n```\n\nThen run the install command below in that session. This is a [Claude Code platform limitation](https://github.com/anthropics/claude-code/issues/14799).\n\n\u003c/details\u003e\n\n```\n/plugin install claude-hud\n```\n\n**Step 3: Configure the statusline**\n```\n/claude-hud:setup\n```\n\nDone! The HUD appears immediately — no restart needed.\n\n---\n\n## What is Claude HUD?\n\nClaude HUD gives you better insights into what's happening in your Claude Code session.\n\n| What You See | Why It Matters |\n|--------------|----------------|\n| **Project path** | Know which project you're in (configurable 1-3 directory levels) |\n| **Context health** | Know exactly how full your context window is before it's too late |\n| **Tool activity** | Watch Claude read, edit, and search files as it happens |\n| **Agent tracking** | See which subagents are running and what they're doing |\n| **Todo progress** | Track task completion in real-time |\n\n## What Each Line Shows\n\n### Session Info\n```\n[Opus | Pro] █████░░░░░ 45% | my-project git:(main) | 2 CLAUDE.md | 5h: 25% | ⏱️ 5m\n```\n- **Model** — Current model in use (shown first)\n- **Plan name** — Your subscription tier (Pro, Max, Team) when usage enabled\n- **Context bar** — Visual meter with color coding (green → yellow → red as it fills)\n- **Project path** — Configurable 1-3 directory levels (default: 1)\n- **Git branch** — Current branch name (configurable on/off)\n- **Config counts** — CLAUDE.md files, rules, MCPs, and hooks loaded\n- **Usage limits** — 5-hour rate limit percentage (opt-in, Pro/Max/Team only)\n- **Duration** — How long the session has been running\n\n### Tool Activity\n```\n✓ TaskOutput ×2 | ✓ mcp_context7 ×1 | ✓ Glob ×1 | ✓ Skill ×1\n```\n- **Running tools** show a spinner with the target file\n- **Completed tools** aggregate by type with counts\n\n### Agent Status\n```\n✓ Explore: Explore home directory structure (5s)\n✓ open-source-librarian: Research React hooks patterns (2s)\n```\n- **Agent type** and what it's working on\n- **Elapsed time** for each agent\n\n### Todo Progress\n```\n✓ All todos complete (5/5)\n```\n- **Current task** or completion status\n- **Progress counter** (completed/total)\n\n---\n\n## How It Works\n\nClaude HUD uses Claude Code's native **statusline API** — no separate window, no tmux required, works in any terminal.\n\n```\nClaude Code → stdin JSON → claude-hud → stdout → displayed in your terminal\n           ↘ transcript JSONL (tools, agents, todos)\n```\n\n**Key features:**\n- Native token data from Claude Code (not estimated)\n- Parses the transcript for tool/agent activity\n- Updates every ~300ms\n\n---\n\n## Configuration\n\nCustomize your HUD anytime:\n\n```\n/claude-hud:configure\n```\n\nThe guided flow walks you through customization — no manual editing needed:\n\n- **First time setup**: Choose a preset (Full/Essential/Minimal), then fine-tune individual elements\n- **Customize anytime**: Toggle items on/off, adjust git display style, switch layouts\n- **Preview before saving**: See exactly how your HUD will look before committing changes\n\n### Presets\n\n| Preset | What's Shown |\n|--------|--------------|\n| **Full** | Everything enabled — tools, agents, todos, git, usage, duration |\n| **Essential** | Activity lines + git status, minimal info clutter |\n| **Minimal** | Core only — just model name and context bar |\n\nAfter choosing a preset, you can turn individual elements on or off.\n\n### Manual Configuration\n\nYou can also edit the config file directly at `~/.claude/plugins/claude-hud/config.json`.\n\n### Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `layout` | string | `default` | Layout style: `default` or `separators` |\n| `pathLevels` | 1-3 | 1 | Directory levels to show in project path |\n| `gitStatus.enabled` | boolean | true | Show git branch in HUD |\n| `gitStatus.showDirty` | boolean | true | Show `*` for uncommitted changes |\n| `gitStatus.showAheadBehind` | boolean | false | Show `↑N ↓N` for ahead/behind remote |\n| `gitStatus.showFileStats` | boolean | false | Show file change counts `!M +A ✘D ?U` |\n| `display.showModel` | boolean | true | Show model name `[Opus]` |\n| `display.showContextBar` | boolean | true | Show visual context bar `████░░░░░░` |\n| `display.showConfigCounts` | boolean | true | Show CLAUDE.md, rules, MCPs, hooks counts |\n| `display.showDuration` | boolean | true | Show session duration `⏱️ 5m` |\n| `display.showUsage` | boolean | true | Show usage limits (Pro/Max/Team only) |\n| `display.showTokenBreakdown` | boolean | true | Show token details at high context (85%+) |\n| `display.showTools` | boolean | true | Show tools activity line |\n| `display.showAgents` | boolean | true | Show agents activity line |\n| `display.showTodos` | boolean | true | Show todos progress line |\n\n### Usage Limits (Pro/Max/Team)\n\nUsage display is **enabled by default** for Claude Pro, Max, and Team subscribers. It shows your rate limit consumption directly in the HUD.\n\nWhen enabled, you'll see your 5-hour usage percentage. The 7-day percentage appears when above 80%:\n\n```\n[Opus | Pro] █████░░░░░ 45% | my-project | 5h: 25% | 7d: 85%\n```\n\nTo disable usage display, set `display.showUsage` to `false` in your config.\n\n**Requirements:**\n- Claude Pro, Max, or Team subscription (not available for API users)\n- OAuth credentials from Claude Code (created automatically when you log in)\n\n**Troubleshooting:** If usage doesn't appear:\n- Ensure you're logged in with a Pro/Max/Team account (not API key)\n- Check `display.showUsage` is not set to `false` in config\n- API users see no usage display (they have pay-per-token, not rate limits)\n\n### Layout Options\n\n**Default layout** — All info on first line:\n```\n[Opus] ████░░░░░░ 42% | my-project git:(main) | 2 rules | ⏱️ 5m\n✓ Read ×3 | ✓ Edit ×1\n```\n\n**Separators layout** — Visual separator below header when activity exists:\n```\n[Opus] ████░░░░░░ 42% | my-project git:(main) | 2 rules | ⏱️ 5m\n──────────────────────────────────────────────────────────────\n✓ Read ×3 | ✓ Edit ×1\n```\n\n### Example Configuration\n\n```json\n{\n  \"layout\": \"default\",\n  \"pathLevels\": 2,\n  \"gitStatus\": {\n    \"enabled\": true,\n    \"showDirty\": true,\n    \"showAheadBehind\": true,\n    \"showFileStats\": true\n  },\n  \"display\": {\n    \"showModel\": true,\n    \"showContextBar\": true,\n    \"showConfigCounts\": true,\n    \"showDuration\": true,\n    \"showUsage\": true,\n    \"showTokenBreakdown\": true,\n    \"showTools\": true,\n    \"showAgents\": true,\n    \"showTodos\": true\n  }\n}\n```\n\n### Display Examples\n\n**1 level (default):** `[Opus] 45% | my-project git:(main) | ...`\n\n**2 levels:** `[Opus] 45% | apps/my-project git:(main) | ...`\n\n**3 levels:** `[Opus] 45% | dev/apps/my-project git:(main) | ...`\n\n**With dirty indicator:** `[Opus] 45% | my-project git:(main*) | ...`\n\n**With ahead/behind:** `[Opus] 45% | my-project git:(main ↑2 ↓1) | ...`\n\n**With file stats:** `[Opus] 45% | my-project git:(main* !3 +1 ?2) | ...`\n- `!` = modified files, `+` = added/staged, `✘` = deleted, `?` = untracked\n- Counts of 0 are omitted for cleaner display\n\n**Minimal display (only context %):** Configure `showModel`, `showContextBar`, `showConfigCounts`, `showDuration` to `false`\n\n### Troubleshooting\n\n**Config not applying?**\n- Check for JSON syntax errors: invalid JSON silently falls back to defaults\n- Ensure valid values: `pathLevels` must be 1, 2, or 3; `layout` must be `default` or `separators`\n- Delete config and run `/claude-hud:configure` to regenerate\n\n**Git status missing?**\n- Verify you're in a git repository\n- Check `gitStatus.enabled` is not `false` in config\n\n**Tool/agent/todo lines missing?**\n- These only appear when there's activity to show\n- Check `display.showTools`, `display.showAgents`, `display.showTodos` in config\n\n---\n\n## Requirements\n\n- Claude Code v1.0.80+\n- Node.js 18+ or Bun\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/jarrodwatts/claude-hud\ncd claude-hud\nnpm ci \u0026\u0026 npm run build\nnpm test\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE)\n\n---\n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=jarrodwatts/claude-hud\u0026type=Date)](https://star-history.com/#jarrodwatts/claude-hud\u0026Date)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjarrodwatts%2Fclaude-hud","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjarrodwatts%2Fclaude-hud","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjarrodwatts%2Fclaude-hud/lists"}