Claude Meter's Windows Quota Loop for Claude Code

Claude Meter looks simple: a Windows taskbar widget that shows how much Claude plan quota remains. The useful article is not that a percentage can sit above the taskbar. The useful article is how a local tool reads Claude Code OAuth credentials, asks Anthropic's usage endpoint for quota rows, polls slowly enough to avoid making the problem worse, and shows the result where a Windows developer will actually notice it.

That makes Claude Meter a good rescue candidate. The old article failed because it treated the repository like a generic productivity tip. The source supports a stronger magazine angle: when should a Claude Code user trust a small Windows tray app with OAuth-derived usage data, what should they verify before running the unsigned executable, and when is a log-based reporting tool or a browser page the better answer?

The Core Loop

The loop is explicit in CLAUDE.md and usage.py: read claudeAiOauth.accessToken from ~/.claude/.credentials.json, call GET https://api.anthropic.com/api/oauth/usage with Authorization: Bearer <token> and anthropic-beta: oauth-2025-04-20, parse known quota rows, then render them in a PySide6 taskbar widget. The parser recognizes five_hour, seven_day, seven_day_sonnet, seven_day_opus, seven_day_claude_design, and the internal seven_day_omelette codename for Claude Design.

That is useful because it tracks the same class of state that interrupts real Claude Code work: current session utilization, weekly model-specific limits, reset timing, daily routine runs, and overage when exposed. The key judgment is that this is a convenience layer over an OAuth usage endpoint, not a billing system and not a stable public monitoring contract. Treat it as local workstation telemetry.

Credential Discovery Is the First Gate

credentials.py is the first file to inspect. It prefers %USERPROFILE%\.claude\.credentials.json on Windows, then WSL ~/.claude/.credentials.json, then a manual key in settings, then ANTHROPIC_API_KEY. The important caveat is in usage.py: plain API keys cannot see the per-model OAuth usage endpoint. The tool needs Claude Code's OAuth credential path to do the interesting part.

For a Windows developer, the setup path is therefore concrete:

npm install -g @anthropic-ai/claude-code
claude

That login creates the credential file. Claude Meter can then run as a taskbar widget. Browser-only users and desktop-app-only users are a weaker fit today because the README says browser cookie support is roadmap work. This is exactly the kind of boundary a Codex or Claude Code practitioner should care about: the tool is useful only when its auth source matches the way the developer actually uses Claude.

Polling Policy Matters More Than the Widget

The best part of the implementation is not the UI. It is the restraint in poller.py. The comments name the endpoint as aggressively rate-limited and define a cadence: 7 minutes normally, 5 minutes during active periods, 20 minutes when quiet, and exponential backoff on 429 with a 60-minute cap. Manual refresh fires immediately, but subsequent ticks still respect backoff.

That makes the article worth publishing. A quota monitor that hammers the endpoint is worse than opening the usage page by hand. A monitor that keeps last-good data, shows token-expired states, and slows down under 429 is closer to workstation infrastructure. The changelog backs this up: 0.1.4 made expired OAuth tokens visible instead of silently keeping stale data, added a single-instance guard, and stopped wsl.exe from flashing a console window on every refresh.

The adoption rule is simple: if you fork or adapt this idea, copy the backoff discipline before you copy the taskbar chrome.

Where It Fits in an Agent Workflow

Claude Meter fits Windows users who run long Claude Code sessions and want usage pressure visible without leaving the editor. It is also useful for developers who switch among Sonnet, Opus, Claude Design, and routine runs and need per-row reset information rather than one blended number. The README's comparison table is helpful because it does not pretend to own the whole category: some alternatives are smaller binaries, some support multi-account use, and ccusage is better for cost reporting from local JSONL logs.

That distinction matters for vibe-coding operations. Live quota awareness and historical cost accounting are different jobs. Claude Meter watches the current plan state. ccusage reads local ~/.claude/projects/*.jsonl logs for spend reporting. Clawdmeter moves a related signal to an ESP32 display. A team should not pick one tool for all three needs.

Use Claude Meter when the question is, "Can I keep working in this Claude Code session without hitting the wall?" Use a reporting tool when the question is, "What did this project cost over the week?" Use nothing extra when the browser usage page is enough.

Packaging and Windows Risk

The build path is intentionally simple but not enterprise-polished. build-exe.cmd creates a venv, installs dependencies, installs the package editable, and runs PyInstaller:

git clone https://github.com/JackBhanded/claude-meter
cd claude-meter
build-exe.cmd
run.cmd

The README documents the first-launch SmartScreen warning because the binary is unsigned. That is not a minor footnote. It tells you the right deployment boundary: personal workstation, open-source inspection, maybe small trusted team. It is not a company-wide standard tool unless someone owns signing, release provenance, update policy, and endpoint-change response.

Settings and history are local too. settings.py stores preferences under %APPDATA%\ClaudeMeter\settings.json; history.py writes 10-minute buckets to %APPDATA%\ClaudeMeter\history.json and trims them to 14 days. That is a good default for a local widget, but if a team wants audit history, this is not enough. The history file is a sparkline cache, not a governed telemetry store.

Failure Modes to Review

The failure modes are practical. If Claude Code has not refreshed the OAuth token, the endpoint returns 401 and the UI should tell the user to run claude again. If Anthropic returns 429, the poller must slow down and honor Retry-After. If WSL credential probing is enabled, subprocess calls must not flash console windows. If the endpoint adds a new quota key, the parser should humanize and display it instead of hiding it.

The tests reinforce several of those boundaries. tests/test_usage.py checks known quota ordering, friendly labels, 0-100 versus 0-1 normalization, UTC reset times, plan capture, overage parsing, count quotas, and unknown keys. That is the difference between a screenshot project and a tool that can survive small response-shape changes.

Still, this remains an OAuth endpoint consumer. Before relying on it daily, run a one-day observation pass and confirm that its readings match claude.ai/settings/usage, that reset countdowns line up after a real reset, and that the widget does not keep stale data without visible warning.

Adoption Verdict

Claude Meter is worth rescuing because it gives Windows Claude Code users a concrete operational pattern: discover OAuth credentials locally, poll the usage endpoint conservatively, keep UI state visible, and make failures obvious. It is not useful because it says "real-time" in the title. It is useful because it names the credential file, the endpoint, the backoff policy, the local settings path, the history retention, and the packaging limits.

Adopt it as a personal quota gauge or as source material for a better internal watcher. Do not adopt it as a billing ledger, compliance feed, or team-wide quota system without hardening the release process and deciding who owns endpoint drift. For a vibe-coding magazine, the lesson is broader than the app: useful agent tooling often starts as a small local loop, but it becomes trustworthy only when credential scope, polling behavior, stale data, and packaging risk are written down.

Claude Meter deserves publication as a Windows Claude Code quota watcher, with the caveat that OAuth credential handling, endpoint drift, rate limits, and unsigned packaging must be reviewed before it becomes daily infrastructure.

Practical takeaway

To test Claude Meter responsibly, run claude once to create %USERPROFILE%\.claude\.credentials.json, launch the widget, compare it against claude.ai/settings/usage, watch one reset cycle, verify 429/401 states are visible, inspect %APPDATA%\ClaudeMeter\settings.json and history.json, and keep the unsigned .exe limited to machines where open-source inspection is acceptable.