cc-statusline

A clean statusline for Claude Code.

It shows your current model, context usage, and rate-limit windows directly in the Claude Code statusline.

Opus xhigh │ ctx(1m)        ⣿⣿⣿⣿⣿ 58% │ 5h          ⣿⣿ 76% 22:00 │ 7d    ⣿⣿⣿⣿⣿⣿⣿⣿ 29% May 06 02:00

Install

npm

Works on macOS, Linux, and Windows. Requires Node.js to be installed.

npm install -g cc-statusline-cli
cc-statusline install

The npm package uses the Node.js runtime and does not require Bash or jq. It does not run a postinstall script, which keeps npm lifecycle scripts disabled-friendly and avoids writing Claude Code settings during package installation. Run cc-statusline install after npm install to register the statusline in Claude Code.

On Windows, run the same commands from PowerShell or CMD. The installer writes to %USERPROFILE%\.claude\settings.json.

Homebrew

Homebrew install is for macOS only. It needs two steps: install the formula, then run cc-statusline configure to wire ~/.claude/settings.json.

brew tap tenondecrpc/tap
brew install cc-statusline-cli
cc-statusline configure

The configure step is required because macOS TCC blocks Homebrew's post_install from writing under ~/.claude/, so the formula cannot register the statusline by itself.

Replace an existing custom statusline:

cc-statusline configure --force

Keep an existing custom statusline (only install files, leave settings.json alone):

cc-statusline configure --keep-existing

cc-statusline configure creates a backup of ~/.claude/settings.json before changing it. After registration, restart Claude Code or open a new session for the statusline to appear.

Requirements

• npm install: Node.js 18+. Bash and jq are not required.
• Homebrew install: Bash 3.2+ and jq 1.6+
• git for repository status

jq is only needed by the Homebrew/Bash runtime. It is not included with macOS by default, but Homebrew installs it automatically as a dependency. The npm install does not need jq.

Help

cc-statusline help
cc-statusline version
cc-statusline install --force

Uninstall

Run cc-statusline uninstall to restore your previous settings.json backup and remove the npm package in one step:

cc-statusline uninstall

If you only want to clean the statusLine entry without removing the package:

cc-statusline uninstall --keep-package

Add --purge to also remove the user config directory (~/.config/cc-statusline):

cc-statusline uninstall --purge

For Homebrew, restore your previous settings.json from the backup before uninstalling, otherwise Claude Code will reference a missing script:

# pick the most recent backup, or remove the .statusLine entry by hand
ls -t ~/.claude/settings.json.bak.* | head -1
cp ~/.claude/settings.json.bak.YYYYMMDD-HHMMSS ~/.claude/settings.json
brew uninstall cc-statusline-cli

Customization

Create ~/.config/cc-statusline/config.json to override any setting from the active preset. Only the fields you specify are changed - everything else keeps its default.

Switch preset

{ "preset": "minimal" }

Built-in presets: default, minimal, developer.

Change modules shown

{
  "lines": [
    ["model", "context_bar", "rate_limit"]
  ]
}

Available modules: model, directory, git, context_bar, rate_limit, cost, session_timer, worktree, agent, vim_mode.

Change separator and colors

{
  "separator": " | ",
  "colors": {
    "model": "cyan",
    "directory": "blue"
  }
}

Color names: black, red, green, yellow, blue, magenta, cyan, white, gray, bright_green, bright_blue.

Tweak a module option

{
  "modules": {
    "directory": { "truncate": 20 },
    "context_bar": { "width": 8 },
    "cost": { "hide_below": 0.10 }
  }
}

Context window label

The context bar prints the model context size next to the label, e.g. ctx(1m) or ctx(200k). The size is read from context_window.context_window_size in the Claude Code session payload and formatted as 200k, 1m, 1.5m, etc.

If the field is missing (Claude Code did not provide it), the bar falls back to modules.context_bar.default_size:

{
  "modules": {
    "context_bar": {
      "default_size": "200k"
    }
  }
}

Changes take effect immediately - no restart needed.

License

MIT