claude-usage-monitor

claude-usage-monitor

  Claude Code statusline plugin that shows your quota usage, context, tokens, and reset countdowns directly in the terminal.

  No API keys. No telemetry. No dependencies. Runs locally.

  Real-time usage tracking - green to yellow to red as your session progresses.

Quickstart

Windows PowerShell

macOS / Linux

What you get

After install, restart Claude Code. Your statusline now shows:

- 5h / 7d quota - see how much is left before you hit limits
- Context % - see when you're running low before Claude tells you
- Token counts - input and output for the current session
- Reset countdown - know when your quota replenishes

Uses your existing Claude Code OAuth session. No extra API key or Python packages needed. Windows launches Python directly - no Git Bash requirement.

Prefer to audit first

On Windows, py -3 install.py works too.

The installer:

- copies launcher files into ~/.claude/plugins/claude-usage-monitor
- updates ~/.claude/settings.json (backs up to settings.json.bak first)
- runs a launcher smoke check and prints the verify command

Verify manually

If you want to verify the launcher yourself before restarting Claude Code:

- Windows: type nul | "C:\Users\you\.claude\plugins\claude-usage-monitor\statusline.cmd"
- macOS / Linux: printf '' | bash ~/.claude/plugins/claude-usage-monitor/statusline.sh

What it shows

All three bars show remaining % by default - they start full (green) and drain toward empty (red) as you use quota, like a fuel gauge. Prefer the fill-up style Claude Code uses? Set CQB_REMAINING=0.

Color coding

Trust and security

At runtime, the tool:

- reads Claude Code session JSON from stdin
- reads ~/.claude/.credentials.json for claudeAiOauth.accessToken (unless CLAUDE_CODE_OAUTH_TOKEN is set)
- runs git rev-parse…