# raycalrui/codexmeter architecture

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

- Interactive diagram: https://gitdiagram.com/raycalrui/codexmeter
- Repository: https://github.com/raycalrui/codexmeter

## Overview

CodexMeter is a native macOS menu-bar app for viewing Codex quota and token activity. Its main workflow launches the local Codex App Server, reads account and rate-limit data, records account-separated history, and presents refreshed status in the menu bar and popover. Users can also browse and export history, customize the interface, and manage updates. The README documents the App Server protocol and these product capabilities; source excerpts are partial, so some internal links remain unverified.

Main entry points: [`CodexMeter/CodexUsageService.swift`](https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/CodexUsageService.swift) (Codex service), [`CodexMeter/CodexMeterApp.swift`](https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/CodexMeterApp.swift) (App lifecycle), [`CodexMeter/UsageHistoryModel.swift`](https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/UsageHistoryModel.swift) (History model), [`CodexMeter/AppSettingsView.swift`](https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/AppSettingsView.swift) (Settings interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Quota Runtime"]
  node_app["App lifecycle"]
  node_service["Codex service"]
  node_quota["Quota models<br/>[QuotaModels.swift]"]
  node_reset["Reset credits"]
end

subgraph group_presentation["App Interface"]
  node_popover["Quota popover<br/>[ContentView.swift]"]
  node_menubar["Menu bar indicator"]
  node_historywindow["History window"]
  node_charts["History charts"]
end

subgraph group_history["Usage History"]
  node_historymodel["History model"]
  node_store[("History store")]
  node_historytypes["History models"]
  node_identity["Account identity"]
  node_backup["History backup"]
  node_backupview["Backup controls"]
end

subgraph group_support["Settings and Support"]
  node_settings["App settings<br/>[AppSettings.swift]"]
  node_settingsview["Settings interface"]
  node_customization["Popover customization"]
  node_developer["Developer options"]
  node_notifications["Notifications"]
  node_updater["Update checker"]
  node_about["About window<br/>[AboutView.swift]"]
  node_appearance["Appearance model"]
  node_popoverconfig["Popover configuration"]
end

node_user(("Mac user"))
node_cli["Codex CLI"]
node_appserver["Codex App Server"]

node_user -->|"launches"| node_app
node_app -->|"starts"| node_service
node_app -->|"presents"| node_popover
node_app -->|"presents"| node_historywindow
node_app -->|"creates"| node_historymodel
node_app -->|"creates"| node_settings
node_app -->|"creates"| node_updater
node_service -->|"launches"| node_cli
node_cli -->|"starts"| node_appserver
node_service -->|"exchanges JSON-RPC"| node_appserver
node_service -->|"records snapshots"| node_historymodel
node_service -->|"evaluates alerts"| node_notifications
node_service -.->|"uses quota values"| node_quota
node_service -.->|"reads reset data"| node_reset
node_popover -->|"shows usage"| node_service
node_popover -.->|"renders indicator"| node_menubar
node_popover -.->|"shows history"| node_historymodel
node_historywindow -->|"loads history"| node_historymodel
node_historywindow -->|"shows current usage"| node_service
node_historywindow -.->|"renders charts"| node_charts
node_historymodel -->|"queries and records"| node_store
node_store -->|"uses account keys"| node_identity
node_store -->|"imports and exports"| node_backup
node_historymodel -.->|"exposes history data"| node_historytypes
node_backupview -->|"manages history"| node_historymodel
node_settingsview -->|"edits preferences"| node_settings
node_settingsview -->|"opens customization"| node_customization
node_settingsview -->|"opens developer options"| node_developer
node_settingsview -->|"opens backup controls"| node_backupview
node_settingsview -->|"opens about"| node_about
node_customization -->|"updates preferences"| node_settings
node_customization -->|"configures sections"| node_popoverconfig
node_developer -->|"updates appearance"| node_settings
node_menubar -->|"renders styles"| node_appearance
node_about -->|"shows update status"| node_updater
node_updater -->|"offers signed updates"| node_user

click node_app "https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/CodexMeterApp.swift"
click node_service "https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/CodexUsageService.swift"
click node_quota "https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/Core/QuotaModels.swift"
click node_reset "https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/Core/RateLimitResetCredits.swift"
click node_popover "https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/ContentView.swift"
click node_menubar "https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/MenuBarProgressView.swift"
click node_historywindow "https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/UsageHistoryView.swift"
click node_charts "https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/HistoryChartComponents.swift"
click node_historymodel "https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/UsageHistoryModel.swift"
click node_store "https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/Core/UsageHistoryStore.swift"
click node_historytypes "https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/Core/HistoryModels.swift"
click node_identity "https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/Core/HistoryAccountIdentity.swift"
click node_backup "https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/Core/HistoryBackup.swift"
click node_backupview "https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/HistoryBackupView.swift"
click node_settings "https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/AppSettings.swift"
click node_settingsview "https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/AppSettingsView.swift"
click node_customization "https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/PopoverCustomizationView.swift"
click node_developer "https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/DeveloperOptionsView.swift"
click node_notifications "https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/NotificationManager.swift"
click node_updater "https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/UpdateChecker.swift"
click node_about "https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/AboutView.swift"
click node_appearance "https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/Core/MenuBarAppearance.swift"
click node_popoverconfig "https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/Core/PopoverContentConfiguration.swift"

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_app,node_service,node_quota,node_reset,node_user toneBlue
class node_popover,node_menubar,node_historywindow,node_charts toneAmber
class node_historymodel,node_store,node_historytypes,node_identity,node_backup,node_backupview,node_appserver toneMint
class node_settings,node_settingsview,node_customization,node_developer,node_notifications,node_updater,node_about,node_appearance,node_popoverconfig toneRose
class node_cli toneIndigo
```

## Components

### Quota Runtime

- [App lifecycle](https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/CodexMeterApp.swift): `CodexMeter/CodexMeterApp.swift`
- [Codex service](https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/CodexUsageService.swift): `CodexMeter/CodexUsageService.swift`
- [Quota models](https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/Core/QuotaModels.swift): `CodexMeter/Core/QuotaModels.swift`
- [Reset credits](https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/Core/RateLimitResetCredits.swift): `CodexMeter/Core/RateLimitResetCredits.swift`

### App Interface

- [Quota popover](https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/ContentView.swift): `CodexMeter/ContentView.swift`
- [Menu bar indicator](https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/MenuBarProgressView.swift): `CodexMeter/MenuBarProgressView.swift`
- [History window](https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/UsageHistoryView.swift): `CodexMeter/UsageHistoryView.swift`
- [History charts](https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/HistoryChartComponents.swift): `CodexMeter/HistoryChartComponents.swift`

### Usage History

- [History model](https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/UsageHistoryModel.swift): `CodexMeter/UsageHistoryModel.swift`
- [History store](https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/Core/UsageHistoryStore.swift): `CodexMeter/Core/UsageHistoryStore.swift`
- [History models](https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/Core/HistoryModels.swift): `CodexMeter/Core/HistoryModels.swift`
- [Account identity](https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/Core/HistoryAccountIdentity.swift): `CodexMeter/Core/HistoryAccountIdentity.swift`
- [History backup](https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/Core/HistoryBackup.swift): `CodexMeter/Core/HistoryBackup.swift`
- [Backup controls](https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/HistoryBackupView.swift): `CodexMeter/HistoryBackupView.swift`

### Settings and Support

- [App settings](https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/AppSettings.swift): `CodexMeter/AppSettings.swift`
- [Settings interface](https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/AppSettingsView.swift): `CodexMeter/AppSettingsView.swift`
- [Popover customization](https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/PopoverCustomizationView.swift): `CodexMeter/PopoverCustomizationView.swift`
- [Developer options](https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/DeveloperOptionsView.swift): `CodexMeter/DeveloperOptionsView.swift`
- [Notifications](https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/NotificationManager.swift): `CodexMeter/NotificationManager.swift`
- [Update checker](https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/UpdateChecker.swift): `CodexMeter/UpdateChecker.swift`
- [About window](https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/AboutView.swift): `CodexMeter/AboutView.swift`
- [Appearance model](https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/Core/MenuBarAppearance.swift): `CodexMeter/Core/MenuBarAppearance.swift`
- [Popover configuration](https://github.com/raycalrui/codexmeter/blob/main/CodexMeter/Core/PopoverContentConfiguration.swift): `CodexMeter/Core/PopoverContentConfiguration.swift`

### Other components

- **Mac user**
- **Codex CLI**
- **Codex App Server**

## Connections

- Mac user → App lifecycle: launches (evidence: `README.md`)
- App lifecycle → Codex service: starts (evidence: `CodexMeter/CodexMeterApp.swift`)
- App lifecycle → Quota popover: presents (evidence: `CodexMeter/CodexMeterApp.swift`)
- App lifecycle → History window: presents (evidence: `CodexMeter/CodexMeterApp.swift`)
- App lifecycle → History model: creates (evidence: `CodexMeter/CodexMeterApp.swift`)
- App lifecycle → App settings: creates (evidence: `CodexMeter/CodexMeterApp.swift`)
- App lifecycle → Update checker: creates (evidence: `CodexMeter/CodexMeterApp.swift`)
- Codex service → Codex CLI: launches (evidence: `README.md`)
- Codex CLI → Codex App Server: starts (evidence: `README.md`)
- Codex service → Codex App Server: exchanges JSON-RPC (evidence: `README.md`)
- Codex service → History model: records snapshots (evidence: `CodexMeter/CodexUsageService.swift`)
- Codex service → Notifications: evaluates alerts (evidence: `CodexMeter/CodexUsageService.swift`)
- Codex service → Quota models: uses quota values
- Codex service → Reset credits: reads reset data
- Quota popover → Codex service: shows usage (evidence: `CodexMeter/ContentView.swift`)
- Quota popover → Menu bar indicator: renders indicator
- Quota popover → History model: shows history (evidence: `CodexMeter/ContentView.swift`)
- History window → History model: loads history (evidence: `CodexMeter/UsageHistoryView.swift`)
- History window → Codex service: shows current usage (evidence: `CodexMeter/UsageHistoryView.swift`)
- History window → History charts: renders charts
- History model → History store: queries and records (evidence: `CodexMeter/UsageHistoryModel.swift`)
- History store → Account identity: uses account keys (evidence: `CodexMeter/Core/UsageHistoryStore.swift`)
- History store → History backup: imports and exports (evidence: `CodexMeter/Core/UsageHistoryStore.swift`)
- History model → History models: exposes history data
- Backup controls → History model: manages history (evidence: `CodexMeter/HistoryBackupView.swift`)
- Settings interface → App settings: edits preferences (evidence: `CodexMeter/AppSettingsView.swift`)
- Settings interface → Popover customization: opens customization (evidence: `CodexMeter/AppSettingsView.swift`)
- Settings interface → Developer options: opens developer options (evidence: `CodexMeter/AppSettingsView.swift`)
- Settings interface → Backup controls: opens backup controls (evidence: `CodexMeter/AppSettingsView.swift`)
- Settings interface → About window: opens about (evidence: `CodexMeter/AppSettingsView.swift`)
- Popover customization → App settings: updates preferences (evidence: `CodexMeter/PopoverCustomizationView.swift`)
- Popover customization → Popover configuration: configures sections (evidence: `CodexMeter/PopoverCustomizationView.swift`)
- Developer options → App settings: updates appearance (evidence: `CodexMeter/DeveloperOptionsView.swift`)
- Menu bar indicator → Appearance model: renders styles (evidence: `CodexMeter/MenuBarProgressView.swift`)
- About window → Update checker: shows update status (evidence: `CodexMeter/AboutView.swift`)
- Update checker → Mac user: offers signed updates (evidence: `README.md`)
