# How the Codex Plugin Handles Structured Output Parsing from Codex Models

> Learn how the Codex plugin transforms Codex model responses into type-safe JavaScript objects by parsing JSON and validating against schemas with ajv.

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

---

**The Codex plugin converts raw Codex model responses into type-safe JavaScript objects by extracting JSON blocks, validating them against predefined schemas using ajv, and wrapping valid results in a `CodexResult` class.**

The `openai/codex-plugin-cc` repository implements a robust pipeline for structured output parsing that transforms free-form text from Codex models into validated, schema-compliant data. This approach ensures downstream automation receives predictable, programmatically accessible objects rather than unstructured text. Understanding this parsing mechanism is essential for developers extending the plugin or debugging model integration issues.

## Schema-Driven Prompt Architecture

The foundation of reliable structured output parsing begins with explicit schema definitions. The plugin stores JSON schemas in `plugins/codex/schemas/`, such as [`review-output.schema.json`](https://github.com/openai/codex-plugin-cc/blob/main/review-output.schema.json), which define the exact structure expected from model responses. These schemas enforce type safety and field requirements before any parsing occurs.

When invoking commands like `codex result` or `codex review`, the plugin embeds schema requirements directly into prompts sent to the model. This instructs Codex to emit responses conforming to the expected JSON structure, minimizing parsing errors at the source.

## JSON Extraction and Parsing Pipeline

Raw model responses often contain explanatory text surrounding the actual JSON payload. In `plugins/codex/scripts/lib/codex.mjs`, the `extractJSON` function handles this noise using a regular expression to isolate the first JSON block:

```javascript
function extractJSON(text) {
  const match = text.match(/\{[\s\S]*\}/);
  if (!match) throw new Error('No JSON block found');
  return match[0];
}

```

The `runCodexCommand` function orchestrates the full pipeline. It captures the raw string from the model, invokes `extractJSON` to isolate the JSON string, and parses it using `JSON.parse`:

```javascript
export async function runCodexCommand(command, payload) {
  const raw = await invokeModel(command, payload);
  const jsonStr = extractJSON(raw);
  const data = JSON.parse(jsonStr);
  // Validation step follows
  return new CodexResult(data);
}

```

## Schema Validation and Error Recovery

After parsing, the plugin validates the resulting object against the appropriate JSON schema using the **ajv** validator. The validation logic compiles the schema for the specific command and throws descriptive errors when constraints are violated:

```javascript
const validate = ajv.compile(getSchemaFor(command));
if (!validate(data)) {
  throw new Error('Schema validation failed: ' + ajv.errorsText(validate.errors));
}

```

When validation or parsing fails, the plugin activates error recovery mechanisms. The [`plugins/codex/agents/codex-rescue.md`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/agents/codex-rescue.md) skill contains logic to re-prompt the model with explicit correction instructions, requesting a properly formatted JSON payload. This retry loop ensures robustness against model hallucinations or formatting errors.

## Typed Result Propagation

Upon successful validation, the plugin wraps the parsed data in a `CodexResult` class defined in `plugins/codex/scripts/lib/codex.mjs`. This class provides typed accessors for schema-defined fields, allowing downstream commands to consume structured data safely without repeated validation checks.

For example, consuming a review result:

```javascript
import { runCodexCommand } from './plugins/codex/scripts/lib/codex.mjs';

async function getResult(prompt) {
  const result = await runCodexCommand('result', { prompt });
  // Returns a CodexResult instance with validated fields
  return result;
}

getResult('Summarize the changes in this PR')
  .then(res => {
    console.log('Summary:', res.summary);
    console.log('Files changed:', res.files);
  })
  .catch(err => {
    console.error('Failed to parse structured output:', err);
  });

```

## Key Files and Components

The structured output parsing system spans several critical files in the repository:

- **`plugins/codex/scripts/lib/codex.mjs`** – Core logic containing `extractJSON`, `runCodexCommand`, and the `CodexResult` class implementation.
- **[`plugins/codex/schemas/review-output.schema.json`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/schemas/review-output.schema.json)** – JSON Schema defining the expected structure for review command outputs.
- **[`plugins/codex/skills/codex-result-handling/SKILL.md`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/skills/codex-result-handling/SKILL.md)** – Documentation detailing how the plugin expects and processes structured responses.
- **[`plugins/codex/agents/codex-rescue.md`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/agents/codex-rescue.md)** – Rescue agent configuration for handling parsing failures through model retry loops.

## Summary

- The **Codex plugin** leverages schema-driven prompts to encourage valid JSON output from models.
- The **`extractJSON`** function uses regex pattern matching to isolate JSON blocks from surrounding text in `plugins/codex/scripts/lib/codex.mjs`.
- **ajv** validates parsed objects against command-specific schemas stored in `plugins/codex/schemas/`.
- The **`CodexResult`** class provides typed wrappers for validated data, ensuring type-safe downstream consumption.
- **Error recovery** via [`codex-rescue.md`](https://github.com/openai/codex-plugin-cc/blob/main/codex-rescue.md) allows automatic retry when parsing or validation fails.

## Frequently Asked Questions

### How does the plugin handle malformed JSON responses?

When the model returns malformed JSON, the `extractJSON` function throws a `No JSON block found` error if it cannot locate a valid JSON pattern. If `JSON.parse` fails or **ajv** validation rejects the structure, the plugin logs the problematic output and may invoke the rescue agent defined in [`plugins/codex/agents/codex-rescue.md`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/agents/codex-rescue.md) to request a corrected payload.

### What validation library does the Codex plugin use?

The plugin uses **ajv** (Another JSON Schema Validator) to compile and validate parsed JSON against predefined schemas. This ensures all structured outputs conform to type constraints and required fields defined in files like [`plugins/codex/schemas/review-output.schema.json`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/schemas/review-output.schema.json).

### Where are the JSON schemas defined in the repository?

JSON schemas reside in the `plugins/codex/schemas/` directory. The [`review-output.schema.json`](https://github.com/openai/codex-plugin-cc/blob/main/review-output.schema.json) file defines the structure for review outputs, while additional schemas exist for other command types. These schemas are referenced dynamically based on the command being executed.

### How does error recovery work when parsing fails?

Error recovery activates when validation or parsing exceptions occur. The plugin logs the raw response and can trigger a retry mechanism through the rescue agent skill. This agent re-prompts the Codex model with explicit instructions to fix formatting errors and return valid JSON, creating a robust feedback loop for handling edge cases.