Claude HUD

A native macOS heads-up display for every Claude Code session you run. It sits at the edge of your screen and shows what each session is doing, what it has cost, how close you are to your limits, and which session needs you next. You can answer from the HUD without switching windows.

▶ Watch the 30-second video

What it does

	Every session at a glance. Sessions are sorted by what needs you first (Needs you → Your turn → Working) and grouped by workspace. Each one shows its tokens, cost at API prices, context fill and live subagents.
	Answer permission prompts from the HUD. Choose Allow, Always or Deny and Claude carries on. You can also pass the prompt back to your editor.
	Rate limits with a forecast. The 5-hour and weekly bars show reset countdowns and estimate when you'll run out at your current pace. Usage spent elsewhere (claude.ai, your phone, another Mac) is detected too.
	Catch runaway sessions. A session burning tokens fast gets flagged. Fresh session starts a new one in the same workspace with a handoff note built from the old transcript. That costs no tokens.
	Toasts you can reply to. When Claude finishes, a toast slides in. Type a reply and it lands in that session's tab.

Also included:

• Save-tokens tips based on your own transcripts. You get the top three by tokens at stake, each with a one-click fix:
  • a large context that is re-sent with every message → Compact
  • a cache that expired during breaks, so the session paid full price again → compact before stepping away
  • Opus or Fable used for heavy routine work → Use Sonnet, showing what share it would save
  • subagents eating most of the day
  • a 5-hour limit you'll hit at your current pace
• A global hotkey and full keyboard control (↑↓ ↩ A D R /)
• Search across sessions
• Do Not Disturb, plus automatic quiet during Zoom meetings
• A menu-bar item, idle reminders, and four themes
• Multi-Mac totals through iCloud Drive, with a list of your remote and claude.ai/code sessions

It is light on resources: native SwiftUI, no dependencies, and about 1.5% CPU while idle.

Works in any IDE or terminal

The HUD is driven by Claude Code hooks, so monitoring works wherever Claude Code runs. For each session it finds the app that hosts it by walking up from the claude process. Cursor and VS Code get the Claude Code extension's deep link (…://anthropic.claude-code/open), which picks the exact tab. Every other app is focused, and any text goes to the clipboard rather than being typed into a window the HUD can't see.

Install

Requires macOS 14+. On Windows? See windows/: a native port for x64, ARM64 and x86 that installs with a double-click.

Homebrew

brew tap louayzouaoui1/claude-hud https://github.com/Louayzouaoui1/claude-hud
brew install --cask claude-hud

Update with brew upgrade --cask claude-hud. Every change merged to main is built by GitHub Actions and published as a new release, so the cask always points at the latest build. brew uninstall --cask claude-hud takes the hooks back out of your settings.

From source

Needs the Xcode command-line tools (xcode-select --install) and jq (brew install jq).

git clone https://github.com/Louayzouaoui1/claude-hud && cd claude-hud && ./install.sh

Both ways do the same setup:

1. Install ClaudeHUD.app (Homebrew: /Applications; from source: ~/Applications).
2. Copy three small hook scripts to ~/.claude/hud/.
3. Add Claude HUD hooks and a status line to ~/.claude/settings.json. A backup is saved as settings.json.bak-claudehud. Your other hooks are left untouched, and an existing status line is kept.
4. Start the app.

It's safe to re-run. Grant Accessibility when asked: the HUD needs it to land in the right editor window and to auto-send handoffs. The app is ad-hoc signed, so macOS may ask again after an update. From source, set CODESIGN_ID to your own signing identity to keep the grant across rebuilds.

How it works

Claude Code ──hooks──▶ ~/.claude/hud/events.jsonl ──▶ Claude HUD (SwiftUI panel)
            ──PermissionRequest──▶ req/<id>.json ◀── answer ── ans/<id>
            ──statusline──▶ limits.json (5-hour / weekly)
transcripts (~/.claude/projects) ──▶ token + cost counting

Privacy

Everything stays on your Mac. There's no server and no telemetry. To show live limits and your remote sessions, the HUD reads your existing Claude Code login from the Keychain and calls the same Anthropic endpoints that Claude Code uses. Those endpoints aren't a public API, so they may change. Turning on device sync writes only daily token and cost totals to your own iCloud Drive.

Uninstall

pkill -x ClaudeHUD; rm -rf ~/Applications/ClaudeHUD.app ~/.claude/hud
cp ~/.claude/settings.json.bak-claudehud ~/.claude/settings.json   # or remove the claude/hud hook entries by hand

Claude HUD is an independent project and isn't affiliated with or endorsed by Anthropic. "Claude" is a trademark of Anthropic. Costs are shown at API list prices for comparison only; subscription plans aren't billed this way.

MIT License