codex-build

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 [email protected]: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: