How JSON Output Mode Is Implemented in the OpenAI Codex Plugin

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 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:

# 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}