claude-usage-monitor

Claude Usage Monitor

---

What You See

Startup Card

Every time you open a session, a full usage summary appears automatically:

✅ Opus (5-hour rolling): ████░░░░░░ 42% (resets in 2h 15m)
✅ All models (7-day rolling): ██████░░░░ 62% (resets in 3d)
✅ Sonnet (7-day rolling): ████░░░░░░ 42% (resets in 3d)

Plan: Max | Extra: $10.49 / $275.00

Status Line

A compact bar at the bottom of your terminal, always visible. Refreshes after each response and on a configurable timer (default 60 s) so you can see usage drain in real time even while idle:

Opus 4.7    Opus 5h █░░░░ 21%(2h)    All 7d █░░░░ 29%(4d)    Ctx ██░░░ 245k/1.0M    Think:ON
Sonnet 4.6  Sonnet 7d ██░░░ 33%(4d)  All 7d █░░░░ 29%(4d)    Ctx █░░░░ 45.2k/1.0M
Haiku 4.5   Haiku 7d █░░░░ 12%(4d)   All 7d █░░░░ 29%(4d)    Ctx █░░░░ 12.1k/200k

The order is always: model name → model-specific limit → All 7d → context window → thinking mode. Each model shows its own relevant limit first (Opus shows the 5-hour window, Sonnet/Haiku show their 7-day windows), then the shared all-models 7-day window.

Smart Alerts

When any limit exceeds 80%, you get a warning:

⚠️ Opus (5-hour rolling): ██████████ 95% (resets in 45m)
   ⚠️ WARNING: Approaching limit!
✅ All models (7-day rolling): ██████░░░░ 62% (resets in 3d)
✅ Sonnet (7-day rolling): ████░░░░░░ 42% (resets in 3d)

Plan: Max | Extra: $10.49 / $275.00

---

Features

Feature	Description
Startup Card	Full usage summary on session start via systemMessage
Status Line	Compact bar at the bottom of the terminal, always visible
Current Model	Status line shows which model is active (Opus 4.7, Sonnet 4.6, Haiku 4.5, …)
Live Updates	Refreshes after each Claude response and on a configurable interval (default 60 s) so usage stays accurate even while idle
Context Window	Live Ctx bar showing tokens used vs the model's context limit
Progress Bars	Unicode bars with color-coded thresholds (green/yellow/red)
Smart Alerts	Warning when approaching any limit (>80%)
Reset Countdown	Time until each limit resets
Thinking Mode	Shows if extended thinking is ON/OFF (detected from transcript)
Extra Usage	Monthly credit balance if enabled
Token Refresh	Auto-refreshes expired OAuth tokens
Silent Fallback	Never blocks session — fails silently on errors
Smart Caching	Only re-fetches API when cache is older than 2 minutes
Zero Config	Works out of the box with your existing Claude Code OAuth
/full-costs	Slash command for detailed usage card on demand

---

Installation

Requirements

Requirement	Details
Claude Code CLI	Latest version
Node.js	18+
Authentication	OAuth (Pro/Max/Team plans)

Install via Marketplace (Recommended)

Step 1: Add the marketplace

claude plugin marketplace add https://github.com/JohnPitter/claude-usage-monitor

Step 2: Install the plugin

claude plugin install claude-usage-monitor

Step 3: Open a new Claude Code session — the usage card appears automatically.

Install via Claude Code

claude /install-plugin https://github.com/JohnPitter/claude-usage-monitor

Status Line Setup

Automatic on first run (since v1.3.0). On the first session start after install, the plugin writes the correct statusLine block into your ~/.claude/settings.json — no manual edit needed. Restart Claude Code once and the bar appears at the bottom of your terminal.

The plugin only writes if statusLine is missing or already points to itself. If you have a different status line (ccstatusline, starship-claude, etc.), the plugin leaves your config alone.

To customize, edit ~/.claude/settings.json directly: