Patriola's Guide to Claude

Running Claude blind is a choice. Most operators don't realize they're making it.

With one session and one task, the terminal is your status display — you watch it scroll and know what's happening. Add a second session, a background worker, and a pipeline running overnight, and that view disappears. A worker stalls at 2 AM. Context fills to 80% on a long job and the session degrades without warning. A rate limit approaches, the queue keeps pushing, and the 429 hits mid-task. None of it was hidden from you. It just had nowhere to go.

This book builds the display layer that surfaces all of it in real time.

Two layers compose the system. First: a per-session statusline that reads from a hook-written state file, showing session cost, context saturation, token burn rate, and rate-limit headroom in a compact line. Hooks write the state on every tool call; the statusline reads and refreshes without blocking the session. Saturation becomes visible before it degrades performance. Burn rate becomes visible before a limit hits.

Second: a system snapshot — a script that walks project directories, finds every worker, reads its last heartbeat, and classifies health as OK, IDLE, DORMANT, or BROKEN. IDLE means the worker missed its last two heartbeats. DORMANT means no state written in four hours. BROKEN means a failure marker exists. Each classification carries a meaning; "running or not running" is too coarse for a fleet you're not watching. The snapshot runs on demand and on a thirty-second timer.

Both layers feed a tmux layout with the whole picture on screen at once: current session's statusline, system snapshot refreshing on the timer, queue depth across all projects. The layout ships as a committed shell script — versioned, reproducible, owned by the codebase.

Chapter by chapter, each component is built separately and explained at the seam where it connects to the others. The hook architecture comes first — what fires on PreToolUse, what fires on PostToolUse, and why the state file is the right boundary between session internals and external display. After that: statusline rendering, health classification with its threshold tuning, and a queue depth reader that counts pending tasks without touching files that workers own. The tmux layout chapter covers assembly, explains what belongs on a live display versus what belongs in a log, and ends with a complete worked session running the full fleet overnight so the reader can see what a real failure looks like when the HUD catches it.

Before the HUD, you are operating on faith that nothing has stalled. After it, you have measurement. That gap is the difference between a pipeline that sometimes works and a system you can leave running.
Written for developers who already run Claude Code across multiple projects and want real visibility into what their system is doing while they are not watching.