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.

A community open-source project by sirmalloc (sirmalloc/ccstatusline). This guide reflects v2.2.32.

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
# or, with Bun
bunx -y ccstatusline@latest

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

When you install from the TUI, ccstatusline writes the statusLine field in ~/.claude/settings.json for you. Claude Code reloads settings automatically and runs the status line command as soon as the file is saved, so the new bar appears without restarting your session.

There are two ways to install:

  • Pinned global install (default) — installs the version you are running globally with npm or Bun and writes "command": "ccstatusline" to settings.json. Claude Code stays on that version, and the runner’s package resolution is skipped on every repaint. Afterward, run ccstatusline directly to open the TUI.
  • Auto-updating — writes npx -y ccstatusline@latest so the status line always follows @latest.

Configure widgets

Choose which widgets to display. The widget picker supports search with substring and fuzzy matching.

  • Model — active Claude model (Opus 5.5, Sonnet 5.5, etc.)
  • Usage — Block Usage (current 5-hour block), Weekly Usage, Weekly Sonnet/Opus/Fable Usage, and Block Timer (time elapsed in the current block)
  • Git Branch — current branch, alongside other Git widgets such as Git PR and Git CI Status
  • Session Clock — elapsed session time
  • Memory Usage — system memory usage
  • Context %, Context Length — current context window usage
  • Claude Status, Cache Timer — Claude service status and time remaining before the prompt cache expires

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.

Refresh interval

Claude Code re-runs the status line on events such as a new assistant message or /compact finishing. For time-based widgets like clocks and usage, set refreshInterval from the TUI’s Configure Status Line menu to re-run it every 1-60 seconds as well (Claude Code 2.1.97 or later).

Editing the config later

Run the TUI again (ccstatusline, or npx -y ccstatusline@latest) to load the existing config and edit it. Settings are saved to ~/.config/ccstatusline/settings.json, so there’s no need to hand-edit any file. To back up or move a configuration, use the TUI’s Export Config and import options.

Pair well with

  • ccusage — daily/monthly token and cost breakdowns. Complements ccstatusline’s live readout.
  • To build your own script instead, run Claude Code’s /statusline command with a natural-language description of what you want displayed (docs).
§ 8

Frequently Asked Questions

frequently asked
§ 8.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.
§ 8.2
How do I apply it?
Run `npx -y ccstatusline@latest` (or `bunx -y ccstatusline@latest`), pick widgets and a theme in the interactive TUI, and install it to Claude Code settings. If you choose Pinned global install, the default option, the TUI installs that version globally and you can run `ccstatusline` directly to open it later.
§ 8.3
Do I have to edit Claude Code settings manually?
No. When you install from the TUI, ccstatusline writes a `statusLine` command object to `~/.claude/settings.json`. Its own settings are saved separately to `~/.config/ccstatusline/settings.json`.
§ 8.4
Where do the usage widgets get their numbers?
Usage widgets such as Block Usage and Weekly Usage make a direct API call to Anthropic, while Block Timer detects 5-hour block boundaries from transcript timestamps. For detailed daily or monthly cost analysis, pair ccstatusline with ccusage.
§ 8.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.