README
¶
claude-statusline
An open-source status line for Claude Code, written in Go. It is at an early stage: for now it shows the working directory and git branch, model, context usage, token counts, prompt-cache hit rate and rate-limit usage bars, and the session cost if you turn it on. On a Pro or Max plan the cost is what the session would have cost at API prices, not what you pay; see Cost. It wraps onto further rows when the terminal is narrow, and anything unexpected gives a blank line rather than an error.
Install
As a Claude Code plugin (it needs Claude Code 2.1.271 or later: its options use options, which older versions cannot load, so the hook would never install or update the binary):
/plugin install statusline --marketplace PaddleHQ/claude-statusline
On Claude Code before 2.1.275, add the marketplace first:
/plugin marketplace add PaddleHQ/claude-statusline
/plugin install statusline@claude-statusline
On your next session start, a hook installs the latest release for your platform, checks it, and sets up the status line. It adds statusLine and subagentStatusLine to your settings.json if you have none, and takes over the ones that already run an earlier install of this tool. It also takes over the old Paddle shell status line (paddle-statusline.sh), but only on the session after an install or update, and only when that script is the whole command. Any other status line of yours is left alone. To install by hand from a release or with Go, see Manual install.
Uninstall
Run this in Claude Code:
/statusline:uninstall
It removes the statusLine and subagentStatusLine entries this tool set up from your settings.json, after backing it up to settings.json.bak, and then runs claude plugin uninstall statusline@claude-statusline -s user, which removes the plugin and its data directory, where the binary and its caches live. The change takes full effect in your next session. If settings.json is a symlink, the file it points to is the one that is edited and backed up.
Use /statusline:uninstall rather than /plugin uninstall on its own: Claude Code leaves settings alone when a plugin is uninstalled, so the entries would stay behind pointing at a binary that is gone, and the status line would silently vanish. If the plugin is installed for a project rather than for you, the command does not uninstall it, because that edits the project's shared .claude/settings.json; it tells you what to run instead.
To turn the status line back on without reinstalling the plugin, run "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/plugins/data/statusline-claude-statusline/bin/claude-statusline" setup from a terminal (or claude-statusline setup if it is on your PATH). Run by hand like this, it adds the entries again even after an uninstall.
Three things stay, because they are yours: ~/.claude/claude-statusline/config.yaml, the hooks in ~/.claude/statusline.d/ and the usage snapshot ~/.claude/usage-latest.json (all under $CLAUDE_CONFIG_DIR if you set it). Delete them by hand if you want them gone. A status line of yours that is not this tool's is never removed.
Configure
Configuration is optional. The easiest way to change the common settings (theme, segments, separator, path and branch display, effort, snapshot) is the plugin's options. Single-value options (theme, separator, the on/off ones) are in /config; the lists (segments, path_strip, path_worktrees) are set with /plugin configure or claude plugin configure statusline@claude-statusline --values-stdin. A value set there wins over config.yaml; pick a built-in theme or point theme_file at your own; leave an option empty (or default) to keep what config.yaml or the built-in default says. See Plugin options for the full list.
config.yaml keeps working for every key, and is the only place for the rest (widths, thresholds, hooks, custom segments). Your file lives in ~/.claude/claude-statusline/config.yaml (under $CLAUDE_CONFIG_DIR if you set it), as YAML:
theme: gradient
segments: [path, model, ctx, tokens, cache, rate5h, rate7d]
With theme: gradient, the bars are shaded from green to red along their length:
Or try theme: saber, which draws each bar as a lightsaber blade coloured by pace:
Or theme: capsule, which draws rounded capsule bars coloured by pace, with or without icons: nerd. It needs a Nerd Font v3 or later in your terminal:
theme picks the colours and bar glyphs, segments chooses what to show and in what order, and icons: nerd swaps the labels for Nerd Font icons if your terminal uses a Nerd Font (a "Mono" variant). Every key, custom segments, wrapping and themes are in Customising. To see what your own line shows, run /statusline:help in Claude Code, or claude-statusline help if you installed by hand. If the status line shows a red row about your config file, run /statusline:config-check, or claude-statusline config-check if you installed by hand.
More
- How it works: what runs when, the shared rate-limit cache, how the plugin updates itself, and manual install.
- Customising: every setting, custom segments, subagent rows, rate bars for other tools and themes.
- CONTRIBUTING.md: how to change the code.
Licence
Released under the terms in LICENSE.
Documentation
¶
Overview ¶
Command claude-statusline prints a configurable status line for Claude Code.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
bar
Package bar draws a usage bar with a pace marker.
|
Package bar draws a usage bar with a pace marker. |
|
cli
Package cli picks the claude-statusline command from its arguments and runs it.
|
Package cli picks the claude-statusline command from its arguments and runs it. |
|
config
Package config layers the user's settings over the defaults embedded in the binary.
|
Package config layers the user's settings over the defaults embedded in the binary. |
|
featuretest
Package featuretest runs the Gherkin feature files under features/ against the status line.
|
Package featuretest runs the Gherkin feature files under features/ against the status line. |
|
featuretest/style
Package style reads and writes the style row format the feature files use to describe colored terminal output.
|
Package style reads and writes the style row format the feature files use to describe colored terminal output. |
|
gitbranch
Package gitbranch finds the current branch, and a linked worktree's main repository, by reading .git files, without running git.
|
Package gitbranch finds the current branch, and a linked worktree's main repository, by reading .git files, without running git. |
|
hook
Package hook runs the user's own segment scripts, with a timeout and a per-session cache.
|
Package hook runs the user's own segment scripts, with a timeout and a per-session cache. |
|
icons
Package icons holds the icon set the user chose.
|
Package icons holds the icon set the user chose. |
|
layout
Package layout arranges rendered segments into one row, or wraps them into several when the terminal is too narrow.
|
Package layout arranges rendered segments into one row, or wraps them into several when the terminal is too narrow. |
|
payload
Package payload decodes the session JSON that Claude Code writes to stdin.
|
Package payload decodes the session JSON that Claude Code writes to stdin. |
|
ratebars
Package ratebars prints the 5h and 7d usage bars as JSON, painted in the user's theme, for tools that draw them in their own layout.
|
Package ratebars prints the 5h and 7d usage bars as JSON, painted in the user's theme, for tools that draw them in their own layout. |
|
ratecache
Package ratecache shares rate-limit readings between sessions.
|
Package ratecache shares rate-limit readings between sessions. |
|
render
Package render lays out the configured segments and the user's hooks into the printed line.
|
Package render lays out the configured segments and the user's hooks into the printed line. |
|
setup
Package setup wires the status line into Claude Code's settings.json, and takes it out again.
|
Package setup wires the status line into Claude Code's settings.json, and takes it out again. |
|
snapshot
Package snapshot saves the latest session payload for other tools to read.
|
Package snapshot saves the latest session payload for other tools to read. |
|
statusline
Package statusline turns the session payload and the environment into the printed line.
|
Package statusline turns the session payload and the environment into the printed line. |
|
subagent
Package subagent renders the rows of Claude Code's agent panel.
|
Package subagent renders the rows of Claude Code's agent panel. |
|
theme
Package theme defines the colors and glyphs a status line is drawn with.
|
Package theme defines the colors and glyphs a status line is drawn with. |
|
transcript
Package transcript reads the few facts the status line takes from a session transcript.
|
Package transcript reads the few facts the status line takes from a session transcript. |
|
Package segments is the composition root of the status line: the one list of plugins it can show, and the one place that connects them to the rest of the program.
|
Package segments is the composition root of the status line: the one list of plugins it can show, and the one place that connects them to the rest of the program. |
|
cache
Package cache provides the cache segment: how much of the latest request's input came from the prompt cache, or that the cache has expired since.
|
Package cache provides the cache segment: how much of the latest request's input came from the prompt cache, or that the cache has expired since. |
|
cost
Package cost provides the cost segment: what the session has cost so far, in US dollars.
|
Package cost provides the cost segment: what the session has cost so far, in US dollars. |
|
ctx
Package ctx provides the ctx segment: context-window usage as a bar.
|
Package ctx provides the ctx segment: context-window usage as a bar. |
|
diagnostics
Package diagnostics provides the segments drawn from the session transcript: boot, skills, skills_stripped, agent_skills and mem.
|
Package diagnostics provides the segments drawn from the session transcript: boot, skills, skills_stripped, agent_skills and mem. |
|
model
Package model provides the model segment: the model's name, and its effort level.
|
Package model provides the model segment: the model's name, and its effort level. |
|
path
Package path provides the path segment: the working directory, shortened, with the git branch, and a worktree as its main repository.
|
Package path provides the path segment: the working directory, shortened, with the git branch, and a worktree as its main repository. |
|
rate
Package rate provides the rate5h and rate7d segments: usage of the 5 hour and 7 day windows as a bar with a pace marker.
|
Package rate provides the rate5h and rate7d segments: usage of the 5 hour and 7 day windows as a bar with a pace marker. |
|
tokens
Package tokens provides the tokens segment: session token totals.
|
Package tokens provides the tokens segment: session token totals. |
|
Package themes embeds the built-in theme files that sit beside it.
|
Package themes embeds the built-in theme files that sit beside it. |
|
tools
|
|
|
screenshots
command
Command screenshots turns the status line's terminal output into SVG images for the documentation.
|
Command screenshots turns the status line's terminal output into SVG images for the documentation. |