Run a Codex Readiness Check From a Script

A small checked harness makes unattended output useful while keeping reported values separate from actual command evidence.

Rick Hightower

Cover image for “Run a Codex Readiness Check From a Script” by Rick Hightower

Save structured JSON, retain the command event log, and check the report before accepting it.

A script needs a result it can check, and a human reviewer still needs the evidence behind that result.

In this article: Create the complete report harness and schema, commit their preparation files, and run the child. Inspect its structured result, command evidence, permissions, and independent seven-test check.

Tested on Codex CLI 0.169.0, macOS, Node.js 22.22.1, and Git 2.47.1.

codex exec runs through the CLI; scheduled-task management lives in desktop or web. Native app Terminal and Scheduled steps are not run.

Yesterday you received a GitHub review, completed a bounded Cloud conversation, and independently verified the unchanged original project with seven tests.

If the previous Codex conversation is still open, enter /quit at its idle composer. Start the terminal command from your ticket-triage directory.

Start here

codex

From the original ticket-triage checkout, save a report script, validate its five-field result, and finish with a clean seven-test project.

Starting fresh or fell behind? Run git switch -C main codex/day-15. This replaces your main with the end of Day 15; to keep your own work, run git branch my-backup first.

Noninteractive means finishing without conversational follow-up. The harness, a script that launches and checks another program, starts a child Codex from your interactive parent session.

Verify the starting project

If prompted, confirm Ticket Triage and choose Trust and continue.

Check: Enter /status, the session-settings command, and check the original directory, AGENTS.md, and Workspace (Ask for approval). Ask for approval asks when an action needs approval under its rules.

From the composer, Codex's input box, run the baseline. The leading ! runs your shell command:

!git status --short && npm test

git status --short lists changed or untracked files; clean status prints no entries. && continues after success, and npm test runs the tests.

Check: Expect seven passes in the original checkout, not the separate eight-test branch.

Create the exact report files

JSON structures data; JSON Schema defines allowed fields and types. Require head for the commit, whole-number tests_passed, true/false clean and ready, and text reason, with no extra fields. git rev-parse HEAD prints the full commit identifier.

codex exec runs a task without the interactive interface. --sandbox workspace-write limits access while permitting workspace edits; the prompt requests none. --output-schema selects the schema, -o saves the final response, and --json emits JSONL, one JSON event per line, saved separately.

Standard I/O, or stdio, means input, output, and error streams. Save output (stdout) in events.jsonl and errors (stderr) in run.stderr.log. Exit status zero means successful process completion; assertions check content.

Paste the whole command once. mkdir -p creates the folder, printf writes lines, and > writes files. Preserve the quoted format-string line breaks:

!mkdir -p automation && printf '%s
' '{"type":"object","properties":{"head":{"type":"string"},"tests_passed":{"type":"integer"},"clean":{"type":"boolean"},"ready":{"type":"boolean"},"reason":{"type":"string"}},"required":["head","tests_passed","clean","ready","reason"],"additionalProperties":false}' > automation/report.schema.json && printf '%s
' 'import assert from "node:assert/strict"' 'import { spawnSync, execFileSync } from "node:child_process"' 'import { readFileSync, writeFileSync } from "node:fs"' '' 'const binary = process.env.CODEX_BIN || "codex"' 'const prompt = "Read AGENTS.md and inspect git status --short and git rev-parse HEAD. Run npm test. Do not edit, commit, push, or publish. Return the current head, count of passing tests, whether status is clean, whether this checkout is ready, and a short reason matching the schema."' 'const run = spawnSync(binary, ["exec", "--sandbox", "workspace-write", "--json", "--output-schema", "automation/report.schema.json", "-o", "automation/report.json", prompt], { encoding: "utf8" })' 'writeFileSync("automation/events.jsonl", run.stdout || "")' 'writeFileSync("automation/run.stderr.log", run.stderr || "")' 'if (run.error) throw run.error' 'assert.equal(run.status, 0, "Codex process must exit successfully; inspect the logs")' 'const report = JSON.parse(readFileSync("automation/report.json", "utf8"))' 'assert.deepEqual(Object.keys(report).sort(), ["clean", "head", "ready", "reason", "tests_passed"])' 'const head = execFileSync("git", ["rev-parse", "HEAD"], { encoding: "utf8" }).trim()' 'assert.equal(report.head, head)' 'assert.equal(report.tests_passed, 7)' 'assert.equal(report.clean, true)' 'assert.equal(report.ready, true)' 'assert.equal(typeof report.reason, "string")' 'assert.ok(report.reason.length > 0)' 'assert.equal(execFileSync("git", ["status", "--short"], { encoding: "utf8" }), "")' 'console.log(JSON.stringify(report, null, 2))' 'console.log("Validated report for " + head)' > automation/report.mjs && printf '%s
' automation/report.json automation/events.jsonl automation/run.stderr.log > .gitignore

Only three preparation files are created. .gitignore excludes generated outputs from status and commits. The complete schema is:

{"type":"object","properties":{"head":{"type":"string"},"tests_passed":{"type":"integer"},"clean":{"type":"boolean"},"ready":{"type":"boolean"},"reason":{"type":"string"}},"required":["head","tests_passed","clean","ready","reason"],"additionalProperties":false}

The generated harness uses Node's built-in modules. spawnSync waits for Codex; execFileSync checks Git independently. The optional environment variable CODEX_BIN selects the executable, defaulting to codex; utf8 captures text. Do not recreate it:

import assert from "node:assert/strict"
import { spawnSync, execFileSync } from "node:child_process"
import { readFileSync, writeFileSync } from "node:fs"

const binary = process.env.CODEX_BIN || "codex" // ①
const prompt = "Read AGENTS.md and inspect git status --short and git rev-parse HEAD. Run npm test. Do not edit, commit, push, or publish. Return the current head, count of passing tests, whether status is clean, whether this checkout is ready, and a short reason matching the schema."
const run = spawnSync(binary, ["exec", "--sandbox", "workspace-write", "--json", "--output-schema", "automation/report.schema.json", "-o", "automation/report.json", prompt], { encoding: "utf8" }) // ②
writeFileSync("automation/events.jsonl", run.stdout || "") // ③
writeFileSync("automation/run.stderr.log", run.stderr || "")
if (run.error) throw run.error
assert.equal(run.status, 0, "Codex process must exit successfully; inspect the logs") // ④
const report = JSON.parse(readFileSync("automation/report.json", "utf8")) // ⑤
assert.deepEqual(Object.keys(report).sort(), ["clean", "head", "ready", "reason", "tests_passed"])
const head = execFileSync("git", ["rev-parse", "HEAD"], { encoding: "utf8" }).trim() // ⑥
assert.equal(report.head, head)
assert.equal(report.tests_passed, 7)
assert.equal(report.clean, true)
assert.equal(report.ready, true)
assert.equal(typeof report.reason, "string")
assert.ok(report.reason.length > 0)
assert.equal(execFileSync("git", ["status", "--short"], { encoding: "utf8" }), "") // ⑦
console.log(JSON.stringify(report, null, 2))
console.log("Validated report for " + head)

① The executable comes from CODEX_BIN when supplied, otherwise from the ordinary codex command.

② The child receives the tested workspace sandbox, JSON event stream, response schema, output file, and bounded prompt.

③ The harness saves the event output and error output separately so the final report does not replace command evidence.

④ A child launch error or unsuccessful process exit stops the harness before it reads a potentially older report.

⑤ JSON parsing and field assertions check the report shape and expected values. The reported test count still needs the command evidence in the event log.

⑥ An independent Git command supplies the current commit, so a report for another commit fails the comparison.

⑦ An independent Git status check requires no changed or untracked file entries; the generated outputs remain ignored.

Note: The full extracted listing at code/codex/part-16-without-you/listings/01-readiness-report.mjs (requires repository access) contains the tested harness without the callout comments.

Check: Compare every assertion and these three ignored output paths:

automation/report.json
automation/events.jsonl
automation/run.stderr.log

Inspect and save the harness

Read with cat; node --check checks syntax without running the report:

!cat automation/report.schema.json automation/report.mjs .gitignore && node --check automation/report.mjs && git status --short && npm test

Check: Expect only the new preparation files and seven passing tests. Save them before reporting readiness, so the child starts from a clean commit. Send the exact bounded request:

Commit only .gitignore, automation/report.schema.json, and automation/report.mjs with message "chore: add structured local readiness report". Do not run the report yet. Do not push or change any other file.

At the approval for writing Git's protected index, its staging metadata, check the three-file scope and choose Yes, proceed once.

Check: Expect the commit, clean status, and seven passes, with no source or test changes and no push.

Run and inspect the result

The child’s verified settings are approval_policy never, workspace-write, and network access false. Parent Ask is not inherited; expect no unattended approval dialog.

Run the harness with Node:

!node automation/report.mjs

Check: Wait for the printed JSON and Validated report for followed by your commit identifier.

Expect this five-field shape; head must contain your own current commit identifier:

{"head":"22293af48de1ddc2f7b4a0e798f4982add672a74","tests_passed":7,"clean":true,"ready":true,"reason":"Git status is clean and npm test passed all 7 tests. Ticket Triage: refund first; tests checked."}

Inspect actual test output in the event log; JSON alone does not prove execution. Check independently:

!cat automation/report.json && git status --short && npm test

Check: Expect the five-field report, no status entries, and seven passes. Keep the generated files ignored, and preserve the script/schema commit. Enter /quit when finished.

The harness saves evidence and validates the report before acceptance.

The desktop path

Not run: app Terminal steps. In the original Local project select New tab > Terminal. Check its working directory, then run the same commands without the leading !.

Check: Inspect automation/report.json, its event log, clean status, and seven tests. This uses CLI inside the app, without native schema controls or scheduling.

What you proved

  • The exact harness and schema are committed before the report runs.
  • The child produces a five-field result that passes the script's assertions.
  • Command evidence and an independent seven-test check support the clean project result.

You can stop here. Going deeper explains why this works and where it breaks.

Going deeper

Read this section to inspect event evidence, choose unattended permissions, or design a separate scheduled or CI workflow.

Check evidence beyond the report's shape

Report, event stream, and independent commands answer different questions.

Process success, report validation, and command evidence need separate checks.

Read the test-command output as well as the final report’s fields.

--json emits events; -o, also called --output-last-message, saves the final answer. The child stream included instruction reads, Git checks, and seven tests with exit zero. The harness checks Git independently; its test-count assertion checks the reported number, without parsing JSONL. Schema validity does not establish truth. Structured output

The seven-test assertion applies to the original checkout, not the eight-test branch. Clean Git status excludes ignored outputs; it does not check every filesystem byte.

Optional evidence inspection, not run: match existing events.jsonl command output, exit code, totals, and commit to report.json. Reset: close files, preserve committed inputs and ignored outputs, and check clean seven-test status with parent Ask for approval.

Choose child permissions before launching

The child’s unattended policy differs from parent Ask.

Noninteractive runs default to read-only; this recipe requests workspace-write. A no-edit prompt leaves that writable scope intact. Its child used policy never with network access false; --approve-for-me is separate automatic review. Stop on launch errors or unsuccessful exits before consuming an old report. Permissions

Optional permission audit, not run: inspect permissions without changing configuration or rerunning the child. Reset: close views, preserve files and settings, and check the clean seven-test original with parent Ask.

Make trust and persistence intentional

Parent, child, and scheduled jobs need distinct permission setup.

The successful child does not establish a scheduler’s credentials or boundary.

Trusted projects load configuration and MCP servers, which can execute outside the sandbox. --trust saves project trust; the interactive step already established it here. --ephemeral avoids session rollout persistence without undoing trust. codex exec resume continues a thread; --last selects the current directory's latest session. Neither alternative was exercised. CLI reference

Optional persistence inspection, not run: choose independent reporting or continuing context without launching either. Reset: preserve the invocation and files, close views, and check the original clean seven-test project with parent Ask.

Scheduling and integrations require separate setup

The CLI harness does not establish Scheduled, SDK, or CI setup.

Not run: scheduled tasks. Scheduled exists in desktop and web, not CLI or the IDE extension. Desktop tasks need the awake host, running app, and project. Web tasks do not inherit local folders. Scheduler defaults normally use approval policy never when organization policy permits; managed requirements can differ. Scheduled

Optional scheduling exercise, not run: prepare a no-edit readiness task for the project in an isolated worktree. Inspect its prompt and schedule in Scheduled; use Run now only if offered, then inspect actual commands. Reset: pause it, confirm the paused state, preserve branches and script, and check the original clean seven-test project with parent Ask.

Not run: SDK and CI integrations. TypeScript and Python SDKs support local threads; Python controls app-server with a pinned runtime. openai/codex-action@v1 installs CLI and uses an API-key Responses proxy. Neither shares this script's authentication setup automatically. Limit runner permissions, trust inputs intentionally, and authorize publication separately. SDK, Action

Optional integration design, not run: record runtime, credentials, sandbox, and output needs without installing packages or adding workflows or secrets. Reset: close docs, preserve repository and account settings, and check the original clean seven-test project with parent Ask.

Illustration: a developer reads a report beside its command evidence.

Keep the structured result attached to the events that support it.

Do this today

Everyone

  • Save the harness and schema, run the child, and inspect both the report and its command evidence.
  • Independently check seven passes and clean status. Keep outputs ignored and parent and child permissions distinct.

If you read Going deeper

  • Inspect event or permission evidence without rerunning. Reset by preserving files and checking the original Local baseline.
  • Pause experimental schedules and leave integration designs uninstalled. Reset by checking seven passes, clean status, and parent Ask for approval.

Coming up in Part 17: Casual, pro, elite, assembling the routine you want to repeat each day.