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

• Recent Updates
• Features
• Localizations
• Quick Start
• Windows Support
• Usage
• Development
• Contributing
• License
• Related Projects

🆕 Recent Updates

v2.2.29 - v2.2.30 - Faster rendering, command caching, and reliable usage

• ⚡ 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 g to 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; use f for 12/24-hour format and o for 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.

v2.2.28 - v2.2.29 - Service health, flexible formatting, and resilient rendering

• 🩺 Claude service health - Added a Claude Status widget 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 h checklist 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 ⚠0 or 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.

v2.2.27 - Portable configuration import and export

• 📦 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 Usage widget 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 authoritative weekly_scoped entries so migrated accounts do not show stale or frozen values.
• 🧠 Correct post-compaction context - Context length and percentage widgets reset immediately from compact_boundary.postTokens after /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 gh calls 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 Timer widget with live HOT state, TTL countdown, configurable 5-minute/1-hour windows, and customizable state glyphs.
• ✅ GitHub CI status - Added a Git CI Status widget that summarizes failing, pending, and successful checks for the current branch's pull request.
• 🔒 Sandbox status - Added a Sandbox Status widget 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.json files are left untouched, defaults render in memory, and the status line shows an invalid-config warning.
• 🧭 Selective Powerline alignment - Press x in 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 Branch and Git Root Dir can cap their visible width with ellipsis-safe truncation while preserving hyperlink targets.
• 🔣 Current directory glyphs - Current Working Dir can prepend an optional custom glyph, including in raw-value mode.
• 🧠 Configurable context fallback - CCSTATUSLINE_CONTEXT_SIZE_FALLBACK overrides the default 200k last-resort context window when Claude Code and the model name do not report one.
• 🧩 Composable compaction metrics - Compaction Counter can render count, auto, manual, unknown, or reclaimed-token values independently for custom layouts.
• 🏷️ CLI version flag - ccstatusline --version now 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.

v2.2.21 - Cache widgets, compaction details, extra usage currency, and package fixes

• 🔣 Custom widget glyphs -