sirmalloc/ccstatusline: A Customizable Status Line for Claude Code CLI

What ccstatusline Is and Who It Is For

ccstatusline is a status line formatter built specifically for the Claude Code command-line interface. Claude Code runs in the terminal and, by default, provides limited visibility into session metrics during a session: which model is active, how many tokens have been used, what the current session cost is, and what state the git repository is in all require separate commands to check. ccstatusline addresses this by rendering a formatted status line that Claude Code can display as part of its interface, updated on each interaction.

The tool is described in its README as a customizable status line formatter that can display model info, git branch, token usage and other metrics. The package is published on npm under the name ccstatusline at version 2.2.30. It is written in TypeScript and compiled to JavaScript for distribution. The binary entry point is ccstatusline, exposed through the npm bin field. The target audience is engineers who use Claude Code regularly and want persistent visibility into session state, similar to how a shell prompt might show git branch and exit code. It has no use outside of the Claude Code CLI context.

Installing ccstatusline from npm

The package is distributed on npm under the name ccstatusline. The package.json lists version 2.2.30. To install globally:

npm install -g ccstatusline

Alternatively, the RELATED SEARCHES data for this project includes "Npx ccstatusline" as a search term, suggesting that running without a global install via npx is also a common path:

npx ccstatusline

The repository root includes a bun.lock file, indicating the project is developed with Bun. The build script in package.json uses Bun to compile the TypeScript source: bun build src/ccstatusline.ts --target=node --splitting --format=esm --outdir=dist. The published package in the dist/ directory contains the compiled JavaScript. Node.js is required at runtime (the package.json engines field targets Node.js 14+). Windows users are directed to a separate document at docs/WINDOWS.md for platform-specific setup instructions.

Widgets: What ccstatusline Displays

The status line is composed of widgets, each displaying a specific metric. The recent update notes in the README describe a wide range of available widgets. Model-related widgets include the current Claude Code model name, weekly Sonnet usage, weekly Opus usage, weekly Fable usage (added in v2.2.25) and session usage, each as a percentage or progress bar. The Claude Status widget (added in v2.2.28) shows live service health severity with a cached 48-hour incident history strip and a fallback character when status data is unavailable.

Git widgets display branch name, clean or dirty state, insertion and deletion counts, conflict count and pull request CI status. The Git CI Status widget (added in v2.2.22) summarizes failing, pending and successful GitHub Actions checks for the current branch's pull request. The Sandbox Status widget shows Claude Code's current sandbox setting. Timing widgets include Block Timer, Block Reset Timer and Weekly Reset Timer, all with configurable progress bars. A Cache Timer widget shows whether a prompt cache is in a HOT state with a TTL countdown. Session metrics include token count, session duration, request speed and compaction state. The full list of widgets is documented at docs/USAGE.md in the repository.

Powerline Mode, Flex Layout and Theme Options

ccstatusline supports a Powerline display mode that uses arrow-shaped separators between widgets, producing the visual style common in terminal prompts with Nerd Font glyphs. Powerline flex mode, added in v2.2.22, allows flex separators in Powerline layouts. Full-width layout is the default for new configurations as of v2.2.29.

Layout controls include one-sided padding (left only, right only, or both sides) for standard and Powerline layouts, added in v2.2.22. Widgets can be hidden conditionally using a shared h checklist added in v2.2.28: numeric, Git, JJ, usage, cache and other widgets all share this unified hide mechanism. The hide conditions include options like hiding a widget when its value is zero, hiding loading states, and hiding error output.

Number formatting is configurable per widget or globally in v2.2.28: precise, compact or whole-number styles apply to token counts, speed values, percentages, memory figures and cost values. Decimal precision can be set explicitly in advanced configurations. Git and JJ symbols are editable: pressing g in the TUI opens fields for insertion and deletion signs, clean and dirty markers, and the JJ Revision prefix.

TUI Configuration and Config Import/Export

Configuration is handled through a built-in terminal user interface. The README's table of contents lists a Configure Status Line section under the Quick Start heading. Within the TUI, pressing g opens symbol editing for Git and JJ markers. Pressing h opens the hide conditions checklist for supported widgets. Pressing f toggles 12/24-hour format for timer widgets, and o toggles weekly hours-only display.

v2.2.27 added configuration import and export: the current TUI configuration can be exported to a JSON file, and an import flow validates and previews a supplied JSON before applying it. Importing can replace all settings or merge only the supplied fields while preserving local installation metadata. Imported settings are left unsaved for review before committing.

The repository includes a configTemplates/ directory with pre-built configuration templates. The docs/ directory holds USAGE.md, DEVELOPMENT.md and WINDOWS.md. The AGENTS.md and CLAUDE.md files at the root suggest the project documents AI agent and Claude Code interaction patterns explicitly, which makes sense given the tool's purpose.

Platform Limitations and Performance Notes

Windows support is documented in a separate file (docs/WINDOWS.md) rather than in the main README, which signals that Windows configuration requires additional steps not covered in the quick start path. The v2.2.29 release notes describe a Linux-specific optimization for terminal width detection (direct probing without subprocesses), with portable fallbacks for other platforms, indicating platform differences in the rendering layer.

For large sessions, the v2.2.28 release addressed a performance issue: transcript-backed token, duration, speed, compaction, effort and session-name metrics previously loaded an entire transcript into a single string. After v2.2.28, those metrics stream JSONL records through one shared scan. This change is relevant for long sessions where the transcript file has grown substantially.

The Git CI widget and Git PR widget use the gh CLI to fetch pull request and check status data. These are network calls, and slow gh responses previously blocked the status line render. v2.2.25 added non-blocking background refresh for both widgets, rendering from a versioned disk cache while the data refreshes.

Release Cadence and MIT License

Three releases appeared in September 2026: v2.2.28 on 2026-09-03, v2.2.29 also on 2026-09-03 and v2.2.30 on 2026-09-17. The last push to the repository was on 2026-09-21. This cadence indicates active development with frequent patch and feature releases.

The license is MIT. MIT imposes no restrictions on commercial or private use and requires only that the copyright and license notice be included in redistributions. The NOTICE file in the repository root suggests there are additional attribution requirements beyond the LICENSE file itself, which is worth reviewing before redistribution.

The package.json prepublishOnly script runs bun run build before publishing, which means the published npm package always contains a freshly compiled dist/ directory. The node_modules are not included in the npm package: only the dist/ directory is listed in the files field. The package does not list any runtime npm dependencies beyond Node.js itself, as all runtime code is bundled into the dist/ccstatusline.js output.

Editorial conclusion

Claude Code users who want token usage, cost, model name and git branch visible at all times without running separate terminal commands will find ccstatusline practical and directly useful. The tool is specific to Claude Code: it has no value outside that CLI. Engineers running Claude Code on Windows should check docs/WINDOWS.md separately before installing, since the README links to a dedicated Windows support document. The latest release is v2.2.30 from 2026-09-17. The MIT license allows unrestricted use, and the npm package name is ccstatusline.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes