Codex /goal is real in the 0.128.0 release line, but you should verify your installed CLI and command surface before building work around it.
As of May 4, 2026, OpenAI's public CLI slash-command docs still omit /goal; the 0.128.0 release/source tree and experimental app-server goal APIs are the stronger availability evidence.
Use it only for a bounded objective with deliverables, files, tests, budget awareness, and a stop rule; if /goal is missing or the objective is not ready to audit, use /plan first and re-check the local command list before continuing.
Quick Answer: Treat /goal as a Verified but Surface-Dependent Workflow
/goal is not a generic prompt trick. In the 0.128.0 Codex release line, it is a command for attaching an objective to a long-running task so the agent can keep that objective active across continuation, status, and completion checks. The 0.128.0 release evidence points to persisted goal workflows, app-server goal APIs, model tools, runtime continuation, and TUI controls for create, pause, resume, and clear.
The practical catch is surface drift. The public OpenAI CLI slash-command page read on May 4, 2026 still lists commands such as /plan, /status, /resume, /compact, /ps, and /stop, but not /goal. The public IDE slash-command page also does not present /goal as an IDE command. That does not make /goal fake; it means operators have to separate release/source evidence from what the current install or UI exposes.
Use this first decision table before trying a long run:
| What you see | What it probably means | Next move |
|---|---|---|
codex --version reports 0.128.0 or newer and /goal appears in the CLI command surface | You can test the goal workflow | Start with a small auditable objective |
| Your Codex install is older than 0.128.0 | The local binary may not include /goal | Update first, then re-check the command list |
Public docs omit /goal but your CLI exposes it | Docs may be behind the release/source tree | Use local behavior plus release evidence, but keep the claim dated |
The IDE or another surface does not show /goal | Surface support may differ from the CLI | Do not assume the CLI command exists everywhere |
| The work cannot be expressed as deliverables, files, tests, and stop rules | The objective is not ready for /goal | Use /plan or a normal conversation first |
The local machine checked for this run was running codex-cli 0.125.0, so that environment could not be used as proof of live /goal availability. That is exactly the operational problem: a fresh Codex feature can be real in the release line and still missing from the terminal you are using today.
What /goal Does in the 0.128.0 Evidence
The shortest observed TUI usage is:
text/goal <objective>
The 0.128.0 source describes the command as the way to "set or view the goal for a long-running task." The source also shows that the command supports inline arguments and can be used while a task is active. When there is no current goal and no objective text, the TUI usage path returns Usage: /goal <objective>.
That matters because you should not invent subcommands just because they sound natural. Do not teach yourself or your team to rely on forms such as /goal set, /goal audit, or /goal complete unless your own installed version explicitly documents or exposes them. The evidence for 0.128.0 supports the simple command form and a managed lifecycle behind it; it does not justify a fake command grammar.
Under the hood, the goal feature is closer to a persisted task contract than a longer system prompt. The release/source evidence ties it to:
- A stored objective for the active thread.
- Runtime continuation that can keep steering toward the objective.
- Token and wall-clock accounting.
- Budget-limit steering when the run should wrap up.
- App-server goal APIs for setting, getting, and clearing thread goals.
- TUI controls around create, pause, resume, and clear.
The continuation template is also conservative in an important way: it treats the objective as untrusted user data and asks Codex to audit concrete deliverables before marking work complete. The budget-limit steering says to wrap up rather than start new substantive work. In other words, /goal is not "let the agent run forever." It is goal persistence with a completion and budget model.
Why /goal May Be Missing
The missing-command case deserves special attention because many people will arrive after seeing demos, social posts, or release notes while their own CLI still behaves differently.
Start with version:
bashcodex --version
If you are below codex-cli 0.128.0, do not spend time debugging syntax. Your installed binary may simply predate the feature. Update Codex through your normal installation route, restart the terminal session if needed, and check again.
Then check the command surface. In an interactive Codex session, look at the slash-command list or autocomplete surface exposed by your current UI. A page in the public docs is useful, but the command list inside the running binary is the contract that decides what you can execute in that session.
Finally, separate CLI, IDE, app, and app-server concepts. The CLI release/source evidence for /goal does not mean every Codex surface has the same slash command. The app-server docs list thread/goal/set, thread/goal/get, and thread/goal/clear as experimental APIs behind capabilities.experimentalApi. That is useful evidence that "goal" is a real thread concept, but it is not the same as telling every end user to call those APIs.
Use this diagnostic sequence:
- Check
codex --version. - Open the CLI command surface and look for
/goal. - Confirm whether you are in CLI, IDE, desktop app, or an app-server integration.
- If
/goalis absent, use/planto shape the objective and rerun the version/surface check after updating. - If your team needs automation through app-server APIs, treat goal APIs as experimental and test capability flags before designing around them.
The safe conclusion is not "the feature does not exist." The safe conclusion is "this surface is not confirmed yet."
How to Write a Good /goal Objective
/goal only helps when the objective is audit-ready. If you give it a vague instruction, the agent can keep moving while still losing the actual job. The objective should tell Codex what success means, where it may edit, what evidence to collect, what tests to run, and when to stop.
Use this shape:
text/goal Implement <specific outcome> in <files or modules>. Acceptance criteria: - User-visible behavior: <what must change> - Files in scope: <paths or ownership boundaries> - Verification: <commands, tests, screenshots, logs, or manual checks> - Evidence to report: <diff summary, test output, changed paths, unresolved risks> - Stop rule: <budget, failing dependency, missing credential, or unclear product choice>
A weak objective is:
text/goal improve the dashboard
A usable objective is:
text/goal Add CSV export to the billing usage table. Acceptance criteria: - Add the export action beside the existing table filters. - Keep edits inside app/billing and shared CSV utilities. - Include account id, period, model, tokens, cost, and status columns. - Run npm test -- billing and npm run lint. - Stop if the billing API does not expose raw row data.
That second objective gives the agent enough context to continue without inventing the product decision. It also gives you enough evidence to review the result. If the objective cannot be made this concrete, use /plan first.
For route and account questions before running Codex, use the Codex API key vs subscription guide. If the risk is spend, quota, or long-running usage windows, keep the OpenAI Codex usage limits guide open while you shape the stop rule. If the issue is local configuration, the Codex config toml guide is the better next document.
A Safe Workflow for Long-Running Tasks
The useful lifecycle is plan, set, monitor, verify, and clear. You can adapt the exact controls to the surface you have, but the safety model should stay the same.
| Stage | What to do | Evidence to keep |
|---|---|---|
| Plan | Convert the request into files, acceptance criteria, verification, and stop rules | Objective text and scope notes |
| Set | Run /goal <objective> only after the goal is audit-ready | Command surface and version evidence |
| Monitor | Watch for paused, continued, or budget-limited behavior | Progress notes, changed files, command output |
| Verify | Compare the result against concrete deliverables before calling it complete | Tests, screenshots, logs, diff summary |
| Clear or continue | Clear the goal when done; continue only with a revised objective | Remaining risks and next action |
The most dangerous failure mode is false completion. A long transcript can feel productive even when the deliverable is not done. Before accepting the result, run a completion audit:
- Did the changed files match the declared scope?
- Did the agent run the promised tests or explain why they could not run?
- Did the result include artifact evidence, not just a summary?
- Did it avoid unrelated refactors and hidden product decisions?
- Did any budget-limited state require wrapping up instead of starting more work?
- Is there a clear reason to continue, or should the goal be cleared?
If any answer is weak, treat the task as incomplete. Ask for the missing evidence or revise the objective. /goal should make continuity easier; it should not lower your review bar.
When Not to Use /goal
Do not use /goal as the first move when the problem is still ambiguous. It is the wrong tool for brainstorming broad product direction, exploring an unfamiliar codebase with no success condition, or running expensive work without budget limits.
Avoid it when:
- The objective requires credentials, production access, or policy decisions you have not granted.
- The task spans too many ownership boundaries to review coherently.
- You cannot name a stop rule.
- You would not know how to tell whether the work is complete.
- You are trying to compensate for a weak prompt by making the agent run longer.
Use /plan first when the work needs decomposition. Use a normal focused prompt when the job is small. Use /resume or /compact for conversation continuity when you are not setting a new long-running objective. /goal is best reserved for work that is large enough to benefit from persistence but concrete enough to audit.
For broader tool-choice context, compare the operating model in Claude Code vs Codex. The key distinction here is not which agent sounds more autonomous; it is whether the workflow can prove that the final state matches the requested outcome.
FAQ
Is Codex /goal officially available?
It is real in the 0.128.0 Codex release/source evidence checked on May 4, 2026. Public CLI and IDE slash-command docs still lagged during this run, so verify your installed version and command surface before relying on it.
What is the syntax for Codex /goal?
The observed TUI usage is /goal <objective>. Do not assume extra subcommands unless your installed version explicitly exposes them.
Why does my Codex CLI not have /goal?
The most likely causes are an older CLI version, a surface that does not expose the command, or public documentation lag. Check codex --version, update if needed, and inspect the command list in the running CLI.
Is /goal the same as /plan?
No. /plan is better for shaping the approach before work starts. /goal should be used after the objective is concrete enough to persist, continue, and audit.
Can /goal run Codex unattended overnight?
Do not treat it that way by default. Use budget limits, concrete acceptance criteria, and reviewable evidence. A budget-limited wrap-up is not the same as success.
Should I use app-server goal APIs?
Only if you are deliberately building against the experimental app-server surface and have verified capabilities.experimentalApi. End users should start with the CLI command surface, not low-level thread APIs.