Codex /goal: run a persistent coding objective

The OpenAI Cookbook still states that Goals are available starting in Codex 0.128.0. Its installation and version-check instructions use the CLI. Run codex --version in your terminal to check that installation; this number is not a documented minimum desktop-app or IDE-extension version.

Current long-running-work documentation explicitly describes Goal mode in the interactive CLI, desktop app and IDE extension. Their controls are not interchangeable:

In a supported interactive CLI session, enter /goal followed by the outcome and acceptance criteria. These are Codex composer commands, not shell commands. The Cookbook lifecycle reference documents the forms below.

For the desktop app, type /goal to start, then use the progress row above the composer to inspect progress, pause, resume, edit or clear. The IDE docs confirm starting Goal mode, but do not establish identical pause/resume/clear command syntax there. That detail is UNKNOWN in the sources checked.

Clearing the Goal removes the objective. The cited documentation does not describe it as undoing edits; inspect your diff separately. Resuming a paused Goal is also different from reopening a saved CLI session.

A normal prompt asks for a result from the current request. A Goal keeps an outcome attached to the thread so Codex can revisit the evidence after a turn and decide whether another attempt is warranted. The benefit is a persistent objective plus repeated verification, not prompt length.

For example, a failing test may lead to reproduction, a small patch, a regression check and another hypothesis. A benchmark improvement can still miss the target. In either case, an intermediate result is not enough to declare the Goal complete.

The official continuation rules require an active Goal, available budget and an idle thread without queued input or other pending work. This is conditional continuation across turns; it does not guarantee an uninterrupted run lasting hours. The Goal belongs to this thread, not global memory or every task in the project.

OpenAI's Goal-writing guidance identifies six useful parts. Treat them as questions to answer, not a mandatory file format:

• Outcome: what observable result should exist?
• Verification surface: which test, measurement or artifact can confirm it?
• Constraints: which behavior must remain unchanged?
• Boundaries: which files, tools, data and environments are in scope?
• Iteration policy: what evidence should guide the next attempt?
• Blocked stop condition: which missing input or exhausted path requires a report back?

This original AgentSkillsHub template reorganizes those ideas. Replace every placeholder before use; it is not an official required syntax. If the target is still vague, ask Codex to draft it first and review the finish line before activating the Goal.

These are original, documentation-based examples—not completed runs. File names, measurements and trial counts are illustrative acceptance criteria. Substitute the actual repository paths, commands and approved target versions before starting. Combine each Goal with its verification, constraints and stop condition.

The Cookbook describes success, pause, clear, interruption, budget limits and blockers requiring user input as stopping conditions.

• Success: inspect the specified evidence and preserved constraints. A plausible explanation or partial improvement is insufficient.
• Pause or clear: the user controls whether the objective should continue or remain attached.
• Interruption: the documented dispatcher pauses the objective; check its state before expecting further work.
• Budget limit: substantive work stops with progress and blockers summarized. Exhausting a budget is not completion.
• Blocked: identify the missing input or decision and the evidence already collected; do not label an unresolved objective successful.

Plan-only work does not trigger automatic continuation. The Cookbook also says that a continuation without a tool call suppresses the next automatic continuation, preventing empty looping. If a Goal appears idle, check its state, pending input, permissions, budget and evidence before asking it to resume.

The sources checked here do not specify one universal budget-setting command or default budget across surfaces. Those details are UNKNOWN; use the controls actually available in your client. A natural-language experiment cap in a prompt is a task instruction, not proof of an enforced billing limit.

Use a normal prompt for a single-file edit, a well-defined one-off bug fix, a short explanation or work that needs no iterative verification. A longer instruction alone does not make Goal mode useful.

Do not activate a vague target such as “improve this repository.” First choose a measurable result. If the evidence source is unavailable, resolve that dependency or define an honest report as the outcome.

Do not leave continuing paid API calls, production writes or external actions open-ended. Establish permitted actions, limits and approval checkpoints before starting. These selection guidelines follow the official advice on when not to use Goals, with additional editorial recommendations for spending and production boundaries.

Starting a Goal does not widen tool access or replace the existing sandbox and approval policy. The current long-running-work guide explicitly preserves those controls; approval documentation explains their separate roles.

Codex may run tests, benchmarks, tools or browser checks only within the access and authorization already available. Repeated work can consume model allowance and, where authorized tools use them, external API credits. A Goal does not supply paid-service authorization.

As an editorial setup checklist, name the allowed repository and environment, whether writes are permitted, and who approves production deployment, destructive database operations, paid API usage, external messages and account changes. For a local coding trial, explicitly exclude those actions unless they are part of the approved task.

When the work stops, review the diff, measurements, test output and unresolved claims. Our agent workflow case studies show ways to organize evidence. Use the Codex Skills guide when you need reusable task instructions alongside the Goal; a skill and a persistent objective serve different purposes.