How to Use Codex /goal: Enable Steps, Commands, and Objective Examples¶

For / Key Points

For: Developers who enabled the Codex CLI goals feature but are unsure what to put into /goal.

Key Points:

A /goal objective should be an AI-designed, human-approved work order, not a wish
Include acceptance criteria, scope, verification, evidence, and a Stop rule
Vague prompts feel convenient, but they break completion audit on long-running work

The first problem after enabling /goal is simple: what should you actually type? Make the codebase better. looks like a reasonable instruction. Codex can even start working from it. The problem is that it has no reliable way to prove when "better" is done.

In this article, the full text you paste into /goal is the objective. The question is not how to write that objective by force. The question is how to have AI design it, then have a human approve the boundary before Codex runs. The mechanics are covered in Codex /goal Deep Dive. This guide focuses on practical objective writing.

Have AI design the objective¶

In practice, writing a clean objective by hand every time is not realistic. The person who has been typing "keep going" repeatedly will not suddenly produce perfect acceptance criteria, scope, verification, evidence, and Stop rules. If you use /goal, have AI design the objective first.

OpenAI's /goal use case also points in this direction: start by discussing what you want to build, then ask Codex to set a goal and start working. ³ In other words, /goal is not where you paste a vague request. Before execution, use an AI conversation to turn the request into a work contract.

You can do that preflight conversation in the same Codex session, or you can use another AI or skill to generate only the objective and paste it into the TUI. The important part is to decompose the rough request into what may change, how it will be verified, and when it must stop before execution begins.

OpenAI's public Skills catalog does not currently appear to include a curated skill dedicated to /goal objective design. The openai/skills repository catalogs Codex skills, but the listed skills focus on deployment, Figma, Playwright, security, GitHub work, and similar workflows rather than goal / objective design. ⁵

Third-party skills are starting to appear. One example is goal-prompt-builder, distributed as a Claude Skill for generating paste-ready /goal prompts from rough requests. Its README describes a five-section template, project-type detection, AGENTS.md / CLAUDE.md reading, and an audit-friendliness score before rendering. ⁶

The practical workflow is three steps.

Give a rough request to AI or an objective-generation skill
Ask it to decompose the request into /goal objective, Scope, Verification, and Stop rules
Review risky boundaries, then paste the result into the Codex CLI TUI and run it

That workflow makes objective design much less annoying. The caveat is that AI or a third-party skill's output still needs human review. The person who runs /goal owns the final instruction.

/plan and /goal do different jobs¶

The natural question is: is this just /plan again? No. /plan is a pre-execution design mode. /goal is an execution lifecycle that keeps working against an already defined objective.

Use /plan to organize what should happen. It is good for surfacing acceptance criteria, scope, validation commands, and risks. But /plan itself does not keep a durable objective attached across turns, audit real evidence until the objective is complete, or summarize state when a budget is reached.

/goal is different in that specific way. It keeps the objective attached to the thread, returns to the same stopping condition on later turns, and audits requirements against evidence before completion. /plan produces the plan. /goal uses that plan to continue execution and decide when to stop.

In practice, use them together. First use /plan or normal chat to draft the objective. Then turn that draft into a paste-ready /goal contract. Finally run /goal <objective>. That gives /plan the design job and /goal the continuation and completion-audit job.

Command	Main job	Output	Best when
`/plan`	Pre-execution design	Steps, risks, acceptance criteria	The work is not shaped yet
`/goal`	Long-running objective retention	Progress, verification, stop state	The target is already defined

Can a goal include the whole workflow?¶

Can the objective say "plan, review, implement, verify, and repeat if needed"? Yes. But that is not the same as asking Codex to run nested slash commands internally.

The official slash-command docs describe /plan as a command the user types to switch into plan mode, and note that it is temporarily unavailable while a task is already running. ⁷/goal is also a TUI command the user uses to set, inspect, pause, resume, or clear a goal. ⁷ So instead of writing "run /plan inside this goal," write the workflow as natural-language checkpoints: create a plan, review it, implement the bounded change, run verification, and audit the evidence before marking the goal done.

OpenAI's /goal use case recommends checkpoints, progress logs, and commands or artifacts that prove progress. ³ That points to the current practical pattern: not a goal that nests slash commands, but a goal that includes planning, review, implementation, and verification as phases.

Example:

/goal Fix the checkout API authorization bug through planning, implementation, verification, and review.

Behavior:
Expired-card and authorization-failed orders must not be treated as successful.

Checkpoints:
1. Read the related files and existing tests, then write a short implementation plan.
2. Review the plan for authorization, API compatibility, and missing test risks.
3. If the plan is sound, change only payment validation and related tests.
4. Run npm test -- checkout. If it fails, diagnose and fix within scope.
5. Before completion, audit changed files, test results, and remaining unverified risks.

Stop rules:
Stop if gateway behavior is undocumented, auth ownership is unclear, or production credentials are required.

This objective is not invoking /plan as an inner command. It is including planning, review, implementation, verification, and final audit inside the /goal execution loop. That is where /goal becomes useful: it can wrap a plan-driven workflow, not merely replace plan mode.

Objective-generation prompt¶

When asking AI for help, do not just say "make a good /goal." Give the rough request and force a fixed output shape.

Convert the following request into a paste-ready Codex CLI /goal objective.
/goal is an experimental long-running feature and needs a verifiable stopping condition.

Request:
[write the rough request here]

Use this output shape.

/goal [one-sentence Objective]

Behavior:
Scope:
Non-goals:
Canonical sources:
Checkpoints:
Verification:
Review:
Commit / push: (when code changes should be delivered)
Evidence to report:
Stop rules:

Rules:
- Replace vague language with files, behavior, commands, and evidence
- Put unknowns in Stop rules instead of guessing
- Stop explicitly if production actions, credentials, or danger-full-access are required
- Keep the first goal small enough to finish and review

The value of this prompt is that it turns a rough request into a contract for end-to-end execution. Because /goal can run longer, a vague entry point means longer confusion. The human job is not to write the perfect objective from scratch. It is to approve the boundary, verification path, and Stop rules created by AI.

Use five lines for small goals¶

You do not need the full template every time. For small tasks, five elements are often enough. A good /goal objective looks like a short work order.

You can write the natural-language parts in your working language. Keep file paths, commands, issue numbers, and API names in their exact literal form. That keeps the instruction readable while preserving the strings Codex must match.

/goal Add CSV export for the Orders admin page.
Behavior: Admin users can download filtered orders as CSV from the existing Orders page.
Scope: Modify only src/admin/orders/*, src/api/orders/*, and related tests.
Verification: Run npm test -- orders and npm run typecheck.
Evidence: Report changed files, test commands, and one sample CSV header.
Stop rule: Stop if auth requirements, CSV columns, or existing API ownership are unclear.

This gives Codex the artifact, boundary, verification path, and reporting format. Evidence reduces human review time. Stop rule tells Codex when it should stop instead of inventing missing requirements.

/goal increases autonomy, but it does not remove the need for boundaries. The clearer the approved boundary, the less the agent has to guess.

Why vague objectives fail¶

The failure mode is not that Codex refuses to work. The risk is that it keeps finding more work. continuation.md tells the model not to accept proxy signals by themselves, so vague objectives tend to remain open-ended. ²

Bad objective	Likely behavior	Better version
`Make the codebase better.`	Infinite improvement space; audit cannot close	`Fix the top 3 ESLint errors in src/payments and run npm run lint -- src/payments.`
`Refactor the API layer.`	No proof that behavior stayed stable	`Split src/api/orders.ts into route, validation, service files without changing responses. Run existing API tests.`
`Improve UX.`	No observable definition of improvement	`Reduce checkout form error recovery from 3 visible errors to inline field messages for email and card fields.`
`Make tests better.`	Test writing becomes the goal	`Add regression tests for issue #123 so the failing case passes before implementation and remains green after fix.`

Vague prompts are useful for brainstorming. /goal is different. Once the agent is expected to continue and audit completion, abstract words must become files, behaviors, and commands.

Use "which file, which behavior, which command" as the conversion rule. That one check catches most bad objectives.

Check the feature only when it fails¶

If /goal feels enabled but does not work, first check where you are typing it. /goal is a slash command inside the interactive Codex CLI TUI, not a normal shell subcommand. The Codex CLI 0.128.0 release notes say it added /goal workflows, continuation handling, and TUI controls. ¹

/goal is still documented as experimental, and whether the goals feature flag is enabled depends on the local build and configuration. Check both the version and the feature flag before opening the TUI.

codex update
codex features list | grep goals
codex features enable goals
codex features list | grep goals
codex

codex features enable goals updates config.toml. Run codex features list | grep goals again and confirm that goals ... true is shown. After launching the TUI, enter /goal ... in the interactive input field.

The practical warning is that codex exec "/goal ..." may not behave like the TUI slash command. If /goal does not appear, check the version, feature flag, and TUI command picker first.

Do not create internal templates¶

continuation.md and budget_limit.md are not files you create in your repository. They are internal /goal prompt templates bundled in the OpenAI Codex repository. ²⁴ In normal use, you do not create, edit, or copy them.

You type /goal <objective> in the TUI. Codex keeps the objective, elapsed time, token budget, and remaining tokens as runtime state. When the next turn should continue, it inserts the continuation.md instructions as the next work instruction.

When the budget is reached, budget_limit.md tells the agent not to start new substantive work and to summarize progress and remaining work instead. The reason to know this is not to edit those files. It is to write objectives that contain auditable requirements and stopping conditions.

Pick the right task¶

/goal fits tasks that already have verification commands. Those tasks can move through repeated inspect-change-test cycles. OpenAI's /goal use case calls out long-running coding work with clear success conditions and validation loops, including code migrations, large refactors, deployment retry loops, experiments, games, and side projects. ³/goal adds objective retention and budget-aware stopping to that loop.

Task	Fit	Why
Known migration	High	Scope, success criteria, and verification are definable
Failing-test repair	High	Red-to-green evidence is clear
Feature addition	Medium	Strong when behavior, permissions, and checks are specified
Research report	Medium	Works if evidence and source requirements are explicit
Design consultation	Low	The center is decision-making, not completion
Broad quality improvement	Low	The improvement space has no natural end

When unsure, use /plan first. If the plan cannot produce acceptance criteria, the task is not ready for /goal. Copy the acceptance criteria, verification commands, and Stop rule from the plan into a bounded /goal objective before starting the loop.

Read stops as state, not failure¶

When /goal stops, first ask why it stopped. This section uses four categories for reading the stop. budget_limit.md tells the agent not to start new substantive work after the budget is reached, and instead to summarize progress, remaining work, blockers, and next steps. ⁴

Ending	Meaning	Next move
`achieved`	Completion audit passed	Review the evidence and proceed
`budget_limited` / `budget-limited`	The budget ended before the work did	Narrow the remaining work and start a smaller follow-up goal
`unmet`	A blocker or uncertainty remains	Supply missing information, access, or dependency decisions
`paused`	Human interruption or judgment is needed	Edit the objective and resume

The internal template uses budget_limited; this article also uses budget-limited for readability. Do not read it as "Codex failed." If the remaining work is specific, the loop stopped usefully. The real failure is an ending that leaves no clear evidence and no clear next step.

Sample objectives you can copy¶

Start with small, reviewable objectives. A bounded two-hour task teaches /goal behavior better than a whole-repository improvement request.

For a first trial, use documentation updates or test additions. They have narrow scope and easy verification. Feature additions and migrations are better after you understand how /goal stops.

Use case	Objective example
Bug fix	`/goal Fix issue #123 where checkout accepts expired cards. Scope payment validation and tests only. Verify with npm test -- checkout. Report changed files and failing-before/passing-after evidence. Stop if gateway behavior is undocumented.`
Test coverage	`/goal Add regression tests for CSV export escaping commas, quotes, and newlines. Do not change production code unless a real bug is found. Verify with npm test -- csv. Report the exact cases covered.`
Small migration	`/goal Replace deprecated Pydantic v1 validators in app/schemas/user*.py with v2 field_validator. Keep API behavior unchanged. Run pytest tests/schemas and mypy app/schemas. Stop if runtime version is not Pydantic v2.`
Documentation	`/goal Update the Codex setup docs to mention goals feature flag and TUI-only usage. Scope docs/generative-ai/chatgpt only. Run markdown link checks. Report links changed and commands run.`

This size keeps review possible. If you shorten these examples back into abstract requests, you lose the thing that makes /goal useful: auditable stopping.

Summary¶

Teams should not treat /goal as a universal long-running execution button. Start with tasks that have verification commands, scoped files, and no production credentials.

Use three rules.

Require Scope, Verification, and Stop rule in every /goal objective
Route danger-full-access or production-affecting goals through a separate approval flow
Before reusing a budget-limited summary, narrow the remaining work manually

The benefit of /goal is fewer human "keep going" prompts. The cost is that vague work can run longer than it deserves. Practical use is not about trusting Codex more. It is about having AI design the objective, then having a human approve the boundary and Stop rules.

openai/codex, Release 0.128.0. ↩
openai/codex, codex-rs/core/templates/goals/continuation.md. ↩↩
OpenAI Developers, Follow a goal. ↩↩↩
openai/codex, codex-rs/core/templates/goals/budget_limit.md. ↩↩
openai, Agent Skills catalog. ↩
win4r, goal-prompt-builder. ↩
OpenAI Developers, Slash commands in Codex CLI. ↩↩