# How JSON Output Mode Is Implemented in the OpenAI Codex Plugin

> Explore the three-layer architecture of the OpenAI Codex plugin and how the --json flag enables machine-readable output via JSON.stringify serialization for sub-commands.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: internals
- Published: 2026-07-04

---

**The Codex plugin implements JSON output mode through a centralized three-layer architecture where the `--json` flag triggers `JSON.stringify` serialization in the `outputResult` function, enabling machine-readable output for all sub-commands.**

The openai/codex-plugin-cc repository provides a command-line interface that supports structured data output for automation and CI/CD pipelines. When you append the `--json` flag to any sub-command, the plugin switches from human-readable text to machine-parseable JSON output. This implementation relies on a lightweight formatting system that maintains consistency across all commands including status, review, task, and setup operations.

## The Three-Layer Architecture of JSON Output Mode

### Argument Parsing in args.mjs

In `plugins/codex/scripts/lib/args.mjs`, the `parseCommandInput` function uses `parseArgs` to register `"json"` as a Boolean option. When users invoke commands like `codex-companion.mjs status --json`, the parser sets [`options.json`](https://github.com/openai/codex-plugin-cc/blob/main/options.json) to `true`, making the flag available to all downstream handlers through the standardized options object.

### Centralized Result Formatting

The `outputResult` function defined in `plugins/codex/scripts/codex-companion.mjs` (lines 91-96) handles the actual serialization logic. When the `asJson` parameter is `true`, the function returns `JSON.stringify(value, null, 2)`, producing pretty-printed JSON with two-space indentation. If the flag is omitted, the function passes the raw string directly to standard output.

### Command-Level Integration

Each sub-command follows a consistent pattern utilizing `outputCommandResult` (lines 99-101), which forwards both the structured payload and the rendered text to the formatting layer. For example, the status handler builds a payload object via `buildStatusSnapshot`, generates human-readable output through `renderStatusPayload`, then calls `outputResult(renderStatusPayload(report, options.json), options.json)` to emit the appropriate format.

## Key Source Files and Implementation Details

The JSON output mode implementation spans four critical files according to the source code:

- **`plugins/codex/scripts/lib/args.mjs`**: Registers the `--json` boolean flag for all sub-commands via `parseCommandInput`.
- **`plugins/codex/scripts/codex-companion.mjs`**: Contains the `outputResult` and `outputCommandResult` functions that control serialization logic.
- **`plugins/codex/scripts/lib/render.mjs`**: Provides human-readable renderers for each command (status, review, task, etc.).
- **`plugins/codex/scripts/lib/state.mjs`**: Supplies the raw data structures that become the JSON payloads.

## Practical Usage Examples

To retrieve structured output from any command, append the `--json` flag:

```bash

# Get job status as JSON

node plugins/codex/scripts/codex-companion.mjs status 12345 --json

# Run code review with structured output

node plugins/codex/scripts/codex-companion.mjs review --json

# Launch background task and receive JSON description

node plugins/codex/scripts/codex-companion.mjs task --background "Fix the bug" --json

```

When the flag is present, the CLI emits pretty-printed JSON objects containing fields like `jobId`, `status`, and `result`, enabling direct integration with scripts, APIs, and test harnesses.

## Summary

- The `--json` flag is registered as a Boolean option in `lib/args.mjs` via `parseCommandInput`.
- The `outputResult` function in `codex-companion.mjs` (lines 91-96) serializes payloads using `JSON.stringify` when `asJson` is true.
- Command handlers build dual representations: structured payloads for JSON mode and formatted strings for human readability via `lib/render.mjs`.
- The architecture ensures all sub-commands (status, review, task, setup) support consistent JSON output mode through shared formatting utilities.

## Frequently Asked Questions

### How does the Codex plugin handle the `--json` flag across different commands?

The plugin registers the `--json` option globally in `lib/args.mjs` through the `parseArgs` utility. Each command handler receives the [`options.json`](https://github.com/openai/codex-plugin-cc/blob/main/options.json) boolean and passes it to the centralized `outputResult` function, ensuring uniform JSON serialization behavior across status, review, task, and setup sub-commands without requiring individual serialization logic.

### What is the difference between `outputResult` and `outputCommandResult`?

According to the source code in `codex-companion.mjs`, `outputResult` (lines 91-96) performs the actual serialization logic, checking the `asJson` flag to determine whether to return pretty-printed JSON or raw text. The `outputCommandResult` helper (lines 99-101) acts as a thin wrapper that forwards both the payload and rendered output to `outputResult`, simplifying the interface for command handlers.

### Where are the data structures for JSON payloads defined?

The raw data structures that populate JSON outputs originate in `plugins/codex/scripts/lib/state.mjs`. These structures are passed to renderer functions in `lib/render.mjs` for human-readable formatting, while the original objects are passed directly to `outputResult` when JSON mode is enabled, ensuring data consistency between formats.

### Can I pipe the JSON output to other tools?

Yes. Because the `outputResult` function uses `JSON.stringify(value, null, 2)`, the output is valid pretty-printed JSON that can be piped to utilities like `jq`, redirected to files, or consumed by CI/CD pipelines for automated processing of Codex job statuses and results.