_ _ _ _
___ ___ ___| |_ __ _| |_ _ _ ___| (_)_ __ ___
/ __/ __/ __| __/ _` | __| | | / __| | | '_ \ / _ \
| (_| (__\__ \ || (_| | |_| |_| \__ \ | | | | | __/
\___\___|___/\__\__,_|\__|\__,_|___/_|_|_| |_|\___|
🎨 A highly customizable status line formatter for Claude Code CLI Display model info, git branch, token usage, and other metrics in your terminal
- Recent Updates
- Features
- Localizations
- Quick Start
- Windows Support
- Usage
- Development
- Contributing
- License
- Related Projects
# Run the configuration TUI with npm
npx -y ccstatusline@latest
# Or use bunx, Bun's alternative to npx
bunx -y ccstatusline@latestStartup 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.
Configure ccstatusline
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_DIRenvironment variable:# Linux/macOS export CLAUDE_CONFIG_DIR=/custom/path/to/.claude
🌐 HTTPS proxy: Usage and Claude Status requests honor uppercase
HTTPS_PROXY, with exclusions from bothNO_PROXYandno_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
nonewith a wrapper script? Skills needs Claude Code hooks, which are only added when the status line command containsccstatusline. See Skills always shows none.
Claude Code settings.json format
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 ccstatusline@2.2.27 |
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 ccstatusline@2.2.27 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.
Includes all 56 PRs merged since the v2.2.32 tag.
- 🔮 Block forecasts - New Block Forecast and Block Limit Timer widgets project 5-hour usage at reset and estimate time to the limit from your recent pace.
- ⏳ Clearer block usage and countdowns - Session Usage is now Block Usage with a
5h:label; hide it at 100% and hide Block Reset Timer below 100% to swap the percentage for a reset countdown. - 💳 Gateway spend limits - New Spend Limit Usage and Spend Limit Amount widgets show gateway-reported usage percentages and dollar amounts without an extra API request.
- ⚡ Fast Mode and Extra Usage Limit - Display Claude Code's fast-mode state and your monthly extra-usage limit, with configurable formats and hide states.
- 👀 Live widget picking - Preview highlighted widgets before adding, inserting, or changing them; long picker lists scroll to keep the preview visible, and global installs no longer pause on each editor keypress.
- 🔗 Directory and status links - Open the current directory in a file manager, VS Code, or Cursor while keeping your preferred path abbreviation; Claude Status can link its text and history strip to the status page.
- 🌿 Shorter Git names - Toggle fish-style abbreviation for Git Branch and Git Worktree while branch links keep their full targets.
- 🎨 Glyph controls - Customize Remote Control Status's Nerd Font on/off glyphs and label formats, with a corrected Nerd Fonts v3 off icon; Shift+Tab clears or restores every glyph slot together.
- 📊 Accurate token and context metrics - Split or interleaved records from one API response no longer inflate token totals or speed; calculated context percentages exclude output tokens until they become input.
- ⏱️ Reliable cache and usage timing - Cache Timer prefers Claude Code's reported cache expiry; stale usage fallback drops windows that have reset, and remaining-usage bars place their cursor at time remaining.
- 👤 Account and profile isolation - Usage caches and backoff locks are separate per Claude config directory, account email follows the live credentials, and macOS credential lookups retry by username and stop further Keychain probes after a timeout.
- 🏷️ Automatic session titles - Session Name falls back to Claude Code's generated title when no custom rename exists.
- ⌨️ Clearer editing - Blinking bar cursors make trailing spaces visible, and label edits update the status-line preview before confirmation.
- 🛠️ Developer reload - Set
CCSTATUSLINE_DEV_RELOAD=1and press Ctrl+R to restart the TUI with the latest code while retaining unsaved settings and navigation. - 🩹 Miscellaneous bug fixes - Preserve manual separators across Powerline toggles and existing refresh intervals during failed version checks; fix wrapped-hook dispatch, block detection, Git/JJ counts and detached-HEAD handling, Git cache timing, install detection, default colors, memory-unit rounding, and the terminal-width menu's default label.
- 📐 Rendering and hook feedback - Hidden widgets end merges unless merged onward; 8-bit terminal colors and hyperlinks render correctly while other control sequences are removed whole, and saves explain when a wrapper command prevents widget-hook installation.
- 🔧 Maintenance - Refresh dependencies and publishing CI, and isolate install and settings tests from the real home directory and unrelated tests.
- 📥 Review imported commands - Config imports show new shell commands in full and require confirmation with Cancel selected by default; control characters are displayed as escaped text.
- 🔒 Private settings stay private - Saves preserve restrictive settings-file permissions, Claude settings backups inherit the source permissions, and installation stops rather than overwriting unreadable Claude settings.
- 🌐 Proxy exclusions and deadlines - Usage and Claude Status requests honor
NO_PROXYandno_proxyand have total five-second deadlines; JJ commands also time out after five seconds. - ⏳ Accurate cache timer state - Interrupts and local slash commands such as
/costno longer leave Cache Timer reportingHOT. - ⚡ Faster Git and text rendering - Git widgets skip unnecessary calls outside repositories and keep separate caches per working directory; text-width calculations reuse Unicode measurements, and Git file/URL parsing avoids quadratic slowdowns.
- 📏 Reliable styled-text truncation - Width limits remain correct when ANSI styling or hyperlinks split an emoji or another display cluster.
- 🛡️ Command and file handling - Update versions are validated before installation, fonts download into private temporary folders, branch/host names stay literal CLI arguments, and Skills logs reject unsafe session IDs.
- 🔄 Reliable usage backoff - Successful usage requests preserve rate-limit backoff written by concurrent renders.
Across the updates since the September 3 release, 64 PRs have been incorporated, plus additional security fixes and test isolation.
- 🩹 Miscellaneous bug fixes - 29 dedicated bug-fix PRs since September 3 cover usage/account caching, transcript reading, Git/JJ and directory displays, Unicode truncation, Powerline colors and layout, keyboard controls, settings recovery, hooks, and installation/update flows.
- 🔒 Security fixes - Three additional fixes restrict repository-controlled Git commands, resolve Windows helper executables from PATH, and filter terminal control sequences while preserving colors and hyperlinks.
- 💰 Session Cost Rate - Track session cost per hour of active API time or total session time, with a one-minute minimum before showing a rate.
- 📅 Extra Usage Daily Budget - Spread the remaining monthly spending limit over the remaining UTC days, with an option to skip future weekend days.
- 🏷️ Editable labels - Press
eto customize text labels. - ⚡ Faster rendering - Piped status lines skip loading the interactive TUI, reducing startup work on every repaint.
- 🧰 Maintenance - Shared widget and editor implementations, broader regression coverage, more reliable tests, dependency updates, and CI actions pinned to commit SHAs.
- ⚡ Faster terminal width detection - Linux can probe the terminal directly without subprocesses, portable fallbacks skip shell wrappers, and configurable caching reuses failed width probes across renders while detected widths refresh on the next render.
- 🔧 Custom command caching and timeouts - Opt into output caching for up to 60 seconds from Configure Status Line, and enforce command timeouts even when descendants retain output pipes.
- 🔣 More customizable Git/JJ symbols - Press
gto edit insertion/deletion signs, Git clean/dirty markers, and the JJ Revision prefix, including empty glyphs for compact layouts. - 🙈 Hide reset-timer placeholders - Block Reset Timer and Weekly Reset Timer can hide loading and error output through
h; useffor 12/24-hour format andofor weekly hours-only display. - 👤 Reliable usage account selection - macOS usage lookup respects the active config profile's Keychain credentials, and access-token refreshes preserve cached usage when the refresh token is unchanged.
- 📊 Unused model quotas show zero - Weekly model usage widgets recognize an explicit 0% quota even before the API supplies a reset timestamp.
↔️ Full-width layouts by default - New configurations and settings without an explicit flex mode now use Full width always.- ⏱️ Bounded Git commands - Cached Git commands have a five-second timeout so a stalled Git invocation cannot block the status line indefinitely.
- 🩺 Claude service health - Added a
Claude Statuswidget with live severity, a cached 48-hour incident-history strip, stale-data fallback, and graceful?output when status data is unavailable. - 🙈 Unified conditional hiding - Numeric, Git, JJ, usage, cache, and other widgets now share an
hchecklist for supported hide conditions, with automatic migration of existing settings and optional merge-target hiding for decorative text or symbols. - 🔢 Configurable number formatting - Numeric widgets can use precise, compact, or whole-number styles per widget or globally by token, speed, percent, memory, and cost type, while advanced configs can set decimal precision explicitly.
- 📜 Faster, reliable large-session rendering - Transcript-backed token, duration, speed, compaction, effort, and session-name metrics now stream JSONL records through one shared scan instead of loading an entire transcript into a single string, while no-active-block results are briefly cached to avoid repeated full-history scans.
⚠️ Git conflict display controls - Git Conflicts can hide when the count is zero or show either⚠0or a customizable clean glyph when the tree is conflict-free.- 🩹 Self-healing usage locks - Usage widgets ignore impossible fetch-lock deadlines more than 24 hours ahead, allowing poisoned locks caused by clock jumps or old test artifacts to recover on the next render.
- 🧹 Bounded Git cache cleanup - Failed persistent Git-cache writes clean up their temporary file and reuse one stable fallback name, preventing Windows file locks from leaking thousands of orphaned temp files.
- 📊 Consistent timer bars - Block Timer, Block Reset Timer, and Weekly Reset Timer now round progress-bar fill to the nearest cell, matching the other progress widgets.
- 📦 Config import/export - Export the current TUI configuration to JSON, validate and preview imports, then replace all settings or merge only supplied fields while preserving local installation metadata and leaving the result unsaved for review.
v2.2.25 - v2.2.26 - Fable usage, migrated usage API support, compaction accuracy, and rendering reliability
- 🪄 Weekly Fable usage - Added a
Weekly Fable Usagewidget with percentage, progress-bar, remaining-mode, and time-cursor controls. - 📊 Reshaped usage API support - Session and all-model weekly usage can fall back to the newer
limits[]response, while Sonnet, Opus, and Fable weekly widgets read authoritativeweekly_scopedentries so migrated accounts do not show stale or frozen values. - 🧠 Correct post-compaction context - Context length and percentage widgets reset immediately from
compact_boundary.postTokensafter/compact, then switch to the first new turn instead of retaining the pre-compaction size. - 🧹 Reliable hidden-widget separators - Manual separators now look past widgets that render empty, preserve the intended visible boundary, and inherit colors from the actual preceding visible widget.
- ⚡ Non-blocking Git PR/CI refreshes - Git PR and CI widgets render from a versioned disk cache while stale data refreshes in the background, preventing slow
ghcalls from blocking the status line.
v2.2.22 - v2.2.24 - Powerline flex mode, cache/CI/sandbox visibility, layout controls, composable metrics, and safer config
- ⏳ Prompt cache timer - Added a
Cache Timerwidget with liveHOTstate, TTL countdown, configurable 5-minute/1-hour windows, and customizable state glyphs. - ✅ GitHub CI status - Added a
Git CI Statuswidget that summarizes failing, pending, and successful checks for the current branch's pull request. - 🔒 Sandbox status - Added a
Sandbox Statuswidget with glyph, text, and Nerd Font formats that follows Claude Code's layered sandbox setting on each refresh. ↔️ One-sided default padding - Default widget padding can now apply to both sides, the left only, or the right only in standard and Powerline layouts.- ⚡ Powerline flex mode - Flex separators now work in Powerline mode, letting Powerline status lines right-align content or absorb available width.
- 🌗 Per-widget dim styling - The color editor can dim an entire widget or only parenthesized text, with reset and clear-all actions covering dim state.
- 🧯 Safer settings recovery - Invalid
settings.jsonfiles are left untouched, defaults render in memory, and the status line shows an invalid-config warning. - 🧭 Selective Powerline alignment - Press
xin the line editor to let a widget and the rest of its line keep their natural widths while earlier Powerline columns stay auto-aligned. - 📏 Git widget width limits -
Git BranchandGit Root Dircan cap their visible width with ellipsis-safe truncation while preserving hyperlink targets. - 🔣 Current directory glyphs -
Current Working Dircan prepend an optional custom glyph, including in raw-value mode. - 📂 Clickable current directory -
Current Working Dircan link its displayed path to a file manager, VS Code, or Cursor while keeping the shortened label. - 🧠 Configurable context fallback -
CCSTATUSLINE_CONTEXT_SIZE_FALLBACKoverrides the default 200k last-resort context window when Claude Code and the model name do not report one. - 🧩 Composable compaction metrics -
Compaction Countercan render count, auto, manual, unknown, or reclaimed-token values independently for custom layouts. - 🏷️ CLI version flag -
ccstatusline --versionnow prints the installed package version and exits. - 🛡️ Guarded invalid-config saves - The TUI warns when it loaded defaults for an invalid settings file and requires confirmation before replacing that file.
- 🔄 Usage display and cache fixes - Used/remaining direction now works in every percentage mode, account switches invalidate cached usage, and fetch locks no longer cause repeated requests or stale timeout output.
- ⏱️ Calmer reset timer startup - Reset timers show labeled loading placeholders instead of transient rate-limit errors while Claude Code's embedded usage-window data is still arriving.
- 🔇 Quieter install detection - Best-effort npm and Bun probes no longer leak expected package-manager errors into the TUI.
- 🔣 Custom widget glyphs - Git and JJ symbol widgets can override or suppress their built-in glyphs from the TUI.
- 🔁 Compaction counter details -
Compaction Counternow counts explicitcompact_boundarymarkers and can optionally show trigger splits plus tokens reclaimed. - 💸 Extra usage improvements - Added
Extra Usage Usedand formats extra usage amounts with the billing currency reported by the usage API. - 📏 Custom command width context -
Custom Commandwidgets receiveterminal_widthin stdin JSON when ccstatusline can detect the terminal width. - 🧠 Prompt cache widgets - Added
Cache Hit Rate,Cache Read, andCache Writewidgets with turn/session scopes and hide-when-empty behavior. - 🔢 Token rounding fix - Token counts from
999950through999999now render as1.0Minstead of1000.0k.
- 🌈 Gradient colors - Added per-widget and whole-line foreground gradients with named presets, custom hex stops, TUI picker support, and Powerline-aware rendering. Press
gon the Edit Colors screen for widget gradients, or pressgfor Override FG Color in Global Overrides for a line-wide gradient. - 🎯 More accurate token counts -
Tokens InputandTokens Outputnow prefer cumulative transcript metrics before falling back to context-window totals. - 💸 Extra usage no-limit fix - Extra usage widgets no longer get stuck on
[Timeout]for accounts with overage enabled but no monthly limit configured. - 🔁 Compaction glitch filtering -
Compaction Counterignores transient below-1% context readings so incomplete status frames do not create false compaction counts. - 🔀 SSH alias Git PR/MR detection - Git PR/MR detection resolves SSH host aliases while preserving canonical GitHub and GitLab hosts for CLI selection and fallback repo links.
- 🧪 Usage test cache isolation - Usage-fetch test probes now isolate
HOME,USERPROFILE,CLAUDE_CONFIG_DIR, and proxy variables so local tests cannot touch the real ccstatusline cache. - 📦 Dependency refresh - Refreshed React/React DOM and Bun lockfile development-tooling resolutions for the release.
Older updates (v2.2.19 and earlier)
- 📌 Version pinning support - Added support for pinned global installs so Claude Code can keep running a specific ccstatusline version.
- 🔐 npm provenance attestations - Published packages now use trusted publishing provenance so users can verify where releases were built while avoiding long-lived npm publish tokens.
- 🔄 Moving from auto-update installs - If you currently use an auto-updating install, use the TUI uninstall option first, then reinstall to go through the version pinning flow. Your ccstatusline settings are preserved when uninstalling.
- 💸 Extra usage widgets - Added Extra Usage Utilization and Extra Usage Remaining widgets for monthly pay-as-you-go overage limits, with null rate-limit buckets handled as zero usage.
- 🔒 Git lock avoidance - Git helpers now pass
--no-optional-locksso background status checks avoid creatingindex.lockraces. - 🧱 Older Git compatibility - Git widgets avoid newer command forms so repository status works on older Git installations.
- ⚡ Persistent Git cache - Git command output is cached under
~/.cache/ccstatusline/git-cachewith configurable TTL and.git/HEAD/.git/indexmtime checks to reduce repeated subprocess work. - 🧭 Install flow polish - Pinned global install is now the default install option, with clearer wording for install and migration flows.
- 🪟 Hidden helper processes - Runtime child processes set
windowsHideso helper commands do not open extra windows on Windows. - 📏 Terminal width override -
CCSTATUSLINE_WIDTHcan provide an explicit terminal width when automatic probing is unavailable.
- 📊 Weekly Sonnet/Opus usage widgets - Added separate weekly usage widgets for Sonnet and Opus API buckets, matching Claude Code's
/usagemodel split. - 🎤 Voice Status widget - Added a widget that shows whether Claude Code voice input is enabled, with icon, text, word, and optional Nerd Font display modes.
- 📉 Timer short bars - Block Timer, Block Reset Timer, and Weekly Reset Timer now support compact short-bar progress displays.
- 🔕 Quieter hook output - Hook handling now suppresses no-op JSON output so non-status updates stay silent.
- 🦊 GitLab PR/MR support -
Git BranchandGit PR/MRnow support GitHub, GitLab, and compatible self-hosted remotes, usingghorglabas appropriate. - 🔄 Status line refresh interval - Installed configs can set Claude Code's
statusLine.refreshIntervalfrom the TUI when Claude Code >=2.1.97 supports it. - 🧭 Wrap-around TUI navigation - Menu/list navigation and move/reorder modes now wrap at the first and last items.
- 📋 Clone widget shortcut - Press
kin the item editor to duplicate the selected widget, with fresh Powerline background color for cloned Powerline items. - 📊 Short bar display modes - Context percentage, Context Bar, Session Usage, Weekly Usage, Block Timer, and reset timer widgets can use compact bar variants.
- ⏱️ Usage time cursor - Session Usage and Weekly Usage progress bars can show the elapsed time position within the current usage window.
- 🕒 Reset timer timestamps - Block and Weekly Reset Timer widgets can show exact reset timestamps with compact formatting, 12/24-hour display, IANA time zones, and locale selection.
- 🪟 Context Window widget - Added a
Context Windowwidget for total model window size, keepingContext Lengthfocused on current context usage. - 🔁 Compaction Counter widget - Added a
Compaction Counterwidget that tracks session context compactions, with icon/text/number formats, optional Nerd Font icon, and hide-when-zero behavior. - 🧮 Git file status widgets - Added
Git Staged Files,Git Unstaged Files,Git Untracked Files, andGit Clean Statusfor file counts and clean/dirty state. - 🏷️ Clear context percentage labels -
Context %andContext % (usable)now label rendered values as used or left when toggling used/remaining mode. - ⚡ More Powerline caps - The Powerline separator editor now supports more than three start/end caps.
- 🧠 Thinking Effort updates - Added
xhigh, showdefaultwhen no effort is set, mark unknown future effort levels with?, and track live status JSON plus/effortcommand changes. Claude Code reports Ultracode asxhighin status line data. - 🧮 More accurate token counts - Streaming duplicate JSONL entries are deduped so token widgets do not overcount live Claude Code output.
- 🏷️ Cleaner model display - The Model widget strips trailing context suffixes like
(1M context); useContext Windowwhen you want the total window size shown. - 🧹 Cleaner empty-widget separators - Manual separators now collapse around widgets that render empty, avoiding dangling separators when hide-when-empty widgets disappear.
- 🧱 More resilient Git helpers - Git widgets handle missing or unusual git command output more defensively.
- 🔀 New Git PR widget - Added a
Git PRwidget with clickable PR links plus optional status and title display for the current branch. - 🧰 Major Git widget expansion - Added
Git Status,Git Staged,Git Unstaged,Git Untracked,Git Ahead/Behind,Git Conflicts,Git SHA,Git Origin Owner,Git Origin Repo,Git Origin Owner/Repo,Git Upstream Owner,Git Upstream Repo,Git Upstream Owner/Repo,Git Is Fork,Git Worktree Mode,Git Worktree Name,Git Worktree Branch,Git Worktree Original Branch, andCustom Symbol. - 👤 Claude Account Email widget - Added a session widget that reads the signed-in Claude account email from
~/.claude.jsonwhile respectingCLAUDE_CONFIG_DIR. - 🧼 Global Minimalist Mode - Added a global toggle in
Global Overridesthat forces widgets into raw-value mode for a cleaner, label-free status line. - 🔎 Smarter widget picker search - The add/change widget picker now supports substring, initialism, and fuzzy matching, with ranked results and live match highlighting.
- 📏 Better terminal width detection - Flex separators and right-alignment now work more reliably when ccstatusline is launched through wrapper processes or nested PTYs.
- 🎨 Powerline theme continuity - Built-in Powerline themes can now continue colors cleanly across multiple status lines instead of restarting each line.