steipete/codexbar

1. Repository shape

- This is a multi-target Swift package for a macOS menu bar app called CodexBar, plus a bundled cross-platform CLI, a WidgetKit extension, and shared core libraries.

- The top-level architecture is intentionally split into app/UI, CLI, core provider logic, and shared runtime/support.

2. Primary product surfaces

- Sources/CodexBar is the macOS app target: menu bar status item, popover menus, settings windows, notifications, onboarding, and update-related UI.

- Sources/CodexBarCLI is the command-line interface used for scripting, diagnostics, cost scans, and local service/serve mode.

- Sources/CodexBarWidget provides WidgetKit views and providers for system widgets.

- Sources/CodexBarCore contains the reusable business logic that powers both the app and CLI.

3. Core architectural boundary: provider abstraction

- The dominant design is a provider plugin model. Each AI service has its own provider folder with:

- a descriptor and fetcher/probe in CodexBarCore,

- an app-side implementation/settings store/login flow in CodexBar,

- and tests for provider-specific behavior.

- The shared provider APIs live under Sources/CodexBarCore/Providers/Shared, which define the contracts for provider discovery, settings, runtime, presentation, and token/cookie access.

4. Data sources and external integration

- Providers pull usage/limits from many different sources: OAuth APIs, API keys, browser cookies, local config files, CLI output, local storage, and local logs.

- Several providers use specialized sources such as gcloud/Vertex OAuth, AWS Cost Explorer/Bedrock signing, Claude/Codex CLI sessions, browser cookie import/decryption, and OpenAI dashboard web scraping.

- This means the system is not a single API client; it is a federation of source adapters with provider-specific auth and parsing rules.

5. Runtime flow from source to UI

- A refresh starts in the app’s UsageStore and ProviderRefreshCoordinator, which coordinate polling, caching, and failure handling.

- Provider fetchers in core produce normalized usage snapshots and status data.

- The app converts those snapshots into menu bar text, icon state, quota warnings, charts, and notifications via StatusItemController, MenuCardView, and related menu/overlay components.

- Widget data flows through the same shared snapshot models.

6. State, persistence, and configuration

- Persistent state is centered around settings/config stores, token stores, keychain-backed credentials, and usage/history stores.

- The repo supports both a modern config path and legacy migration path, with helpers in SettingsStore+Config* and CodexBarConfigMigrator.

- Storage is split by concern:

- config and toggles,

- provider credentials,

- usage history and snapshots,

- keychain/browser-cookie artifacts,

- local caches for performance and resilience.

7. UI subsystem

- The UI is mostly macOS-native and centered on a status item / popover menu experience.

- StatusItemController is the orchestrator for menu presentation, provider switching, refresh indicators, icon rendering, and transient effects like quota warnings or confetti.

- Settings live in a dedicated preferences experience with provider-specific panes, general/display/advanced sections, and debug tooling.

- There is also optional Merge Icons mode, where a single status item can present multiple providers through a switcher.

8. Login and credential management

- Authentication is handled per-provider, with separate login runners/flows for OAuth, device flow, browser-session import, or CLI bootstrap.

- The repo has substantial credential plumbing: keychain access gates, cookie header stores, token stores, and managed account reconciliation for Codex/OpenAI-style accounts.

- This is a major boundary: the app often reuses existing user sessions rather than collecting passwords, and some flows deliberately avoid persistent secrets beyond the required token/header artifacts.

9. CLI as a parallel interface

- The CLI is not just a thin wrapper; it exposes configuration management, diagnostics, caching, usage queries, serve mode, and cost analysis.

- Core CLI support includes a local HTTP server, terminal/process runners, and output/rendering layers for machine-readable and human-readable responses.

- Linux-specific tests in TestsLinux suggest the CLI is meant to be portable beyond macOS even though the app itself is macOS-first.

10. Cost, history, and analytics subsystem

- Beyond live quota display, the app tracks historical usage, spend, reset windows, and cost scans.

- The core includes vendored CostUsage scanning logic for parsing local logs and deriving spend/cost history for supported providers.

- Chart views and usage history menu components in the app consume these normalized historical models to render inline dashboards.

11. Status and resilience

- Several providers expose live status probes, and the app surfaces that in the menu bar and popover UI.

- There are watchdogs, memory-pressure relief, timeout handling, background refresh logic, and process/subprocess helpers to keep the app responsive and avoid hanging on external calls.

- This is a resilience-heavy architecture because many providers depend on flaky web sessions, local CLIs, or rate-limited endpoints.

12. Packaging, release, and distribution

- The repo includes extensive release automation: packaging scripts, signing/notarization, appcast generation, Sparkle update verification, and CLI tarball release helpers.

- GitHub Actions handles CI, release publishing, and upstream monitoring.

- The product is distributed as both a macOS app and a standalone CLI, with release assets and update metadata managed separately.

13. Testing strategy

- The test suite is large and highly provider-focused, with broad coverage for parsing, auth flows, UI snapshot behavior, configuration, caching, and resilience paths.

- The tests are a strong architectural signal: the system is designed around many small provider adapters and a shared core contract, with lots of characterization tests to prevent regressions.

- Linux tests further reinforce that core logic is separated from AppKit-specific code.

14. What to draw in an architecture diagram

- The most accurate diagram would show:

- macOS app UI layer and CLI layer on top,

- both calling into shared core provider logic,

- core talking outward to provider-specific sources (APIs, browsers, CLIs, local files, keychain),

- plus persistent config/cache/history storage in the middle,

- and optional widget/update/release side channels around the edges.