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

📚 Table of Contents

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

🆕 Recent Updates

v2.2.14 - Version pinning

• 📌 Version pinning support - Added support for pinned global installs so Claude Code can keep running a specific ccstatusline version.
• 🔄 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.

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 activity so displayed speeds better reflect actual concurrent work.

✨ Features

• 📊 Real-time Metrics - Display model name, git branch, token usage, per-model weekly usage, 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)
• 🚀 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

• tweakcc - Customize Claude Code themes, thinking verbs, and more.
• ccusage - Track and display Claude Code usage metrics.
• 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.

🙏 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