Codex Dev

/codex-dev — delegate-to-codex development loop

Division of labor: Claude plans, writes the task brief, orchestrates, runs acceptance + review + merge; codex only implements. The flow advances on its own and only stops to ask the user when BLOCKED, when a merge conflict needs a ruling, or when something would cross the role boundary. Report a one-line progress update on every task state change.

One engine: every codex task runs as an omegacode agent. There is no "serial vs concurrent" split — N tasks are N agents. How many, and whether they run in parallel or in sequence, is an orchestration decision you make in Step 1, not a separate tool:

• One task → a 1-agent run.
• Several independent tasks → one run, agents in parallel().
• Dependent tasks → separate runs in dependency order (dispatch B after A merges).

Because everything goes through omega, every dispatch — even a single hours-long task — gets a live web dashboard, a completion notification (the run is a Bash run_in_background job, so the harness wakes you when it exits), and disk-persisted reconnect. Right after dispatching, always print the run's dashboard address to the user — a long task with no visible progress is a black box; never leave the user blind.

Step 0: Preflight checks

REPO_ROOT=$(git rev-parse --show-toplevel)
command -v codex >/dev/null && codex --version || echo "CODEX_NOT_FOUND"
OMEGA=$(command -v omegacode) || echo "OMEGA_NOT_FOUND"
command -v python3 >/dev/null || echo "PYTHON3_NOT_FOUND"
[ -f "${CODEX_HOME:-$HOME/.codex}/auth.json" ] || [ -n "$CODEX_API_KEY" ] || [ -n "$OPENAI_API_KEY" ] || echo "AUTH_MISSING"
git -C "$REPO_ROOT" status --porcelain | head -5
mkdir -p "$REPO_ROOT/.runtime/codex-dev"

• CODEX_NOT_FOUND → stop: npm install -g @openai/codex. AUTH_MISSING → stop: codex login.
• OMEGA_NOT_FOUND → stop. omega is the execution engine — without it there is no dispatch. Don't auto-install (env-level change + network); show the standard global-install command for the user to confirm: npm install -g omegacode (installs into the user's npm global prefix; if that dir needs permissions, suggest sudo, or npm config set prefix and add its bin to PATH). After consent, install and run omegacode doctor to confirm the codex worker is OK.
• PYTHON3_NOT_FOUND → stop: install python3 (used to build args and persist run state).
• codex 0.120.0–0.120.2 has a stdin-deadlock bug → warn to upgrade, don't block.
• Sandbox iron rule: the user's global ~/.codex/config.toml may be sandbox_mode = "danger-full-access" (desktop config). The workflow MUST set defaultSandbox: "workspace-write" and never rely on the global default; a missing setting is an incident — abort and re-dispatch.
• .runtime/, .omegacode/, .claude/worktrees/ should be in the project's .gitignore; if not, add them before starting.

Step 1: Task decomposition & tiers (first anti-collision gate)

Collisions are prevented at dispatch-time orchestration, not patched up afterward:

1. Independence check: for each candidate task, estimate the set of files/modules it will touch (from the project's spec docs and existing code structure). Tasks whose file sets are disjoint and have no import/interface coupling may run in the same run as parallel agents; any overlap or coupling → split into separate ordered runs, or merge into one task.
2. Dependency ordering: B depends on A's output → dispatch B only after A is merged back to the main branch.
3. Concurrency capped at 10: the dispatch passes --concurrency 10 (omega's own default is 100). Each agent is a real codex coding agent that uses codex API rate-limit budget, but they're CLI processes — light on local memory — so 10 concurrent is a comfortable ceiling; a batch with more independent tasks simply queues.
4. Model & reasoning-effort tiers (set per agent; honor the user's request when named):

| Tier | When | Params | |---|---|---| | chore | config edits, mechanical refactors, docs | gpt-5.5 + medium | | normal (default) | single-module features, bug fixes, adding tests | gpt-5.5 + high | | hard | cross-module design, money/accounting/matching core logic, concurrency & timing, performance | gpt-5.5 + xhigh |

Claude decides the tier and notes it in the dispatch progress report (e.g. "T9 backfill pipeline → xhigh").

Step 2: Write the task brief

Write the brief to $REPO_ROOT/.runtime/codex-dev//brief.md (slug = task id or a short English kebab-case name). First read the project's CLAUDE.md / AGENTS.md / relevant spec docs and distill the project's red lines and quality constraints into the "Hard constraints" section — the brief must be self-contained; do not assume codex has read the conversation history.

Template (prose follows the project's language convention; code identifiers/paths in English):

# Task: 

## Goals & acceptance criteria
- 

## Spec basis
- 
- 

## Environment
- Working directory is ; build/test env is ready.
- No installing dependencies and no network operations (the sandbox is usually offline, but this is a behavioral red line, not a technical backstop); if a dependency is missing or network is genuinely needed, stop and explain it in the final report — do not work around it.

## Hard constraints
1. No git write operations whatsoever (commit/push/rebase/checkout/stash). Only edit working-tree files; version operations are done by the reviewer. Git writes may be blocked by the sandbox — that's expected, don't retry.
2. Write scope is limited to ; going out of scope = task failure.
3. 
4. New logic must come with tests; run  yourself and pass before considering it done.

## Completion report
The final message must list: changed-files list, added-tests list, lint/test results, open items and known limitations.

Step 3: Execution environment (second anti-collision gate)

Isolation is proportional to concurrency. A branch gives logical isolation; a worktree gives physical isolation, which omega needs in exactly one case: when it runs two or more agents at the same time (parallel()), since several codex agents in one working tree collide — git status can't be attributed, test caches conflict, and on rework codex "helpfully fixes" others' changes it sees. A single task, or tasks dispatched one after another, do not need a worktree. Do not force a worktree, and do not gate dispatch on being isolated.

Default — main working tree, one branch per task (a single task, or a batch you run sequentially); the agent's cwd is the repo root (keeps the real env, skips the worktree + env-rebuild overhead):

git -C "$REPO_ROOT" checkout -b "codex/$SLUG"   # the main working tree belongs to this task during dispatch

The main tree must be clean before dispatching here. If it is dirty:

• changes are unrelated to the task → ask the user to commit or git stash first (preserves the env), then dispatch in the main tree;
• changes ARE the task's baseline (the user got halfway and wants codex to continue) → build the branch on the current state; do not stash it away.

Concurrent fan-out (≥2 omega agents in parallel()) — one worktree per task, each agent's cwd its own worktree:

SLUG=
WT="$REPO_ROOT/.claude/worktrees/codex-$SLUG"
git -C "$REPO_ROOT" worktree add "$WT" -b "codex/$SLUG" 

The worktree needs its own environment. omega's codex runs under workspace-write with network on, so the simplest path is to have codex build the env itself as the first step inside the worktree (pip install -e .[dev] / npm install); Claude pre-builds only when the setup is non-obvious. Editable-install caveat: a worktree must not share the main repo's editable venv (its path is hard-coded to the main repo, so tests would run against main-repo code) — build a fresh one. Then run the project's lint/test once inside the worktree: the baseline must be green — dispatching on red makes failures unattributable; if the baseline is red → fix the main branch first, don't dispatch.

> Rule of thumb: one task, or a sequential batch → main tree. Worktrees only to run agents at the same time. Don't pay the per-worktree env-rebuild cost for isolation you won't use.

Step 4: Dispatch via omega

One agent per task. A single task is just a one-element tasks array; independent tasks are multiple elements (omega runs them in parallel, capped at its concurrency). Pick a name BATCH for this run (lowercase kebab-case, e.g. oauth-migration) — the workflow, log, state, and args all use it as prefix; set it once and reuse the same variable throughout so names can't drift apart. Write the workflow to $RUN_DIR/$BATCH-fanout.workflow.js (omega shows the run on the dashboard by filename, so you can tell which one at a glance; the -fanout.workflow.js suffix is fixed, marking it the orchestration script):

export const meta = {
  name: "codex-dev-fanout",
  description: "Dispatch one codex agent per task, implementing inside its prebuilt worktree (or the repo root for a single task)",
  defaultProvider: "codex", defaultModel: "gpt-5.5",
  defaultSandbox: "workspace-write",
  phases: [{ title: "Implement" }],
}
const REPORT = {
  type: "object", required: ["files_changed", "tests_added", "test_result", "notes"],
  properties: {
    files_changed: { type: "array", items: { type: "string" } },
    tests_added: { type: "array", items: { type: "string" } },
    test_result: { type: "string" }, notes: { type: "string" },
  },
}
phase("Implement")
return await parallel(args.tasks.map((t) => () =>
  agent(t.brief, { label: t.slug, cwd: t.worktree, effort: t.effort, schema: REPORT })
    .then((r) => ({ slug: t.slug, report: r }))
))

tasks[].brief carries the full brief text; tasks[].worktree is the task's cwd (its worktree, or the repo root for a single main-tree task). First set per-batch names and write the args:

RUN_DIR="$REPO_ROOT/.runtime/codex-dev"; mkdir -p "$RUN_DIR"
BATCH=                               # lowercase kebab-case; the only variable used throughout, so names can't drift
WF="$RUN_DIR/$BATCH-fanout.workflow.js"          # the workflow above MUST be written to this file
LOG="$RUN_DIR/$BATCH.log"; RUNJSON="$RUN_DIR/$BATCH-run.json"; ARGSFILE="$RUN_DIR/$BATCH-args.json"
# refuse if this BATCH is already in use — locally (run.json) OR as an omega run with the same filename (a prior dispatch may have registered before its run.json was written)
{ [ -e "$RUNJSON" ] || "$OMEGA" runs 2>/dev/null | awk -v f="$BATCH-fanout.workflow.js" '$NF==f{seen=1} END{exit seen?0:1}'; } && { echo "batch name '$BATCH' already in use — pick a unique BATCH"; exit 1; }
python3 -c 'import json;print(json.dumps({"tasks":[...]}))' > "$ARGSFILE"   # persist args; reused verbatim on resume
[ -s "$ARGSFILE" ] || { echo "ARGS generation failed, stop"; exit 1; }

Dispatch this command as a Bash run_in_background job (NOT nohup/detached): omega run blocks until the run finishes — omega has no executor daemon by design, the run lives in one process — so when it exits the harness fires a completion notification, which is your cue to go to Step 5. Don't add --json (it suppresses the view: line):

"$OMEGA" run "$WF" --args-file "$ARGSFILE" --concurrency 10 > "$LOG" 2>&1

Right after (foreground; reads the log the background run is writing), capture the dashboard URL and persist the reconnect record:

# runId is authoritative from `omega runs` (matched by our unique filename); the dashboard URL is best-effort — only present if the viewer came up
RID=""; VIEW=""
for _ in $(seq 1 20); do
  [ -z "$VIEW" ] && VIEW=$(grep -oE 'http://127\.0\.0\.1:[0-9]+/#/run/wf_[0-9a-f]+' "$LOG" | head -1)
  RID=$("$OMEGA" runs 2>/dev/null | awk -v f="$BATCH-fanout.workflow.js" '$NF==f{print $1; exit}')
  [ -n "$RID" ] && break; sleep 0.5
done
# hard-fail ONLY if the run never registered; a missing viewer (no view: line) is NOT a failure — omega runs fine without one
[ -n "$RID" ] || { echo "omega run never registered, check $LOG:"; tail -20 "$LOG"; exit 1; }
python3 - "$RID" "$VIEW" "$WF" "$LOG" "$ARGSFILE" "$RUNJSON" /state.json`:

```json
{"slug":"...","phase":"dispatched|accepted|rework-N|merged|failed|blocked",
 "batch":"","worktree":"...","branch":"...","tier":"high"}

• Print the dashboard address ($VIEW) to the user — a read-only web board to watch each codex's phase / progress / token use live; it's the full per-run URL (with /#/run/), so it stays unambiguous across multiple dispatches.
• Key design: don't use omegacode's worktree: option (when it builds its own worktree, Claude can't inject the env-setup step); use cwd: pointing at the prebuilt worktree — omegacode does pure deterministic orchestration (concurrency scheduling, 30-min no-progress watchdog, journal, token stats), and the worktree lifecycle belongs to Claude.
• It drives codex over codex app-server JSON-RPC (no stdin/timeout pitfalls of a raw codex exec).
• The runId comes from omega runs (matched by the unique filename — authoritative even if the viewer never started); the dashboard URL, when the viewer is up, is the view: line in the log. On completion read the structured result from the log or ${OMEGACODE_HOME:-~/.omegacode}/runs//.
• A single failed agent shows as null/failed in the results array — rework only that task, the rest are unaffected.
• Extras (only when the user asks): hard tasks can run the built-in bake-off (codex and claude-code each implement in isolated worktrees, blind-judged for a winner) or multi-provider-review (two models review independently, then synthesize).

Completion & reconnect

You get woken automatically. Because the dispatch is a Bash run_in_background job and omega run blocks until the run finishes (omega has no executor daemon by design — a run lives and dies with its one process), the harness fires a completion notification when that process exits. That is your cue to proceed to Step 5 — no watcher or polling needed.

A stuck task surfaces — it does not hang silently. omega arms a 30-min no-progress watchdog per agent: a stalled turn is failed (turn_stalled), its result becomes null, the run settles, and omega run exits — so within ~30 min a stall becomes an ordinary completion notification carrying a failed task, which you report by name ("task X stalled") and then rework or mark blocked. The always-printed dashboard/log also lets the user watch a stall live. Residual edge: a wedged codex app-server that ignores both interrupt and SIGTERM could keep omega run from exiting — so if the completion notification hasn't arrived well past the watchdog window (~45 min) and the dashboard shows no progress, stop waiting: run "$OMEGA" runs + tail the log, report the stuck run to the user, and "$OMEGA" runs --prune-stale (or kill its pid) to clear it. Never wait indefinitely.

If the session died before omega finished (the background run dies with the session; omega's recovery model is "the run dir is the truth, --resume continues"), reconnect from a new session via the persisted record:

• Source of truth: $RUN_DIR/-run.json (runId / dashboard / workflow / argsFile, per-batch, never overwriting each other) + omega's own ${OMEGACODE_HOME:-~/.omegacode}/runs// journal.
• Reconnect from any new session (even if the original terminal is closed):

```bash OMEGA=$(command -v omegacode) || { echo "omegacode not on PATH → first npm install -g omegacode"; exit 1; } # stop if not found, don't run on with an empty command RUNDIR="$(git rev-parse --show-toplevel)/.runtime/codex-dev" ls "$RUNDIR"/*-run.json # list each batch's record, pick the one to recover RUNJSON="$RUN_DIR/-run.json" J() { python3 -c 'import json,sys;print(json.load(open(sys.argv[1]))[sys.argv[2]])' "$RUN

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: shengyy
• Source: shengyy/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.