Skip to content

overview.md

Latest commit

 

History

History
72 lines (57 loc) · 3.31 KB

overview.md

File metadata and controls

72 lines (57 loc) · 3.31 KB
Raw

Architecture Overview

Codex Quota is a local macOS application. It selects and launches a user-confirmed Codex executable, reads quota data over stdio, and displays only results that have passed the identity gates in a floating panel.

Components

  • QuotaApp manages application lifecycle, the floating panel, Settings, notifications, and the login item.
  • QuotaCore handles environment resolution, executable trust, identity hashing, the app-server protocol, account sessions, quota state, and local persistence.
  • The Codex subprocess is launched from the executable explicitly selected by the user with app-server --listen stdio://.
  • state.json stores this app's preferences and confirmed snapshots. Keychain stores the random salt used for account hashing.

The app is not an implementation of Codex or an OpenAI service, and it does not sign in on the user's behalf.

Startup and Data Flow

  1. In Settings, the user selects a Codex executable and confirms its file name and short SHA-256 digest.
  2. The environment resolver revalidates the trust receipt, resolves the effective CODEX_HOME, and creates a restricted subprocess environment.
  3. The app uses the same trust boundary for a --version probe, then starts app-server --listen stdio://.
  4. The client sends initialize, verifies that the returned Codex Home matches, and then sends initialized.
  5. The client uses account/read to confirm sign-in state with refreshToken: false.
  6. The client reads quota with account/rateLimits/read and handles account/updated and account/rateLimits/updated notifications.
  7. Quota enters the Live position only after account identity, authentication file fingerprint, and connection epoch all match. Other accounts retain only their last confirmed snapshots.

When an account or environment changes, the old connection exits and old data is never attributed to the new account. A connection error may retain a confirmed snapshot, but the interface labels it as retrying, failed, or stale.

Local System Boundary

Codex Quota runs with current-user permissions. It does not provide a system sandbox for the Codex subprocess, and an environment-variable allowlist is not permission isolation. The selected Codex may access resources already available to the current user and may access the network.

The app uses these macOS capabilities:

  • Keychain: stores a non-synchronizable local random salt;
  • User Notifications: requests permission only after quota alerts are enabled;
  • SMAppService.mainApp: manages Launch at Login;
  • Application Support: stores this app's state.json.

See Privacy and Data Flow for the complete data boundary and Codex Compatibility for protocol assumptions and verification status.

Trust Boundary

For a confirmed executable, the app records its canonical absolute path, file identity, and SHA-256. It revalidates them before every probe or launch and holds a file-descriptor lease during startup. The final posix_spawn still executes by path, so a residual race remains if the same user replaces the path between the final check and the system opening it.

A confirmation record means only that the current file matches bytes confirmed earlier. It does not prove an official distribution channel. Select only a file you trust.