Build a HUD

The display layer your fleet is missing

A practical guide to building real-time visibility into Claude operations. With one session, the terminal is your status display. Add a second session, a background worker, and a pipeline running overnight, and that view disappears. This book builds it back.

Before the HUD, you’re operating on faith that nothing has stalled. After it, you have measurement.

Five components, one live display

• hook-architecture — PreToolUse fires before each tool call with the tool name and input; PostToolUse fires after with the result and exit code. Hooks write a JSON state file to a known path on every call: cost, context tokens, tool name, timestamp. The state file is the only interface between the session and the display layer — never read session internals directly.
• statusline — Reads the state file with jq, formats five metrics per session: tokens_used, tokens_max, saturation percent, cost_usd, and calls-per-minute. Runs as a background poll loop (default 5s refresh). Never blocks — if the state file is missing, the statusline shows the last known value and a staleness indicator.
• health-classification — Four states derived from last-call timestamp and exit code: OK (called within active_threshold, last exit 0), IDLE (no calls for >idle_threshold minutes), DORMANT (no calls for >dormant_threshold hours), BROKEN (last hook exited nonzero). All four thresholds are config values. The classifier runs in under 10 ms.
• queue-depth — Count pending tasks without touching files workers own. Two patterns: scan a JSONL task file and count lines where status=="queued", or query a SQLite task DB with SELECT COUNT(*) WHERE status='queued'. Both are read-only. Both run in an independent poll loop that doesn’t interfere with any worker it watches.
• tmux-layout — Three panes assembled by a shell script: statusline top (3-line fixed height), system snapshot middle (watch -n 30 auto-refresh), queue depth bottom. tmux new-session -d, split-window -v -p 70, split-window -v -p 30, send-keys per pane. Committed to the repo. One command launches the full HUD.
• statusline — Per-session display: cost, context saturation, token burn rate, rate-limit headroom. Hooks write on every tool call; the statusline reads and refreshes without blocking the session.
• health-classification — OK, IDLE, DORMANT, BROKEN — each with a threshold and a meaning. “Running or not running” is too coarse for a fleet you’re not watching.
• queue-depth — How to count pending tasks across all projects without touching files that workers own. The read-only pattern that doesn’t interfere with what’s running.
• tmux-layout — The assembly step: statusline, snapshot refreshing on a thirty-second timer, queue depth on one screen. Shipped as a committed shell script — versioned, reproducible, owned by the codebase.

A preview

A worker stalls at 2 AM. Context fills to 80% on a long job and the session degrades without warning. None of it was hidden from you. It just had nowhere to go.

The final chapter runs the full fleet overnight. What a real failure looks like when the HUD catches it is in there too.

Operators running Claude across multiple projects

Developers who already run Claude Code across multiple projects and want real visibility into what their system is doing while they aren’t watching. Claude Code hooks, tmux, and shell scripting assumed.

A longer excerpt is available to newsletter subscribers.

Buy on Amazon