Field guide / 11 min
Stream JSONL and constrain the final result
Separate execution telemetry from the schema-checked answer your automation consumes.
With --json, codex exec emits newline-delimited JSON events to stdout. --output-schema constrains the final response with a JSON Schema, while --output-last-message writes the final message to a chosen file. These are distinct surfaces: event streaming supports progress and diagnostics; the final artifact supports a stable consumer contract. Neither proves the underlying code change is correct.
Verified terminal sequence
- $
codex exec --json "Audit the current diff" | jq -c . - $
codex exec --json --output-schema schema.json --output-last-message final.txt "Return the audit result"
Working principles
JSONL is a stream
Parse one complete line at a time. Do not treat stdout as one JSON document or assume every event has the same shape.
Schema controls shape
A valid final object can still contain a wrong conclusion. Apply domain rules and verify cited tests or files independently.
Keep channels clean
Reserve machine output for the parser, send operator diagnostics elsewhere, and never splice terminal color or debug prose into JSONL.
Field procedure
- 01
Design the consumer object
Define the smallest final object needed by the next system, including explicit success, blocked, and evidence fields.
- 02
Run with separate outputs
Stream --json to the event consumer and use --output-last-message only when a distinct final artifact is useful.
- 03
Parse incrementally
Reject malformed lines, cap retained events, and preserve the event type and stable identifiers needed for observability.
- 04
Validate twice
Validate the final response against the schema, then validate repository state, file paths, counts, and test evidence against reality.
- 05
Fail before side effects
Do not publish, merge, or notify from partial output. Require a completed process and a valid final result.
PASS / FAIL
Acceptance checklist
- Every stdout line is parsed independently.
- The schema is version-controlled.
- Refusal, timeout, and malformed output have explicit states.
- Semantic evidence is independently checked.
- Secrets are redacted before event retention.
WATCH / REJECT
Failure patterns
- Using JSON.parse on the entire JSONL stream.
- Equating schema validity with task success.
- Triggering writes from an intermediate event.