ccbrief

The status line for Claude Code,
kept brief.

ccbrief shows how full your context is, when your rate limit resets, what the session costs and which model you're on, right under the prompt.

  • ccbrief/mainRepo and branch
  • 42% ━━━━─────Context used
  • ⏳2h 0m · 40%5-hour limit: resets in, used
  • Opus 5.5Model
npx ccbrief init

Needs Node 22 or newer. Runs on macOS, Linux, Windows and WSL. No restart needed. See ccbrief on npm.

A terminal running npx ccbrief init, which installs ccbrief and prints a preview of the status line, then npx ccbrief config: the picker switches presets, turns on the session cost segment, moves it next to the context bar, cycles the symbol sets, toggles icons and saves. The live preview updates on every keypress.
Install, then choose what it shows. The badge on the right names each key as it is pressed. Open full size.

Not affiliated with, or endorsed by, Anthropic. ccbrief is an independent, open-source project that reads the data Claude Code already provides. It makes no network calls and sends no telemetry.

Install

npx ccbrief init

This copies a self-contained renderer into ~/.claude/ccbrief/, backs up your settings.json and adds the statusLine block to it. The rest of your settings stay as they are. When it finishes, it shows a preview and the next steps.

You don't need to restart. Claude Code reloads its settings on its own, so the status line appears the next time you interact with it.

Requires Node 22 or newer. Works on Windows, macOS, Linux and WSL.

Update

npx ccbrief@latest init

Running init again is how you upgrade. It copies the renderer, so a newer package has no effect until you run it. It's safe to re-run: your config and your other settings are kept.

Installed globally instead? Run npm install -g ccbrief@latest, then ccbrief init.

Uninstall

npx ccbrief uninstall

This restores your backed-up settings.json, or removes only the statusLine block ccbrief added. It asks before deleting ~/.claude/ccbrief/.

Presets

standard is the default. It shows where you are, how full the context is, when your limit resets and how much of it you've used, and which model you're on.

ccbrief/main │ 42% ━━━━───── │ ⏳2h 0m · 40% │ Opus 5.5

detailed adds the folder name, lines changed, tokens, session cost, the weekly limit and reasoning effort. Press p in the picker to switch to it, then turn off anything you don't need.

ccbrief │ ccbrief/main │ +120/-34 │ 42% ━━━━───── │ 128k │ $1.23 │ ⏳2h 0m · 40% │ wk 3d 4h · 62% │ high │ Opus 5.5

If the line is wider than your terminal, ccbrief moves whole segments onto up to three rows. A segment is never split, and the terminal never wraps it halfway:

ccbrief │ ccbrief/main │ +120/-34 │ 42% ━━━━───── │ 128k │ $1.23
⏳2h 0m · 40% │ wk 3d 4h · 62% │ high │ Opus 5.5

Segments with no data are hidden. Context % and rate limits are null early in a session and right after /compact, so ccbrief leaves them out until Claude Code reports a value. It never shows a placeholder 0%.

Configure

npx ccbrief config

This opens an interactive picker with a live preview. It lists every segment, each with a plain-English name. Saving also updates settings.json, so your changes appear on Claude Code's next render. You don't need to reinstall.

Picker keys
KeyDoes
spaceShow or hide the focused segment
↑ ↓Move between segments
← →Move the focused segment left or right
pCycle preset
yCycle symbols
cToggle colors
iToggle icons
lCycle layout
dOn repo: show or hide the working-tree diff (+3/-1)
t %On fiveHour and weekly: show or hide the countdown (t) or the usage percent (%)
↵Save and exit
escQuit without saving

The config file

The config lives at ~/.claude/ccbrief/config.json. Set CLAUDE_CONFIG_DIR to move the base directory. The file is optional: if it's missing or malformed, ccbrief uses the defaults and the status line keeps working. The picker writes it for you.

Config keys
KeyValuesDefault
presetstandard, detailed or customstandard
layoutauto, single-line (drops the segments that don't fit) or multi-lineauto
maxRows1 to 33
symbolssimple, emoji, nerd-font or asciisimple
colorstrue or falsetrue
iconstrue or falsetrue
segmentsOrdered list, read only when preset is customNone

Written by hand, a custom config looks like this:

{
  "preset": "custom",
  "segments": [
    { "id": "repo", "enabled": true, "showDiff": true },
    { "id": "context", "enabled": true },
    { "id": "fiveHour", "enabled": true, "showTime": true, "showPercent": true },
    { "id": "model", "enabled": true }
  ]
}

A named preset has its own fixed list, so a segments key next to it does nothing. Unknown ids are ignored.

Segments

Each segment hides itself when its data is missing.

SegmentShowsHidden when
directoryCurrent directory (ccbrief)No workspace directory
repoRepo and branch (ccbrief/main); showDiff adds +3/-1Not in a git repo
contextContext used, with a bar (42% ━━━━─────)Early in a session, or after /compact
tokensTokens in context (128k)Before the first response, or after /compact
costSession cost ($1.23)No data
fiveHourSession limit: reset countdown and usage (⏳2h 0m · 40%)Not on Pro/Max
weeklyWeekly limit: reset countdown and usage (wk 3d 4h · 62%)Not on Pro/Max
linesLines Claude added and removed this session (+120/-34)No data
effortReasoning effort (high)No data
modelActive model (Opus 5.5)No data
prPR number and review state, as a clickable link (OSC 8)No PR for the branch
worktreeActive git worktree nameNot in a worktree
thinkingThinking indicatorThinking is off
outputStyleOutput style name (concise)No data
agentActive subagent nameNo subagent running

The last five aren't in either preset. The picker still lists them, and space turns one on. The rate-limit countdown shows the time left until your limit resets, so it never turns red. The usage % next to it is the part that changes color as you use up the limit.

Colors and symbols

Each field has its own color so you can find it at a glance: context is magenta, tokens yellow, the reset timer green and the model cyan. Only the context bar and the rate-limit percent change color with their value, going from green to yellow to red as they fill.

ccbrief uses the standard ANSI palette instead of fixed RGB values, so your terminal theme sets the exact shades and the line stays readable on dark and light themes.

The ccbrief status line showing directory, git branch, lines changed, context-window usage with a bar, tokens, session cost, 5-hour and weekly rate-limit resets, reasoning effort and the active model, rendered on a dark and a light terminal theme.
The same line on a dark and a light terminal.

There are four symbol sets. Each one sets the icons, the bar characters and the separator. simple is the default: plain text plus the ⏳ timer, with no special font needed.

simple    ccbrief/main │ 42% ━━━━───── │ 128k │ ⏳2h 0m · 40% │ high │ Opus 5.5
emoji     🌿ccbrief/main │ 42% ━━━━───── │ 🔸128k │ ⏳2h 0m · 40% │ ⚡high │ 🧠Opus 5.5
nerd-font   ccbrief/main │ 42% ━━━━───── │ 128k │ ⧗ 2h 0m · 40% │  high │  Opus 5.5
ascii     ccbrief/main | 42% ####----- | 128k | S 2h 0m · 40% | high | Opus 5.5

nerd-font shows blank boxes unless you have a Nerd Font installed. The picker's live preview lets you check it before you save. If the ⏳ timer shows as a box, your terminal has no emoji font, so pick ascii. To turn colors or icons off, set colors: false or icons: false, or press c or i in the picker.

FAQ

How do I add a status line to Claude Code?
Run npx ccbrief init. It writes the renderer to ~/.claude/ccbrief/, backs up your settings.json, and adds a statusLine block to it. You don't need to restart Claude Code.
Why did my context percentage disappear?
Claude Code hasn't reported it yet. used_percentage is null early in a session and right after /compact, so ccbrief hides the segment instead of showing 0%. It comes back after the next response.
Can I see my 5-hour and weekly rate limits?
Yes. The fiveHour and weekly segments show the reset countdown and the percent used. Claude Code only reports rate limits on Pro and Max plans, so on other plans they stay hidden.
Does it work on Windows?
Yes. It runs on Windows, WSL, macOS and Linux with Node 22 and 24. CI runs the full test suite on Windows, macOS and Linux.
How is this different from a shell script with jq?
A typical bash status line runs jq once per field, about twenty processes on every render. ccbrief is a single Node process that parses the session JSON once, and the renderer it installs is one self-contained file with no dependencies.
Can I choose which segments to show?
Yes. Run npx ccbrief config. It lists all fifteen segments with a live preview. See Segments.