Skip to content

codex-compatibility.md

Latest commit

 

History

History
66 lines (49 loc) · 2.64 KB

codex-compatibility.md

File metadata and controls

66 lines (49 loc) · 2.64 KB
Raw

Codex Compatibility

Current Evidence

This release-preparation run did not launch real Codex and did not use a real account, quota, or authentication file. Current tests use a synthetic app-server, temporary directories, and synthetic protocol frames, so this document does not invent a supported Codex version range.

A “last locally verified” entry records the environment and result of one test. It is not a support guarantee. There is currently no real Codex local verification record to publish.

Required Commands and Protocol

The code has two process entry points:

  • --version: reads one printable line in a bounded two-second window, with a 128-byte maximum; the result is diagnostic only.
  • app-server --listen stdio://: starts the long-running stdio sidecar.

The current protocol depends on:

  • initialize, whose returned codexHome must match the selected CODEX_HOME;
  • initialized;
  • account/read with refreshToken: false;
  • account/rateLimits/read;
  • account/updated;
  • account/rateLimits/updated.

If a method is missing, returns an error, has an incompatible response shape, times out, or closes the connection, the app reports unavailability or retries. It never treats an old-account response as current live data.

Explicit Executable Trust

The app does not automatically search its bundle, inherited PATH, Homebrew, or common installation directories. The user must explicitly choose a local file in Settings and confirm its trust receipt.

The trust receipt binds the canonical absolute path, device, inode, size, modification/status-change times, and SHA-256. Every --version and app-server launch reopens and validates the file under the same restricted environment. Any file change requires confirmation again.

This mechanism does not verify a developer signature, publisher identity, or official origin. The final posix_spawn launches by path, leaving a residual same-user path-replacement race. The selected Codex runs as the current user, can read the selected CODEX_HOME, may access the network, and may use allowed proxy and certificate settings.

Recording Future Compatibility

A real compatibility record may be added only with explicit user participation and without collecting credentials. Record:

  • the version text reported by Codex;
  • the macOS major version and chip architecture;
  • the verification date and source commit;
  • whether the commands, methods, and notifications above passed;
  • known failures and whether the app degraded safely.

Never record an account ID, quota, absolute CODEX_HOME path, host name, or authentication-file content. One passing result cannot imply support for untested versions.