openusage README

The project's README from github.com/robinebers/openusage. As one markdown file: README.md.

OpenUsage

Track your AI coding subscriptions from the macOS menu bar — native Swift edition.

OpenUsage shows how much of your AI coding plans you've used: session and weekly limits, credits, and spend, all in one popover. Pin your most important metrics straight into the menu bar.

OpenUsage menu bar tracker showing Claude and Codex session, weekly, and spend usage

Installation

Homebrew:

brew install --cask openusage

Direct download: grab the latest universal DMG from the releases page, open it, and drag OpenUsage to your Applications folder.

Either way, the app updates itself in place via signed, notarized Sparkle updates. Requires macOS 15 (Sequoia) or later.

Supported Providers

Most providers read the credentials already on your machine (keychain, auth files, app state) — no extra login. OpenRouter and Z.ai are the exceptions: they have no local credential to reuse, so you supply an API key (see OpenRouter setup or Z.ai setup). Credentials are used only for the corresponding provider requests. OpenUsage's separate anonymous summaries and public pricing downloads are documented under Privacy & usage data.

Features

Documentation

Behavior docs live in docs/: the dashboard, menu bar pins, settings, refresh & caching, the CLI, the local HTTP API, the proxy, and one page per provider.

For working on the code, see the developer docs: architecture, adding a provider, and debugging & capturing logs.

Requirements

The Today / Yesterday / Last 30 Days spend tiles are computed natively from local CLI logs (Claude, Codex, and Grok) or Cursor's usage export — no Node.js or other runtime needed. Dollars are estimated with dynamically refreshed model pricing.

Building

swift build            # debug build
swift test             # run the test suite
./script/build_and_run.sh   # build and launch the dev app from dist/ (no install)

Architecture

SwiftPM package, SwiftUI content hosted in an AppKit-owned NSStatusItem + custom key-capable NSPanel, Swift 6 strict concurrency. The app and CLI share one module: providers implement a small ProviderRuntime protocol (auth store → usage client → mapper → ProviderSnapshot), and both surfaces read the same normalized data — see the architecture overview for how the pieces fit together and AGENTS.md for engineering conventions.

Releasing

Releases are automated: pushing a v* tag on main builds, signs, notarizes, and publishes a new version. A plain tag (v0.7.1) ships to everyone; a pre-release suffix (v0.7.1-beta.1) ships to the beta channel. The pipeline lives in .github/workflows/release.yml, and the step-by-step is in the release-swift skill.

Release setup (one-time)

The release workflow needs these repository secrets (Settings → Secrets and variables → Actions):

Secret What it is
APPLE_CERTIFICATE base64 of your Developer ID Application .p12
APPLE_CERTIFICATE_PASSWORD the password set when exporting that .p12
APPLE_ID the Apple ID email used for notarization
APPLE_PASSWORD an app-specific password for that Apple ID
APPLE_TEAM_ID your Apple Developer team ID
APPLE_DEVELOPER_ID_ICLOUD_PROFILE base64 Developer ID provisioning profile for the production iCloud container
SPARKLE_PUBLIC_KEY base64 EdDSA public key, baked into the build as SUPublicEDKey
SPARKLE_PRIVATE_KEY base64 EdDSA private key used to sign the DMG
POSTHOG_CLI_API_KEY PostHog personal API key used to upload dSYMs for crash symbolication
POSTHOG_CLI_PROJECT_ID numeric PostHog project ID the dSYMs upload to

Export the Developer ID Application cert (with its private key) from Keychain Access as a .p12, then base64 -i DeveloperID.p12 | pbcopy. App-specific passwords come from appleid.apple.com → Sign-In and Security → App-Specific Passwords. Generate the Sparkle EdDSA key pair once with Sparkle's generate_keys tool; the public and private values must be a matching pair or signing is silently skipped.

For iCloud Sync, store the original development and Developer ID provisioning profiles in 1Password as secure documents. Install the development profile on each registered Mac; base64-encode the Developer ID profile and store it only in the APPLE_DEVELOPER_ID_ICLOUD_PROFILE Actions secret. See iCloud Sync for the container identifiers, build command, and file-inspection command.

The two POSTHOG_CLI_* secrets are only used to upload debug symbols (dSYMs) so PostHog can symbolicate crash reports: POSTHOG_CLI_API_KEY is a PostHog personal API key (PostHog → Settings → Personal API keys) and POSTHOG_CLI_PROJECT_ID is the numeric ID from your project URL. The upload host is hardcoded in the workflow (https://us.i.posthog.com), so there is no POSTHOG_CLI_HOST secret. Unlike the secrets above these don't block a release — if POSTHOG_CLI_API_KEY is unset the workflow skips the upload with a warning and the release still ships, but crash reports for that version show raw addresses instead of symbolicated stack traces.

The repository must be public (Sparkle fetches the DMG and appcast anonymously), and the appcast is served from GitHub Pages — confirm Settings → Pages points at the gh-pages branch after the first release.

Contributing

Issues are welcome. Pull requests are strict and issue-first: comment on an issue, wait for a maintainer to add the approved label and assign it to you, then reference it in your PR with Fixes #123. Automation closes external PRs without an approved issue assigned to their author, and warns when an accepted PR adds more than 1,000 lines. Read CONTRIBUTING.md before opening one. Report security issues privately per SECURITY.md. The OpenUsage name and logo are covered by the trademark policy.

License

MIT

openusage (robinebers/openusage)

Searching Database…

4.4K ·GitHub
Openusage
Что это такое?OpenUsage — бесплатное нативное macOS-приложение в строке меню с открытым кодом, написанное на Swift: оно показывает, сколько вы израсходовали в подписках на ИИ-кодинг (Claude, Codex, Copilot, Cursor и другие) — сессионные и недельные лимиты, кредиты и траты — и всё это в одном всплывающем окне.
Какая версия macOS нужна?macOS 15 (Sequoia) или новее; OpenUsage поставляется как универсальный бинарник, который нативно работает и на Apple Silicon, и на Intel Mac.
Нужно ли отдельно входить в каждого провайдера?Для большинства провайдеров — нет: OpenUsage читает учётные данные, которые уже есть на вашей машине (связка ключей, файлы аутентификации, состояние приложений); только для OpenRouter и Z.ai нужно вручную указать API-ключ, поскольку локальных учётных данных для повторного использования у них нет.
Не раскрываются ли где-то мои данные об использовании и учётные данные?Локальный HTTP API слушает только 127.0.0.1 и никогда не отдаёт учётные данные, но в README отмечается, что открытые в браузере страницы тоже могут читать данные с этого loopback-эндпоинта.
Можно проверить расход из терминала, не открывая приложение?Да — однострочный CLI (openusage) читает те же кешированные данные о лимитах в виде JSON, а openusage --force обходит 5-минутный кеш; чтобы это работало, приложение в строке меню запускать не нужно.
Могут ли другие приложения читать мои данные об использовании?Да — через локальный HTTP API по адресу 127.0.0.1:6736/v1/limits, который доступен только через loopback и никогда не отдаёт учётные данные.
Можно пускать запросы к провайдерам через прокси?Да, OpenUsage поддерживает маршрутизацию запросов к провайдерам через прокси SOCKS5 или HTTP(S), настроенный в ~/.openusage/config.json.
Как OpenUsage считает траты в долларах?Плитки расходов (Сегодня/Вчера/Последние 30 дней) вычисляются нативно из локальных логов CLI для Claude, Codex и Grok или из экспорта использования Cursor, а доллары оцениваются по динамически обновляемым ценам моделей — Node.js или другая среда выполнения не требуются.
What are similar projects?token-monitor, casbin-gateway, tokscale, CodexBar, codenotch, headroom, ThinkWatch-Lite, codeburn
Which topics is it in?subscription, subscriptions, cost-tracking, token-usage, copilot, openrouter, menu-bar, grok, github-copilot, opencode, macos-app, homebrew
Creator
robinebers
Size
45.6 MB
Stars
4.4K
Updated
CommitOct 14Releasev0.7.14Oct 06
Age
8mo
Commits · 90 Days