Goals: From One-Off Instructions to Persistent Task Contracts
Traditional AI code interaction follows a single-cycle “instruct-execute-wait” pattern, requiring users to provide explicit instructions in every round. The Goals feature, introduced by OpenAI for its Codex model, breaks this pattern by introducing a persistent objective mechanism. With Goals, users can set a long-term “completion contract” for Codex, which clearly defines the task’s final state, validation criteria, and procedural constraints.
The core value of Goals lies in handling exploratory or iterative tasks where the next action depends on the previous result. Examples include performance tuning, reproducing flaky bugs, dependency library migration, benchmark-based parameter searching, and research projects requiring extensive documentation. In these scenarios, Goals allow Codex to autonomously check progress, analyze evidence, decide on the next strategy, and continue working within a set budget and boundaries until a predefined, evidence-verifiable completion condition is met.
How to Build and Manage an Effective Goal
As of Codex version 0.128.0, the Goals feature is available through the /experimental interface of the Codex command-line tool (CLI). Users can enable this feature by updating Codex to the latest version via npm or Homebrew.
Lifecycle management commands include:
/goal <description>: Set or view the current goal./goal pause: Pause the currently active goal./goal resume: Resume a paused goal./goal clear: Remove the goal from the current thread.
An effective Goal is not a lengthy instruction but a concise contract. A “strong Goal” typically defines the following six elements clearly:
- Result: Describes the exact state when the work is complete.
- Validation: Specifies the evidence used to prove the result, such as a specific test suite, benchmark report, or command output.
- Constraints: Explicitly states which metrics or states must not regress during task execution.
- Boundaries: Limits the files, tools, and resources that Codex can use.
- Iteration Strategy: Guides Codex on how to evaluate and choose the next action after each iteration.
- Blocking Conditions: Defines how Codex should report a roadblock and request user intervention when the task cannot proceed.
Weak Goal Example:
/goal reduce p95 checkout latency to under 120ms without causing correctness test regressions
Strong Goal Example:
/goal reduce p95 checkout latency to under 120ms, verified by the checkout benchmark, while ensuring the correctness test suite passes completely. Use only the checkout service and related tests. After each iteration, log the changes, benchmark results, and next plan. If the benchmark fails to run or there's no viable path, stop and report the attempted paths, evidence, and the blocking point.
Internal Architecture and Working Mechanism
Architecturally, a Goal is a persistent and thread-scoped state, not a global memory. It tightly binds the objective to the context within the thread (such as checked files, run commands, and generated code changes). This design choice ensures the relevance and contextual consistency of the goal.
A state machine manages the Goal’s lifecycle, including states like active, paused, completed, and budget exceeded. The Codex scheduler uses these states to decide whether to continue the task in an event-driven and conservative manner. Codex will only resume work automatically when the thread is idle, the goal is active, the budget is sufficient, and no user input is queued. This mechanism prevents the model from acting autonomously at unsafe or inappropriate times, such as when a user is typing or another task is in progress.
Budget management is another key constraint of this mechanism. When the preset budget limit is reached, the Goal stops, and Codex will summarize the current progress, collected evidence, and encountered obstacles, rather than incorrectly marking “budget exhausted” as “task completed.”
Practical Case: Using Goals for Complex Research Replication
Goals demonstrate their unique value in complex research tasks that require rigorous verification. For example, when attempting to replicate the paper “Deep Hedging” by Buehler et al., a vague objective like /goal replicate the paper is ineffective.
A stronger research Goal should be defined as: Using the available materials, produce the strongest evidence-backed replication of the paper’s core conclusions and generate an audit report. This report must clearly distinguish between: which mechanisms were successfully replicated, which are based on approximate training results, which were hindered by missing materials, and any remaining uncertainties.
When executing this Goal, Codex breaks down the complex paper into multiple verifiable evidence channels:
- Reconstructing pricing and hedging mechanisms that can be tested locally.
- Training neural network policies to approximate the experiments in the paper.
- Annotating parts that cannot be precisely reproduced due to missing original training data, random seeds, or model checkpoints.
Ultimately, what Codex produces is not a simple “success” declaration but a layered audit report. For instance, for a specific conclusion, the report will detail its validation path, evidence source, replication status (e.g., “near-approximate replication”), and remaining uncertainties. This method ensures the rigor of the research process and the honesty of the conclusions, preventing over-claiming based on insufficient evidence.
Applicable Scenarios and Limitations
Goals are not suitable for all tasks. For simple single-line code modifications, code explanations, or brief code reviews, the traditional prompt-based interaction model is more direct and efficient. Similarly, tasks with a vague endpoint (like “optimize the code”) are not suitable for Goals unless they can be transformed into a strong Goal with clear validation criteria and constraints.
The Goals feature is most powerful for tasks that simultaneously possess the following three characteristics:
- Persistent Objective: The task requires multiple rounds of interaction to complete.
- Evidence-Driven: The task’s completion state can be verified by objective evidence (e.g., tests, benchmarks).
- Exploratory Path: The solution path is uncertain and requires multiple rounds of investigation and trial based on intermediate results.
