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+.

go install github.com/kylesnowschwartz/tail-claude-hud/cmd/tail-claude-hud@latest

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:

git clone git@github.com:kylesnowschwartz/tail-claude-hud.git
cd tail-claude-hud
just build

Setup

Add to ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "tail-claude-hud",
    "refreshInterval": 1
  }
}

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.

Presets

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

Preset	Lines	Description
default	3	Model, context, project, todos, duration / tools / agents
compact	1	Model, context, cost, duration
detailed	4	Everything: tokens, speed, messages, lines added/removed
powerline	2	Arrow segments with auto-detected light/dark theme
minimal	1	Model, context, duration. Space-separated, no backgrounds

tail-claude-hud --preset powerline

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

Documentation

• Widgets -- 19 available widgets and what they display
• Configuration -- TOML reference, render modes, themes
• CLI -- Flags and commands
• Architecture -- Pipeline design and transcript processing
• Development -- Building, testing, releasing

Related

• tail-claude -- Terminal TUI for reading Claude Code session logs

License

MIT