{"slug": "claude-usage-in-your-menu-bar", "title": "Claude usage in your menu bar", "summary": "A macOS menu bar app and desktop widget called Claude Usage now displays a Claude Code user's plan limits — the 5-hour session, the weekly cap, and any per-model weekly caps — mirroring the numbers shown by the `/usage` command in Claude Code. The app requires macOS 14 or later, the Xcode Command Line Tools, and a Claude Code login, and is built and installed with `make install`; it offers Pills, Stacked, Focus and Text menu bar styles, a pace caret showing whether usage is on track to hit a limit before reset, and a `--print`/`--json` terminal mode that outputs the same table as `/usage`.", "body_md": "A macOS menu bar item and desktop widget that show your Claude plan limits: the 5-hour session, the weekly cap, and any per-model weekly caps. These are the same numbers `/usage` shows in Claude Code.\n\n| Popover | Desktop widget | \n|---|---|\n\nRequires macOS 14+, the Xcode Command Line Tools (`xcode-select --install`), and a Claude Code login (` claude`, then `/login`).\n\n```\nmake install      # builds \"Claude Usage.app\", copies it to ~/Applications, launches it\n```\n\nTo build without installing, run `make app`. The app ends up in `build/`.\n\nDon't see it in the menu bar? Menu bar managers such as Hidden Bar, Ice and Bartender put new items in their hidden section. Expand that section and ⌘-drag the item into the visible part. Opening the app again (Spotlight, Finder) always brings up Settings.\n\n- **Click** the menu bar item for the detail popover: each limit, its reset time, a pace marker, and a forecast (\"Limit in ~1h 12m\" or \"~62% at reset\").\n- **Right-click** for Refresh, the desktop widget toggle, Settings and Quit.\n- **Desktop widget** : turn it on in Settings or from the right-click menu. It sits on the desktop, above the icons and below your windows. Drag it anywhere; right-click it for options, including \"Keep Above Other Windows\".\n- **Terminal** :`ClaudeUsage --print` prints the same table as`/usage` .`--json` gives you the parsed data as JSON.\n\n```\nClaude usage  ·  Team · 5x\n\nCurrent session            █████████░░░░░░░░░░░░░░░   37%   Resets in 3h 49m · 18:39  ⚠ limit in ~1h 59m at this pace\nCurrent week (all models)  ████░░░░░░░░░░░░░░░░░░░░   17%   Resets Tue 06:59 · in 5d 16h  (~90% at reset)\nCurrent week (Fable)       ░░░░░░░░░░░░░░░░░░░░░░░░    0%   Resets Tue 07:00 · in 5d 16h\n```\n\nMenu bar space is scarce, especially on notched MacBooks, where items that don't fit just disappear. The design started from three questions you want answered at a glance: *how much have I used, am I burning it too fast, and when does it come back?*\n\n**Pills (default), about 80pt for two limits.** Each limit is a small rounded bar with its percentage printed on it, like the battery glyph. The fill knocks the digits out of itself, so the number stays readable wherever the fill edge lands, on a light or dark menu bar. Digits are monospaced and the pill is sized for \"88%\", so going from 19% to 20% never moves your other menu bar items.\n\n**The pace caret.** The small caret under each pill marks how much of the window has passed. Its position is where your usage would be if you spread it evenly. If the fill is **past the caret**, you're on track to hit the limit before it resets. If it's behind, you have room. The caret takes no extra width, and it sits outside the pill so it never cuts through the digits. An earlier version drew it inside the pill, which made \"47%\" look like \"4|7%\".\n\n**Color means something.** In the default *Warnings* mode, pills use the menu bar's own text color and look like any monochrome system item until a limit passes 75% (orange) or 90% (red). *Claude* mode tints them clay. *Mono* never colors them.\n\n**At 100% the pill shows a countdown.** Once you're blocked, the percentage tells you nothing, so the pill turns red and shows the time until reset instead (`1h12m`).\n\n**Stale data fades.** If the last successful fetch is too old (offline, expired login), the item is drawn at reduced opacity instead of showing numbers you shouldn't trust. The popover says why.\n\nOther styles, in Settings → Menu bar style:\n\n| Style | Width | Shows | \n|---|---|---|\n| Pills | ~80pt | A bar behind each percentage (labels optional: `5h` ,`7d` ) | \n| Stacked | ~50pt | Two mini bars stacked vertically, numbers to the right. The narrowest option. | \n| Focus | ~55pt | One pill for whichever limit is closest to running out, with its label | \n| Text | ~70pt | Just the numbers, colored the same way | \n\nYou choose which limits appear (session, week, per-model weeks). The order always follows the server's: session first, then weekly.\n\nLight menu bar:\n\n- **Data** :`GET https://api.anthropic.com/api/oauth/usage` , the endpoint Claude Code's`/usage` reads. It is undocumented and may change. The parser prefers the structured`limits` array, falls back to the older flat`five_hour` /`seven_day_*` keys, and ignores fields it doesn't recognize.\n- **Login** : reads Claude Code's OAuth token from the Keychain item`Claude Code-credentials` using`/usr/bin/security` . Claude Code writes that item with the same tool, so reading it doesn't trigger a Keychain prompt. It falls back to`~/.claude/.credentials.json` . The app never writes credentials and never refreshes the token itself. That would rotate Claude Code's refresh token out from under it. If the token has expired, the app keeps showing the last known numbers (faded) until Claude Code renews it, which happens the next time you use it.\n- **Polling** : every 2 minutes by default (configurable), when the popover opens, and after wake. On HTTP 429 it backs off. Only percentages and reset times are cached, in`~/Library/Application Support/ClaudeUsage/snapshot.json` . Tokens are never written to disk.\n- **Reset rollover** : when a window's reset time passes between fetches, it shows 0% right away instead of a stale number.\n\n```\nswift build                                    # debug build\nswift run ClaudeUsage --print                  # live usage in the terminal\nswift run ClaudeUsage --render-previews docs   # regenerate the images in this README\nCLAUDE_USAGE_DEBUG=1 \"build/Claude Usage.app/Contents/MacOS/ClaudeUsage\"   # log fetches and draws\n```\n\n| File | What's in it | \n|---|---|\n| `MenuBarRenderer.swift` | All menu bar drawing (Core Graphics). Used by the live item, the Settings tiles and the preview renderer. | \n| `UsageParser.swift` | API response → `UsageSnapshot` | \n| `Credentials.swift` | Finding Claude Code's login | \n| `UsageStore.swift` | Polling, caching, backoff, the clock behind countdowns | \n| `StatusItemController.swift` ,`PopoverView.swift` | Menu bar item and popover | \n| `DesktopWidget.swift` | Desktop panel (Liquid Glass on macOS 26, vibrancy on older versions) | \n| `SettingsView.swift` | Settings window | \n\nIt's a SwiftPM executable, so you don't need Xcode. `scripts/build-app.sh` wraps the binary in an app bundle, generates the icon, and signs it ad hoc. Set `SIGN_IDENTITY` to sign with a Developer ID.\n\nA native WidgetKit widget, the kind in Notification Center and on the desktop since Sonoma, would need an Xcode project, a signed app extension and an App Group. The desktop panel gives you the same view without any of that.", "url": "https://wpnews.pro/news/claude-usage-in-your-menu-bar", "canonical_source": "https://github.com/trthomps/claude-usage-widget", "published_at": "2026-11-11 23:09:51+00:00", "updated_at": "2026-11-11 23:20:48.805994+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "ai-products"], "entities": ["Claude", "Claude Code", "Claude Usage", "macOS", "Xcode", "Hidden Bar", "Ice", "Bartender"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/claude-usage-in-your-menu-bar", "markdown": "https://wpnews.pro/news/claude-usage-in-your-menu-bar.md", "text": "https://wpnews.pro/news/claude-usage-in-your-menu-bar.txt", "jsonld": "https://wpnews.pro/news/claude-usage-in-your-menu-bar.jsonld"}}