v0.3.1

Preview build — ad-hoc signed, not notarized. macOS Gatekeeper may block
this app on first launch; right-click the app and choose Open, or allow it in
System Settings → Privacy & Security. The widget extension needs a code-signed
build to be registered by macOS. This is a source-tag preview for local testing;
a Developer ID–signed and notarized build is still pending.

Attachment: CodexSatellites-0.3.1-preview-adhoc.dmg (build 29)
SHA256: de999775eb1a9a40c596903a46267cf24e8322aa574b5d1892398c2f170367c1

Adds click-to-reload to the widget.

Highlights

• Clicking the widget's content area reloads the latest quota snapshot the app has cached. This is the widget's only interaction and the only widget-driven refresh.
• The click never fetches from OpenAI, never reads Codex auth, never starts or activates the app, and never writes the snapshot. It asks WidgetKit for a fresh timeline; the widget's timeline provider then re-reads the cache.
• No refresh affordance was added: no icon, spinner, label, timestamp, toast, or pressed overlay. The Small and Medium layouts render exactly as before.
• The click area covers the widget's content area — gauges, labels, and the empty space between them. The system content margin around the content is not part of it: on a 180pt Small widget the hit boundary sits about 24pt in from the edge. Tapping that margin uses the system's default widget tap, which opens CodexSatellites — the same thing a tap anywhere on the widget did before.

How it works

• The whole widget content is wrapped in Button(intent:) with .buttonStyle(.plain), a full-area frame, and .contentShape(Rectangle()).
• RefreshCachedQuotaIntent.perform() deliberately does nothing. WidgetKit guarantees a timeline reload after a button interaction, and that reload re-runs CodexWidgetProvider.getTimeline, which re-reads the snapshot the app cached.
• The widget stays passive otherwise: timeline policy .never, no scheduled or background refresh, no WidgetCenter.reloadTimelines from the app, no widget network request, no Timer.
• RefreshCachedQuotaIntent is not discoverable in Shortcuts, does not open the app, and carries an English accessibility label and hint. Widget text stays English-only.

Signing

• The widget extension is sandboxed, which WidgetKit requires; the containing app stays non-sandboxed because it must read ~/.codex/auth.json.
• ./script/build_and_run.sh and ./script/release.sh preview ad-hoc sign the appex first (own identifier + entitlements) and the app second.
• The attached preview DMG is ad-hoc signed and unnotarized, published as a pre-release. A Developer ID–signed and notarized build is still pending.

Requirements

• macOS 15+
• MacBook with a hardware notch (notch satellites only; the widget works on any Mac)
• Existing local Codex CLI authentication

Privacy

CodexSatellites does not implement its own login or OAuth flow. It reads the existing local Codex authentication state and does not refresh tokens or write Codex auth files. The widget still never reads Codex auth and never calls the usage endpoint — a click only re-reads the app's cached snapshot.

Known limitations

• Codex usage currently depends on an undocumented ChatGPT usage endpoint.
• No automatic updater yet.
• The widget requires a code-signed build to be registered by macOS.
• During local ad-hoc upgrade testing, an already-running widget extension could continue using the previous widget code until macOS recycled the extension process. There is no public API that guarantees recycling. Developer ID upgrade behaviour has not yet been verified.
• If the app has never run, there is no cached snapshot and a click keeps showing —.

Integrity

The release includes the SHA-256 value for verifying the preview DMG.

Project status

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

v0.3.0

Preview build — ad-hoc signed, not notarized. macOS Gatekeeper may block
this app on first launch; right-click the app and choose Open, or allow it in
System Settings → Privacy & Security. The widget extension needs a code-signed
build to be registered by macOS. This is a source-tag preview for local testing;
a Developer ID–signed and notarized build is still pending.

Attachment: CodexSatellites-0.3.0-preview-adhoc.dmg (build 26)
SHA256: 0d4914156d8a75e68e01653634d73223c1cd7bc5048da23cfa05abd108946d70

Adds a WidgetKit widget for the desktop and Notification Center.

Highlights

• New CodexSatellitesWidget widget extension, available in Small and Medium:
  • Small → 5-hour and weekly remaining gauges
  • Medium → both gauges plus reset times
• The widget works on any Mac — including Mac mini, Mac Studio, and external displays — while the notch satellites still require a built-in notched display.
• Widget presentation follows system conventions: SwiftUI Gauge, semantic foreground styles, system content margins, and containerBackground(for: .widget).
• The widget is a read-only presentation layer. The app remains the only component that reads Codex authentication and requests usage.
• Widget text is English-only.

How it works

• The app saves a snapshot after every successful fetch and after a failure that retains last-good data. The widget is intentionally passive: the app keeps the shared quota snapshot current, while WidgetKit controls when the widget is rendered again. Its provider returns one entry with .never; normal quota changes do not call WidgetCenter.reloadTimelines. No scheduled background widget refresh is used.
• On macOS 15+, App Group containers are protected and membership must be authorized by the code-signing/provisioning model. An ad-hoc build has neither a provisioning profile authorizing the registered group.* App Group nor a Developer Team ID for a team-prefixed macOS group, so the widget extension's group-container read is denied by TCC.
• For ad-hoc preview builds the app therefore hands the snapshot off through the widget extension's own sandbox container. This is a development compatibility workaround, not the production sharing architecture.
• WidgetSnapshotTransport keeps the two paths explicit: widgetContainer today, appGroup once a Developer ID build provisions the App Group. In widgetContainer mode the App Group container is never touched; only an appGroup build falls back to the legacy preview snapshot.

Signing

• The widget extension is sandboxed, which WidgetKit requires; the containing app stays non-sandboxed because it must read ~/.codex/auth.json.
• ./script/build_and_run.sh and ./script/release.sh preview ad-hoc sign the appex first (own identifier + entitlements) and the app second.
• This preview DMG is ad-hoc signed and unnotarized. It is for local validation only and must not be published as a formal release.

Requirements

• macOS 15+
• MacBook with a hardware notch (notch satellites only; the widget works on any Mac)
• Existing local Codex CLI authentication

Privacy

CodexSatellites does not implement its own login or OAuth flow. It reads the existing local Codex authentication state and does not refresh tokens or write Codex auth files. The widget never reads Codex auth and never calls the usage endpoint.

Known limitations

• Codex usage currently depends on an undocumented ChatGPT usage endpoint.
• Full-screen Space behavior may vary.
• No automatic updater yet.
• The widget requires a code-signed build to be registered by macOS.
• The widget extension is sandboxed and reads only the snapshot the app publishes.
• During local ad-hoc upgrade testing, an already-running widget extension could continue using the previous widget code until macOS recycled the extension process. There is no public API that guarantees recycling. Developer ID upgrade behaviour has not yet been verified.

Integrity

The release includes the SHA-256 value above for verifying the preview DMG.

Project status

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