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. 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:
/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 if you do not already have one. To install by hand from a release or with Go, see Manual install.
Configure
Configuration is optional. Your settings live 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:
theme picks the colours and bar glyphs, and segments chooses what to show and in what order. 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.
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 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. |
|
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. |
|
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 once.
|
Package setup wires the status line into Claude Code's settings.json once. |
|
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.
|
Package cache provides the cache segment: how much of the latest request's input came from the prompt cache. |
|
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. |
Click to show internal directories.
Click to hide internal directories.