better-statusline

A status line for Claude Code, drawn above the prompt:
the session's figures as dot-matrix rings, and the music you are playing beside them.

The film · What it shows · Install · Options

The film

_{Fifty-two seconds. All of it is drawn in code: the picture, the two covers and the score.
With sound: 1080p · 4K}

What it shows

Drawn in dots

A braille cell is eight dots. Every drawing here is made of them: a ring is a true circle, found on the screen and snapped dot by dot to the terminal's grid.

Rings

Each ring is lit clockwise from its top, with its figure at its heart.

• Context: how full the window is.
• Cache: the minutes left before the prompt cache goes cold, counted from the last response. An hour on a subscription inside its limits, five minutes otherwise.
• 5-hour and weekly: how much of each limit is spent, and when it starts over. The arc turns yellow once you spend faster than the window passes.

Above them, a header names the model and its effort, the folder, the git branch with its staged and modified files, the lines the session added and removed, and the subagents at work.

Spend

One bar for each recent turn, beside the session's total. The bars grow by the square root of the cost, so one dear turn leaves the rest standing.

Music

On macOS a card shows what Spotify or Apple Music is playing, in an accent read out of the cover. It takes the mouse: play, pause, skip, seek along the line, shuffle, repeat, and the volume at the right end of the controls.

The band

/fold folds the whole band into one row, and opens it again. The colours are Claude Code's own theme, so the band follows it from dark to light.

Requirements

Each missing piece takes only its own part away: without a player the band is the status alone, without pictures the card has no cover, without a Nerd Font the icons are plain Unicode.

The plugin is built on Claude Code's function hooks, an early-access API that still changes between releases. It is developed on macOS in Ghostty. The other terminals are handled by what each one reports, and are untested.

Install

From the marketplace this repository carries:

claude plugin marketplace add Autumn1337/better-statusline
claude plugin install better-statusline@better-statusline

To take a new version later:

claude plugin marketplace update better-statusline
claude plugin update better-statusline@better-statusline

Or from a clone, for one session:

git clone https://github.com/Autumn1337/better-statusline
claude --plugin-dir ./better-statusline

To load a clone in every session, name its parent folder in CLAUDE_CODE_PLUGIN_DIRS, in the env block of ~/.claude/settings.json.

Options

Both are rows in /config.

What it costs

At rest the band costs nothing you can measure. Each frame it draws is a redraw of the terminal's, so while music plays the meter's sway takes 3 to 4% of one core in every open session. motion: reduced holds it still.

How it is built

hooks/register.tsx   every hook, and all that reaches the engine
hooks/*.ts           what the hooks compute: the status, the music, the terminal
ui/*.tsx             the three surface modules: the status, the card, the one-line player
ui/dots.ts           the dot drawings: rings, bars, lanes
bridge/              the scripts that reach the Mac: the players, the cover, the cell size
types/index.d.ts     the state the plugin keeps

The players reach the plugin through one contract: bridge/now-playing.js prints a line of JSON, a MusicPlayer as types/index.d.ts declares it, each time what plays changes. A bridge for another system, MPRIS on Linux say, needs only to print the same lines.

Development

claude --plugin-dir . loads the plugin from its folder, reloads it on every save, and lays the engine's types under .claude-plugin/types/. Then:

claude plugin validate .
tsc -p .

License

MIT © Ewen Gao