claude-usage

Read your Claude plan usage from the command line, or as an MCP tool.

These are the numbers behind claude.ai's "Current session" and "Weekly" meters. Anthropic publishes no API for them, so this reads them through a browser you are logged into. See How it works.

$ ./usage
{
  "status": "ok",
  "session_pct": 14.0,
  "session_resets_at": "2026-08-07T18:00:00Z",
  "weekly_pct": 38.0,
  "weekly_resets_at": "2026-08-08T07:00:00Z",
  "blocking": [],
  "credits_enabled": false,
  "credits_spent": 0.0,
  "credits_limit": null,
  "source": "browser"
}

Features

• CLI printing JSON, exit 0 on success and 1 on failure

• MCP tool, so Claude can check its own remaining usage

• Works on Windows, macOS and Linux

• Docker optional — needed only on machines without a screen

• No API key, no browser download; several accounts from one browser

Related MCP server: claudeusage-mcp

Requirements

• Python 3.9+

• A browser (Chrome, Chromium or Edge), or Docker on a headless machine

• A machine that stays on, since the browser has to keep running

• One manual login, repeated roughly monthly when the session expires

Install

git clone https://github.com/AlbeeDev/claude-usage.git
cd claude-usage

Then follow A if the machine has a screen, or B if it does not.

A. Machine with a screen

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
./usage

Windows:

py -3 -m venv .venv
.venv\Scripts\pip install -r requirements.txt
usage

The first run finds a browser and starts one:

$ ./usage
No browser is running. Starting one...
Started /usr/bin/google-chrome

Log into claude.ai in the window that opened, leave it running,
then run this again.

Log in, leave the window open, run ./usage again.

B. Headless machine (Docker)

The container provides the screen you log in through.

docker compose up -d

Then forward the port from your own machine and open http://localhost:3000:

ssh -L 3000:localhost:3000 you@your-server

Log into claude.ai there, then close that tab — leave the blank one, which keeps the browser alive. The session is saved to disk, so the tab is only needed for typing your password, and a page left open accumulates memory for as long as the browser runs. Back on the server:

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
./usage

The Chromium image is about 4.6 GB. Check you have the disk.

Anything that can reach port 9222 controls a browser signed into your Claude account — it can read your conversations, act as you on any site that browser is logged into, and take its cookies. There is no authentication on that port; that is how the debug protocol works. All ports bind to 127.0.0.1 for this reason. Do not republish them on 0.0.0.0, and treat any machine where you do not trust every local user as unsuitable.

Put it on PATH

To call it from anywhere, or from another program:

./usage --add-to-path

$ cd /anywhere && claude-usage
{"status": "ok", "session_pct": 15.0, ...}

It links into a directory already on your PATH — /usr/local/bin as root, ~/.local/bin otherwise — and prints where it went. On Windows it writes a small .bat shim instead, since symlinks there need admin rights.

It is a link, not a copy, so updating the repo updates the command, and the venv and browser profile are still found. To remove it, delete the file it names. It will not overwrite a file it did not create.

Usage

./usage                  # print usage as JSON
./usage --login          # open claude.ai in the running browser, to sign in again
./usage --register-mcp   # register the MCP server with Claude Code
./usage --add-to-path    # install as claude-usage, runnable from anywhere

./usage --capture-account <id>   # remember the account now signed in, under this id
./usage --accounts               # list captured accounts and when they expire
./usage --account <id>           # read that account instead of whoever is signed in
./usage --plans                  # every configured account and its plan, in one pass

On Windows, usage instead of ./usage.

MCP

./usage --register-mcp

Registers the server for all projects and prints what it wrote. Start a new Claude session to pick it up. Claude then gets a claude_usage tool returning status, session_pct and resets_at.

To register by hand, point command at the Python inside .venv — an MCP client runs a command, it does not activate anything:

{
  "mcpServers": {
    "claude-usage": {
      "type": "stdio",
      "command": "/path/to/claude-usage/.venv/bin/python",
      "args": ["/path/to/claude-usage/mcp_server.py"]
    }
  }
}

On Windows the interpreter is .venv\Scripts\python.exe.

The tool reads the browser but never starts one. If none is running it returns browser_unavailable; start it with ./usage.

More than one account

If you have several Claude accounts, one browser can still serve them all. Log into each one in turn and capture it:

./usage --capture-account pro     # while signed in as that account
# sign in as the other account in the browser UI, then:
./usage --capture-account team

Then read either, without logging in again:

./usage --account team
BURROW_USAGE_ACCOUNT=team ./usage   # same thing, for callers that set env vars

With no --account, nothing changes: you get whoever the browser is signed in as, exactly as before.

How it works: each account's claude.ai session cookies are stored in accounts.json (mode 0600) and installed before the reading. Cloudflare's cookies are left alone, so switching does not trigger a fresh challenge. Only one browser is needed no matter how many accounts you have.

An account can own more than one chat-capable organisation — a Team one and a free one, say. The organisation is pinned when the account is captured, so readings keep using the same one rather than whichever the API lists first.

Every reading checks that the organisation it read matches the account asked for, and fails with request_failed if not. A session that silently failed to install would otherwise return the previous account's numbers under the requested name, which is worse than an error.

Listing the accounts and their plans

./usage --plans answers "which accounts are set up, and what are they on" in a single pass:

{
  "status": "ok",
  "accounts": [
    { "account": "pro",  "status": "ok", "plan": "claude_max 5x",
      "org_uuid": "...", "org_name": "..." },
    { "account": "team", "status": "unauthenticated",
      "detail": "HTTP 403; log in again and re-capture team" }
  ]
}

One browser connection for all of them rather than one process each, so it is quicker than calling --account per account, and the result is cached for 60 seconds. Each account carries its own status: one expired session does not stop the others being reported, and the call still exits 0 as long as the browser could be reached.

Every reading reports session_expires_in_days, so a session can be renewed while that is still a two-minute login rather than an outage. Surface it below a week or so.

A stored session is re-saved after every successful reading, so it rolls forward with the real one instead of ageing out. Without that an account died a fixed number of days after capture no matter how often it was read: the stored cookie keeps the expiry it had when captured, while the live one is extended by the site on use, and installing an expired cookie is silently a no-op.

accounts.json holds live sessions. It is gitignored and readable only by you, but it is a credential file — the honest cost of not running one browser per account. Sessions expire roughly monthly; ./usage --accounts shows when.

Output

blocking can name a model that is exhausted while both percentages still look healthy.

The percentages are relative to the account's current limits, so a plan change is invisible in them — an upgrade makes the same work report a smaller number. plan is what makes that visible. It is Anthropic's own analytics_subscription_plan, undocumented and passed through untouched, so treat it as an opaque label that may be null.

Failure statuses

All exit 1, with the reason in status and detail in detail.

A response the digest does not recognise is reported as request_failed, never as ok with null percentages — a null renders as 0%, which reads as plenty of headroom and is the opposite of the truth. Treat every reading as best-effort and show "usage unavailable" rather than zero.

Configuration

USAGE_CDP_URL=http://other-host:9222 ./usage

Behaviour

• Results are cached for 60 seconds; polling is cheap.

• Concurrent callers are serialised with a file lock on macOS and Linux. Windows has no such lock, so the cache is the only guard there.

• A claude.ai tab is opened per reading and closed again, so the browser keeps no page alive between runs and its memory stays flat. If you already have claude.ai open, that tab is used instead and left exactly as it was — nothing of yours is opened, navigated or closed.

• On Windows the browser starts minimised once a profile exists. The first run stays visible, because that is the run you log in on.

• The browser uses its own profile directory, not your everyday one. A browser with debugging enabled can be driven by anything else on the machine.

• Closing the browser does not lose the login — it is on disk. ./usage starts it again.

• Tabs this tool opens are stamped, so a run that is killed before it can clean up is tidied by the next one. Without that, the tab it left behind is indistinguishable from one you opened: it gets borrowed, borrowed tabs are never closed, and every later reading reuses the same page forever.

• The idle tab that keeps the browser alive is replaced once its heap passes USAGE_IDLE_TAB_MAX_MB. A replacement opens before the old one closes, so the tab count never reaches zero and the browser never restarts — but the old renderer dies and its memory is returned. Without this the browser creeps upward forever: every reading commits a few hundred KB of V8 heap in that process which is never given back, and no amount of garbage collection helps because none of it is garbage.

• A browser left running for a long time can keep answering the debugger's HTTP side while its debug protocol stops replying. The reading then fails with browser_unavailable saying exactly that, and restarting the browser fixes it — nothing else does, so it will not try to start a second one.

How it works

Anthropic publishes no API for plan usage. The only source is the endpoint claude.ai's own settings page calls, which needs your session — and Cloudflare rejects any client that is not a real browser.

Cookies alone are not enough, which is worth knowing before trying the obvious shortcut:

• An HTTP client with valid cookies gets 403 and cf-mitigated: challenge.

• A freshly minted __cf_bm does not change that.

• Neither does replaying a complete browser header set.

• Chrome's new headless mode is challenged too, while the same browser visible is not.

What is fingerprinted is the client itself. So a browser you are logged into stays running, and usage.py connects to it and runs the fetch from inside a claude.ai tab — the same request the settings page makes. No cookie is copied out and no browser is launched behind your back.

This reads your own account through your own session. No API key, no token, nothing sanctioned, and therefore best-effort. Do not build anything critical on it.

Tests

./test_usage.py    # or: pytest

Covers the digest and the debugger address. No browser or network needed.

License

MIT — see LICENSE.