Tail Claude Hud

tail-claude-hud

A terminal statusline for [Claude Code](https://docs.anthropic.com/en/docs/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`.

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]`; missing, unreadable, or malformed files are ignored.

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	Mo