version: "1.0.0" name: codex-goal-loop description: Explain and write effective instructions for OpenAI Codex's /goal feature — the persistent self-checking agent loop (plan → act → test → review → iterate). Use when the user mentions Codex /goal, "goal loop", wants to kick off a long-running autonomous Codex run, asks how to write a goal prompt, or wants a one-paragraph goal instruction drafted.

Codex /goal Loop

What /goal is

/goal is a slash command in Codex v0.128.0+ (April 30, 2026) that turns a Codex prompt into a persistent agent looping plan → act → test → review → iterate until a stop condition is met, the user pauses, or the token budget runs out.

Key difference from a normal prompt: when a turn ends but the goal isn't met, Codex auto-continues instead of waiting for input.

Lifecycle states: pursuing, paused, achieved, unmet, budget-limited.

Not: a budget command, a safety boundary, "run forever", or a replacement for /plan. It's a contract enforcer with a verification loop.

Requirements

• Codex CLI/app/extension v0.128.0+
• goals = true in ~/.codex/config.toml (or codex features enable goals)
• ChatGPT auth (Plus/Pro/Business/Edu/Enterprise) — API-key auth does not work. Pro is the realistic minimum for long runs.

When to use it

Use only when all three are true:

1. Task is >30 min of mechanical work.
2. There's a verifiable stop condition (tests pass, coverage hit, eval ≥ X, build green).
3. Repo is agent-ready (working build, decent tests, AGENTS.md present).

Fits: migrations, coverage lifts, TDD feature builds, refactors with contract tests, prompt/eval optimization, deploy retry loops, bug-repro-then-fix.

Bad fits: exploratory work, vague "improve this", anything without a "done" definition, prod credentials, destructive shared-infra ops.

The 4-part contract (every goal needs this)

1. Objective — one sentence, one concrete outcome.
2. Constraints — what must NOT change (public API, files, libs, conventions).
3. Validation command — the exact shell command that proves progress (pytest -q, pnpm test, etc.).
4. Stop condition — verifiable: "Stop when X passes" OR "when further changes need human/product input."

Plus: tell Codex what to read first, ask it to work in checkpoints with a short progress log.

Writing a one-paragraph goal (the core deliverable)

When the user wants a quick one-paragraph /goal instruction, produce a single dense paragraph that packs the 4-part contract into flowing prose. Template:

/goal <one-sentence objective>. Read first: <files/PLAN.md/issue>. Constraints: <what not to change, libs, conventions>. Validate after each change with: <exact command>. Work in checkpoints and log progress briefly. Stop when: <verifiable condition>, OR when further changes require human/product input.

Example (migration)

/goal Migrate this project from Pydantic v1 to v2. Read first: pyproject.toml, src/, tests/. Constraints: no public API changes; keep imports backwards-compatible via shims if needed; no new dependencies. Validate after each change with: pytest -q. Work in checkpoints; log progress briefly. Stop when: full suite passes with zero deprecation warnings, OR when a change requires architecture decisions.

Example (coverage lift)

/goal Raise coverage in src/auth/ from ~38% to ≥75%. Read first: src/auth/, tests/auth/, AGENTS.md. Constraints: no new deps; mirror existing test style; do not modify production code unless strictly required for testability. Validate with: pytest --cov=src/auth --cov-report=term-missing. Work in checkpoints; log coverage delta each one. Stop when: coverage ≥75% AND all tests pass, OR when uncovered code needs design changes.

Writing rules

• One objective, one stop condition. Not a backlog.
• Use literal strings for paths, commands, issue numbers — exact.
• Forbid scope creep explicitly: "Do not refactor unrelated code. Do not add dependencies."
• Tell Codex when to pause: "If <condition>, pause and ask before proceeding."
• Short, vague goals burn tokens for no extra value vs. a normal prompt.

Meta-prompting trick (highest-leverage)

Hand-written goals under-specify. Ask a second AI session (Claude with the codebase loaded, ChatGPT with project connected, or a separate Codex thread in the same dir) to: (1) inspect the codebase, (2) surface hidden assumptions/constraints/edge cases, (3) emit a dense /goal paragraph using the 4-part contract. Paste that into Codex. Order-of-magnitude better runs.

Launching

1. cd <repo> (goals run scoped to the working directory).
2. Run codex (bare — opens TUI). Not codex exec "/goal ..." — /goal is a TUI slash command only.
3. Sign in with ChatGPT (not API key).
4. Type /goal <your contract> in the composer, Enter.
5. Walk away.

Always launch on a branch or worktree. Never on main.

Controlling a running goal

Resuming across sessions: goal state is persisted server-side. cd back into the repo, run codex, /goal for status, /goal resume.

Budget-limited state: Codex doesn't stop abruptly — it summarizes, notes what's left, saves state. /goal resume works after budget refresh or upgrade.

When a goal drifts

• Minor drift: just type a correction in the composer (auto-pauses, folds it in, resumes).
• Loose objective: /goal pause, read status, then /goal <tighter version> — replaces the contract. Don't pile instructions on a vague goal.
• Bad mess: /goal clear, git reset --hard HEAD or git stash, rewrite with the meta-prompting trick, restart.

Don't let a drifting goal keep running "to see where it goes." Tokens burn, diffs compound.

Operational tips

• Inspect status periodically with bare /goal.
• Always review the diff before merging — long autonomy means more code to validate, not less. Human oversight becomes more critical, not optional.
• Keep approvals/sandboxing tight; default permissions are correct.
• First run: pick a 30-min scoped task so you learn how /goal actually stops before trusting it overnight.

Troubleshooting

Mental model

/goal is a contract enforcer with a verification loop, not a "run forever" button. The shift: stop writing prompts, start writing specifications with stop conditions. Spend the time upfront defining "done"; the run takes care of itself.