Codex Build

One model orchestrates. Another writes the code. The tests run before every commit.

Your agent (Claude Code, or any Skills-capable harness) plays orchestrator: it sequences an approved plan, briefs OpenAI Codex to write all the product code, reviews every diff, runs the test gate, and commits — one task per commit, one PR per plan. Codex does the typing; the orchestrator guards the gate.

No mega-diffs. No "trust me, it works." No silent takeover when the coder gets stuck.

---

Why I built it

I write at littlemight.com (and run BestSelf.co on the side). When I hand a plan to a coding agent, the two things that go wrong are always the same: it writes a giant unreviewable diff, and it commits code whose tests it never actually ran.

So I split the job. The model with my context and taste never gets to skip the review or the gate — and it's a different model than the one that wrote the code, so the check is real. The coder model runs cheap, high-effort reasoning and does the mechanical work. The result is a reviewable history: one task, one commit, tests green before each one, and exactly one PR at the end.

The gate is the point. A task is committable only when its tests pass — run by the orchestrator, not taken on faith from the coder.

---

What it does

preflight → persist run state → materialize tasks → for each task:
    claim → brief Codex → enforce allowlist → review diff + verify tests
          → test gate (BEFORE commit) → commit (no AI attribution)
          → persist interfaces ledger → close
finish → full-suite gate → push → ONE PR

• Tests run before every commit. Not "usually." Every one. Red gate → no commit.
• One task, one commit; one plan, one PR. Reviewable history, no mega-diffs.
• Scope is executable. Each task gets an on-disk file allowlist. A bundled script fails on tracked, staged, deleted, renamed, or non-ignored untracked paths outside it—after Codex runs and again before commit.
• Runs survive compaction. Task status, allowlists, test/commit evidence, and interfaces live under the worktree's private Git directory and are reloaded on resume.
• No silent takeover. If Codex can't land a task in three tries, the run stops and hands you the diff — it never quietly rewrites the code itself and pretends it passed.
• Reproducible. Model and reasoning effort are pinned per invocation, not inherited from whatever your Codex config happens to be today.

Two ideas do most of the work:

• The Codex brief (references/codex-brief.md). codex exec is stateless and sees only the prompt, so the brief carries the goal, the verbatim plan excerpt, the allowed files, and the conventions to match. Brief quality is the main driver of output quality.
• The interfaces ledger. After each green commit the orchestrator writes the verified public surface (signatures, types, endpoints, paths, source commit) to a durable file and feeds the relevant slice into the next task's brief—so Codex builds on real contracts instead of guessing across stateless calls.

---

Requirements

Tool	Required?	Purpose
A Skills-capable agent	yes	runs the skill (built for Claude Code)
codex CLI, authed	yes	the coder (codex login)
git	yes	commits, branch, diff
Python 3	yes	runs the bundled exact-path scope gate
gh or glab	optional	opens the PR/MR (falls back to a compare URL)
bd (beads)	optional	richer task tracking; defaults to a Markdown checklist

---

Install

# Clone the repo somewhere, then symlink the inner skill into Claude Code's skills dir
git clone git@github.com:cathrynlavery/codex-build.git ~/code/codex-build
ln -s ~/code/codex-build/skills/codex-build ~/.claude/skills/codex-build

The real skill lives at skills/codex-build/ inside the repo (so the same tree works as a Claude Code plugin, a Codex plugin, and a standalone skill). The symlink points Claude Code at that inner directory.

Restart Claude Code. The skill registers as codex-build and activates when you hand over a plan or say "codex-build this."

Alternative: install as a plugin

Claude Code:

/plugin marketplace add cathrynlavery/codex-build
/plugin install codex-build@codex-build

Claude Cowork: Customize → Directory → Plugins → + → paste cathrynlavery/codex-build → Sync, then install from the Personal list.

Codex:

npx skills add https://github.com/cathrynlavery/codex-build --skill codex-build

---

Quickstart

1. Write (or have your agent write) an approved plan with an ordered task list. See references/plan-example.md for the shape.

2. Hand it over — in chat:

   "codex-build this plan: plan.md" "You orchestrate, Codex codes — execute the approved plan."

   or via the slash command:

   /codex-build:build plan.md            # effort defaults to `high`
   /codex-build:build plan.md xhigh      # harder / architectural work
   /codex-build:build plan.md --model gpt-5.6-codex
   

The orchestrator confirms the model/effort, shows you the ordered tasks, then runs the per-task loop until the queue is empty and opens one PR. See references/walkthrough.md for a full trace of a single task.

Configuration

Variable	Default	Notes
CODEX_BUILD_MODEL	your Codex config default	pin a model you have access to; check ~/.codex/config.toml
CODEX_BUILD_EFFORT	high	high or xhigh

--model / the effort argument override the env vars for a single run.

---

Architecture

Progressive disclosure. SKILL.md is the whole loop; the references are pulled in only when needed.

codex-build/
├── .claude-plugin/                  — Claude Code plugin + marketplace manifest
├── .codex-plugin/                   — Codex plugin manifest
├── commands/
│   └── build.md                     — /codex-build:build slash command
└── skills/codex-build/
    ├── SKILL.md                     — the loop: roles, config, per-task steps, rails
    ├── scripts/check_scope.py       — exact-path allowlist enforcement
    ├── tests/test_check_scope.py
    └── references/
        ├── codex-brief.md           — the Codex brief skeleton (highest-leverage part)
        ├── plan-example.md          — the shape of an input plan
        └── walkthrough.md           — a full trace of one task, start to finish

---

When not to use this

• A one-file, five-line change → just make the edit; the ceremony isn't worth it.
• Exploratory / throwaway spikes → no plan, no gate, no PR discipline needed.
• Work with no tests and no intention of writing any → the gate is the whole point; without tests this skill has nothing to enforce.
• You want the orchestrator to write the code → that's a normal coding session, not this. Here the orchestrator reviews; Codex writes.

---

About

Made by Cathryn Lavery — founder of BestSelf.co. I write about AI, agents, and building things at littlemight.com — blog + newsletter.

If this is useful, star the repo and come say hi on X.