codex-exec-json

This is a tiny wrapper around codex exec. It runs a one-shot, non-interactive Codex task, forces a JSON-shaped final answer, writes that JSON to a file, prints the file path, and exits. It is meant for agents and automations that want a predictable machine-readable output and no long-lived session.

Install / npx

npx -y codex-exec-json "summarize this repo"

Usage

codex-exec-json [options] <prompt...>

Options are --schema <json> for an inline JSON schema string, --schema-file <path> to load a schema from disk, --out <path> to control the output file path (default is /tmp/.codex-exec.<uuid>.json), --model <name> to select a model, --reasoning <level> to set reasoning effort, --codex-bin <path> to point at a different Codex binary, --yolo to bypass approvals and sandboxing, --keep-trace to keep Codex session files, --models to print available models, --models-json to print models as JSON, and --help to show usage.

Pass through args to Codex after --:

codex-exec-json -- --add-dir /tmp "update the README"

For LLMs and agents

The point is to return a JSON file and exit. Treat stdout as the file path and read the JSON from disk.

npx -y codex-exec-json --schema '{"type":"object","properties":{"summary":{"type":"string"},"next":{"type":"array","items":{"type":"string"}}},"required":["summary","next"]}' "Summarize and list next steps"

Example flow:

OUT=$(npx -y codex-exec-json "Describe the repo in JSON")
cat "$OUT"

By default the tool deletes any new Codex session files created during the run. Use --keep-trace if you want to keep those files.

Models and reasoning levels

To list available models and their supported reasoning levels with descriptions, run:

npx -y codex-exec-json --models

For JSON output:

npx -y codex-exec-json --models-json

This uses a built-in preset list that matches Codex’s own defaults, no API calls required.

Default schema

If no schema is provided, this default is used, so you always get a predictable JSON object:

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "ok": { "type": "boolean" },
    "result": { "type": "string" },
    "error": { "type": "string" }
  },
  "required": ["ok", "result"]
}

Skill

If you use the Codex skills format, a ready-to-pull skill is included at skills/codex-exec-json/SKILL.md.