JSON Events & Structured Output

Start with the one idea that makes everything else click: codex exec deliberately splits its output into two channels, and --json swaps what flows down one of them.

When you run codex exec "…" non-interactively, Codex:

• streams its progress (what it's reading, running, thinking) to stderr, and
• prints only the final agent message to stdout.

That split is what makes it pipe-friendly. RESULT="$(codex exec 'summarize the repo')" captures just the answer, because the noisy progress went to stderr and never landed in your variable. The default stdout is prose for a human — perfect to read, useless to parse reliably.

--json changes the contract on stdout. Instead of one final prose message, stdout becomes a JSONL stream: one JSON object per line, one per event, as the run unfolds. Now stdout is structured data for a machine. You're no longer scraping text — you're consuming an event log you can filter, count, and route.

Think of it as two different deliverables from the same run:

A note on the flag name: --json and --experimental-json are listed as aliases in the CLI reference. The naming is still settling, so confirm against codex exec --help on your installed version rather than assuming one is canonical.

With --json, every line on stdout is one event describing something that just happened. Read top to bottom, the stream is a timeline of the whole run. There are two layers: a handful of lifecycle events that bracket the run and its turns, and item events that wrap the concrete things Codex does inside a turn (covered in the next section).

The lifecycle events you'll see:

Two of these deserve special attention up front:

• thread.started carries the thread_id. Stash it (e.g. to an env var or a file) and you can later run codex exec resume <SESSION_ID> "<follow-up>" to continue exactly where you left off — the backbone of multi-step automations.
• turn.failed and error are your failure signals in the stream. The exact codex exec exit-code table isn't fully documented, so the robust rule is: treat a non-zero exit as failure, and additionally watch for turn.failed/error events if you want to react to why it failed, not just that it did.

A turn is one model round-trip; a complex task is many turns. So a single run typically looks like thread.started → (turn.started → many item.* → turn.completed) repeated → end. That nesting is the structure your parser walks.

Each turn.completed event carries a usage object. These four fields are how you turn an agent run into a line on a dashboard or a cost report:

Why each matters in practice:

• cached_input_tokens is the lever behind prompt caching. A high cache ratio means you're re-sending the same context (your AGENTS.md, repo files, instructions) cheaply across turns. If it's near zero on a long multi-turn run, your context is churning and your bill is higher than it needs to be.
• reasoning_output_tokens is its own bucket because reasoning effort is configurable (model_reasoning_effort). On a high/xhigh run this can dwarf the visible output — which is exactly the cost you're trading for better answers. Logging it separately lets you see what reasoning effort is actually costing you.
• Summing input_tokens + output_tokens across every turn.completed gives you the run's total token footprint — the raw number you multiply by the live rate card to estimate cost.

Because usage arrives per turn, a multi-turn task emits several turn.completed events; add them up to get the run total rather than reading only the last one.

Exact prices and the credit rate card change often, so don't hard-code a cost-per-token. Capture the token counts from the stream and apply the current rates from the live pricing page.

Inside a turn, the interesting content rides on items — wrapped by item.started, item.updated, and item.completed events. The item.type field tells you what kind of thing it is, so you can parse only what you care about and ignore the rest.

The item types you'll encounter:

This taxonomy is what makes the stream genuinely useful. A few patterns fall straight out of it:

• Extract the final answer. Filter for a completed agent_message item and read its text — the structured way to get the same string default stdout would have printed:

  bash Copy

  codex exec --json "summarize the changes" \
    | jq -r 'select(.type=="item.completed" and .item.type=="agent_message") | .item.text'

• Audit every command it ran. Collect each command_execution item to build a log of exactly what touched your machine — gold for security review and CI audit trails.

• Show a live activity feed. Map file_change, command_execution, and web_search items into UI rows for a dashboard that shows what the agent is doing right now.

• Track progress. The plan/todo updates let you render a checklist that fills in as the agent works.

The jq filters above are an applied pattern, not a verbatim doc quote — the event and item shapes (the type field, item.type, the fields per item) are the documented contract; the exact filter you write on top is yours.

The event stream tells you what Codex did. Often you also need the result itself in a guaranteed shape — not prose you have to coax a value out of. That's what --output-schema is for. It's the headless equivalent of "structured outputs": you hand Codex a JSON Schema file, and it forces the final response to conform to that schema.

codex exec --output-schema ./schema.json \
  -o ./result.json \
  "Audit this repo's dependencies and report status"

Two flags working together:

• --output-schema <path> points at a JSON Schema file. The final response must validate against it — so a downstream step can JSON.parse the result and trust the fields exist, instead of regexing prose.
• -o <path> (alias of --output-last-message) persists the final message to a file in addition to printing it to stdout. Pair the two and you get a schema-valid result.json on disk, ready for the next CI step.

A minimal schema looks like this:

{
  "type": "object",
  "properties": {
    "summary": { "type": "string" },
    "status": { "type": "string", "enum": ["ok", "action_required"] },
    "issues": { "type": "array", "items": { "type": "string" } }
  },
  "required": ["summary", "status"],
  "additionalProperties": false
}

Now a CI job can gate on status == "action_required" with total confidence the field is present. This is the difference between hoping the model said "ok" somewhere in a paragraph and programming against a contract.

You can combine --output-schema with --json too: the event stream gives you the full audit trail of the run, while the schema-validated final message gives you the clean result. Stream for observability; schema for the payload.

Everything above has a programmatic twin in the Codex SDK, so you don't have to shell out to the CLI from your application. The SDK wraps the same engine — in fact the TypeScript SDK literally spawns the codex CLI and exchanges these JSONL events over stdio — so the concepts map one-to-one.

Structured output is exposed via the outputSchema option on run():

import { Codex } from "@openai/codex-sdk";

const schema = {
  type: "object",
  properties: {
    summary: { type: "string" },
    status: { type: "string", enum: ["ok", "action_required"] },
  },
  required: ["summary", "status"],
  additionalProperties: false,
} as const;

const codex = new Codex();
const thread = codex.startThread();
const turn = await thread.run("Summarize repository status", { outputSchema: schema });
console.log(turn.finalResponse); // JSON conforming to the schema

The result lands on turn.finalResponse — the SDK's equivalent of the schema-validated stdout message. The Python SDK mirrors this shape: thread.run("…") returns a result whose final_response holds the answer.

To react to the stream of events (not just the final answer), the TS SDK offers thread.runStreamed(input), which yields an async generator of stream events — including "item.completed" (carrying the item) and "turn.completed" (carrying usage). These are the same event and item types you saw on the CLI's --json stream, just delivered as objects instead of JSONL lines. And thread.id is the SDK's thread_id — persist it and call codex.resumeThread(threadId) to continue later.

The payoff: whether you drive Codex from a shell script (--json + --output-schema) or from application code (runStreamed + outputSchema), you're consuming one contract — a typed event stream plus a schema-validated result.

Step back and see the whole pattern. A reliable automation around Codex has two halves, and you've now met both:

1. Observe the run via the --json event stream — capture thread_id, tally usage for cost, audit command_execution and file_change items, and surface progress to a dashboard.
2. Trust the result via --output-schema (or SDK outputSchema) — get a final payload your next step can parse without guessing.

That combination is what lets you wire Codex into things that can't tolerate free text:

• CI gates — fail the build when a schema field says so; attach the run's usage totals and command log as artifacts.
• Dashboards — render a live feed of items as they complete, plus per-run token spend.
• Downstream steps — feed the schema-valid JSON straight into the next job (open a PR, post a Slack message, update a ticket) with no scraping.
• Multi-step jobs — persist thread_id and resume to continue a conversation across pipeline stages.

The through-line of this whole module: default output is for humans; --json and --output-schema are for programs. The moment you stop reading Codex's prose and start consuming its events and validated results, you've crossed from running a tool by hand to building automation on top of an agent.

A pipe-and-gate skeleton that ties it together:

# Capture the thread id from the stream, log usage, and persist a schema-valid result
codex exec --json --output-schema ./schema.json -o ./result.json \
  "Run the test suite; report status and failing tests" \
  | tee run.jsonl \
  | jq -rc 'select(.type=="thread.started") | .thread_id' > thread.id

jq -r .status ./result.json   # -> "ok" or "action_required", guaranteed present