Codex Goals Guide: How to Make Long-Running Tasks Actually Finish

If you repeatedly type “keep going,” “try the next fix,” and “run the benchmark again,” the missing ingredient may be persistence rather than prompt length. A Codex Goal attaches a finish line to the thread so work can continue after intermediate results.

A Goal is not unbounded autonomy. You define the outcome and operating boundary; Codex evaluates tests, benchmarks, files and reports in the thread to decide whether the evidence supports completion.

Use a Goal when the finish is clear but the path is not

Performance tuning, flaky-test reproduction, migrations and iterative bug investigation fit because the next action depends on the latest result.

A typo, short explanation or one-pass review should remain a normal prompt. A Goal is state for work with a durable objective and uncertain route.

The /goal lifecycle

The official guide says Goals are available starting with Codex 0.128.0. Start one with /goal followed by the objective. Use the bare command to inspect it and pause, resume or clear to control the lifecycle.

The Goal is thread state, not global memory or a project instruction. It stays with the files, commands, diffs and failed attempts in that thread.

/goal Reduce p95 checkout latency below 120 ms without regressing correctness tests
/goal          # view the current Goal
/goal pause    # pause it
/goal resume   # continue
/goal clear    # remove it

The six parts of a strong Goal

Outcome states what must be true. Verification names the test, benchmark, report or artifact that proves it. Constraints protect behavior; boundaries limit files, tools and data.

Iteration policy tells Codex how to select the next experiment. The blocked stop condition defines when no defensible path remains and what evidence and missing input to report.

• Outcome
• Verification surface
• Constraints
• Boundaries
• Iteration policy
• Blocked stop condition

From a weak Goal to an auditable contract

“Improve checkout speed” has no threshold or evidence. Adding “p95 below 120 ms” still omits correctness and the measurement environment.

A strong Goal is not strong because it is long. It is strong because success, failure and uncertainty can be distinguished.

/goal Reduce checkout p95 below 120 ms on the checkout benchmark while keeping the correctness suite green.
Use only the checkout service, fixtures and related tests.
After each iteration, record the change, result and next best experiment.
If the benchmark cannot run or no valid paths remain, stop with attempted paths, evidence, blocker and required input.

Evidence—not narration—decides completion

Plausible-looking code is not proof. Performance needs comparable before/after measurements; non-regression needs test results; documentation needs a successful build and accurate commands.

Research Goals should separate confirmed results, approximate reconstruction, support-only evidence, blocked claims and remaining uncertainty. Define that evidence taxonomy before investigation begins.

Why long-running Goals still fail

“Improve the whole system” has no audit surface. A Goal without a blocker policy can spin against missing access. A metric without correctness constraints can reward a harmful shortcut.

Read the final sentence before activating the Goal. If an outside reviewer cannot distinguish success from failure, neither can Codex. Make the evidence more specific, not the aspiration larger.

Frequently asked questions