Guide · Open source

How to use ccstatusline: install, configure and customize

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

ccstatusline is an open-source status bar for the Claude Code command-line tool. It can show things like the model in use, the git branch and token usage, and you can add, remove, reorder and color those pieces in a terminal settings screen. This guide covers what you need installed, how to launch the configuration screen, how the setup is saved to Claude Code settings, and what to check when something does not appear.

ccstatuslinesirmalloc/ccstatusline · ★ 13.5k · MIT Install options & downloads

Quick start

1Check prerequisites. Make sure Claude Code CLI is installed and that you have Node.js or Bun available.
2Open the TUI. Run npx -y ccstatusline@latest or bunx -y ccstatusline@latest in your terminal.
3Choose your widgets. Add, remove and reorder widgets, and set colors, in the preview screen.
4Install to Claude Code. Use the install option in the TUI so ccstatusline writes the statusLine entry to Claude Code settings.
5Optionally pin the version. Choose Pinned global install to run the ccstatusline command directly for faster repeated launches.
6Verify in a trusted folder. Open Claude Code in a trusted workspace and confirm the status line shows your chosen widgets.

What you need before you start

ccstatusline only works as a status line for Claude Code, so you need the Claude Code CLI installed. You also need either Node.js (to run npx) or Bun (to run bunx).

ccstatusline is licensed under MIT and written in TypeScript.

Claude Code CLI
Node.js, to run npx, or Bun, to run bunx

Launch the configuration screen with npx or bunx

The project needs no separate installation step to start. Run one of the two commands below from your terminal. Both launch the same terminal UI (TUI) for configuring the status line.

Startup time can vary with the package runner, its cache and your platform. If repeated status line launches feel slow, the README suggests a pinned global install instead.

npx -y ccstatusline@latest
bunx -y ccstatusline@latest

Pick and arrange the widgets you want

Inside the TUI you can configure multiple separate status lines, add, remove and reorder widgets, and customize colors for each widget. You can also configure flex separator behavior, edit custom text widgets and preview the status line in real time.

Use the preview to check the result before you install. Your settings are saved automatically to ~/.config/ccstatusline/settings.json.

Add, remove or reorder status line widgets
Set colors for each widget
Configure flex separator behavior
Edit custom text widgets
Preview the status line in real time

Install into Claude Code settings

When you install from the TUI, ccstatusline writes a statusLine command object to your Claude Code settings. With the @latest command, the written entry looks like this:

Choose Pinned global install if you want Claude Code to stay on the ccstatusline version you are running instead of following @latest. The TUI installs that version globally with npm or Bun and writes the command ccstatusline to settings. After a pinned install you can run ccstatusline directly to open the TUI.

refreshInterval is written only when your Claude Code version supports it, and the TUI can set it from 1 to 60 seconds.
Leaving the refreshInterval input empty removes it.
Under npx, pinning a version did not measure faster in the README's tests, so the pinned global install is the option the README recommends for faster repeated launches.

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

Fix common problems

If the status line is empty in one folder but works elsewhere, the README says Claude Code only runs the status line command in trusted workspaces, and nested git repositories stopped inheriting trust in Claude Code 2.1.232. The project's USAGE documentation has a section on this case.

If the Skills widget always shows none while you use a wrapper script, the README says Skills needs Claude Code hooks, which are only added when the status line command contains ccstatusline.

If your Claude Code configuration lives in a non-standard location, set the CLAUDE_CONFIG_DIR environment variable to that path.

Empty status line in one folder: check workspace trust.
Skills always none: make sure the command contains ccstatusline.
Custom config location: set CLAUDE_CONFIG_DIR.

export CLAUDE_CONFIG_DIR=/custom/path/to/.claude

Windows, proxies and backups

Windows users should read docs/WINDOWS.md in the repository, which covers PowerShell examples, fonts, troubleshooting, WSL and Windows Terminal configuration.

Usage and Claude Status requests honor an uppercase HTTPS_PROXY, with exclusions from NO_PROXY and no_proxy. The TUI can also export JSON backups and preview imported configs before replacing or merging settings.

What people use it for

See the model in use while you work in Claude Code all day.
Keep the current git branch visible in the status bar.
Watch token usage during long coding sessions.
Build a powerline-style status bar with custom colors.
Keep separate status lines with different widgets.

Frequently asked questions

Is ccstatusline free?

ccstatusline is released under the MIT licence, according to the project's README and repository metadata. The README does not mention any paid tier.

What do I need to install ccstatusline?

You need the Claude Code CLI plus either Node.js (for npx) or Bun (for bunx). The project itself runs with one of those commands and does not require a separate install to start.

How do I install ccstatusline?

Run npx -y ccstatusline@latest or bunx -y ccstatusline@latest, then use the TUI to configure and install it into Claude Code settings. You can choose a pinned global install for faster repeated launches.

Why is my ccstatusline status line slow?

The README notes that npx and bunx launches can be slow, and that the status line command runs on every repaint. Its suggested fix is the Pinned global install, which writes the ccstatusline command to settings.

Where are my ccstatusline settings saved?

Settings are saved automatically to ~/.config/ccstatusline/settings.json. The statusLine entry for Claude Code is written to your Claude Code settings file.

Does ccstatusline work outside Claude Code?

No. The README describes it as a status line for Claude Code CLI, so it has no use without Claude Code. It also does not provide a graphical app or browser interface.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

ccstatusline suits developers who use Claude Code in the terminal every day, want git branch or token usage on screen, and are comfortable editing settings in a terminal UI. If you do not use Claude Code, want a graphical or browser tool, or need a guaranteed fast startup, look elsewhere or follow the README's pinned global install advice.

Install options & downloads