claudekit / guides / ccstatusline-guide
[ Guide · Practical · 10 min ]

Upgrade Your Terminal with ccstatusline

published · updated

Walks through customizing the Claude Code status line with ccstatusline — Powerline-style themes, model and token usage, and Git info on a single line.

Why replace the status bar?

Claude Code’s default status bar shows only the essentials. During long sessions you want token usage, active model, and git branch visible at a glance — context-switching to check those costs attention.

ccstatusline is an independent CLI that lets you configure those widgets interactively.

Install and first setup

npx -y ccstatusline@latest

This opens an interactive TUI. Use arrow keys to navigate, Enter to select, ESC to back out.

When you save, ccstatusline writes the statusLine field in ~/.claude/settings.json for you. The next Claude Code session uses the new bar.

Configure widgets

Choose which widgets to display:

  • Model — active Claude model (Opus 4.7, Sonnet 4.6, etc.)
  • Token usage — live state of the 5-hour usage block
  • Git branch — current branch
  • Session timer — elapsed session time
  • Memory — system memory indicator
  • Context window — current conversation token usage

Enable only the widgets you actually need. Cramming too many widgets in a narrow terminal causes truncation.

Themes and colors

ccstatusline ships several Powerline-style themes — preview them with arrow keys. Per-widget color is adjustable in the TUI’s color settings, so you can match your terminal theme.

Editing the config later

Running npx -y ccstatusline@latest again loads the existing config and lets you edit it. There’s no need to hand-edit any config file.

Pair well with

  • ccusage — daily/monthly token and cost breakdowns. Complements ccstatusline’s live readout.
§ 7

Frequently Asked Questions

frequently asked
§ 7.1
What does ccstatusline do?
It's an independent CLI that decorates the Claude Code terminal status bar with Powerline-style widgets — active model, token usage, git branch, and more — so the information you actually want is visible at a glance.
§ 7.2
How do I apply it?
Run `npx -y ccstatusline@latest`, pick a theme and widgets in the interactive TUI, save, and Claude Code's status line picks it up automatically.
§ 7.3
Do I have to edit Claude Code settings manually?
No. The ccstatusline TUI updates the `statusLine` field in `~/.claude/settings.json` for you.
§ 7.4
Are the token usage numbers accurate?
The 5-hour block readout reflects what Claude Code exposes, so it's accurate for that view. For detailed daily/monthly cost analysis, pair ccstatusline with ccusage.
§ 7.5
How do I customize themes and colors?
ccstatusline ships built-in Powerline themes, and the TUI's color settings let you tune each widget's color individually.