_        _             _ _            
  ___ ___ ___| |_ __ _| |_ _   _ ___| (_)_ __   ___ 
 / __/ __/ __| __/ _` | __| | | / __| | | '_ \ / _ \
| (_| (__\__ \ || (_| | |_| |_| \__ \ | | | | |  __/
 \___\___|___/\__\__,_|\__|\__,_|___/_|_|_| |_|\___|
                                                     

📚 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 - Git and JJ symbol widgets can override or suppress their built-in glyphs from the TUI.
• 🔁 Compaction counter details - Compaction Counter now counts explicit compact_boundary markers and can optionally show trigger splits plus tokens reclaimed.
• 💸 Extra usage improvements - Added Extra Usage Used and formats extra usage amounts with the billing currency reported by the usage API.
• 📏 Custom command width context - Custom Command widgets receive terminal_width in stdin JSON when ccstatusline can detect the terminal width.
• 🧠 Prompt cache widgets - Added Cache Hit Rate, Cache Read, and Cache Write widgets with turn/session scopes and hide-when-empty behavior.
• 🔢 Token rounding fix - Token counts from 999950 through 999999 now render as 1.0M instead of 1000.0k.

v2.2.20 - Gradients, token accuracy, usage reliability, and Git PR/MR fixes

• 🌈 Gradient colors - Added per-widget and whole-line foreground gradients with named presets, custom hex stops, TUI picker support, and Powerline-aware rendering. Press g on the Edit Colors screen for widget gradients, or press g for Override FG Color in Global Overrides for a line-wide gradient.
• 🎯 More accurate token counts - Tokens Input and Tokens Output now 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 Counter ignores 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.

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.

✨ Features

• 📊 Real-time Metrics - Display model name, git branch, token usage, Sonnet/Opus/Fable weekly usage, extra usage limits, voice input state, session duration, compaction count, block timer, and more
• 🎨 Fully Customizable - Choose what to display and customize colors for each element
• ⚡ Powerline Support - Beautiful Powerline-style rendering with arrow separators, caps, and custom fonts
• 📐 Multi-line Support - Configure multiple independent status lines
• 🖥️ Interactive TUI - Built-in configuration interface using React/Ink
• 🔎 Fast Widget Picker - Add/change widgets by category with search and ranked matching
• ⚙️ Global Options - Apply consistent formatting across all widgets (padding, separators, bold, minimalist mode, and color overrides)
• 📦 Portable Configurations - Export settings to JSON and preview replace-or-merge imports for backups and sharing
• 🚀 Cross-platform - Works seamlessly with both Bun and Node.js
• 🔧 Flexible Configuration - Supports custom Claude Code config directory via CLAUDE_CONFIG_DIR environment variable
• 📏 Smart Width Detection - Automatically adapts to terminal width with flex separators
• ⚡ Zero Config - Sensible defaults that work out of the box

🌐 Localizations

The localizations in this section are third-party forks maintained outside this repository. They are not maintained, reviewed, or endorsed by this repository, so review their code and releases before using them.

• 🌏 中文版 (Chinese): ccstatusline-zh

🚀 Quick Start

No installation needed! Use directly with npx or bunx:

# Run the configuration TUI with npm
npx -y ccstatusline@latest

# Or with Bun (faster)
bunx -y ccstatusline@latest

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.

{
  "statusLine": {
    "type": "command",
    "command": "npx -y ccstatusline@latest",
    "padding": 0,
    "refreshInterval": 10
  }
}

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Support

If ccstatusline is useful to you, consider buying me a coffee:

📄 License

MIT © Matthew Breedlove

👤 Author

Matthew Breedlove

• GitHub: @sirmalloc

🔗 Related Projects

• ccstatusline-editor - A visual editor for building ccstatusline configurations — drag, drop, preview, ship.
• tweakcc - Customize Claude Code themes, thinking verbs, and more.
• ccusage - Track and display Claude Code usage metrics.
• ccsidekick - A Claude Code status-line with a reactive character plus cost, git, and usage widgets.
• codachi - A tamagotchi-style statusline pet that grows with your context window.
• AIWatch - Live status monitor for 30+ AI APIs and apps; pairs with a Custom Command widget to surface provider outages in your status line.
• ccsessions - CLI session manager for Claude Code; includes cc-session-num, a Custom Command widget that shows the current session's rank (#1, #2, …).
• crispy-recall - Searchable memory for your Claude Code and Codex sessions. Local, fast, no daemon.
• statuslin.es - Community gallery of Claude Code status lines with live, sandbox-rendered previews.
• claude-carbon - Live CO2 estimate for your Claude Code sessions, next to the cost. Ships a --segment mode built to embed as a Custom Command widget.
• claudenews - Developer news in your status line while the agent works: Hacker News, GitHub Trending, and per-language sources, with optional translation and short summaries. Ships a --segment mode built to embed as a Custom Command widget.

🙏 Acknowledgments

• Built for use with Claude Code CLI by Anthropic
• Powered by Ink for the terminal UI
• Made with ❤️ for the Claude Code community

Star History