CLIUsageMonitorforClaudeCode

The Challenge

Claude Code users on Anthropic's Max plan have token usage limits but no built-in way to monitor consumption in real time. Developers working on intensive coding sessions had no visibility into how much of their allocation they had used, leading to unexpected rate limits at critical moments. The community needed a lightweight, open-source tool to track and visualize token usage directly from the terminal.

What We Did

An open-source CLI tool that monitors Claude Code token usage in real time, built for developers who live in the terminal.

• Real-time tracking — reads Claude Code's local usage data and displays current consumption against known limits
• Terminal dashboard — a clean, color-coded display showing tokens used, remaining allocation, and projected usage based on current session pace
• Usage history — tracks consumption over time so developers can understand their usage patterns across sessions and days
• Alert thresholds — configurable warnings when usage approaches defined percentages of the limit (e.g., 75%, 90%), so developers can adjust their workflow before hitting a wall
• Zero configuration — works out of the box by reading Claude Code's existing data files. No API keys, no setup wizard, no configuration files required for basic usage

Design principles guided every decision:

• Minimal dependencies — the tool should install fast and not drag in a tree of packages
• Non-intrusive — runs alongside Claude Code without interfering with its operation
• Accurate — reads directly from source data rather than estimating or approximating
• Open source — MIT licensed, accepting contributions, and transparent about how it works

The Outcome

The tool filled a gap in the Claude Code ecosystem. Developers can now monitor their usage proactively rather than discovering limits reactively. The project is open source on GitHub and available for the community to use, fork, and contribute to.

Tech Stack

• Node.js (CLI framework)
• Terminal UI rendering
• Local file system monitoring
• MIT open-source license