ccstatusline
🎨 A highly customizable status line formatter for Claude Code CLI
Display model info, git branch, token usage, and other metrics in your terminal
📚 Table of Contents
🚀 Quick Start
No installation needed! Use directly with npx or bunx:
# Run the configuration TUI with npm
npx -y ccstatusline@latest
# Or use bunx, Bun's alternative to npx
bunx -y ccstatusline@latest
Startup time can vary with the package runner (npx or bunx), its cache, and your platform. If repeated status line launches are slow, consider the Pinned global install option described below to run ccstatusline directly.
Both commands launch the same TUI. During the initial setup flow, choose Pinned global install if you want Claude Code to stay on the ccstatusline version you are running instead of following @latest; the TUI will install that version globally with npm or Bun and write the pinned ccstatusline command to Claude Code settings. After a pinned install, you can run ccstatusline directly to launch the TUI in the future.
The interactive configuration tool provides a terminal UI where you can:
- Configure multiple separate status lines
- Add/remove/reorder status line widgets
- Customize colors for each widget
- Configure Claude Code status line refresh interval when supported
- Edit custom text widgets
- Export JSON backups and preview imported configs before replacing or merging settings
- Install/uninstall to Claude Code settings
- Preview your status line in real-time
💡 Tip: Your settings are automatically saved to ~/.config/ccstatusline/settings.json
🔧 Custom Claude Config: If your Claude Code configuration is in a non-standard location, set the CLAUDE_CONFIG_DIR environment variable:
# Linux/macOS
export CLAUDE_CONFIG_DIR=/custom/path/to/.claude
🌐 HTTPS proxy: Usage, Claude Status and update-check requests honor uppercase HTTPS_PROXY, with exclusions from both NO_PROXY and no_proxy. See proxy settings for host, domain, and port matching.
🪟 Windows Support: PowerShell examples, installation notes, fonts, troubleshooting, WSL, and Windows Terminal configuration are in docs/WINDOWS.md.
🫥 Status line empty in one folder? Claude Code only runs the status line command in trusted workspaces, and nested git repositories stopped inheriting trust in Claude Code 2.1.232. See Status line empty in one folder.
🧩 Skills always none with a wrapper script? Skills needs Claude Code hooks, which are only added when the status line command contains ccstatusline. See Skills always shows none.
When you install from the TUI, ccstatusline writes a statusLine command object to your Claude Code settings:
{
"statusLine": {
"type": "command",
"command": "npx -y ccstatusline@latest",
"padding": 0,
"refreshInterval": 10
}
}
refreshInterval defaults to 10 seconds on fresh installs when Claude Code supports it (>=2.1.97). Reinstalling preserves an existing value even if the version check fails. The TUI can set it to 1-60 seconds, or remove it by leaving the input empty.
Other supported command values are:
bunx -y ccstatusline@latestccstatusline (for self-managed/global installs)
The status line command runs once per repaint, so what it costs to invoke is paid over and over. Under
Bun that cost depends on the specifier: bunx re-resolves the latest dist-tag against the registry
on every run, because a dist-tag is not cacheable. Measured on Windows with a warm cache, median of
five runs of --version, which exits before rendering:
| command | median |
|---|
bunx -y ccstatusline@latest | 633 ms |
bunx -y [email protected] | 202 ms |
bunx -y ccstatusline | 207 ms |
Dropping @latest is worth about 430 ms per repaint there. npm does not behave this way: npx -y ccstatusline@latest and npx -y [email protected] measured 1082 ms and 1135 ms, so pinning buys
nothing under npx. A Pinned global install, which writes "command": "ccstatusline", avoids the
resolution entirely on both.
For pinned installs, launch the TUI with npx -y ccstatusline@latest or bunx -y ccstatusline@latest, then choose Pinned global install. The TUI pins the active version by installing it globally and writing "command": "ccstatusline" to settings.json; afterward, you can run ccstatusline directly to open the TUI.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
