Anthropic’s opaque usage limits just got a lot more visible for macOS users. A new open-source project, Claude Usage Widget, places a persistent menu bar item and desktop widget that tracks the 5-hour session cap, weekly limits, and per-model quotas. This tool effectively mirrors the data found in Claude Code’s /usage command, but does so without requiring developers to constantly switch contexts or open terminal windows. For those of us who treat API rate limits as a critical resource to manage, this level of visibility is a necessary quality-of-life improvement.

Exposing the Undocumented API

The widget operates by hitting GET https://api.anthropic.com/api/oauth/usage, the same endpoint Claude Code uses internally. Crucially, this endpoint remains undocumented by Anthropic, meaning its structure could change without warning. The parser is built defensively, preferring a structured limits array while falling back to older flat keys like five_hour or seven_day_*. It also ignores unrecognized fields, which provides a slight buffer against breaking changes. Authentication is handled by reading the OAuth token directly from the macOS Keychain via /usr/bin/security, specifically looking for the 'Claude Code-credentials' item. This approach avoids triggering Keychain prompts and ensures the widget never attempts to refresh the token itself, preventing conflicts with Claude Code’s own token rotation logic.

Designing for Menu Bar Real Estate

The UI design prioritizes glanceability and space efficiency, addressing the cramped nature of modern menu bars, especially on notched MacBooks. The default 'Pills' style uses rounded bars with knock-out digits to ensure readability against both light and dark backgrounds. A subtle pace caret indicates whether usage is ahead or behind schedule relative to the reset time. If a limit hits 100%, the display shifts to a countdown timer rather than a percentage, providing actionable data when you are blocked. The tool offers multiple display modes, including 'Stacked' for maximum narrowness and 'Focus' to highlight only the most critical limit. Color coding kicks in at 75% (orange) and 90% (red), providing immediate visual feedback on burn rates.

Key Takeaways

  • The tool requires macOS 14+ and Xcode Command Line Tools, but runs as a SwiftPM executable without needing a full Xcode project.
  • It polls the usage API every 2 minutes by default, with exponential backoff on HTTP 429 errors to avoid triggering further rate limits.
  • Data is cached in ~/Library/Application Support/ClaudeUsage/snapshot.json, but tokens are never written to disk, enhancing security.
  • Users can toggle between different visual styles, including a 'Mono' mode that hides color cues for a cleaner aesthetic.

The Bottom Line

This widget is a brilliant example of community tooling filling the gaps left by corporate API design. By exposing the undocumented usage endpoint, it gives developers the control and visibility Anthropic’s dashboard lacks. For heavy Claude Code users, this is no longer optional. Managing token burn is as critical as managing memory, and having that data permanently in the menu bar changes how you interact with the model. It turns a black-box limitation into a manageable resource.