Codex Code Cleanup: AGENTS.md Rules and a Quality Gate for OpenAI Codex

To clean up after OpenAI Codex, put a code quality section in AGENTS.md so it writes less slop, then run a scan-fix-handoff loop on what still gets through. Like every coding agent, Codex is good at getting a task to pass and less careful about what it leaves behind.

Codex leaves the same residue as other agents

SlopCodeBench shows these patterns compound as an agent extends its own code. A typical example:

def load_config(path):
  try:
      with open(path) as f:
          return json.load(f)
  except Exception:
      return {}

def load_config_v2(path):
  return load_config(path)

• The broad except returns a default, so a missing or broken config looks like an empty one. That is a swallowed exception.
• load_config_v2 is left from a second attempt and adds only a name: a thin wrapper.
• Not shown: new requirements get appended to an existing function until it is the biggest one in the file.

Step 1: put the standard in AGENTS.md

Codex reads AGENTS.md before it starts: a global file in ~/.codex/AGENTS.md and project files from the repository root down. Add a short quality section:

## Code quality
- Change only what the task needs. Delete code you replaced:
no leftover helpers, _v2 functions, flags, or dead branches.
- Never catch a broad exception and return a default. Handle the
specific error or let it propagate.
- No type escape hatches (Any, cast, "as any") to make checks pass.
- Comments explain why or a non-obvious constraint. Never narrate
the code or describe your edit.
- Prefer splitting a growing function over appending to it.
- Before finishing, run: npx aislop scan --changes
Fix every finding it reports in files you touched.

Or let aislop write its own rules block:

npx aislop hook install --codex       # project AGENTS.md
npx aislop hook install --codex -g    # ~/.codex/AGENTS.md

The installer wraps its section in markers, so it never overwrites what you wrote by hand, and npx aislop hook uninstall --codex removes only that section.

Step 2: scan, fix, hand back to Codex

aislop’s Codex integration is rules-only, with no per-edit hook like the ones for Claude Code and Cursor. Rules guide Codex but do not enforce anything (see AGENTS.md is not enough), so run the check as a loop:

npx aislop scan --changes
npx aislop fix
npx aislop fix --codex

1. scan --changes scores only what changed, so legacy debt does not drown the new findings.
2. fix applies the safe, mechanical fixes and leaves judgment calls alone.
3. fix --codex launches the Codex CLI with every remaining finding, file, line and rule as its prompt.

If you use Codex outside the CLI, npx aislop fix --prompt prints the same prompt to paste wherever you work. All handoff options: agent handoff docs.

Step 3: gate the pull request

Codex often works in the cloud and opens a pull request instead of editing your local tree, so the pull request is the reliable place to enforce the standard. Add the aislop GitHub Action with the two-minute quality gate and set the threshold at your current score, so Codex’s changes cannot lower it.

The same setup for other agents: Claude Code and Cursor.