/ Directory / Playground / Claude HUD
← All servers ↗ GitHub
● Community jarrodwatts ⚡ Instant

Claude HUD

by jarrodwatts · jarrodwatts/claude-hud

A real-time HUD for Claude Code — context budget, active tools, running subagents, todo progress. Stop flying blind.

claude-hud is a Claude Code plugin that surfaces what's actually happening during a session: how full the context window is, which tools are firing, which subagents are alive, todo-list progress. Aimed at devs running long sessions or multi-agent workflows where 'why is this getting slow?' becomes a real question.

▶ Watch demo 📦 Install 💡 Use Cases

Why use it

Key features

Live Demo

What it looks like in practice

ready

Install

Pick your client

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "claude-hud-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/jarrodwatts/claude-hud",
        "~/.claude/plugins/claude-hud"
      ],
      "_inferred": true
    }
  }
}

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "claude-hud-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/jarrodwatts/claude-hud",
        "~/.claude/plugins/claude-hud"
      ],
      "_inferred": true
    }
  }
}

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "claude-hud-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/jarrodwatts/claude-hud",
        "~/.claude/plugins/claude-hud"
      ],
      "_inferred": true
    }
  }
}

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "claude-hud-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/jarrodwatts/claude-hud",
        "~/.claude/plugins/claude-hud"
      ],
      "_inferred": true
    }
  }
}

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "claude-hud-skill",
      "command": "git",
      "args": [
        "clone",
        "https://github.com/jarrodwatts/claude-hud",
        "~/.claude/plugins/claude-hud"
      ]
    }
  ]
}

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json
{
  "context_servers": {
    "claude-hud-skill": {
      "command": {
        "path": "git",
        "args": [
          "clone",
          "https://github.com/jarrodwatts/claude-hud",
          "~/.claude/plugins/claude-hud"
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

claude mcp add claude-hud-skill -- git clone https://github.com/jarrodwatts/claude-hud ~/.claude/plugins/claude-hud

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use Claude HUD

Diagnose why a long session is suddenly slow

👤 Devs running multi-hour Claude Code sessions ⏱ ~10 min beginner

When to use: Replies feel slower than at the start; you suspect context pressure.

Prerequisites
  • Plugin installed — Place under ~/.claude/plugins or per Claude Code plugin convention
Flow
  1. Open HUD
    Open the HUD. What's my context usage right now?✓ Copied
    → Live percentage with breakdown
  2. Identify hogs
    Which tool calls produced the largest results in the last 30 minutes?✓ Copied
    → Top-N list of fat tool outputs
  3. Compact
    Compact the conversation to summary. Verify HUD shows context dropped.✓ Copied
    → Context bar drops; speed returns

Outcome: Sessions you can run all day without unexplained slowdowns.

Pitfalls
  • Aggressive compaction loses important detail — Compact selectively — keep the last meaningful exchange

Track multiple subagents working in parallel

👤 Devs spawning subagents ⏱ ~15 min intermediate

When to use: You launched 3 subagents and lost track of who's doing what.

Flow
  1. List
    Show me all active subagents and their current tasks.✓ Copied
    → Tile per subagent
  2. Drill
    Show the recent tool calls and todo progress for subagent 'tester'.✓ Copied
    → Per-subagent timeline

Outcome: Visibility into a multi-agent setup that would otherwise be a black box.

Pitfalls
  • Too many subagents — HUD itself gets cluttered — Filter / collapse non-active
Combine with: mcp-agent-mail

Combinations

Pair with other MCPs for X10 leverage

claude-hud-skill + mcp-agent-mail

Coordinate + monitor multi-agent setups

Use mail for coordination, HUD for live status.✓ Copied
claude-hud-skill + claude-best-practice-skill

Disciplined plans + live tracking

Plan with best-practice, watch progress in HUD.✓ Copied

Tools

What this MCP exposes

ToolInputsWhen to callCost
show_context (none) Anytime you suspect bloat free
tool_timeline since? Find latency / fat outputs free
list_subagents (none) Track multi-agent runs free
todo_status (none) Session checkpoints free

Cost & Limits

What this costs to run

API quota
N/A
Tokens per call
Tiny — HUD is read-only telemetry
Monetary
Free
Tip
HUD itself is cheap; use it to find expensive things to cut

Security

Permissions, secrets, blast radius

Minimum scopes: Read access to Claude Code session state
Credential storage: None
Data egress: None

Troubleshooting

Common errors and fixes

HUD shows nothing

Plugin not loaded; verify install path and restart Claude Code

Context numbers don't match settings

HUD reads accurate session state; the discrepancy is usually about reserved system tokens

Alternatives

Claude HUD vs others

AlternativeWhen to use it insteadTradeoff
cc-lensYou want a separate dashboard windowDifferent UX; not inline
Claude Code's built-in /contextQuick check is enoughNo timeline, no subagent view

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills