Two minutes to a better Claude Code status line

I spend a lot of time in Claude Code sessions, and one thing that always nagged at me was how little the default status line told me. Model name, roughly. Not much else. When you’re mid-session trying to judge whether you’re approaching the context limit, or want to know which git branch the agent is working on without breaking flow — the default gives you nothing.

I came across ccstatusline while looking at how others were customising their setups. It’s a community-built status line formatter that plugs directly into Claude Code’s settings.json and replaces the default status bar with a configurable, real-time display.

What caught my attention immediately: it shows token usage in real time. Input tokens, output tokens, cached tokens, context window percentage. That context percentage alone changed how I work — I can now see at a glance when I’m approaching the point where I should compact or start a new session, rather than blindly pushing into the dumb zone.

What it shows

Once configured, my status line displays three rows:

Row 1 — session context: model, current context window usage, git branch, count of modified files.

Row 2 — token usage: input, output, cached (your cost saving), and session total.

Row 3 — context health: a visual progress bar of context consumption plus a compaction counter.

It supports 40+ widgets in total — you pick exactly what you want through an interactive terminal UI, and it saves your preferences to ~/.config/ccstatusline/settings.json.

Setting it up

Took me under two minutes. No installation — it runs via npx.

1. Run the interactive configurator:

npx -y ccstatusline@latest

This opens a terminal UI where you pick widgets, set colours, and preview the result live before committing to anything.

2. Let it write to settings.json. Once you’re happy, the tool offers to write directly to your Claude Code settings.json. Accept it. It adds a block like this:

"statusLine": {
  "type": "command",
  "command": "npx -y ccstatusline@latest",
  "padding": 0,
  "refreshInterval": 10
}

The refreshInterval: 10 means the status line updates every 10 seconds (requires Claude Code 2.1.97 or later).

3. Or copy my exact configuration. To replicate my three-row layout, save this to ~/.config/ccstatusline/settings.json:

{
  "version": 3,
  "lines": [
    [
      { "id": "1", "type": "model", "color": "cyan" },
      { "id": "2", "type": "separator" },
      { "id": "3", "type": "context-length", "color": "brightBlack" },
      { "id": "4", "type": "separator" },
      { "id": "5", "type": "git-branch", "color": "magenta" },
      { "id": "6", "type": "separator" },
      { "id": "7", "type": "git-changes", "color": "yellow" }
    ],
    [
      { "id": "a1", "type": "tokens-input" },
      { "id": "a2", "type": "separator" },
      { "id": "a3", "type": "tokens-output" },
      { "id": "a4", "type": "separator" },
      { "id": "a5", "type": "tokens-cached" },
      { "id": "a6", "type": "separator" },
      { "id": "a7", "type": "tokens-total" }
    ],
    [
      { "id": "b1", "type": "context-bar" },
      { "id": "b2", "type": "separator" },
      { "id": "b3", "type": "compaction-counter" }
    ]
  ],
  "flexMode": "full-minus-40",
  "compactThreshold": 60,
  "colorLevel": 2,
  "inheritSeparatorColors": false,
  "globalBold": false,
  "minimalistMode": false,
  "powerline": {
    "enabled": false,
    "separators": [""],
    "separatorInvertBackground": [false],
    "startCaps": [],
    "endCaps": [],
    "autoAlign": false,
    "continueThemeAcrossLines": false
  }
}

4. Restart Claude Code. That’s it — the new status line is live on next launch.

What changed for me

The context window percentage is the one I use most. Before this, I was guessing when to compact — now I can see the number climbing and make an intentional call. It also surfaces the cached token count, which gives you a real sense of whether prefix caching is actually working across your requests.

The git branch display is small but useful during AFK runs — when I come back to a session I can see at a glance which branch the agent has been working on without having to ask.

Worth knowing

• It runs via npx on every refresh, which adds a small startup cost each time. bunx is faster if you have Bun installed.
• It’s a community tool, not an official Anthropic project — keep that in mind if your environment has strict software policies.
• Requires Claude Code 2.1.97+ for the refreshInterval setting.

GitHub: github.com/sirmalloc/ccstatusline