tail-claude-hud

tail-claude-hud

A terminal statusline for Claude Code sessions. Shows model, context usage, tools, agents, todos, git status, and more -- updated on every tick.

Install

Requires Go 1.25+.

To update, run the same command. go install puts the binary in ~/go/bin by default, so make sure that's in your PATH.

To build from source:

Setup

Add to ~/.claude/settings.json:

By default Claude Code only re-runs the statusline on conversation events, so dynamic widgets (duration, peers, usage windows, permission indicators) go stale while you're idle. refreshInterval (Claude Code >= 2.1.97, seconds, minimum 1) re-runs it on a timer as well -- the HUD's per-tick cost is single-digit milliseconds, so a 1-second interval is negligible.

Works out of the box with the default preset. To customize, run tail-claude-hud --init to generate a config at ~/.config/tail-claude-hud/config.toml.

An external theme tool can set per-widget colors in ~/.config/tail-claude-hud/theme-active.toml. Its top-level widget tables use fg and bg keys and override both the built-in theme and [theme.overrides] field by field, so a table with only fg keeps the bg beneath it; missing, unreadable, or malformed files are ignored.

Presets

Five built-in presets. Apply one without editing TOML:

Custom presets go in ~/.config/tail-claude-hud/presets/*.toml.

Activity box

tch-activity is a Claude Code mod that draws a box above the prompt saying what Claude is doing right now, in the HUD's icons and colors, with an expandable history of each step. Install it in Claude Code:

It reads its look from tail-claude-hud style --json, so it needs a HUD binary that has the style command.

Documentation

- Widgets -- 26 available widgets and what they display
- Configuration -- TOML reference, render modes, themes
-…