Skip to content
moonD4rkPublic

About

Customizable status line formatter for Claude Code CLI, written in Go

Topics

Resources

Stars

9 stars

Watchers

1 watching

Forks

Repository files navigation

ccstatus

Go CI codecov Go Reference License

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.

ccstatus in Claude Code terminal

Features

  • Single static binary with no runtime dependencies beyond git for 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/uninstall commands

Installation

Homebrew

brew install moond4rk/tap/ccstatus

Go

go install github.com/moond4rk/ccstatus/cmd/ccstatus@latest

Quick Start

# 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 preview

That's it. Claude Code will now display the status line after each assistant message.

CLI Reference

ccstatus [flags]
ccstatus [command]

Commands

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)

Global Flags

Flag Description
-h, --help Show help for any command
-v, --version Print version

Command Details

ccstatus init

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

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 (writes subagentStatusLine running ccstatus subagent; --subagent=false removes it). See Subagent Rows.
  • --refresh N — re-run the status line every N seconds (writes refreshInterval). A fresh install uses 30 so time-based widgets (session-clock, block-timer, prompt-cache) and git widgets keep moving while Claude Code is idle; --refresh 0 removes 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 (writes padding; a fresh install uses 0).
  • --hide-vim-indicator — suppress Claude Code's built-in -- INSERT -- line (writes hideVimModeIndicator; --hide-vim-indicator=false removes it). Set this if you use the vim-mode widget so the mode isn't shown twice; install prints a hint when no line has one.

ccstatus uninstall

ccstatus uninstall

Removes the statusLine and subagentStatusLine blocks whose command runs ccstatus. A block that runs another command is reported and left alone.

ccstatus validate

ccstatus validate

Reads 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 in subagentLine)
  • options that do nothing on their widget: rawValue without a raw mode, display values and thresholds the widget does not support, barWidth without a bar display, and character, customText, commandPath, timeout or preserveColors on another widget
  • a custom-text or custom-command without its text or command, and a threshold without gte
  • out-of-range values: an unknown flexMode, colorLevel outside 0–3, compactThreshold outside 0–100, barWidth outside 1–100, a negative maxWidth, timeout or terminalWidth, and a subagentHideStatuses entry 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

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

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 subagent

ccstatus subagent

The 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 schema

ccstatus schema

Prints the JSON Schema of settings.json, generated from the widget registry of the installed version. See Editor Support.

ccstatus widgets

ccstatus widgets

Lists all registered widget types with their descriptions, default colors and default prefixes.

Usage

# 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 120

Run by hand in a terminal with nothing piped in, ccstatus prints its help instead of waiting for input.

Configuration

Settings are stored at ~/.config/ccstatus/settings.json (or $XDG_CONFIG_HOME/ccstatus/settings.json). Edit manually to customize.

Default Layout

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.)

Settings Reference

{
  "$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" }
        ]
      }
    ]
  ]
}

Global Settings

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

Widget Item Options

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.

Flex Modes

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

Subagent Rows

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"]

Editor Support

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.

Upgrading Settings

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

Available Colors

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.

Available Widgets

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 -

Subagent Row Widgets

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

How It Works

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.

Debugging

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.json that fails to parse renders the default layout below a red ccstatus: 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 validate lists 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 --debug logs.

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

References

License

Apache License 2.0

About

Customizable status line formatter for Claude Code CLI, written in Go

Topics

Resources

Stars

9 stars

Watchers

1 watching

Forks

Releases

Contributors

Languages