Skip to content

v0.3.0

Pre-release
Pre-release

Choose a tag to compare

View all tags
@NTLx NTLx released this 09 Sep 10:17
· 11 commits to main since this release
v0.3.0
03e645d

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.

Assets 3
Loading