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.14 - v2.2.19 - Version pinning, npm provenance, usage overage widgets, and Git lock avoidance

• 📌 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-locks so background status checks avoid creating index.lock races.
• 🧱 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-cache with configurable TTL and .git/HEAD/.git/index mtime 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 windowsHide so helper commands do not open extra windows on Windows.
• 📏 Terminal width override - CCSTATUSLINE_WIDTH can provide an explicit terminal width when automatic probing is unavailable.

v2.2.13 - Weekly model usage, voice status, hooks, and docs

• 📊 Weekly Sonnet/Opus usage widgets - Added separate weekly usage widgets for Sonnet and Opus API buckets, matching Claude Code's /usage model 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.

v2.2.9 - v2.2.12 - GitLab support, reset timers, context, compaction, and git widgets

• 🦊 GitLab PR/MR support - Git Branch and Git PR/MR now support GitHub, GitLab, and compatible self-hosted remotes, using gh or glab as appropriate.
• 🔄 Status line refresh interval - Installed configs can set Claude Code's statusLine.refreshInterval from 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 k in 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 Window widget for total model window size, keeping Context Length focused on current context usage.
• 🔁 Compaction Counter widget - Added a Compaction Counter widget 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, and Git Clean Status for file counts and clean/dirty state.
• 🏷️ Clear context percentage labels - Context % and Context % (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, show default when no effort is set, mark unknown future effort levels with ?, and track live status JSON plus /effort command changes.
• 🧮 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); use Context Window when 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.

v2.2.8 - Git widgets, smarter picker search, and minimalist mode

• 🔀 New Git PR widget - Added a Git PR widget 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, and Custom Symbol.
• 👤 Claude Account Email widget - Added a session widget that reads the signed-in Claude account email from ~/.claude.json while respecting CLAUDE_CONFIG_DIR.
• 🧼 Global Minimalist Mode - Added a global toggle in Global Overrides that 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.

v2.2.0 - v2.2.6 - Speed, widgets, links, and reliability updates

• 🚀 New Token Speed widgets - Added three widgets: Input Speed, Output Speed, and Total Speed.
  • Each speed widget supports a configurable window of 0-120 seconds in the widget editor (w key).
  • 0 disables window mode and uses a full-session average speed.
  • 1-120 calculates recent speed over the selected rolling window.
• 🧩 New Skills widget controls (v2.2.1) - Added configurable Skills modes (last/count/list), optional hide-when-empty behavior, and list-size limiting with most-recent-first ordering.
• 🌐 Usage API proxy support (v2.2.2) - Usage widgets honor the uppercase HTTPS_PROXY environment variable for their direct API call to Anthropic.
• 🧠 New Thinking Effort widget (v2.2.4) - Added a widget that shows the current Claude Code thinking effort level.
• 🍎 Better macOS usage lookup reliability (v2.2.5) - Improved reliability when loading usage API tokens on macOS.
• ⌨️ New Vim Mode widget (v2.2.5) - Added a widget that shows the current vim mode, with ASCII and optional Nerd Font icon display.
• 🔗 Git widget link modes (v2.2.6) - Git Branch can render clickable GitHub branch links, and Git Root Dir can render clickable IDE links for VS Code and Cursor.
• 🤝 Better subagent-aware speed reporting - Token speed calculations continue to include referenced subagent act