auto-codex

Four autonomous coding pipelines for Claude Code.
Pick a lane by how much you want Codex involved, from fully Codex-driven to Claude-only, plus a 19-phase lane for building whole projects from a spec.

Live visual tour →

Why this exists

Long autonomous Claude sessions burn tokens fast. This plugin exists to spread the work across models that are good at different parts of it: planning, adversarial review, parallel implementation. That beats asking one Claude session to do all of it and grade its own homework.

Codex (via the Codex MCP server, billed to your existing ChatGPT account) is one option for offloading planning and building. It isn't required. The plugin ships four lanes so you can choose how much of that work you want to hand to Codex versus keep in Claude:

/auto-codex          research → plan-codex → codex hard gate → swarm → verify → [optimize] → complete
/makeitso             research → plan → review → swarm → verify → [optimize] → complete
/makeitso-codex       research → plan-codex → codex hard gate → codex build → verify → [optimize] → complete
/makeitso-project     19 gated phases (see below)

Four lanes, pick one

Every lane shares the same underlying engine (scripts/) and the same anti-fallback discipline: one correct approach per plan step, hard-gated reviews, no silent degradation.

The lane map

flowchart TD
    Start(["Pick a lane"]) --> AC["/auto-codex<br/>research → plan-codex → codex gate → swarm → verify → [optimize] → complete"]
    Start --> MI["/makeitso<br/>research → plan → review → swarm → verify → [optimize] → complete"]
    Start --> MC["/makeitso-codex<br/>research → plan-codex → codex gate → codex build → verify → [optimize] → complete"]
    Start --> MP["/makeitso-project<br/>19 phases: research → requirements → plan → traceability → review → swarm → integration-check → write-tests → test-traceability → verify → gap-analysis loop → red-team → fix-redteam → [optimize] → re-verify → cleanup → deploy → complete"]
    AC --> Done(["Task complete → next task or done"])
    MI --> Done
    MC --> Done
    MP --> Done

Cross-check flow on the Codex lanes: Codex plans → Opus interrogates → Codex verifies resolution → builder implements → reviewer checks. Every handoff has a hard gate; nothing advances until the gate passes. The Claude-only lanes (/makeitso, /makeitso-project) run the same shape of gate with fresh Claude subagents standing in for Codex and Opus.

Prerequisites

• Claude Code (this is a Claude Code plugin)
• Python 3.8+ · git (almost certainly already installed)

Codex is optional. Two of the four lanes use it, two don't:

If you want either Codex lane:

• Codex CLI: npm install -g @openai/codex (one-time)
• Codex auth: codex login (uses your existing ChatGPT/Codex account)

No Codex account, or don't want to install one? Start with /makeitso: same pipeline shape, Claude runs every phase itself, nothing else to install.

Install

In any Claude Code session:

/plugin marketplace add neonplants/auto-codex
/plugin install auto-codex@auto-codex-marketplace

Restart Claude Code (or run /plugin reload). The plugin's plugin.json automatically registers the Codex MCP server so mcp__codex__codex is available in your sessions. You only need it running if you use one of the two Codex lanes.

Quick start

/auto-codex          # Codex plans, Sonnet swarm builds (needs Codex)
/makeitso             # Claude does every phase itself (no Codex needed)
/makeitso-codex       # Codex plans and builds, Claude reads twice (needs Codex)
/makeitso-project     # 19-phase build from a spec (no Codex needed)

Not sure which one? Check the lane table above. If you're not sure and don't have Codex installed, /makeitso is the safe default.

Each command is smart-default: running it with no argument inspects state and does the right thing.

• No session yet → drafts a scope of work in tmp/scope_of_work.md (from your git log, README, any STATE.md / tasks.md), asks Claude to fill in real prioritized tasks, shows you the scope, waits for your explicit approval, then commits and starts executing. (/makeitso-project asks "What are we building?" instead of drafting a scope, since it's built for a single spec-based project, not a task queue.)
• Scope draft exists from before → asks whether to use, edit, or regenerate it.
• Session already active → fetches the next action and resumes the autonomous loop.

Subcommand shape differs slightly by lane. Here's what each one actually supports:

How /auto-codex orchestrates models

The other three lanes route reviewers by the same principles: task classification, cross-family reviewer routing (whoever builds is never who reviews), a hard ask-gate before ever escalating to your most expensive model, and orchestrator economy for delegating the phase loop off an expensive driver model. Each lane's command file (commands/makeitso.md, commands/makeitso-codex.md, commands/makeitso-project.md) documents its routing rules in full. Start there if you want the exact reviewer for a given blast radius.

The optimize loop (the killer feature)

Inspired by karpathy/autoresearch, Andrej Karpathy's autonomous experiment loop where an agent edits a single training script, runs a time-boxed eval, and keeps or reverts the change. We wired the same pattern as the final phase of every lane in this plugin.

How it works: if your plan declares an ## Optimization Target block, the pipeline runs the optimize loop (Codex-driven on the Codex lanes, same engine on the Claude-only lanes). Each cycle: read the target file, propose ONE change, run your eval, parse the metric, keep the change if the metric improved (git commit), revert if not. Repeat.

Plan block format:

file: path/to/single/file.py
eval: command that prints metric_name=value
metric: name_of_metric
direction: higher|lower
cycles: 30
constraints: what prevents gaming the eval

Results land in tmp/optimize_results.tsv (one row per cycle: timestamp, commit hash, metric value, status, description, duration).

What makes this different from "ask Claude to optimize my code":

What people optimize: trading strategies (Sharpe, drawdown), model training (val loss, perplexity), GPU kernels (throughput, memory bandwidth), template engines (render time, bundle size), tabular ML (cross-val score, AUC). If you can print metric=value, this loop can hill-climb it.

Requirements: project must be a git repo (loop uses commit/revert), eval must print the metric, plan for ~3.5 hours at 30 cycles × ~7 min/cycle, write your eval so it can't be gamed.

Fallback behavior

This plugin has exactly one declared fallback, and it is never automatic.

• /auto-codex and /makeitso-codex both require Codex. Before either one starts or resumes autonomous work, it runs a definitive availability check: is the CLI present, authenticated, and is the Codex MCP server actually reachable.
• If that check fails, the command stops, prints exactly what's missing and how to fix it (install the CLI, run codex login, or whatever the check names), and offers /makeitso by name: same pipeline shape, Claude does the planning and building itself, no Codex required.
• It does not switch lanes for you. You get an explicit choice: fix Codex and retry, or knowingly run /makeitso instead. Nothing runs silently in a lane you didn't ask for.

Separately from that one lane-level fallback, every lane also enforces an anti-fallback code quality rule: no silent except: pass, no default-to-success, one correct approach per plan step. That rule is about the code the pipelines produce, not about which lane runs; see the details below.

Commands shipped with this plugin

• /auto-codex: the original 6-phase lane. Codex plans, a Sonnet swarm implements, Codex is the final gate. (subcommands: status/stop/resume/kill/doctor)
• /makeitso: Claude-only lane, no Codex required. Same phase shape, with task-classification and ask-gated escalation rules built in. (subcommands: status/start/stop/resume/kill)
• /makeitso-codex: Codex plans and builds; Claude reads the plan once and the diff once. Offers /makeitso if Codex isn't available. (subcommands: status/start/stop/resume/kill)
• /makeitso-project: 19-phase full-rigor pipeline for building a whole project from a spec: requirements, traceability, gap analysis, red-team, cleanup, deploy. (subcommands: status/stop/kill; no argument handles start/resume)
• /plan-codex: standalone planning mode (Codex drafts, Opus reviews). Called internally by /auto-codex and /makeitso-codex.
• /swarm: standalone parallel implementation. Called internally by /auto-codex, /makeitso, and /makeitso-project. Requires a reviewed plan gate.

You can run /plan-codex and /swarm on their own without an autonomous lane if you just want one phase.

mkdir -p /tmp/auto-codex-fresh-test && cd /tmp/auto-codex-fresh-test
git init -q && git commit --allow-empty -q -m baseline
claude --bare --plugin-dir /path/to/auto-codex

License

MIT · vanilla Claude Code plugin · no telemetry