Using Goal Mode in Codex

In Codex, a goal is a persistent task that lets a thread keep moving toward a defined outcome across multiple turns. A goal gives Codex a completion condition: what should be true, how success is verified, and which constraints must stay unchanged.

For large coding tasks, Codex already performs quite well — for example, inspecting repository state, fixing bugs, analyzing failures, or implementing specific adjustments.

Goals suit tasks where the next action depends on what Codex learns along the way: for example performance analysis, patch fixes, benchmarking, reproducing flaky tests, or turning a research question into an evidence-backed audit.

These tasks don't need more prompting; they need a clear, persistent goal. In goal mode, Codex keeps its attention on the progress of the current goal, automatically assesses whether the work is done, and decides on its own what action to take next, without you having to interrupt each time. Put plainly: in goal mode, you just wait to accept the result once the final goal is complete, and you don't have to keep prompting Codex to continue in between.

"Goal" mode is not completely unbounded background autonomy. Rather, it is a user-controlled completion protocol with a clear scope. When you define an outcome, Codex works from the evidence in the thread, and the goal can be paused, resumed, cleared, completed, or terminated because plan usage has run out.

Prerequisites

• A version of Codex that supports goals

• A task with clear completion criteria and a verifiable source of evidence, such as tests, a benchmark or a final deliverable.

• Enough repository or research context for Codex to verify progress, not just describe it.

Quick Start: Using Goals Mode

To use the "goal" feature, install or update Codex and confirm your version. The feature has been available since Codex 0.128.0. You can use the commands below to check or update your codex version.

PLAINTEXT

复制

 # Using npm
 npm install -g @openai/codex@latest
 codex --version
 ​
 # Using Homebrew
 brew update
 brew upgrade --cask codex
 codex --version

Then use the slash command "/goal" followed by the expected outcome to set a goal and turn on goal mode. For example:

PLAINTEXT

复制

 /goal Reduce p95 latency below 120 ms without regressing correctness tests

You can manage the lifecycle from the same command interface:

PLAINTEXT

复制

 /goal       View the current goal
 /goal pause    Pause the current goal
 /goal resume   Resume a paused goal
 /goal clear    Delete the current goal

Once a "goal" is in effect, Codex can inspect code, run related commands, make changes, test results, and keep executing until a stop condition is reached.

Stop conditions may include success, pause, clear, interruption, a budget limit, or a blocking condition that needs user input. Use "goals" when you find yourself repeating things like the following at the end of every turn.

PLAINTEXT

复制

 Keep going.
 Try the next likely fix.
 Run the benchmark again.
 Now check the tests.
 Continue until this is actually done.

Goal Mode vs. Prompt Mode

An ordinary prompt might be do this next.

A goal-mode prompt rule might be: keep working until this outcome holds.

This distinction matters. In an ordinary request, Codex carries out the instruction at hand, reports the result, and then waits. With a goal, Codex attaches a persistent objective to the thread.

After a turn ends, it can examine the current evidence and judge whether the goal has been met. If the answer is no, and the goal is still valid and within budget, Codex can continue from the latest state.

This makes "goals" most useful when the right next action depends on what Codex just learned. For example:

PLAINTEXT

复制

 /goal Reduce checkout latency in the p95 checkout benchmark to below 120 ms while keeping the correctness test suite passing (shown as green)

This request doesn't merely ask for better performance; it also gives Codex a measurable outcome, a basis for verification, and constraints. Codex can run the benchmark, inspect the hot paths, make targeted changes, rerun the benchmark, execute the correctness test suite, and keep optimizing if the result is still unsatisfactory.

How to Write a Goal

A good goal is more than just a broader prompt. It is a concise protocol that defines how Codex should operate, what counts as success, and what to do while success hasn't yet been reached.

A precise goal usually spells out these six points:

• Outcome: the state the work should reach when it is done.

• Evidence of verification: the tests, benchmarks, reports, artifacts, command output or source material that can prove the outcome.

• Constraints: what must never regress while Codex runs.

• Boundaries: which files, tools, data, repositories or resources Codex may use.

• Iteration strategy: how Codex should decide the next direction to try after each attempt.

• Blocked-stop condition: when Codex should stop running and report that no feasible path remains under the current limits.

A decent goal-setting template:

PLAINTEXT

复制

 /goal <desired end state>, verified by <specific evidence>, while satisfying <constraints>. Use <allowed inputs, tools or boundary conditions>. Between iterations, <how Codex should choose the next-best action>. If blocked or no valid path remains, <what Codex should report, and what would move things forward>.

For example, the goal below works, but is a bit rough:

PLAINTEXT

复制

 /goal Reduce p95 checkout latency below 120 ms without causing regressions in the correctness tests

We can optimize it:

PLAINTEXT

复制

 /goal Reduce p95 checkout latency below 120 ms (verified by the checkout benchmark), while keeping the correctness test suite "green". Use only the checkout service, the benchmark fixtures and the related tests. Between iterations, record what changed, what the benchmark showed, and the most promising experiment to try next. If the benchmark can't run or no valid path remains, record the paths tried, the evidence gathered, the blocking problem and the input needed next, and stop the current iteration.

The same principle applies to research and investigation. The evidence standard should be set before the work begins, especially when conclusive evidence may be unavailable:

PLAINTEXT

复制

 /goal Using the available materials and local resources, reproduce the paper's findings as accurately as possible, and provide the strongest supporting evidence. Where feasible, try to reproduce the main results, verify outputs as far as possible, and end the report by clearly separating confirmed findings, approximate reconstructions, refuted claims and remaining uncertainty.

A goal like this leaves Codex room to explore while ensuring the final result is truthful. By clearly defining what "done", "blocked" and "not yet certain" mean, it goes beyond the simple request to "keep going". When a task is clear but the goal is not yet clear, Codex can help write the goal itself. A simple two-step workflow works well:

• First, describe the work in plain language and let Codex turn it into a draft goal;

• Second, before activating the goal, review the draft and refine the success conditions, the verification scope, the constraints and the blocked-stop conditions.

For example:

PLAINTEXT

复制

 Please help me turn this into a strong `/goal`: I want Codex to keep investigating this flaky checkout test until we fix the problem with evidence, or can clearly explain what is blocking progress.

Codex can then propose a fuller goal, ask about any genuinely necessary missing details, and give you a more concise /goal to use. This is in fact a kind of Codex bootstrapping: have codex draft a goal itself, then use goal mode to accomplish that goal itself.

What Changes When a Goal Is Active

When a goal is active, three things change.

• First, the goal stays visible. If a test Codex runs fails, the thread still keeps the original goal. If the benchmark result improves but doesn't reach the threshold, Codex can keep running. If the research path runs into missing data, Codex can adjust the evidence plan without departing from the research standard.

• Second, an idle thread can continue executing. Codex does not continue when another turn is active, user input is queued, or other thread work is pending. It continues only when the thread is idle and the goal is active and within budget.

• Third, completion must be based on evidence. A goal shouldn't be marked complete just because the model thinks it "may be done". It should be considered complete only after it has been verified against relevant files, tests, logs, benchmark output, generated artifacts or other concrete evidence. This is the core of the design: Codex can keep pushing forward, but whether it is done is decided by evidence.

How Goals Are Designed in Codex:

Goals are implemented as persistent thread state, not global memory and not project-level instructions. This design choice is crucial: a goal belongs to the thread that contains the relevant context, including the files Codex has inspected, the commands it has run, the diffs it has generated, the logs it has viewed and the reasoning trail it has built.

At the architectural level, a "goal" is a persistent state that is valid within a thread's scope. It records the objective, lifecycle, budget and progress statistics Codex needs to evaluate that thread over time. The key delineation is scope: a "goal" belongs to the current thread, not to global memory or project instructions.

Codex treats this state as a contract among the user, the model and the thread. A "goal" can be active, paused, complete or budget-limited. These states determine whether Codex may continue executing, whether it should wait for the user, and whether it should summarize progress rather than start new work.

Continuation is event-driven, not a simple loop. Codex checks whether to continue only at safe boundaries: when a turn ends, when no other work is pending, when no user input is queued, and when the thread is idle.

The scheduler's behavior is deliberately conservative by design. Planning-only work does not trigger continuation. An interruption pauses execution of the goal. When appropriate, resuming a thread can restart the goal. If a continuation turn invokes no tools, the next automatic continuation is suppressed, so that Codex doesn't get caught spinning idle.

The prompt layer reinforces this architecture. Continuation prompts keep Codex working around the current goal, but those prompts also need to be audited before completion. Codex must compare the goal against concrete evidence: file changes, commands run, tests passed, benchmark results, generated artifacts or research evidence.

Budget management is explicit. When the budget limit is reached, Codex should stop substantive work, summarize progress and blockers, and identify the next useful action. Reaching the budget limit does not equal completing the goal.

The tool contract limits lifecycle control. The model may start a goal, but may mark an existing goal as complete only when evidence supports completion. Pausing, resuming, clearing and budget-limited transitions remain under the control of the user or the system.

The architecture to keep in mind: a goal is a completion contract scoped to a thread. It combines persistent goal state, lifecycle control, a continuation policy, budget accounting and evidence-based completion. The point isn't to make Codex loop forever, but to keep the goal in place until the evidence shows the work is done.

Turning a Vague Goal into a Clear One

The strengthened version gives Codex three things: an outcome, a verification method and a constraint. It also gives Codex a way to judge when it should not stop. If p95 improves from 180 ms to 135 ms, the goal is not yet met. If latency drops below 120 ms but the correctness tests fail, the goal is not yet met. If the benchmark can't be run, Codex must point out that blocker rather than declare success.

This rule also applies to work beyond performance optimization: a goal should be specific enough to verify, yet open enough to support exploration.

A goal should be specific enough to audit, yet broad enough to let Codex choose the next action. "Fix the failing checkout test" may be too narrow if the real problem lies in an upstream dependency; "improve the whole system" is too broad because it offers no auditable entry point. By contrast, "make the checkout test suite on the current branch pass without changing public API behavior" is a better goal.

A rough version of a goal might look like this:

PLAINTEXT

复制

 /goal Write documentation for this feature

And a robust, well-developed goal should be:

PLAINTEXT

复制

 /goal Create a documentation page for "Goals" that explains its lifecycle, command interface and two examples. Verify that the page builds locally, and ensure all referenced commands match the behavior of the current CLI.

The second goal gives Codex things it can check: a page, a build command, and the behavior of the commands. For research goals, this rigor matters especially. Before the investigation starts, the evidence standard should be set first: what counts as an exact reproduction, what counts as a partial reconstruction, what counts as indirect support, and what should be treated as blocked.

A strong research goal should ask Codex to build a claims list, map claims to evidence, carry out the parts that are feasible, flag blockers, and produce an audit report that separates confirmed claims, merely supporting evidence, blocked claims and remaining uncertainty. This makes the goal specific enough to audit without prescribing the whole path in advance. Codex can choose its own next action, but the completion criteria are fixed.

When Not to Use Goal Mode

Goals aren't the right tool for every task. For one-line code changes, simple explanations, short code reviews, or questions that end with a single answer, don't use "goals". Those cases suit an ordinary Codex prompt better.

Don't use "goals" when the objective is unclear. "Improve this code" gives Codex no reliable completion condition. "Refactor this code" is just as limited, unless you clearly define the expected end state, the test cases and the constraints.

Don't use "goals" to mask uncertainty. If the data may be unavailable, say so in the goal; if the benchmark may be flaky, say how to handle it; if substitute evidence is allowed, define how it should be labeled.

References and citations:

• https://developers.openai.com/cookbook/examples/codex/using_goals_in_codex#quickstart-using-goals

+