openai / openai/codex

Feature request: version marker (or stability guarantee) for the `codex exec --json` event schema — 0.144 "canonical turn items" silently broke downstream parsers

Open
#41,216 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

CLI enhancement exec
Dominant language
Rust
Stars
125k
Forks
19.4k
PR merge metrics
PR metrics pending

Description

Context: I maintain Agent Console, a desktop console that runs Codex and Claude Code side by side. Multi-agent "room" sessions consume codex exec --json (thread.started / item.completed / turn.completed).

What happened: 0.144 restructured the event schema ("canonical turn items"). The change itself is fine — but there's no version marker in the stream and no schema changelog, so downstream parsers fail silently on upgrade instead of failing fast. Anyone consuming exec --json (CI integrations, wrappers, dashboards) has the same problem on every schema change.

Ask: one of:

  1. a schema_version field in the first event of the stream (cheapest, unblocks everyone), or
  2. --json-schema-version N flag with N frozen per major, or
  3. if codex app-server is the intended stable surface for integrators, saying so explicitly in the docs would let us migrate deliberately instead of chasing TUI/CLI churn.

Happy to beta-test whichever direction you pick against a real multi-engine integration.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by tracing the codex exec --json event stream, including thread.started, item.completed, and turn.completed, and compare it with the codex app-server surface. Review the repository documentation for the supported integration contract. Done means one compatibility strategy is selected, documented, and usable by downstream parsers.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
api, cli
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.