A customizable status line formatter for Claude Code CLI. Reads JSON session data from stdin, renders an ANSI-colored status line, and outputs to stdout.
- Single static binary with no runtime dependencies beyond
gitfor the git widgets - 61 configurable widgets (model, tokens, context, git, cost, rate limits, prompt cache, and more)
- Custom subagent rows in Claude Code's agent panel (
subagentStatusLine) - Multi-line status line with flex separator layout
- Threshold colors (e.g. context % turning yellow, then red) and progress bars
- The 16 ANSI colors, the 256-color palette and true color (
#rrggbb) - A JSON Schema for
settings.json, so editors complete and check it - Configurable via
~/.config/ccstatus/settings.json - Automatic Claude Code integration via
install/uninstallcommands
brew install moond4rk/tap/ccstatusgo install github.com/moond4rk/ccstatus/cmd/ccstatus@latest# Generate default settings
ccstatus init
# Register in Claude Code (re-run anytime to update; --subagent / --refresh N / --padding N / --hide-vim-indicator optional)
ccstatus install
# Try your layout against sample data, without starting Claude Code
ccstatus previewThat's it. Claude Code will now display the status line after each assistant message.
ccstatus [flags]
ccstatus [command]
| Command | Description |
|---|---|
init |
Generate default settings.json at the ccstatus config directory |
schema |
Print the JSON Schema of settings.json |
install |
Register ccstatus as the status line (and, with --subagent, subagent row) command in Claude Code's settings.json |
uninstall |
Remove the blocks that run ccstatus from Claude Code's settings.json |
validate |
Validate settings.json for correctness |
preview |
Render your settings against sample data (or --input FILE) |
subagent |
Render subagent rows for Claude Code's subagentStatusLine (Claude Code runs it) |
dump |
Save raw JSON input from Claude Code to a file for debugging (--subagent for the subagent row payload) |
widgets |
List all registered widget types with descriptions, default colors and prefixes |
completion |
Generate shell autocompletion script (bash, zsh, fish, powershell) |
| Flag | Description |
|---|---|
-h, --help |
Show help for any command |
-v, --version |
Print version |
ccstatus init [--force]Generates a default settings.json at ~/.config/ccstatus/settings.json (under $XDG_CONFIG_HOME when that is set). Use --force to overwrite an existing file. The file starts with a $schema reference, so editors complete and check it (see Editor Support).
ccstatus install [--subagent] [--refresh N] [--padding N] [--hide-vim-indicator]Registers ccstatus in Claude Code's ~/.claude/settings.json (or $CLAUDE_CONFIG_DIR/settings.json). A fresh install adds:
{
"statusLine": {
"type": "command",
"command": "ccstatus",
"padding": 0,
"refreshInterval": 30
}
}Every other key keeps its position and value, the file is replaced atomically, and a symlinked settings.json (for example one managed by a dotfiles repo) stays a symlink. Re-running install keeps the padding, refreshInterval and hideVimModeIndicator you set by hand and points command back at ccstatus, which also ends a temporary ccstatus dump.
Claude Code finds ccstatus through PATH. When it is not there, which is common after go install, the status line stays blank without an error, so install warns and names the fix: add the directory to PATH, or set command to the binary's absolute path. A command that names ccstatus by absolute path keeps that path on later installs, and --subagent uses it too.
Optional flags:
--subagent— also render subagent rows in the agent panel (writessubagentStatusLinerunningccstatus subagent;--subagent=falseremoves it). See Subagent Rows.--refresh N— re-run the status line everyNseconds (writesrefreshInterval). A fresh install uses30so time-based widgets (session-clock,block-timer,prompt-cache) and git widgets keep moving while Claude Code is idle;--refresh 0removes it so the status line runs only on Claude Code's events.--padding N— extra horizontal spacing, in characters, that Claude Code adds to the status line (writespadding; a fresh install uses0).--hide-vim-indicator— suppress Claude Code's built-in-- INSERT --line (writeshideVimModeIndicator;--hide-vim-indicator=falseremoves it). Set this if you use thevim-modewidget so the mode isn't shown twice;installprints a hint when no line has one.
ccstatus uninstallRemoves the statusLine and subagentStatusLine blocks whose command runs ccstatus. A block that runs another command is reported and left alone.
ccstatus validateReads settings.json strictly. Rendering skips what it does not understand, so a typo costs nothing but the effect you wanted; validate reports each one with its location:
- JSON errors and values of the wrong type, as
path:line:column - unknown keys, with the key a typo resembles (
unknown field "tresholds" (did you mean "thresholds"?)) or what replaced a removed one, and keys set twice - missing or unknown widget types, invalid colors (threshold and override colors included), and widgets on the wrong kind of line (
task-*widgets belong insubagentLine) - options that do nothing on their widget:
rawValuewithout a raw mode,displayvalues andthresholdsthe widget does not support,barWidthwithout abardisplay, andcharacter,customText,commandPath,timeoutorpreserveColorson another widget - a
custom-textorcustom-commandwithout its text or command, and a threshold withoutgte - out-of-range values: an unknown
flexMode,colorLeveloutside 0–3,compactThresholdoutside 0–100,barWidthoutside 1–100, a negativemaxWidth,timeoutorterminalWidth, and asubagentHideStatusesentry that is not a documented task status
Exits non-zero when any problem is found, so it works as a CI gate. Without a settings file it says that the defaults are in use and exits zero.
ccstatus dump [-o|--output FILE] [--append] [--subagent]Reads JSON from stdin (same as normal mode), saves it to a file, and renders the status line. Default output: /tmp/ccstatus-dump.json. Useful for inspecting what Claude Code sends. With --append, every invocation adds one JSON line — {"ts", "columns", "lines", "input"} — to /tmp/ccstatus-dump.jsonl (or --output), so a whole session can be captured. With --subagent, it stands in for ccstatus subagent instead: it saves the subagentStatusLine payload to /tmp/ccstatus-subagent-dump.json (/tmp/ccstatus-subagent-dump.jsonl with --append) and prints the subagent rows.
ccstatus preview [--input FILE] [--width N] [--subagent]Renders your current settings.json against the full sample payload from the official docs, with its timestamps moved to now and a sample branch and diff for the git widgets, so you can try a layout without starting Claude Code. --input renders a payload of your own (for example a dump capture); --width N renders as if the terminal were N columns wide (the flex-mode margin still applies); --subagent renders subagentLine for a sample task list, at the sample's columns unless --width is set.
ccstatus subagentThe subagentStatusLine command (set up by ccstatus install --subagent). Claude Code pipes the visible subagents as {"columns", "tasks": [...]}; ccstatus renders subagentLine for each task and prints one {"id", "content"} JSON line per row. A task whose status is listed in subagentHideStatuses gets an empty content, which hides its row. Rows that render empty, and every row on any error, are left out so Claude Code keeps its default rendering.
ccstatus schemaPrints the JSON Schema of settings.json, generated from the widget registry of the installed version. See Editor Support.
ccstatus widgetsLists all registered widget types with their descriptions, default colors and default prefixes.
# Default: read JSON from stdin, render status line
echo '{"model":{"id":"claude-opus-4-7","display_name":"Opus"}}' | ccstatus
# Replay captured dump data
cat /tmp/ccstatus-dump.json | ccstatus
# Preview the configured layout against sample data in a 120-column terminal
ccstatus preview --width 120Run by hand in a terminal with nothing piped in, ccstatus prints its help instead of waiting for input.
Settings are stored at ~/.config/ccstatus/settings.json (or $XDG_CONFIG_HOME/ccstatus/settings.json). Edit manually to customize.
A lean 2-line layout. Widgets with nothing to show — effort, fast-mode, git-worktree, rate-limits, session-name — are dropped, so a plain session collapses to model | Ctx% | branch | +/- | $ over cwd | Session.
Line 1: model · effort | Fast | context % | git branch + worktree | lines +/- | session cost (Fast only while fast mode is on)
Line 2: working directory | rate limits (5h/7d and the gateway spend limit, whichever are present) | session clock | session name (the name is capped at 30 columns)
Context % and the subagent task-context share one color scale: gray below 30%, white from 30%, yellow from 60% and red from 90%. Rate limits follow the same steps a shade brighter: white, then bright white from 30%.
Opus 4.7 (1M context) · max | Fast | Ctx: 36% | main feat-x | +12 -3 | $0.34
~/dev/myproj | Limit 5h: 3% / 7d: 12% | Session: 2h15m | Fix login redirect
Sonnet | Ctx: 12% | main | +4 | $0.05
~/dev/myproj | Session: 30m
To customize, edit the lines array in settings.json — e.g. swap rate-limits for the per-window rate-limit-5h (display: bar/reset/full), or add prompt-cache / cache-hit-rate. Fields you leave out of settings.json keep their defaults. (If line 1 is getting truncated with ..., see terminalWidth below.)
{
"$schema": "https://raw.githubusercontent.com/moonD4rk/ccstatus/main/schema.json",
"colorLevel": 2,
"hyperlinks": true,
"flexMode": "full-until-compact",
"compactThreshold": 90,
"defaultSeparator": "|",
"defaultPadding": " ",
"inheritSeparatorColors": false,
"globalBold": false,
"lines": [
[
{ "type": "model", "color": "cyan" },
{ "type": "separator" },
{
"type": "context-percentage",
"color": "brightBlack",
"thresholds": [
{ "gte": 30, "color": "white" },
{ "gte": 60, "color": "yellow" },
{ "gte": 90, "color": "red" }
]
}
]
]
}| Field | Type | Default | Description |
|---|---|---|---|
$schema |
string | (set by init) |
The JSON Schema editors use to complete and check the file; ccstatus does not read it |
colorLevel |
int | 2 |
0 disables color; 1 emits the 16 ANSI colors, 2 the 256-color palette, 3 true color (see Available Colors) |
hyperlinks |
bool | true |
Make the pr number and the repo name clickable OSC 8 links. Set false if your terminal, tmux or SSH session prints the escape codes instead |
flexMode |
string | "full-until-compact" |
Right margin each main line leaves: where the line is cut with ... and how far flex-separator fills (see Flex Modes) |
compactThreshold |
int | 90 |
Context % (0–100) at which full-until-compact switches to the wider (−40 col) right margin |
terminalWidth |
int | (auto) | Override the detected terminal width; the flexMode margin still applies. Leave unset/0 to auto-detect: ccstatus reads the COLUMNS variable that Claude Code (v2.1.153+) sets for status line commands, then falls back to the attached terminal, then 80. |
defaultSeparator |
string | "|" |
Text a separator item shows unless it sets character |
defaultPadding |
string | " " |
Inserted between adjacent widgets, separators included, except after an item with merge |
inheritSeparatorColors |
bool | false |
A separator without its own color takes the color of the widget before it |
overrideForegroundColor |
string | (none) | Force one foreground color on every widget and separator, thresholds included |
overrideBackgroundColor |
string | (none) | Force one background color the same way |
globalBold |
bool | false |
Apply bold to all widgets |
| Field | Type | Description |
|---|---|---|
type |
string | Widget type (see list below) |
color |
string | Foreground color: a name, #rrggbb or a palette index (see Available Colors) |
backgroundColor |
string | Background color, written the same way |
bold |
bool | Bold text |
prefix |
string | Text before the widget output, in place of the widget's default prefix such as Ctx: (ccstatus widgets lists them); "" removes the default |
suffix |
string | Text after widget output |
character |
string | The text of a separator, or an icon before the git-branch name |
rawValue |
bool | Use the widget's raw mode, on widgets that have one (the widget tables say what it shows) |
display |
string | One of the widget's display modes, such as bar (the widget tables list them, the default first) |
barWidth |
number | Width of a bar display in columns, 1–100 (default 10) |
maxWidth |
number | Cap the widget's text at this many columns, ending it with … (the prefix and suffix are not counted; wide characters count as two) |
merge |
bool | Join this widget to the next one without defaultPadding |
customText |
string | The text of custom-text |
commandPath |
string | Shell command for custom-command, run with sh -c and given Claude Code's JSON on stdin; the first line of its output is shown |
timeout |
number | custom-command timeout in milliseconds (default 3000); when it expires, the command and everything it started are killed and the widget is left out |
preserveColors |
bool | Keep the ANSI colors in custom-command output |
thresholds |
array | Restyle a numeric widget by value: [{ "gte": 70, "color": "yellow" }, { "gte": 90, "color": "red", "bold": true }]. The highest gte reached wins; below the first, color applies. Each entry may set color, backgroundColor, bold |
Thresholds work on widgets that render a number: the context and remaining percentages, cache-hit-rate, the rate-limit widgets (rate-limits uses the highest of its limits), spend-limit, prompt-cache (minutes until cold, or the hit percentage in hit mode), session-cost, context-length, the token counts, block-timer (the percentage of the window that has run), and task-tokens / task-context in subagentLine. ccstatus validate flags thresholds on any other widget.
| Mode | Description |
|---|---|
full |
Terminal width - 10 characters |
full-minus-40 |
Terminal width - 40 characters |
full-until-compact |
Terminal width - 10, switching to - 40 once context % >= compactThreshold (default) |
exact |
Terminal width, with no margin: for Claude Code's fullscreen rendering, where notifications get a row of their own |
With ccstatus install --subagent, Claude Code runs ccstatus subagent for the agent panel below the prompt, and each subagent row renders subagentLine — one row of widget items, configured like a line in lines. When subagentLine is absent, this default applies:
"subagentLine": [
{ "type": "task-name", "color": "cyan" },
{ "type": "task-status" },
{ "type": "task-elapsed" },
{ "type": "separator" },
{ "type": "task-model" },
{ "type": "task-effort", "prefix": "· " },
{ "type": "task-tokens" },
{ "type": "task-context", "color": "brightBlack", "thresholds": [{ "gte": 30, "color": "white" }, { "gte": 60, "color": "yellow" }, { "gte": 90, "color": "red" }] },
{ "type": "task-sparkline" },
{ "type": "separator" },
{ "type": "task-label" }
]reviewer running 1m23s | Sonnet 5.5 · high 45.2k 23% ▅▄▆▇██▇ | Reading internal/auth/session.go
Explore completed | Haiku 5.5 · 16k 18.4k 9% | Find every caller of Session.Refresh
Rows are sized to the width Claude Code reports, with no flex-mode margin. subagentLine takes the task-* widgets plus separator, flex-separator and custom-text; ccstatus validate flags anything else, and task-* widgets on the main lines. Try it with ccstatus preview --subagent.
To keep the panel short, subagentHideStatuses hides the rows of tasks in the listed states. It takes running, completed, failed and killed, and hides nothing by default:
"subagentHideStatuses": ["completed", "killed"]settings.json has a JSON Schema, generated from the widget registry. With it an editor completes widget types (with what each one shows), option names, display modes and colors, and flags most of what ccstatus validate reports as you type. ccstatus init writes the reference; add it to an existing file as the first key:
"$schema": "https://raw.githubusercontent.com/moonD4rk/ccstatus/main/schema.json"That URL follows the latest version. ccstatus schema > schema.json writes the schema of the version you have installed, to reference by path instead.
Settings written for v0.5 and earlier still render, without the options that changed. ccstatus validate names each one:
| Before | Now |
|---|---|
"id": "1" on every item, "version": 4 |
Removed: delete them |
"metadata": { "display": "bar", "barWidth": "20" } |
"display": "bar", "barWidth": 20 on the item itself |
"merge": "no-padding" |
"merge": true |
block-timer display progress / percentage |
bar / percent |
"prefix": "" kept the default prefix |
It removes the default prefix |
8 basic: black, red, green, yellow, blue, magenta, cyan, white
8 bright: brightBlack, brightRed, brightGreen, brightYellow, brightBlue, brightMagenta, brightCyan, brightWhite
Hex: "#ff8700", or the short form "#f80"
256-color palette: an index as a string, "0" to "255", such as "208"
The names are your terminal theme's own 16 colors, at every colorLevel. Hex and palette colors depend on the level: 3 emits a hex color exactly, 2 (the default) maps it to the nearest palette color, and 1 maps hex and palette colors to the nearest of the 16. Set colorLevel to 3 when your terminal supports true color.
| Widget | Source | Description | Default Color |
|---|---|---|---|
model |
JSON | Current Claude model name | cyan |
version |
JSON | Claude Code version | white |
session-id |
JSON | Session ID (8-char short) | white |
session-name |
JSON | Session name (--name / /rename, or the AI-generated title) |
white |
session-cost |
JSON | Session cost in USD | green |
session-clock |
JSON | Session duration | white |
output-style |
JSON | Output style name | white |
git-branch |
Git | Current branch name, or the short commit hash on a detached HEAD | magenta |
git-changes |
Git | Uncommitted changes count | yellow |
git-worktree |
JSON/Git | Worktree name | magenta |
tokens-input |
JSON | Input tokens in current context, incl. cache (~= context-length since CC v2.1.132) |
white |
tokens-output |
JSON | Output tokens from the most recent API response | white |
tokens-cached |
JSON | Cached tokens | white |
tokens-total |
JSON | Tokens currently in the context window (in + out) | white |
current-usage-input |
JSON | Current round input tokens | white |
current-usage-output |
JSON | Current round output tokens | white |
cache-creation |
JSON | Cache creation tokens | white |
context-length |
JSON | Context usage in tokens | white |
context-percentage |
JSON | Context usage % (display: bar for ▓▓▓░░░░░░░ 32%) |
white |
context-percentage-usable |
JSON | Usable context % (heuristic: 80% of max, leaving auto-compact headroom; bar display) |
white |
remaining-percentage |
JSON | Remaining context % (bar display) |
white |
cache-hit-rate |
JSON | Session prompt cache hit ratio (prompt_cache.hit_ratio; older Claude Code: the last request's cache reads; bar display) |
cyan |
prompt-cache |
JSON | Prompt cache state, e.g. warm 42m / cold — green while warm, dim once cold (display: status/ttl/hit/misses/full, e.g. warm 42m · 91% hit · 2 misses (tools_changed)) |
green |
api-duration |
JSON | Total API response time this session | white |
block-timer |
JSON | Time into the 5-hour rate-limit window, e.g. 2h47m/5h; hidden without rate-limit data (display: time/bar/percent) |
white |
rate-limits |
JSON | Combined limits, e.g. 5h: 3% / 7d: 12% or spend: $314.12/$500.00 behind a Claude apps gateway (each shown only when present) |
yellow |
spend-limit |
JSON | Claude apps gateway spend limit, e.g. $314.12 / $500.00 (63% until the dollar amounts arrive; display: amount/percent/bar/reset/full) |
yellow |
rate-limit-5h |
JSON | 5-hour rate-limit usage (display: percent/bar/reset/full) |
yellow |
rate-limit-7d |
JSON | 7-day rate-limit usage (display: percent/bar/reset/full) |
yellow |
current-working-dir |
JSON | Current directory name (raw: the full path, ~-shortened) |
blue |
project-dir |
JSON | Project root directory name (raw: the full path) | blue |
transcript-path |
JSON | Transcript file name (raw: the full path) | white |
added-dirs |
JSON | Directories added via /add-dir (display: list for names) |
blue |
repo |
JSON | Repository owner/name from the origin remote, an OSC 8 link to https://host/owner/name (raw: name only, unlinked) |
blue |
pr |
JSON | Open PR number + review state, e.g. #1234 approved, or !1234 for a GitLab merge request; the number is an OSC 8 link when pr.url is present (raw: number). Colored by review state: green approved, yellow pending, red changes requested, dim draft |
by state |
lines-changed |
Git | Uncommitted lines changed (+N/-M) | green |
lines-added |
Git | Uncommitted lines added | green |
lines-removed |
Git | Uncommitted lines removed | red |
session-lines |
JSON | Lines Claude added and removed this session (+N/-M) | green |
vim-mode |
JSON | Vim mode indicator | yellow |
agent-name |
JSON | Agent name | cyan |
effort |
JSON | Reasoning effort level | cyan |
thinking |
JSON | Extended thinking indicator | magenta |
fast-mode |
JSON | Fast while fast mode is on |
yellow |
exceeds-200k |
JSON | Warning at 200k tokens | red |
terminal-width |
System | Line width: the terminal width minus the flexMode margin |
white |
custom-text |
- | User-defined static text | white |
custom-command |
System | Shell command output | white |
separator |
- | Visual separator; dropped at either end of a row, beside a flex-separator and after another separator |
white |
flex-separator |
- | Fills the remaining width, keeping at least one column between the groups it separates | - |
Usable only in subagentLine; each reads the task Claude Code passes for that row.
| Widget | Description | Default Color |
|---|---|---|
task-name |
Subagent name, else its agent type, else the task type | cyan |
task-type |
Agent type, e.g. Explore or a custom agent |
magenta |
task-status |
running / completed / failed / killed, colored yellow / green / red / dim |
by state |
task-label |
Progress summary, else the task description | white |
task-elapsed |
Running time of a running subagent, e.g. 1m23s |
white |
task-model |
Model, e.g. Sonnet 5.5 (raw: model ID) |
cyan |
task-effort |
Configured effort level, or a token budget such as 32k |
cyan |
task-tokens |
Running token count, e.g. 45.2k (thresholds) |
white |
task-context |
Tokens as % of the model's context window (bar display, thresholds) |
white |
task-sparkline |
Tokens a running subagent added per refresh tick, e.g. ▂▅█▁ (▁ for none) |
cyan |
task-cwd |
Base name of the subagent's working directory | blue |
Claude Code pipes JSON session data to stdin on each update (after assistant messages, permission changes, vim mode toggles). ccstatus parses the JSON, renders widgets according to the configured layout, and outputs ANSI-colored text to stdout.
Claude Code --[JSON]--> ccstatus --[ANSI text]--> status line
For the full JSON schema, see the official documentation.
The separate subagentStatusLine command works the same way per subagent row, printing JSON lines instead of text; see Subagent Rows.
ccstatus never exits non-zero while rendering, because Claude Code hides the whole status line when the command fails. Problems show up in the status line instead:
- A
settings.jsonthat fails to parse renders the default layout below a redccstatus: settings.json:LINE:COL: ... (run ccstatus validate)line. Other mistakes, such as an unknown widget type or color name, are skipped without a message;ccstatus validatelists them. - Input that is not JSON renders a single red
ccstatus: invalid input: ...line. - A crash while rendering is caught and shown as a red
ccstatus: internal error: ...line, with the stack trace on stderr. - A field whose type changed in a newer Claude Code is coerced when that is unambiguous (a quoted number, a fractional epoch) or dropped otherwise, and the rest still renders; dropped fields are listed on stderr, which
claude --debuglogs.
Use ccstatus dump to capture the raw JSON that Claude Code sends:
# Temporarily switch to dump mode in ~/.claude/settings.json:
# "command": "ccstatus dump" (latest payload only)
# "command": "ccstatus dump --append" (every payload of the session, one JSON line each)
# and, for subagent rows, in the subagentStatusLine block:
# "command": "ccstatus dump --subagent --append"
# Then inspect the captured data:
cat /tmp/ccstatus-dump.json | jq .
jq -c '{ts, columns, model: .input.model.display_name}' /tmp/ccstatus-dump.jsonl
jq -c '{ts, tasks: [.input.tasks[] | {id, status}]}' /tmp/ccstatus-subagent-dump.jsonl
# Replay captured data to test rendering:
ccstatus preview --input /tmp/ccstatus-dump.json- Claude Code Status Line Documentation
- ccstatusline - Original TypeScript implementation
- Design RFCs - Architecture decisions and release plans
Apache License 2.0
