How to enable JSON output in Codex

A coding task can produce tool results and progress messages before its final reply. In Codex, JSON output exposes those events as a stream that another program can parse.

Each nonblank stdout line is one JSON object. The top-level type field identifies the event, while item.* records can carry agent messages, reasoning, command executions, file changes, MCP tool calls, web searches, and plan updates. A completed turn and a failed turn have different event types, so valid JSON alone does not establish success.

JSON Lines describes the event stream, while the agent's reply can still be ordinary text. A fixed JSON structure for the reply itself requires an output schema. The CLI needs a working model provider and a Git repository; Bash or zsh handles stream redirection, and jq reads the saved events.

1. Enable JSON output for a task with separate diagnostics.

   $ codex exec --json 'Explain the difference between git fetch and git pull in one sentence.' > codex-run.jsonl 2> codex-run.log

   --json writes one JSON object per stdout line to codex-run.jsonl. Stderr diagnostics go to codex-run.log; combining them with stdout using 2>&1 can break JSON parsing. Without the redirections, the events and diagnostics appear in the terminal. JSON output needs no extra permissions; codex exec uses a read-only sandbox by default. If the run reports a repository trust error, the launch directory needs attention.
   Related: How to fix the Codex trusted-directory error
   Related: How to skip Codex git repository checks

2. Extract the completed agent reply from the saved stream.

   $ jq -r 'select(.type == "item.completed" and .item.type == "agent_message") | .item.text' codex-run.jsonl

   The filter prints the text from completed agent messages. Other events, such as command executions, remain in the original JSONL file. A longer task can produce several agent messages, including progress updates.

3. Confirm that the event stream ends with a completed turn.

   $ jq -r '.type' codex-run.jsonl
   thread.started
   item.completed
   turn.started
   item.completed
   turn.completed

   A successful run ends with turn.completed and has a completed agent_message containing the reply. item.completed alone describes one item, which can be a command, a message, or a notice. turn.failed reports a failed turn; a top-level error event reports an error and can precede a retry. A nonzero Codex exit status, a failed turn, or a missing completion means the result is not ready for use. Diagnostics remain in codex-run.log. Valid JSON alone does not prove that the task succeeded.
   Tool: JSON Validator