Claude Hud

claude-hud

A heads-up display for Claude Code — know your context, own your handoffs, light up your statusline.

Long Claude Code sessions hit three walls: context runs out unannounced, every terminal looks identical, and session continuity is manual. claude-hud fixes all three as one plugin.

Features

See your context burn

The bar fills left-to-right through your theme's gradient. The monitor hook reads actual token counts from the session JSONL (input_tokens + cache_creation + cache_read), not an estimate, and tightens thresholds 10% earlier on fast-burning sessions. At the hard threshold Claude surfaces /handoff on the next turn.

Install

Plugin — statusline + manual handoff + auto-restore:

/plugin marketplace add ericrihm/claude-hud
/plugin install claude-hud@claude-hud

Restart Claude Code and the statusline lights up on your next prompt. That's it.

Autonomous handoff wrapper — opt-in, requires a wrapper that owns the TTY:

git clone https://github.com/ericrihm/claude-hud ~/code/claude-hud
cd ~/code/claude-hud && make install
claude-hud   # launches claude through the supervisor

Windows native: bin\claude-hud-wrap.cmd from the same checkout. make install refuses to clobber an existing ~/.local/bin/claude-hud that isn't ours, warns if the dir isn't on PATH, and flags precedence conflicts. make uninstall reverses it. Requires Python 3.10+.

Theme gallery

parrot — ParrotOS security green/cyan	kali — cool blues with red accents
vaporwave — Win11 Fluent × synthwave	operator — full telemetry, all segments on
hacker — green-on-black terminal purist	dashboard — three-line boxed, max density

Pick one with {"theme":"<name>"} in ~/.claude/oh-my-claude/config.json. Use "theme":"auto" to match the detected distro. Custom themes drop into ~/.claude/oh-my-claude/themes/.

Assets regenerate from the real theme JSONs via python scripts/render_hud_svg.py.

What gets wired up

How each piece works

🎯 Context bar

The monitor is authoritative — it reads real token counts, not an estimate. Thresholds adapt to burn rate: a fast-burning session (>5k tokens/turn) gets alerted 10% earlier than a slow one. Override via env:

• CLAUDE_HUD_CTX_LIMIT — default 200000 (Opus 4.6 window minus output headroom)
• CLAUDE_HUD_SOFT — default 65
• CLAUDE_HUD_HARD — default 78

🖥️ Pretty machine ID

Detects via /etc/os-release, WSL_DISTRO_NAME, sys.platform, and socket.gethostname(). On Windows native the identity segment shows the hostname (not a generic "Win11") so two Windows boxes are distinguishable. Themes live in plugin/themes/*.json — all colors, segment order, separators, and icon tier are declarative.

↪️ Session handoff

Three entry points, all producing briefs at ~/.claude/handoffs/<project-slug>/:

• Manual — /handoff [focus-note] spawns a summarizer subagent that reads the session JSONL and produces a structured brief via chain-of-density summarization. Written to <UTC-timestamp>.md plus a latest.md pointer.
• Auto-restore — On next session start in the same project, the SessionStart hook injects the brief as additionalContext. Size-guarded at 8000 chars, age-guarded at 48h (both env-overridable).
• PreCompact snapshot — Fires before /compact, captures the current state via the same capture worker.
• Bypass — /bypass-handoff 2h long-running-refactor writes a sentinel that suppresses the 78% nag until it expires. For multi-hour tasks where you've consciously chosen to ride the context wall.

🤖 Autonomous handoff (opt-in)

When claude is launched through bin/claude-hud-wrap, a Python orchestrator runs as a sibling process (not a child — that matters). It watches the same ctx_state the statusline reads. When context crosses the hard threshold and the session is idle (no in-flight tool calls, no JSONL writes for 2s), the daemon:

1. Spawns a capture worker that writes the brief atomically to disk.
2. Waits for confirmation the brief landed (or a 12s fallback timeout).
3. SIGTERMs the claude process directly — works because the daemon is a sibling, not a child, sidestepping claude-code#45717.
4. The supervisor notices exit, finds restart_request.json, relaunches.
5. New session's SessionStart hook loads the brief and acks via handoff/<id>/ack.json.

Safety design:

• Brief is on disk before any signal. Worst-case data loss is bounded to the in-flight tool call — and we already wait for inflight_count=0 first.
• Hysteresis (HYSTERESIS_TICKS=3) prevents oscillation near threshold.
• Three-tier failure backoff. 1st failure → 90s cooldown. 2nd → 180s. 3rd → autonomous mode self-disables (writes handoff/<slug>/disabled.json).
• 7-day GC on handoff/<id>/ directories.
• User-visible failure note at last_failure.md surfaced on next session start with a hint to /handoff manually.

Diagnose with bin/claude-hud-doctor (green/yellow/red summary of install + per-project state) — run it first when something feels off.

✅ Brief verifier

After capture, the orchestrator fires a separate claude -p --output-format json verifier session that reads the brief and returns a structured verdict across five dimensions: goal, state, decisions, next_actions, blockers. Results are appended atomically as a ## Verification section to brief.md and latest.md, and saved as handoff/<id>/verification.json.

The verifier is a fresh session — it never saw the brief being authored — which sidesteps the circular-reasoning problem where the author rationalizes away gaps. Budget: 60s, independent of CAPTURE_TIMEOUT. Best-effort: a deadline fall-through transitions straight to awaiting_idle so the handoff never stalls on a slow verifier. Disable with CLAUDE_HUD_NO_VERIFY=1.

🔗 Cross-machine auto-memory sync

Claude Code's auto-memory lives at ~/.claude/projects/<slug>/memory/, per-project, machine-local. bin/claude-hud-memory-sync syncs every project's memory dir against a dedicated private git repo in both directions.

Three-way reconcile per sync: files added, deleted, or modified by another host flow into your local dir. Local edits always win on conflict. Same-file conflicts fall through to rebase, abort cleanly, and retry next cycle. First-time init against a populated remote seeds your local dir.

# one-time setup (private repo you've created — HTTPS recommended)
bin/claude-hud-memory-sync init https://github.com/you/claude-memories.git

# manual flush / status
make memories-sync
make memories-status

Triggered via a Stop hook (detached, rate-limited, default 10 min). The hook returns in <100ms so it can't block turn teardown. Failures are fail-open — next trigger retries.

Why Stop and not SessionEnd: per claude-code#41577, SessionEnd async work gets killed before completion.

Shipped vs scaffold

claude-hud/
├── .claude-plugin/marketplace.json   # Claude Code marketplace manifest
├── bin/
│   ├── claude-hud-wrap               # Bash supervisor wrapper (Linux/WSL/macOS)
│   ├── claude-hud-wrap.cmd           # Windows supervisor wrapper
│   ├── claude-hud-doctor             # Self-diagnostic CLI
│   └── claude-hud-memory-sync        # Git-backed cross-machine auto-memory sync
├── assets/                           # Generated SVGs for README
├── docs/
│   ├── AUTONOMOUS_HANDOFF_DESIGN.md
│   ├── state_schema.md               # 10 file schemas, lock protocol, state machine
│   └── prior-art.md                  # Why each design choice (links to upstream issues)
├── scripts/render_hud_svg.py         # Regen README SVG assets from theme JSON
└── plugin/
    ├── .claude-plugin/plugin.json    # Plugin manifest
    ├── statusline.py                 # Statusline entry point
    ├── lib/                          # Detection, rendering, segments, colors, icons
    ├── themes/                       # JSON theme files
    ├── hooks/                        # PostToolUse, UserPromptSubmit, SessionStart, PreCompact, Stop
    ├── claude_hud/                   # orchestrator, capture worker, verifier, doctor
    ├── commands/                     # /handoff, /bypass-handoff
    └── skills/theme/                 # Theme-switching skill

Docs

• docs/state_schema.md — full file + state-machine spec (10 schemas, lock protocol)
• docs/AUTONOMOUS_HANDOFF_DESIGN.md — why the supervisor exists, how it survives /compact
• docs/prior-art.md — links to upstream Claude Code issues that drove each design choice
• CHANGELOG.md — release notes

Relationship to oh-my-claude

claude-hud lifts the statusline + context monitor out of the oh-my-claude theming project and packages them as a proper Claude Code plugin with the handoff system added on top. oh-my-claude remains a broader theming playground; claude-hud is the shippable subset focused on operator awareness and session continuity.

Roadmap

• Orchestrator log rotation (50MB / 7d) in _cleanup_stale
• Doctor checks supervisor liveness via /proc/<pid>/stat (Linux) / ps -p (macOS)
• Native handoff parity once claude-code#11455 ships

License

Personal use. For running Claude Code on your own machines.