# steipete/codexbar architecture

> Architecture diagram of the GitHub repository steipete/codexbar, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/steipete/codexbar
- Repository: https://github.com/steipete/codexbar

## Overview

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.

Main entry points: [`Sources/CodexBar`](https://github.com/steipete/codexbar/tree/main/Sources/CodexBar) (CodexBar), [`Sources/CodexBarCore/Providers`](https://github.com/steipete/codexbar/tree/main/Sources/CodexBarCore/Providers) (Provider Adapters), [`Sources/CodexBar/UsageStore.swift`](https://github.com/steipete/codexbar/blob/main/Sources/CodexBar/UsageStore.swift) (Usage Store), [`Sources/CodexBarCLI`](https://github.com/steipete/codexbar/tree/main/Sources/CodexBarCLI) (CodexBarCLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app["App UI"]
  node_codexbar_app["CodexBar<br/>macOS app"]
  node_status_item["Status Item<br/>menu bar controller"]
  node_usage_store[("Usage Store<br/>state coordinator<br/>[UsageStore.swift]")]
  node_settings_store[("Settings Store<br/>config/state")]
  node_provider_refresh["Refresh Coordinator<br/>refresh orchestration"]
  node_preferences_ui["Preferences<br/>settings UI"]
  node_provider_ui["Provider UI<br/>provider-specific ui"]
end

subgraph group_group_cli["CLI"]
  node_codexbar_cli["CodexBarCLI<br/>CLI tool"]
  node_cli_server["Local Server<br/>http serve mode"]
  node_cli_render["CLI Output<br/>rendering layer<br/>[CLIRenderer.swift]"]
end

subgraph group_group_core["Core"]
  node_codexbar_core["CodexBarCore<br/>shared core"]
  node_provider_apis["Provider APIs<br/>contracts"]
  node_provider_catalog["Provider Catalog<br/>registry<br/>[Providers.swift]"]
  node_provider_adapters["Provider Adapters<br/>provider federation"]
  node_auth_storage[("Auth & Storage<br/>persistence/auth")]
  node_usage_history["History & Cost<br/>usage analytics"]
  node_shared_runtime["Runtime Support<br/>process/logging"]
end

subgraph group_group_widget["Widget"]
  node_widget_bundle["WidgetKit<br/>widget extension"]
end

subgraph group_group_release["Release"]
  node_release_tools["Release Tooling<br/>packaging/ci"]
end

node_status_item -->|"reads snapshots"| node_usage_store
node_status_item -->|"triggers refresh"| node_provider_refresh
node_usage_store -->|"reads config"| node_settings_store
node_usage_store -->|"uses core models"| node_codexbar_core
node_provider_refresh -->|"polls providers"| node_provider_adapters
node_provider_ui -->|"configures flows"| node_provider_adapters
node_provider_ui -->|"uses contracts"| node_provider_apis
node_preferences_ui -->|"edits settings"| node_settings_store
node_preferences_ui -->|"shows provider panes"| node_provider_ui
node_codexbar_app -->|"hosts"| node_status_item
node_codexbar_app -->|"presents"| node_preferences_ui
node_codexbar_app -->|"runs login"| node_provider_ui
node_codexbar_app -->|"persists state"| node_auth_storage
node_codexbar_cli -->|"queries core"| node_codexbar_core
node_codexbar_cli -->|"serve mode"| node_cli_server
node_codexbar_cli -->|"renders output"| node_cli_render
node_codexbar_core -->|"defines contracts"| node_provider_apis
node_provider_apis -->|"registers"| node_provider_catalog
node_provider_catalog -->|"selects adapters"| node_provider_adapters
node_provider_adapters -->|"reads credentials"| node_auth_storage
node_provider_adapters -->|"uses runtime"| node_shared_runtime
node_usage_history -->|"derives cost"| node_provider_adapters
node_usage_history -->|"feeds charts"| node_usage_store
node_widget_bundle -->|"reads snapshots"| node_usage_store
node_release_tools -->|"packages app"| node_codexbar_app
node_release_tools -->|"packages cli"| node_codexbar_cli
node_codexbar_app -->|"supports"| node_widget_bundle
node_codexbar_core -->|"scans logs"| node_usage_history

click node_codexbar_app "https://github.com/steipete/codexbar/tree/main/Sources/CodexBar"
click node_status_item "https://github.com/steipete/codexbar/blob/main/Sources/CodexBar/StatusItemController.swift"
click node_usage_store "https://github.com/steipete/codexbar/blob/main/Sources/CodexBar/UsageStore.swift"
click node_settings_store "https://github.com/steipete/codexbar/blob/main/Sources/CodexBar/SettingsStore.swift"
click node_provider_refresh "https://github.com/steipete/codexbar/blob/main/Sources/CodexBar/ProviderRefreshCoordinator.swift"
click node_preferences_ui "https://github.com/steipete/codexbar/blob/main/Sources/CodexBar/PreferencesView.swift"
click node_provider_ui "https://github.com/steipete/codexbar/tree/main/Sources/CodexBar/Providers"
click node_codexbar_cli "https://github.com/steipete/codexbar/tree/main/Sources/CodexBarCLI"
click node_cli_server "https://github.com/steipete/codexbar/blob/main/Sources/CodexBarCLI/CLILocalHTTPServer.swift"
click node_cli_render "https://github.com/steipete/codexbar/blob/main/Sources/CodexBarCLI/CLIRenderer.swift"
click node_codexbar_core "https://github.com/steipete/codexbar/tree/main/Sources/CodexBarCore"
click node_provider_apis "https://github.com/steipete/codexbar/blob/main/Sources/CodexBarCore/Providers/ProviderDescriptor.swift"
click node_provider_catalog "https://github.com/steipete/codexbar/blob/main/Sources/CodexBarCore/Providers/Providers.swift"
click node_provider_adapters "https://github.com/steipete/codexbar/tree/main/Sources/CodexBarCore/Providers"
click node_auth_storage "https://github.com/steipete/codexbar/blob/main/Sources/CodexBarCore/KeychainAccessGate.swift"
click node_usage_history "https://github.com/steipete/codexbar/blob/main/Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift"
click node_shared_runtime "https://github.com/steipete/codexbar/tree/main/Sources/CodexBarCore/Host"
click node_widget_bundle "https://github.com/steipete/codexbar/tree/main/Sources/CodexBarWidget"
click node_release_tools "https://github.com/steipete/codexbar/tree/main/Scripts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_codexbar_app,node_status_item,node_usage_store,node_settings_store,node_provider_refresh,node_preferences_ui,node_provider_ui toneBlue
class node_codexbar_cli,node_cli_server,node_cli_render toneAmber
class node_codexbar_core,node_provider_apis,node_provider_catalog,node_provider_adapters,node_auth_storage,node_usage_history,node_shared_runtime toneMint
class node_widget_bundle toneRose
class node_release_tools toneIndigo
```

## Components

### App UI

macOS menu bar app, preferences, status item, and provider-specific UI

- [CodexBar](https://github.com/steipete/codexbar/tree/main/Sources/CodexBar): macOS app · Menu bar app target with popover UI, settings, notifications, and update surfaces · `Sources/CodexBar`
- [Status Item](https://github.com/steipete/codexbar/blob/main/Sources/CodexBar/StatusItemController.swift): menu bar controller · Orchestrates icon state, menu presentation, refresh indicators, and provider switching · `Sources/CodexBar/StatusItemController.swift`
- [Usage Store](https://github.com/steipete/codexbar/blob/main/Sources/CodexBar/UsageStore.swift): state coordinator · Coordinates refresh, caching, quota status, history, and widget snapshot production · `Sources/CodexBar/UsageStore.swift`
- [Settings Store](https://github.com/steipete/codexbar/blob/main/Sources/CodexBar/SettingsStore.swift): config/state · Owns app configuration, provider toggles, token accounts, and config migration · `Sources/CodexBar/SettingsStore.swift`
- [Refresh Coordinator](https://github.com/steipete/codexbar/blob/main/Sources/CodexBar/ProviderRefreshCoordinator.swift): refresh orchestration · Schedules provider polling, failure handling, and status updates · `Sources/CodexBar/ProviderRefreshCoordinator.swift`
- [Preferences](https://github.com/steipete/codexbar/blob/main/Sources/CodexBar/PreferencesView.swift): settings UI · Provider panes, general/display/advanced sections, and debug tooling · `Sources/CodexBar/PreferencesView.swift`
- [Provider UI](https://github.com/steipete/codexbar/tree/main/Sources/CodexBar/Providers): provider-specific ui · Provider settings, login flows, menus, and presentation helpers · `Sources/CodexBar/Providers`

### CLI

Command-line surface for config, diagnostics, usage, and local serving

- [CodexBarCLI](https://github.com/steipete/codexbar/tree/main/Sources/CodexBarCLI): CLI tool · Command-line interface for usage queries, config, diagnose, cost, cache, and serve mode · `Sources/CodexBarCLI`
- [Local Server](https://github.com/steipete/codexbar/blob/main/Sources/CodexBarCLI/CLILocalHTTPServer.swift): http serve mode · Embedded HTTP server and router for local programmatic access · `Sources/CodexBarCLI/CLILocalHTTPServer.swift`
- [CLI Output](https://github.com/steipete/codexbar/blob/main/Sources/CodexBarCLI/CLIRenderer.swift): rendering layer · Human and machine-readable output formatting and termination handling · `Sources/CodexBarCLI/CLIRenderer.swift`

### Core

Shared provider engine, models, auth plumbing, storage, and adapters

- [CodexBarCore](https://github.com/steipete/codexbar/tree/main/Sources/CodexBarCore): shared core · Shared provider logic, models, auth, storage, and parsing · `Sources/CodexBarCore`
- [Provider APIs](https://github.com/steipete/codexbar/blob/main/Sources/CodexBarCore/Providers/ProviderDescriptor.swift): contracts · Provider descriptor, implementation, runtime, presentation, token, and menu contracts · `Sources/CodexBarCore/Providers/ProviderDescriptor.swift`
- [Provider Catalog](https://github.com/steipete/codexbar/blob/main/Sources/CodexBarCore/Providers/Providers.swift): registry · Catalog and registry of provider implementations and discovery metadata · `Sources/CodexBarCore/Providers/Providers.swift`
- [Provider Adapters](https://github.com/steipete/codexbar/tree/main/Sources/CodexBarCore/Providers): provider federation · Provider-specific fetchers, probes, login/auth flows, and snapshot normalization · `Sources/CodexBarCore/Providers`
- [Auth & Storage](https://github.com/steipete/codexbar/blob/main/Sources/CodexBarCore/KeychainAccessGate.swift): persistence/auth · Keychain, cookie headers, token stores, managed accounts, and config storage · `Sources/CodexBarCore/KeychainAccessGate.swift`
- [History & Cost](https://github.com/steipete/codexbar/blob/main/Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift): usage analytics · Historical usage, spend, reset windows, cost scanning, and pace calculations · `Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift`
- [Runtime Support](https://github.com/steipete/codexbar/tree/main/Sources/CodexBarCore/Host): process/logging · Process execution, HTTP client, logging, browser detection, and resilience helpers · `Sources/CodexBarCore/Host`

### Widget

WidgetKit bundle and shared snapshot rendering

- [WidgetKit](https://github.com/steipete/codexbar/tree/main/Sources/CodexBarWidget): widget extension · Widget bundle, provider, and views powered by shared usage snapshots · `Sources/CodexBarWidget`

### Release

Packaging, signing, CI, and distribution automation

- [Release Tooling](https://github.com/steipete/codexbar/tree/main/Scripts): packaging/ci · Packaging, signing, appcast generation, CI, and release automation · `Scripts`

## Connections

- Status Item → Usage Store: reads snapshots · Menu bar UI consumes normalized usage and history state
- Status Item → Refresh Coordinator: triggers refresh · UI actions and timers request provider polling and updates
- Usage Store → Settings Store: reads config · Refresh and display logic depend on persistent settings and provider selection
- Usage Store → CodexBarCore: uses core models · App state is backed by shared provider and usage models
- Refresh Coordinator → Provider Adapters: polls providers · Coordinator invokes provider fetchers and probes through core adapters
- Provider UI → Provider Adapters: configures flows · App-side provider panes and login flows bind to provider-specific behavior
- Provider UI → Provider APIs: uses contracts · Provider UI is built against shared provider interfaces
- Preferences → Settings Store: edits settings · Preferences persist provider toggles, config, and token account choices
- Preferences → Provider UI: shows provider panes · Preferences hosts provider-specific settings and login surfaces
- CodexBar → Status Item: hosts · Main app wires the menu bar controller and presentation lifecycle
- CodexBar → Preferences: presents · App exposes the settings and debug experience
- CodexBar → Provider UI: runs login · App launches provider-specific authentication and account flows
- CodexBar → Auth & Storage: persists state · App manages keychain, cookies, tokens, and migration paths
- CodexBarCLI → CodexBarCore: queries core · CLI reuses shared provider logic, config, and usage models
- CodexBarCLI → Local Server: serve mode · CLI can expose a local HTTP interface for programmatic access
- CodexBarCLI → CLI Output: renders output · CLI formats diagnostics, usage, and cache responses
- CodexBarCore → Provider APIs: defines contracts · Core exposes shared provider APIs and runtime contracts
- Provider APIs → Provider Catalog: registers · Shared APIs feed provider discovery and registry wiring
- Provider Catalog → Provider Adapters: selects adapters · Registry resolves concrete provider implementations
- Provider Adapters → Auth & Storage: reads credentials · Providers consume keychain, cookies, tokens, and config-backed artifacts
- Provider Adapters → Runtime Support: uses runtime · Providers rely on process, HTTP, logging, and resilience helpers
- History & Cost → Provider Adapters: derives cost · Historical scanners and parsers ingest provider logs and usage traces
- History & Cost → Usage Store: feeds charts · App history views and quota displays consume normalized analytics
- WidgetKit → Usage Store: reads snapshots · Widget views use the same shared snapshot models as the app
- Release Tooling → CodexBar: packages app · Scripts and workflows build, sign, notarize, and publish the macOS app
- Release Tooling → CodexBarCLI: packages cli · Release tooling also produces CLI artifacts and tarballs
- CodexBar → WidgetKit: supports · App and widget share the same usage data model and release pipeline
- CodexBarCore → History & Cost: scans logs · Core includes cost and spend scanning for local logs and history