Claude Code Essential Plugin: See What Your AI is Actually Doing

Context window filling up? What files is Claude reading? How long has that sub-agent been running? Now you can see it all.

What's the most frustrating thing about using Claude Code?

You have no idea what it's doing.

Context fills up before you know it. Claude reads files in the background while you wait. A sub-agent runs for 5 minutes doing... what exactly?

Claude HUD solves this. Real-time display at the bottom of your terminal: context usage, tool calls, agent status, task progress.

---

Installation

Three commands:

/plugin marketplace add jarrodwatts/claude-hud
/plugin install claude-hud
/claude-hud:setup

Done. No restart needed, HUD appears immediately.

Linux users: If you encounter EXDEV: cross-device link not permitted:

mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude

---

What It Shows

Line 1: Basic Info

[Opus | Max] │ my-project git:(main*)

Model, subscription type, project path, Git branch.

Line 2: Resource Usage

Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h)

Context bar (green→yellow→red) + rate limits for Pro/Max users.

Line 3: Tool Activity

◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2

What file Claude is editing, how many reads, how many searches.

Line 4: Sub-Agents

◐ explore [haiku]: Finding auth code (2m 15s)

Agent name, model, task, runtime.

Line 5: Todos

▸ Fix authentication bug (2/5)

Current task, completion progress.

---

Three Modes

Run /claude-hud:configure:

• Full: Show everything
• Essential: Activity lines + Git, less clutter
• Minimal: Just model and context bar

After choosing a preset, you can toggle individual elements.

---

Configuration

Edit ~/.claude/plugins/claude-hud/config.json:

Project Path Levels

{
  "pathLevels": 2
}

• 1: my-project
• 2: apps/my-project
• 3: dev/apps/my-project

Git Details

{
  "gitStatus": {
    "showDirty": true,        // * for uncommitted
    "showAheadBehind": true,  // ↑2 ↓1
    "showFileStats": true     // !3 +1 ?2
  }
}

Symbols: ! modified, + added, ✘ deleted, ? untracked.

Context Format

{
  "display": {
    "contextValue": "percent"  // percent | tokens | remaining
  }
}

Show/Hide

{
  "display": {
    "showTools": true,
    "showAgents": true,
    "showTodos": true,
    "showDuration": true,
    "showSpeed": true
  }
}

---

Usage Limits (Pro/Max/Team)

Pro/Max/Team users see rate limits:

Usage ██░░░░░░░░ 25% (1h 30m / 5h)

When usage ≥ 80%, shows 7-day limit:

Usage ██░░░░░░░░ 25% (1h 30m / 5h) | ██████████ 85% (2d / 7d)

API users pay per token, no limits shown.

---

How It Works

Claude Code → stdin JSON → claude-hud → stdout → terminal
             ↘ transcript JSONL

• Native token data (not estimated)
• Parses transcript for activity
• Updates every 300ms

No extra windows, no tmux needed.

---

Troubleshooting

Config not working?

• Check JSON syntax
• pathLevels must be 1/2/3
• Delete config and re-run /claude-hud:configure

Git not showing?

• Confirm you're in a git repo
• Check gitStatus.enabled isn't false

Tools/Agents/Todos not showing?

• Hidden by default, need to enable
• Only show when there's activity

Usage limits not showing?

• Log in with Pro/Max/Team account (not API key)
• Check display.showUsage isn't false

---

Why Use It

Solution	Pros	Cons
Native Claude Code	No install	Can't see details
Manual log checking	Full info	Need to switch windows
Claude HUD	Real-time, native, unobtrusive	Need plugin

Core advantages:

• Uses Claude Code official API
• 300ms refresh
• Bottom of terminal, no space taken
• Three presets + fine-grained config

---

Open Source

• GitHub: https://github.com/jarrodwatts/claude-hud
• License: MIT

Contribute:

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

---

Summary

Claude Code is powerful but opaque. Claude HUD makes it transparent.

Three commands, instant effect:

/plugin marketplace add jarrodwatts/claude-hud
/plugin install claude-hud
/claude-hud:setup

Context, tools, agents, progress—all at the bottom of your terminal.