leeguooooo/claude-code-usage-bar

What it solves

Claude Code does not provide detailed, real-time visibility into rate limits, context window usage, or prompt-cache status. This project eliminates the need to switch windows or contexts to check how much quota remains and when it resets.

How it works

It integrates directly into Claude Code's statusLine in the terminal or provides a floating HUD for the macOS desktop app. It tracks official 5-hour and 7-day rate limits, monitors the current model and context window fill level, and calculates a countdown for prompt-cache freshness. It can run as a lightweight daemon to maintain low CPU usage (under 1%) while refreshing data every second.

Who it’s for

Developers and power users who use Claude Code or the Claude desktop app and want a glanceable, real-time dashboard of their API usage and session status.

Highlights

• Official Rate Tracking: Displays 5h/7d usage bars with reset countdowns and end-of-window projections.
• Cache Monitoring: Includes a countdown timer to show how long the prompt cache remains "warm."
• Dual Interface: Supports both a terminal status line and a macOS floating HUD.
• Customizable Visuals: Offers 3 styles and 9 themes to change the look of the status bar.
• Low Overhead: Optional daemon mode ensures minimal CPU impact.
• Zero-Dependency Install: Available as a prebuilt binary or a Python package.