A macOS menu bar app that shows how close your Claude Code and Codex CLI accounts are to their usage limits (the 5-hour, 7-day and any other windows), and when each window resets. It tracks any number of profiles side by side. Licensed under the MIT License.
- Lives only in the menu bar: a gauge and the highest percentage across your profiles, orange from 80% and red from 95%.
- A native menu lists every visible profile on one row, with its provider logo, each window's percentage and reset countdown, and when the data was last updated.
- Discovers
~/.claude*and~/.codex*config directories, plusCLAUDE_CONFIG_DIRandCODEX_HOME, and asks before adding them. - Optional alerts when a window crosses 80% or 95% and when it resets; launch at login.
Unofficial. ChoscorUsage reads usage from undocumented endpoints (
api.anthropic.com/api/oauth/usageandchatgpt.com/backend-api/wham/usage) that may change without notice. It is not affiliated with, endorsed by, or supported by Anthropic or OpenAI.
ChoscorUsage reuses each CLI's existing sign-in read-only. It never refreshes tokens
and never writes to the Keychain or to any file in a CLI config directory, so it cannot
sign you out of a CLI. When a token expires, the profile shows as stale until you run
claude or codex login in that profile. Tokens, account IDs and response bodies are
never logged or stored. Claude tokens are read with macOS's own security tool, which
Claude Code's Keychain items already trust, and kept in memory until they expire, so
normally macOS does not ask for Keychain access. Only Refresh Now and Retry fall
back to a read that may ask; if you deny it, the app stops asking until you press Retry.
Each release ships as a Developer ID signed and notarized DMG on the Releases page. Open the DMG and drag ChoscorUsage to Applications. The app does not update itself: to update, download the new DMG and replace the app. You can also build from source (see docs/BUILD.md). Requires macOS 26 or later on Apple Silicon.
Install Xcode 26, Python 3.12+, actionlint 1.7.7 and the pinned Python tools, then use the repository-owned quality interface:
python -m pip install -r scripts/ci/requirements.txt
python scripts/ci/quality.py swiftlint-install
python scripts/ci/quality.py fast
python scripts/ci/quality.py fullfast runs swift-format, SwiftLint, the architecture, file-header and secrets policies,
Ruff and the Python tests, actionlint, and the package tests. full adds
xcodebuild build test and swiftlint analyze. Every gate is also a focused stage; run
python scripts/ci/quality.py --help and see docs/CI.md. Contribution policy
is in CONTRIBUTING.md.
The app target is a thin SwiftUI shell (MenuBarExtra, Settings, notifications, login
item). All behavior lives in the local Swift package Packages/ChoscorUsageKit, layered
ChoscorUsageCore ← ChoscorUsageProviders ← ChoscorUsageKit:
- Core holds models and pure policy (window labels, menu bar summary, notification rules, backoff) and the protocols for every external effect.
- Providers reads credentials, calls and decodes each endpoint, parses Codex session logs, discovers profiles, and implements the protocols with URLSession, Security and FileManager.
- Kit orchestrates refreshes, persistence and preferences for the app.
The compiler enforces the direction, and scripts/ci/architecture.py bans specific APIs
per layer. See CLAUDE.md for the full table.