Skip to content

v0.4.0

Latest
Latest

Choose a tag to compare

View all tags
@NTLx NTLx released this 13 Oct 04:32
· 3 commits to main since this release
v0.4.0
8aa5d87

CodexSatellites v0.4.0

Released: 2026-10-13

Makes the Small and Medium widgets useful as both a status surface and a native macOS configuration surface.

Highlights

  • Both widget sizes now show the 5-hour and weekly remaining quotas, available reset count, and whether CodexSatellites.app is currently Running or Stopped.
  • macOS Edit Widget exposes two app settings: Launch at Login and quota check frequency (1m, 5m, 15m).
  • Clicking the normal widget content performs a local-only refresh that re-reads cached information and re-checks the main app's current process state.
  • Macs without a usable hardware notch can configure Launch at Login and Frequency through the native widget editor. There is still no conventional Settings window or menu bar item.

Widget interactions

  • The normal widget face always displays remaining percentages. Widget configuration is reserved for Launch at Login and Frequency; there is no custom gear/settings face.
  • Clicking the widget content explicitly requests a fresh WidgetKit timeline. The provider re-reads the app-owned quota/settings caches and probes the current app process state.
  • That refresh never fetches from OpenAI, reads Codex auth, starts or activates the app, or writes quota/settings snapshots.
  • Reset count is read-only. Fresh 0 is shown as 0; stale or unavailable quota state shows —.
  • The widget timeline remains .never; no scheduled/background widget refresh, Timer, push refresh, or direct usage request was added.

Native widget configuration

  • Launch at Login continues to use the main app's SMAppService.mainApp path.
  • Frequency maps exactly to 1m, 5m, or 15m; applying a new value replaces the app's refresh loop without triggering an immediate quota request solely because the interval changed.
  • WidgetKit stores configuration per widget instance, while these two settings are global to CodexSatellites. The app therefore treats an instance's native configuration as a command surface rather than as the global source of truth.
  • The running app compares current WidgetKit configurations with a persisted baseline and applies only the field that actually changed on one widget instance. An unchanged stale field does not overwrite a newer global setting.
  • Adding, removing, resizing, or ambiguously changing multiple widgets updates the baseline without mutating global settings.
  • WidgetKit has no public API for rewriting another installed widget instance's stored editor values, so other instances may continue to display their previously stored editor values until edited.
  • Editing a widget while CodexSatellites is stopped does not wake the app. The change is reconciled the next time the app launches.

State model

  • Quota data remains in the existing WidgetQuotaSnapshot contract.
  • v0.4.0 adds a separate app-owned WidgetSettingsSnapshot for Launch-at-Login state, refresh frequency, and freshness-correct reset count.
  • The app publishes both quota and settings snapshots through the existing widgetContainer transport. Developer ID signing does not implicitly switch the runtime to App Group transport.
  • Main-app Running/Stopped state is intentionally not persisted; the widget probes it on each real timeline request so it cannot remain stale simply because the app exited.

Privacy and authentication

The app remains the only component that reads the existing local Codex authentication state and calls the usage endpoint. The widget extension never reads Codex auth and never calls the usage endpoint. Settings snapshots contain only widget-safe settings state and never contain credentials.

Distribution

The v0.4.0 GitHub release uses an ad-hoc signed app and widget extension inside an unnotarized DMG. It is not Developer ID signed and has not been submitted to Apple's notarization service. macOS may therefore require explicit user approval on first launch; if it blocks the app, use Finder's Open action or review the app under System Settings → Privacy & Security. SHA256SUMS is published with the DMG for integrity verification.

Requirements

  • macOS 15+
  • Existing local Codex CLI authentication
  • Hardware notch required only for the notch satellites; the widget works independently of notch availability

Known limitations

  • Codex usage currently depends on an undocumented ChatGPT usage endpoint.
  • Full-screen Space behavior has not been explicitly validated.
  • No automatic updater yet.
  • WidgetKit does not expose a public API for synchronously rewriting the native editor values stored by every other widget instance after one instance changes a global setting.
  • An already-running widget extension may temporarily continue using the previous widget binary after an in-place app update until macOS recycles that extension process. No public WidgetKit API guarantees immediate process recycling.

Project status

CodexSatellites is an independent community utility and is not affiliated with or endorsed by OpenAI.

Assets 4
Loading