Claude Code weekly quota meter
You can type /usage inside Claude Code. It works. It also stops the loop, costs a turn, and prints a stale snapshot the second it lands. A weekly quota meter is the same number on a 60-second tick, outside Claude Code, where the loop never sees it.
Direct answer (verified 2026-05-11)
A Claude Code weekly quota meter is a small ambient display (menu bar, status line, or CLI) that polls claude.ai/api/organizations/{uuid}/usage every 60 seconds with your existing browser cookie and renders the six weekly utilization buckets (seven_day, seven_day_sonnet, seven_day_opus, seven_day_oauth_apps, seven_day_omelette, seven_day_cowork) plus extra-usage dollars, outside of Claude Code itself. Open-source reference implementation: github.com/m13v/claude-meter (MIT, macOS menu bar plus browser extension, no telemetry).
/usage is a snapshot. A meter is a tick.
Both read the same endpoint. The difference is who runs the call and when. With /usage you pay for the read inside the conversation; with a meter, the read happens in a separate process at a known cadence and never touches your loop.
Reading your weekly quota during an agentic loop
Type /usage inside the conversation. Claude Code pauses, makes its own round-trip to the same endpoint, and prints a snapshot into the chat buffer. Your loop is interrupted. The snapshot ages the moment it lands.
- Costs a turn (or interrupts an agent step) every time you ask.
- Only the 5-hour window is highlighted; weekly buckets are summary lines.
- If the wall fires between two /usage calls, you find out via 429.
The endpoint both /usage and the meter read
This is the JSON shape your account returns when you reload claude.ai/settings/usage. Claude Code's /usage slash command hits the same path and rolls these fields into an inline message. A meter parses them directly into a struct and renders each bucket separately so you can spot which one is about to fire.
On a Claude Code-heavy week, the bucket to watch is seven_day_oauth_apps. It walls Claude Code while web chat keeps working, because OAuth-token requests count against this bucket on top of seven_day.
How the meter polls, in 6 lines
The 60-second cadence is one constant in the extension. Audit it yourself: open extension/background.js line 3. There is no remote config server. There is no “telemetry mode” toggle. The cadence is what the file says.
The six weekly buckets the meter renders
The Rust struct below is the deserializer the meter uses on every poll. Every non-null field becomes a row in the popover. Claude Code's /usage slash command summarizes the same fields into a paragraph; the meter keeps them separate.
Install in one brew command
The cask installs the menu-bar app and a claude-meter CLI binary. The extension lifts your existing claude.ai cookie out of whatever Chromium browser you use, so the meter lights up the first time you reload claude.ai with the extension installed.
What the meter promises (audit any of it)
Properties the source code enforces
- Polls every 60 seconds via chrome.alarms (POLL_MINUTES = 1, extension/background.js line 3).
- Reads the same JSON claude.ai/settings/usage reads on reload. Same cookie, same Referer, same /api/organizations/{uuid}/usage endpoint.
- Parses six weekly buckets into the UsageResponse Rust struct (src/models.rs lines 21-26). Each is Option<Window>, with utilization (f64) and resets_at (UTC).
- Bridge between extension and menu bar runs on 127.0.0.1:63762. Nothing on your network can see it.
- Zero telemetry. One HTTPS request per minute, only to claude.ai itself. MIT licensed.
Frequently asked questions
What is a Claude Code weekly quota meter?
A small ambient display (menu bar, status line, or CLI tile) that polls Anthropic's internal /api/organizations/{uuid}/usage endpoint every 60 seconds using your existing claude.ai browser cookie and renders the live utilization for the six weekly buckets the server returns. The meter sits outside Claude Code itself, so an agentic loop can run uninterrupted while you watch the numbers accrue. The open-source one is ClaudeMeter (github.com/m13v/claude-meter), MIT licensed, no telemetry.
Claude Code already has /usage. Why do I need a separate meter?
Because /usage is a slash command, not a meter. Three problems: (1) typing /usage costs a turn or interrupts an active agent step; if the model is mid-tool-call you cannot run it without breaking the chain. (2) the print is point-in-time and stale the moment it lands. (3) the inline output emphasizes the 5-hour window; the six weekly buckets are summarized, not laid out side-by-side. A meter is continuous, lives outside Claude Code's context window, and shows every bucket at once.
Which weekly bucket actually walls a Claude Code loop?
seven_day_oauth_apps, almost always. Claude Code authenticates via an OAuth token, so its requests count against the OAuth-apps weekly bucket on top of the all-up seven_day aggregate. Your account can sit at seven_day = 62% and seven_day_oauth_apps = 100% at the same time. The web UI on claude.ai/settings/usage shows seven_day's aggregate bar; the meter shows every non-null bucket separately so you see the OAuth one cross 80% before the CLI 429s you.
What does the meter actually display?
Three numbers in the menu bar: 5h X%, 7d Y%, $Z.ZZ metered (extra-usage spend). Click the badge and a popover lists every non-null bucket from the UsageResponse struct: seven_day, seven_day_sonnet, seven_day_opus, seven_day_oauth_apps, seven_day_omelette, seven_day_cowork, plus extra_usage. Each row shows utilization and resets_at. A CLI tool prints the same JSON for status-line scripts.
How does the meter pull the number without me pasting a cookie?
There are two routes. Route A is the browser extension: it runs inside Chrome/Arc/Brave/Edge under your claude.ai origin, so it inherits your session cookie automatically. The extension fetches /api/organizations/{uuid}/usage and POSTs the snapshot to the menu-bar app over 127.0.0.1:63762. Route B is keychain-only: the menu-bar app shells out to security find-generic-password to get Chrome Safe Storage's AES key, decrypts the cookie store directly, and makes the call itself. Route A avoids the keychain prompt; Route B avoids loading an extension.
Is this just polling? Will I get rate-limited or flagged?
One GET per minute per org membership, with the exact three headers a browser tab reload sends (Cookie, Referer: https://claude.ai/settings/usage, Accept: */*). It is byte-identical to you alt-tabbing to claude.ai/settings/usage and hitting refresh once a minute. Anthropic's /usage endpoint is unauthenticated rate-limit-wise the way the /api endpoints are, and the call does not consume any tokens. No reports of accounts being flagged for this pattern as of May 2026; the source for src/api.rs is 142 lines, audit it before trusting me.
Can ccusage do this instead?
No, and that is not a knock on ccusage. ccusage sums input and output tokens from ~/.claude/projects/*.jsonl on your disk. The numerator is real and ccusage prints it well. The denominator (Anthropic's enforced weekly cap) is server-side and not on disk; it is a private dimensionless utilization the server computes against an undocumented per-plan ceiling. So ccusage can say '5% used' the same week the server says seven_day_oauth_apps = 91% and walls the next Claude Code request. The two are honest about different things. Run both.
How do I read the meter from my tmux/Starship/Fig status line?
The brew cask installs a `claude-meter` CLI next to the app. Run `/Applications/ClaudeMeter.app/Contents/MacOS/claude-meter --json` and pipe the output to jq. You get the same UsageResponse JSON the menu bar parses, machine-readable. A common pattern: pin a tmux right-status segment that prints `7d_oauth Y%` and turns red above 80%. The CLI is one-shot, so call it on whatever cadence your status line refreshes; the menu bar's snapshot is cached in localhost and the CLI reads from the same cache.
Where exactly is the 60-second cadence set, in case I want to audit it?
extension/background.js, line 3: const POLL_MINUTES = 1. Two chrome.alarms.create('refresh', { periodInMinutes: POLL_MINUTES }) calls register the alarm. The menu-bar app on the other side speeds polling up to ~90 seconds when any bucket crosses 80% utilization (src/bin/menubar.rs around line 29-34, search for HIGH_UTIL_FAST_POLL). You can fork the extension and change POLL_MINUTES to 0.5 if you want 30-second cadence, but Anthropic's endpoint does not refresh that fast on its side, so the extra polling will just see the same number twice.
What does the meter cost?
Free, MIT licensed, no account, no signup. github.com/m13v/claude-meter. The only outbound network traffic is the one HTTPS GET per minute per org to claude.ai, plus the two sibling reads (subscription_details and overage_spend_limit) that fire less often. No analytics, no telemetry, no auth server, no cloud account. The 127.0.0.1:63762 bridge between extension and menu bar is loopback-only.
Setting up a weekly meter for a Claude Code team?
20-minute call: best route for shared accounts, status-line integration, and pre-emptive alerts before the OAuth bucket walls a multi-agent loop.
Related guides
The Claude weekly quota server-truth meter
Field-by-field walkthrough of every window in the /api/organizations/{uuid}/usage response, with the exact Rust deserialization on lines 18-28 of src/models.rs.
The Claude Code weekly quota wall: what the CLI hides
When the wall fires, Claude Code prints a generic 'rate_limit_error: ... limit reached' string. The OAuth token in your Keychain plus the right endpoint will name the bucket.
Claude Code weekly limit during long workflows
Long Claude Code refactors wall on seven_day_oauth_apps, not seven_day. The pre-flight check, the live signal to watch, the abort threshold.
Comments (••)
Leave a comment to see what others are saying.Public and anonymous. No signup.