How Job Files Are Structured in the Codex CC Plugin: JSON Schema and Data Fields

The Codex CC plugin persists every asynchronous operation as a JSON job file containing identity metadata, state timestamps, payload data, and error or result objects.

The openai/codex-plugin-cc repository implements a durable job queue system that serializes every operation to disk as a JSON job file. These files reside in the plugin workspace under the *.job.json pattern and follow a strict schema defined in plugins/codex/scripts/lib/tracked-jobs.mjs, enabling crash recovery and persistent state management without an external database.

JSON Job File Structure

A job file follows a strict schema that mirrors the internal Job type used by the runtime. The structure contains four logical sections that track the complete lifecycle of asynchronous operations such as reviews, rescues, and cancellations.

Identity Fields

Every job file begins with unique identification metadata:

• id: A UUID string that uniquely identifies the job across the system.
• type: The job category as a string—valid values include "review", "rescue", or "cancel".
• queue: An optional string specifying which broker queue manages this job.

State and Timing

The runtime constantly updates these fields to reflect the current execution status:

• status: The current state as a string—one of "queued", "running", "succeeded", "failed", or "canceled".
• created_at: An ISO-8601 timestamp recording when the job was first queued.
• started_at: An ISO-8601 timestamp (nullable) indicating when execution actually began.
• finished_at: An ISO-8601 timestamp (nullable) marking when the job reached a terminal state.

Payload and Result Data

These fields contain the actual work data and outcomes:

• payload: An object containing the input data required for the job, such as PR numbers, repository information, or user-provided options.
• result: An object (nullable) storing the successful output produced by the job, such as a review summary or rescue plan.
• error: An object (nullable) containing error details if the job fails, with the structure { message, stack, code }.

Metadata and Retry Configuration

Additional fields control execution behavior and debugging:

• attempts: An integer counting how many times the job has been started or restarted.
• max_attempts: An integer defining the upper bound of retry attempts before the job is marked as failed.
• tags: An optional array of strings for arbitrary filtering and debugging purposes.

Schema Implementation and Validation

The runtime implementation that reads and writes these files lives in plugins/codex/scripts/lib/tracked-jobs.mjs. This module exports a Job class that mirrors the JSON structure described above and handles file serialization.

The first 30 lines of tracked-jobs.mjs contain the JSON schema definition used for validation, ensuring that every *.job.json file conforms to the expected structure before the runtime processes it.

Hook configurations that reference job types are declared in [plugins/codex/hooks/hooks.json](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/hooks/hooks.json), which maps command entry points to their corresponding job types.

Job Lifecycle and State Transitions

The runtime updates the JSON job file atomically as the job progresses through its lifecycle:

1. Queueing: The CLI or a hook creates a new UUID, populates the payload, sets status to "queued", and writes the JSON file.
2. Running: The broker loads the file, updates status to "running", and records the started_at timestamp.
3. Success: Upon completion, the runtime fills the result object, sets status to "succeeded", and populates finished_at.
4. Failure: If an exception occurs, the runtime populates the error object with { message, stack, code }, sets status to "failed", and records finished_at.
5. Retry: If attempts is less than max_attempts, the broker re-queues the job; otherwise, it remains in the "failed" state.

This persistent state machine enables crash recovery, allowing the broker to resume interrupted jobs by reading the current state from disk.

Creating Job Files Programmatically

You can create job files using the Job class from tracked-jobs.mjs. The constructor automatically adds missing fields and validates the shape against the schema:

import { Job } from './plugins/codex/scripts/lib/tracked-jobs.mjs';
import { writeFile } from 'node:fs/promises';
import { v4 as uuidv4 } from 'uuid';

async function queueReviewJob(prInfo) {
  const job = new Job({
    id: uuidv4(),
    type: 'review',
    status: 'queued',
    created_at: new Date().toISOString(),
    payload: prInfo,
    max_attempts: 3,
  });

  await writeFile(`jobs/${job.id}.job.json`, JSON.stringify(job, null, 2));
}

The Job constructor initializes the attempts counter to zero, sets empty result and error fields to null, and validates that required fields are present before returning the instance.

Summary

• Job files in Codex CC use the *.job.json extension and store the complete state of asynchronous operations.
• Each file contains identity fields (id, type), state timestamps (created_at, started_at, finished_at), payload data, and result or error objects.
• The schema is defined and enforced by the Job class in plugins/codex/scripts/lib/tracked-jobs.mjs.
• The runtime uses atomic file updates to track job progression through queued, running, succeeded, failed, and canceled states.
• Retry logic is built into the file structure via attempts and max_attempts counters.

Frequently Asked Questions

What file extension do Codex CC job files use?

Codex CC job files use the .job.json extension. The runtime creates these files in the plugin workspace directory using the pattern jobs/${id}.job.json where ${id} is the job's UUID.

How does the plugin handle retries when a job fails?

The runtime inspects the attempts and max_attempts fields in the JSON job file. If attempts is less than max_attempts, the broker increments the counter and resets status to "queued". If the maximum is reached, the job remains "failed" with the error object preserved for debugging.

What data is contained in the payload field of a JSON job file?

The payload field contains the input data required to execute the specific operation. For review jobs, this includes the PR number and repository information. For rescue or cancel operations, it contains the specific identifiers and options needed to process the request.

Where is the job file schema defined in the source code?

The JSON schema and validation logic are defined in the first 30 lines of plugins/codex/scripts/lib/tracked-jobs.mjs. This file exports the Job class that handles schema validation, file I/O, and state management for all job files in the system.

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