Claude Code Supervising Codex: A Reproducible Acceptance Framework to Keep AI from Drifting

Keeping AI Running Without Letting It Drift Is Hard

#

After using tools such as Claude Code and Codex for a while, it is tempting to let them run continuously. The problem is that they may write in the wrong direction, skip validation, or overflow the useful context window during long runs. To address this, I designed a workflow where Claude Code supervises Codex.

This idea is suitable for iterative development from 1 to n. For a 0 to 1 new project, I still recommend doing the early work yourself or watching the model closely.

1
2
3
4
5
6

Supervisor = Claude Code
Worker = Codex
Process ledger = tasks.md
State ledger = feature_list.json
Handoff ledger = progress.txt
Validation bundle = reproducible scripts/logs/screenshots

Choose the Right Tools

#

My own setup includes ChatGPT Plus, Codex access, and GLM coding plan lite, which can be configured in Claude Code. I also have Gemini, but my personal experience with Gemini CLI is average, so this article demonstrates Claude Code + Codex.

• GLM coding plan: large quota, and I rarely hit the limit.
• Claude Code: sometimes finishes too early.
• Codex: relatively steadier, but more expensive, so use it carefully.

For the Codex model, I recommend ChatGPT-5.2-medium. Officially, Codex-suffix models are optimized for coding and agent tasks¹, but my own test results were not ideal. medium is close to “Auto.” You can choose high, but avoid Xhigh; it worked well in my test but burned through a week of quota in one day.

Overall Idea

#

Role split: Claude Code acts as Supervisor, and Codex acts as Worker.

The real danger is not that the model cannot write code, but that it thinks it is finished when it only made something that looks complete, skips reproducible validation, or drifts confidently until the human receives a mess. Splitting the work across two agents reduces this risk: one writes, one accepts.

Startup: the process begins with an OpenSpec change proposal generated by Codex. The proposal is transformed into tasks in tasks.md. When a task needs execution, Claude Code starts a worker call through codex exec and invokes OpenSpec in natural language. OpenSpec 0.21.0 is preferred because newer versions changed the workflow and use skills triggers².

Execution and delivery: after Codex writes code, it must create a reproducible validation bundle under auto_test_openspec.

• CLI tasks must include an automated script, usually run.sh.
• GUI tasks must include a Markdown MCP operation procedure and a script only for starting the service.

Acceptance: Claude Code personally runs the scripts. For GUI tasks, it follows the MCP procedure, drives a browser with playwright-mcp, and captures screenshots as evidence³.

Only after Claude Code confirms the validation bundle passes and the evidence chain is complete can it check tasks, update feature_list.json, commit/archive, and write evidence pointers into progress.txt.

Directory structure:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

openspec/
  changes/<change-id>/
    tasks.md
    feature_list.json
    progress.txt
auto_test_openspec/
  <change-id>/
    <run-folder>/
      run.sh
      logs/
      screenshots/

Memory Design

#

Each task uses a separate worker context to avoid context pollution. Memory is handled through three files:

1. tasks.md is task memory and the process source of truth.
2. progress.txt is append-only process memory for handoffs, validation results, failures, and blockers.
3. feature_list.json is the authoritative feature-state ledger. Worker may read it, but only Supervisor updates it after validation passes³.

A useful startup ritual is to require Worker to read progress.txt, feature_list.json, and recent Git history before starting, then write worker_startup.txt as evidence that previous context was inspected.

Two Layers of Anti-Drift Insurance

#

The two ledgers are connected through Ref tags such as [#R1]. A task line in tasks.md maps to a corresponding feature ref in feature_list.json. Supervisor must first verify the task evidence in tasks.md; only then can it update the feature state.

Initial Configuration

#

Install Claude Code, Codex, and OpenSpec. For OpenSpec, I recommend version 0.21.0 for this workflow.

1
2

npm install -g openspec@0.21.0
openspec init

For GUI or mixed tasks, configure playwright-mcp so Supervisor can operate the browser and collect screenshots instead of relying on manual clicks. A Context7 MCP server is also useful when the agent needs documentation during a blocker.

The workflow also uses repository skills for requirement interviewing, feature-list generation, and unblock research:

• openspec-change-interviewer
• openspec-feature-list
• openspec-unblock-research

Repeated Workflow

#

Open Codex and ask it to create a change proposal, for example: Create an OpenSpec proposal for adding automatic night-mode switching to this project.

Then run $openspec-change-interviewer <id> so the model interviews you and aligns requirements. The <id> is the current proposal folder name under openspec/changes.

Next, run $openspec-feature-list <id> so the model generates feature_list.json.

Finally, open Claude Code and run /monitor-openspec-codex <id>.

<id> is the folder name of the current proposal under openspec/changes.

References

#