UsageHub (formerly OpenUsage Bar) is a local-first AI usage dashboard. The current release form is the desktop client (Electron wrapping the local web dashboard) with the native SwiftUI menu-bar build maintained in parallel; both share the Python collection layer. Keep credentials and network mutation in Python adapters; renderers (Web/Electron/SwiftUI) read only sanitized local facts.
- Apple Silicon Mac
- macOS 15 or later
- Xcode with Swift 6.2 or later
- Python 3.11 or later
- Git
Prepare a clean checkout and run the full gate:
scripts/bootstrap.sh
scripts/build_app.shTo build and package the desktop client (current release form):
cd desktop && npm run dist:macThe build runs Python and Swift tests, coverage gates, privacy scans, the repository secret scan, Release compilation, packaging, and code-signature verification. Do not bypass a failing gate.
- Keep changes focused and add a regression test.
- Do not add a dependency when the Python standard library or native Apple API already provides the capability.
- Never commit real keys, cookies, tokens, provider payloads, prompts, responses, paths containing account identity, or copied Keychain data.
- Run
scripts/release_secret_scan.py --historybefore opening a pull request. - Run
scripts/build_app.shand include the exact result in the pull request.
Provider adapters must preserve last-good data on failure and represent unknown quota as unavailable, never as zero.
Prefer a declarative quota, daily usage, or daily cost feed before adding provider-specific Python or Swift code. Start from the Provider Adapter Kit example and validate it:
python3 scripts/check_provider_adapter.py examples/provider-adapter-kit/example-providerThe bundle and its fixtures must be synthetic and redacted. Static conformance does not replace a separately reported live-account canary.