Architecture overview

December 28, 2025 · View on GitHub

Modules

  • Sources/CodexBarCore: fetch + parse (Codex RPC, PTY runner, Claude probes, OpenAI web scraping, status polling).
  • Sources/CodexBar: state + UI (UsageStore, SettingsStore, StatusItemController, menus, icon rendering).
  • Sources/CodexBarWidget: WidgetKit extension wired to the shared snapshot.
  • Sources/CodexBarCLI: bundled CLI for codexbar usage/status output.
  • Sources/CodexBarMacros: SwiftSyntax macros for provider registration.
  • Sources/CodexBarMacroSupport: shared macro support used by app/core/CLI targets.
  • Sources/CodexBarClaudeWatchdog: helper process for stable Claude CLI PTY sessions.
  • Sources/CodexBarClaudeWebProbe: CLI helper to diagnose Claude web fetches.

Entry points

  • CodexBarApp: SwiftUI keepalive + Settings scene.
  • AppDelegate: wires status controller, Sparkle updater, notifications.

Data flow

  • Background refresh → UsageFetcher/provider probes → UsageStore → menu/icon/widgets.
  • Settings toggles feed SettingsStore → UsageStore refresh cadence + feature flags.

Concurrency & platform

  • Swift 6 strict concurrency enabled; prefer Sendable state and explicit MainActor hops.
  • macOS 14+ targeting; avoid deprecated APIs when refactoring.

See also: docs/providers.md, docs/refresh-loop.md, docs/ui.md.