Claude Code Usage Monitor

by MaciejCLI toolWrite code

Shows your Claude Code usage live in the terminal and warns you before you hit a limit

The problem it solves

You are halfway through a long task in Claude Code when it tells you that you have hit your usage limit until later today.

For Claude Code subscribersHeavy Claude Code users

Before: You guess how much of your session is left and find out only when Claude Code stops.
After: A terminal window shows tokens, messages and cost used so far, when the limit resets and when you are likely to run out.

Stars: ★ 8.8k
License: MIT
Cost: Free
Platforms: Mac · Win · Linux
Level: Intermediate

Screenshots

From the project's own repository.

The monitor in a terminal, with bars for cost, tokens and messages, time to reset and a forecast of when tokens run out — Image: Maciej (MIT). Original file

Overview

Claude Code Usage Monitor is a terminal tool that reads the usage records Claude Code keeps on your computer. Run one command and it shows live bars for tokens, messages and cost in the current 5-hour session, the time until the limit resets and a forecast of when you will run out. It also has daily and monthly tables and can save its numbers to a file. It suits Claude Code users on a subscription who keep running into usage limits.

It predicts when your session limit will run out from your own recent usage, so you can pace a long task instead of being cut off halfway.

Try these first

Start with the first one: it is a small task you can check easily.

Run claude-monitor with no options while you work in Claude Code, and compare its time to reset with what Claude Code shows.First try · read-only
Run claude-monitor --plan pro to use the Pro plan limits instead of the automatic ones.
Run claude-monitor --view daily to see a table of token usage per day.
Run claude-monitor --timezone Europe/London so reset times show in your own time zone.

Example prompts written by Agent Flows Hub.

Features

From the creator's documentation.

Feature	What it does	Runs
Live session bars	Tokens, messages and cost used in the current 5-hour session, refreshed as you work	Your computer
Forecast	When your tokens are likely to run out and when the limit resets	Your computer
Plan presets	Pro, Max5 and Max20 presets, or limits worked out from your own recent sessions	Your computer
Daily and monthly views	Tables of token usage per day or per month	Your computer
Export	Writes a snapshot as JSON or a state file for status bars, and CSV reports from an opt-in local history	Writes files

Good to know

Keep an eye on a Claude Code subscription session while you work. The monitor reads local usage records, shows how much of the current 5-hour window is used and forecasts when the limit will be reached.

Limits

Numbers are read from the Claude Code logs on this computer, and the README labels the ones that do not come from Claude Code's official limit data as local estimates.
The default custom plan works out its limits from your own last eight days of sessions; the Pro, Max5 and Max20 presets use fixed figures that the README calls local estimates.

Notes by Agent Flows Hub (original project name: Claude-Code-Usage-Monitor (claude-monitor)), written from the creator's documentation, not from running it ourselves. Claude Code Usage Monitor: README and installation

Stuck setting it up?

Tell us what happened. We take a look first; if it needs paid work, you get an estimate before anything starts.

Get help

How to start

Install itPaste the install request into an AI agent you already use, or run the official command yourself or follow the official guide.macOS, Windows, Linuxuv tool install claude-monitor
macOS, Windows, Linuxpipx install claude-monitor
macOS, Windows, Linuxpip install claude-monitor
Set it upFollow the first-run steps in the official guide.
Give it a first taskStart the monitor with its default settings during a Claude Code session and compare the time-to-reset it shows with what Claude Code reports.

Steps follow the creator's instructions. The request tells your agent to read them first and wait for your OK.

Before you start

A computer with macOS, Windows or Linux.
Claude Code, already used on the same computer
The uv installer, or Python 3.9 or newer with pip
Free. Nothing to pay.

Details

Made by: Maciej
License: MIT Terms
Platforms: macOS, Windows, Linux
Runs on: Your computer

View source Official docs Report a problem

For AI agents

This page as a Markdown install brief:

/en/library/claude-code-usage-monitor/install.md

Other cli tools

Claude Token Optimizer Shrinks the notes Claude Code rereads at every session start, so each uses fewer tokens
CodeBurn Shows what your AI coding tools cost, split by project, model and task
Dev Browser Lets your coding agent drive a real Chrome browser to open pages, click and check results
Fabric Runs ready-made AI prompts on any text, such as summarising an article into key points
Horizon Turns the news sources you follow into a ranked daily briefing in English or Chinese
LLM Lets you ask many AI models questions from the terminal and keeps a log of every answer

See all 18 cli tools

GitHub