claude HUD: The Missing Plugin for Claude Code Insights

Why This Claude HUD Matters

If you're using Claude Code, you've probably felt blind at times. You're typing away, but you have no idea how full your context window is, what tools are running, or what agents are doing. It's like driving a car without a dashboard. That's where Claude HUD comes in. This plugin gives you real-time insights into your Claude Code session, so you can avoid context overflows, track tool activity, and monitor agent progress—all without leaving your terminal.

What is Claude HUD?

Claude HUD is a plugin for Claude Code that provides a heads-up display (HUD) showing critical session information. It's always visible below your input, giving you a constant stream of data about your project, context usage, tool activity, agent tracking, and todo progress.

Key Features

Installation

Getting started with Claude HUD is straightforward. Here's how to install it:

Step 1: Add the Marketplace

Inside a Claude Code instance, run the following command:

/plugin marketplace add jarrodwatts/claude-hud

Step 2: Install the Plugin

Next, install the plugin:

/plugin install claude-hud

Step 3: Configure the Statusline

Finally, set up the statusline:

/claude-hud:setup

Done! The HUD appears immediately—no restart needed.

What Each Line Shows

Session Info

📁 my-project | [Opus 4.5] ████░░░░░░ 19% | 2 CLAUDE.md | 8 rules | 6 MCPs | 6 hooks | ⏱️ 1m

• Project: Current working directory folder name
• Model: Current model in use
• Context bar: Visual meter with color coding (green → yellow → red as it fills)
• Config counts: Rules, MCPs, and hooks loaded
• Duration: How long the session has been running

Tool Activity

✓ TaskOutput ×2 | ✓ mcp_context7 ×1 | ✓ Glob ×1 | ✓ Skill ×1

• Running tools show a spinner with the target file
• Completed tools aggregate by type with counts

Agent Status

✓ Explore: Explore home directory structure (5s)
✓ open-source-librarian: Research React hooks patterns (2s)

• Agent type and what it's working on
• Elapsed time for each agent

Todo Progress

✓ All todos complete (5/5)

• Current task or completion status
• Progress counter (completed/total)

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)
• Parses the transcript for tool/agent activity
• Updates every ~300ms

Requirements

• Claude Code v1.0.80+
• Node.js 18+ or Bun

Development

If you want to contribute or modify Claude HUD, here's how to get started:

git clone https://github.com/jarrodwatts/claude-hud
cd claude-hud
npm ci && npm run build
npm test

Why You Need Claude HUD

Avoid Context Overflow

One of the biggest pain points in using Claude Code is managing the context window. Without a visual indicator, it's easy to overflow the context, leading to truncated responses and lost information. Claude HUD's context bar gives you a real-time visual meter, so you can see exactly how full your context window is and avoid overflows.

Track Tool Activity

Ever wondered what tools Claude is using behind the scenes? With Claude HUD, you can watch Claude read, edit, and search files as it happens. This transparency helps you understand what's going on and troubleshoot any issues.

Monitor Agent Progress

If you're using agents, Claude HUD's agent tracking feature is a game-changer. You can see which subagents are running and what they're doing, along with the elapsed time for each agent. This helps you keep track of complex workflows and ensures everything is running smoothly.

Real-Time Todo Progress

Keeping track of tasks can be a hassle, especially in long sessions. Claude HUD's todo progress feature shows you the current task or completion status, along with a progress counter. This keeps you informed and helps you stay on track.

Real-World Example

Imagine you're working on a large project with multiple files and agents. Without Claude HUD, you might not realize your context window is about to overflow until it's too late. With Claude HUD, you can see the context bar filling up and take action before it's too late. You can also track which tools are being used and monitor agent progress, giving you a comprehensive view of your session.

Conclusion

Claude HUD is a must-have plugin for anyone using Claude Code. It provides real-time insights into your session, helping you avoid context overflows, track tool activity, monitor agent progress, and keep track of todos. Installation is quick and easy, and the benefits are immediate. Give it a try and see the difference it makes in your workflow.

TL;DR

• What it is: A plugin for Claude Code that shows real-time session insights.
• Why you need it: Avoid context overflows, track tool activity, monitor agent progress, and keep track of todos.
• How to install: Add the marketplace, install the plugin, and set up the statusline.
• Key features: Project name, context health, tool activity, agent tracking, todo progress.
• Requirements: Claude Code v1.0.80+, Node.js 18+ or Bun.

Give Claude HUD a try and take control of your Claude Code sessions.