jatinsmu/cc-usage-tracker-menu-bar

1. What this repo is

- CCUsageBar is a macOS menu bar utility, written in Swift using Swift Package Manager, that displays Claude Code quota status in real time.

- It is a single-user desktop app rather than a client/server system: the main runtime is the app bundle itself, plus a polling timer.

2. App shell and lifecycle

- Sources/CCUsageBar/CCUsageBarApp.swift is the entry point.

- The app uses MenuBarExtra to create a menu bar item with a popover, and Resources/Info.plist sets LSUIElement=true, so there is no Dock icon.

- This makes the app behave like a background menu-bar agent with a UI only when the user clicks the icon.

3. Central coordination layer

- UsageViewModel.swift is the main orchestration boundary.

- It is @MainActor and acts as the state holder for the UI, driving:

- initial load,

- periodic polling every 15 minutes,

- manual refresh,

- update-check state,

- and error/offline fallback state.

- This is the main hub where keychain access, API calls, and UI state converge.

4. Token retrieval boundary

- KeychainReader.swift reads the Claude Code OAuth token from the macOS Keychain item Claude Code-credentials.

- The repo intentionally reads the existing system Keychain entry rather than storing its own credentials.

- This boundary matters architecturally because access is asynchronous/off-main-thread to avoid freezing the UI when macOS shows a Keychain prompt.

5. Remote usage data flow

- UsageClient.swift performs the network request to Anthropic’s internal OAuth usage endpoint: https://api.anthropic.com/api/oauth/usage.

- The request uses the token from Keychain and the anthropic-beta: oauth-2025-04-20 header.

- This is the only runtime network dependency for quota data, and the app relies on standard macOS TLS validation.

6. Domain model and quota computation

- Models.swift defines the response/domain shapes such as usage snapshots, windows, limits, and severity levels.

- QuotaMetrics.swift contains the pure calculation logic for percentages, pace, and reset timing.

- This separation keeps business logic testable and independent from UI, keychain, and networking.

7. UI composition

- Views/PopoverView.swift is the popover state machine rendered for the user.

- Views/QuotaTrackView.swift renders the quota bar/track and visual severity cues.

- Views/Theme.swift holds the app’s color palette.

- The UI is state-driven: the popover shows live usage, reset countdowns, refresh controls, offline/expired-token messaging, and update banners.

8. Update subsystem

- UpdateChecker.swift checks GitHub Releases for newer versions and can download the release asset.

- The user-facing update path is integrated into the popover: when a newer release exists, the app shows an “Update available” banner with an install action.

- This is a second external dependency besides Anthropic: GitHub Releases is the distribution/update source.

9. Failure and degradation behavior

- The app is designed to keep showing the last known state when the network is unavailable.

- It also distinguishes between several non-success modes: offline, expired token, not signed in / not connected, and unknown errors.

- That means the view model does not treat polling failure as fatal; it maps failures into UI states instead of crashing or exiting.

10. Testing boundary

- Tests/CCUsageBarTests/ focuses on pure logic and parsing:

- Keychain parsing,

- model decoding,

- quota math,

- update-check logic,

- usage-client behavior,

- and view-model state mapping.

- The tests intentionally avoid real network and Keychain access, which keeps the architecture cleanly separated into testable core logic and platform-integrated adapters.

11. Build, release, and distribution

- scripts/build-app.sh assembles CCUsageBar.app and signs it locally with a self-signed identity.

- The repo is not sandboxed, which is intentional because it needs Keychain access and outbound HTTPS to Anthropic.

- .github/workflows/ci.yml validates build and tests on pull requests and main-branch pushes; .github/workflows/release.yml publishes tagged releases to GitHub.

12. Overall architecture in one line

- The app is a small macOS menu-bar client with a single stateful view model coordinating three adapters: Keychain for auth, Anthropic for usage data, and GitHub Releases for updates, with pure quota logic and rendering kept separate for testability.