Codex Loop

Hand Codex a PRD. Get a working feature back. One story per subagent, fresh context every time.

Codex Loop is a Codex skill for autonomous, story-by-story implementation. You write a codex-loop/prd.json file listing the user stories you want shipped; Codex runs as the orchestrator, spawning a fresh worker subagent for each story. Each worker implements exactly one story, runs the right checks, commits the work, records durable learnings, and exits.

This repository is intentionally skill-only. It does not ship a standalone CLI, npm package, or script runner. Codex already provides the workflow surfaces this skill needs: skills, subagents, git operations, worktrees, and browser/tool verification.

• Sequential mode is the default. Codex runs one story at a time in priority order. This is safest for PRDs where stories touch overlapping files or build directly on each other.
• Parallel wave mode is opt-in. Ask Codex to "run the loop in parallel", "run stories in tandem", "run waves", or "fan out". Codex groups dependency-ready stories into waves, runs each story in an isolated git worktree, then merges and verifies the integrated branch before starting the next wave.

Long autonomous coding sessions degrade when every implementation detail stays in one context. Earlier decisions get blurred, repeated mistakes become more likely, and the agent spends more time managing its own history than shipping work.

Codex Loop makes the context boundary explicit. The orchestrator keeps high-level state small and delegates each story to a fresh subagent. Durable memory persists through:

• Git history - every story produces a focused commit
• codex-loop/progress.txt - append-only learnings with a ## Codebase Patterns section at the top
• AGENTS.md files in the source tree - per-module knowledge that Codex reads when working in those directories

The result is a repeatable loop for feature work that can resume cleanly and does not depend on one ever-growing chat context.

• A git repository for the project you want Codex to modify
• Codex with skills enabled
• Codex subagent support available in the current environment
• Recommended: a typecheck and/or test command
• Recommended for UI stories: the Codex in-app Browser plugin, Playwright, or another browser automation tool

Parallel wave mode additionally requires:

• A clean working tree before the wave starts
• Git worktree support
• codex-loop/.worktrees/ ignored or approved before use
• Honest story dependencies through dependsOn

Install this repository as a Codex skill.

Per project:

git clone https://github.com/aronprins/codex-loop.git .agents/skills/codex-loop
mkdir -p codex-loop

Global:

git clone https://github.com/aronprins/codex-loop.git ~/.agents/skills/codex-loop

For global installs, create codex-loop/prd.json in each project where you want to run the loop.

Codex detects skill changes automatically in most cases. Restart Codex if the skill does not appear.

1. Create codex-loop/prd.json at your project root. See prd.example.json.
2. Open Codex in that project.
3. Say one of:
   • "run the codex loop"
   • "work through the prd"
   • "process codex-loop/prd.json"
   • "implement all the stories with Codex Loop"
4. Codex runs preflight, detects your stack, checks out the branch from branchName, and starts one subagent per story.
5. When all stories pass, the run archives itself to codex-loop/archive/YYYY-MM-DD-<branchName>-complete/ and Codex emits <promise>COMPLETE</promise>.

For parallel execution, say:

• "run the codex loop in parallel"
• "run the stories in tandem"
• "run waves"
• "fan out the loop"

flowchart TD
    Start([User: run Codex Loop]) --> Read[Read codex-loop/prd.json<br/>and progress.txt]
    Read --> Preflight[Preflight git, stack, checks,<br/>browser tools, subagent support]
    Preflight --> Setup[Detect stack<br/>check out PRD branch]
    Setup --> Mode{Parallel requested?}
    Mode -->|No| Seq[Sequential:<br/>one worker per story]
    Mode -->|Yes| Waves[Parallel waves:<br/>dependency-ready workers<br/>in isolated worktrees]
    Seq --> Verify{Verify commit<br/>and state}
    Waves --> Barrier[Merge barrier<br/>and integrated verification]
    Verify -->|More stories| Mode
    Barrier -->|More waves| Mode
    Verify -->|Complete| Archive[Archive codex-loop state]
    Barrier -->|Complete| Archive
    Archive --> Done([Emit COMPLETE])

Two roles:

• Orchestrator: reads the PRD, manages the branch, detects commands, starts workers, verifies results, owns shared state in parallel mode, and archives finished runs. It does not implement application stories itself.
• Worker: one fresh Codex subagent per story. It reads the PRD and local guidance, implements one story, runs checks, commits, and returns.

codex-loop/prd.json is the task list. Minimal shape:

{
  "project": "MyApp",
  "branchName": "feat/wagering-history",
  "description": "User Wagering History - Persist and display each user's past wagers",
  "userStories": [
    {
      "id": "WAGER-001",
      "title": "Add wagers table to database schema",
      "description": "As a developer, I need a database table to store wager records so we can persist user wagers across sessions.",
      "acceptanceCriteria": [
        "Migration creates a `wagers` table with id, userId, amount, outcome, createdAt",
        "Foreign key to users table",
        "Index on userId",
        "Typecheck passes"
      ],
      "dependsOn": [],
      "priority": 1,
      "passes": false,
      "notes": ""
    }
  ]
}

Fields:

• project - short project name
• branchName - git branch for the work; Codex creates it from main or master if missing
• description - one-line feature summary
• userStories[].description - story requirement, usually "As a X, I want Y so that Z"
• acceptanceCriteria - explicit, testable requirements
• dependsOn - optional array of story IDs that must pass before this story starts; ignored by sequential mode and used by parallel wave mode
• priority - lower number runs first
• passes - starts false, changes to true after the story is implemented and committed
• notes - scratchpad for blockers or useful context

The shape intentionally stays close to Ryan Carson's Ralph prd.json so PRDs are portable.

Keep these locations distinct:

Runtime state stays at the repo root rather than under the skill directory because the loop rewrites prd.json and appends progress.txt as work completes. The skill source should stay read-only while a loop is running.

A populated project looks like:

your-project/
├── .agents/
│   └── skills/codex-loop/          # skill source, installed once
├── codex-loop/                     # runtime state
│   ├── prd.json
│   ├── progress.txt
│   ├── .last-branch
│   ├── .worktrees/                 # transient parallel mode checkouts
│   └── archive/
├── AGENTS.md
└── src/
    └── ...

Sequential mode is the default.

For each pending story, Codex:

1. Loads subagent-prompt.md.
2. Fills the story ID, title, branch, detected check commands, and browser tool availability.
3. Spawns one worker.
4. Waits for the worker to commit, update prd.json, append progress.txt, and return.
5. Verifies the commit, shared state, checks, and clean working tree.

Use sequential mode for short PRDs, deeply dependent stories, or any feature where stories likely edit the same files.

Parallel wave mode is opt-in and dependency-driven.

Add dependsOn to each story:

{
  "id": "WAGER-003",
  "title": "Build wager history list UI",
  "dependsOn": ["WAGER-002"],
  "priority": 3,
  "passes": false
}

Then ask Codex to run in parallel. Codex will:

1. Compute waves from the dependency graph.

2. Create one git worktree per story in the wave:

   git worktree add -b wt/<story-id> codex-loop/.worktrees/<story-id> <branchName>

3. Spawn each wave worker with parallel-subagent-prompt.md.

4. Wait for every worker in the wave.

5. Merge successful worker branches one at a time.

6. Run typecheck/tests on the integrated branch.

7. Update prd.json and progress.txt once for the merged wave.

8. Clean up merged worktrees and branches.

Parallel mode is safe because workers do not write shared runtime files. They return structured results; the orchestrator records shared state only after the merge barrier.

If no story declares dependsOn, Codex warns and can fall back to equal-priority waves. That fallback is weaker because it assumes stories with the same priority are independent, so dependency-based PRDs are preferred.

Tradeoffs:

• Speedup is bounded by the dependency graph.
• Merge conflicts are the main failure mode.
• Dependency installs and lockfile changes should usually happen in an early scaffolding story before wider waves.
• Additive story design works best: new files, auto-discovered modules, and minimal shared-file edits.

The orchestrator detects commands from common project signals and passes them to workers:

If your project has custom commands, add them to AGENTS.md or edit the prompt templates to hardcode the placeholders.

• All stories pass - archive run state and emit <promise>COMPLETE</promise>.
• Subagent blocker - stop, summarize the blocker, and wait for direction.
• Verification failure - stop and report what is missing.
• Parallel merge conflict - preserve the blocked branch/worktree, report the conflict, and stop.
• Manual interruption - resume later; the next run starts from the next passes: false story.

Codex Loop does not silently auto-retry failed stories. A clear stop is better than compounding broken work.

Sensible defaults:

• Commit .agents/skills/codex-loop/ if you want the skill shared with the project.
• Commit codex-loop/prd.json when the PRD belongs with the feature branch.
• Commit codex-loop/progress.txt and codex-loop/archive/ when you want learnings shared.
• Gitignore codex-loop/.last-branch.
• Gitignore codex-loop/.worktrees/.

You can also gitignore codex-loop/ entirely and treat it as personal runtime state.

Why not just run one long Codex session? Fresh subagents keep each story focused. The orchestrator only carries high-level state.

Why not keep the CLI runner? Codex Loop is a reusable Codex workflow, and skills are Codex's native surface for that. Keeping a separate package runner adds maintenance cost and duplicates behavior Codex already provides through skills, subagents, and worktrees.

Can I run workers in parallel? Yes, but only when you explicitly ask for parallel wave mode. Codex isolates workers in git worktrees and keeps shared runtime files owned by the orchestrator.

Can I resume after stopping? Yes. codex-loop/prd.json is the source of truth. Re-run the loop and Codex starts from the next pending story or ready wave.

What does the orchestrator verify after each worker? In sequential mode, it requires a new commit with subject feat: [Story ID] - [Story Title], passes: true for that story, a progress entry containing the story ID, checks/browser evidence, and a clean working tree. In parallel mode, workers do not update shared state; the orchestrator verifies worker commits, merges branches, runs integrated checks, then records shared state once per wave.

• SKILL.md - orchestrator instructions
• subagent-prompt.md - sequential worker prompt template
• parallel-subagent-prompt.md - parallel wave worker prompt template
• prd.example.json - sample PRD
• agents/openai.yaml - optional Codex app metadata