Understanding the Codex CLI /goal Feature

AI Agent · 2026-05-02 · 9 min read

How to use a goal-based coding agent that tells you once and keeps working

In this article, we will summarize the /goalfunction added to Codex CLI 0.128.0.

This is not simply a story of adding a new slash command./goalis more of a way of telling Codex, “Keep working on this goal until it’s done.” Previously, once a response was completed, the user had to continue with instructions such as “Continue,” “Run the test,” and “Do the rest.”/goalis a function designed to continue the next task while maintaining the goal state.

This article looks at it from a usage and practical application perspective. The internal code structure is covered separately in Part 2.

Analysis base date: 2026-05-02 Base version: Codex CLI0.128.0 Key references: OpenAI Codex changelog, Codex GitHub PR #18073–#18077, Codex CLI slash command document, GitHub issue #19910/#20536 Note:/goalis a soon-to-be-launched feature. As of 2026-05-02 confirmation, it is reflected in the official changelog and PR, but the/goalitem is not yet visible in the official CLI slash command document. It is recommended to double-check the actual command name in the help of the installed version.

Key takeaways

/goalis a function that stores the goal in thread units and continues the continuation turn until the goal is completed.
Based on the official changelog, “persisted/goalworkflows” has been added to Codex CLI0.128.0.
/planestablishes a plan before execution,/resumeresumes the previous conversation, and/goalis close to a goal loop that continues the next task while maintaining the active goal.
/goalshould not be understood as an OS daemon function that continues to run in the background even if the terminal is closed. More precisely, it is a combination of target state storage + idle continuation + resumeable thread state.
In practice, it works well for “tasks that have clear completion criteria and require multiple turns,” such as refactoring, fixing test failures, finalizing feature implementations, or preparing PRs.

1. Why should I look at`/goal`separately?

If you use an AI coding tool for a long time, there is the most frustrating moment.

1# Reading Guide: The blocks below are examples of commands, state flows, or templates.2User: Please implement this feature and pass the test.3AI: Modified some files and ran tests. You're done up to this point.4User: Fix failed test.5AI: Fixed.6User: Run the full test again.7AI: One more failure.8User: Fix that too.

This flow must be continuously supervised by humans. Even if AI is good at fixing the code, humans still need to determine whether “the goal is over” and open the next turn.

/goaltouches on this point. The key is task continuity rather than the ability to generate code itself. When the user specifies a goal, Codex keeps that goal in the active state and continues with the next continuation turn when the session is idle.

Ultimately, in practical terms, this change is important.

1# Reading Guide: The blocks below are examples of commands, state flows, or templates.2Traditional method:3User prompt to one turn operation to stop to user instructed to continue4 5/goal method:6Save goal to Task to Completion Audit to If not completed Continue to Complete/Stop/Repeat until budget is reached

2. What does`/goal`do?

Based on the OpenAI Codex changelog, the persisted/goalworkflow has been added to Codex CLI0.128.0. The changelog describes this feature with the following components:

component	meaning
persisted workflow	Goal state is maintained on a per-thread basis
app-server APIs	Client can read, set, and clear goal state
model tools	The model can view, create, and complete goals in a limited way.
runtime continuation	If there is an active goal, you can continue to the next work turn.
TUI controls	Control goal creation, pause, resume or unpause, and clear in TUI

Simply put,/goalis not a “long remember prompt function”. This is a function that stores the goal state separately and connects the goal to the runtime life cycle.

An example goes something like this:

1# Reading Guide: The blocks below are examples of commands, state flows, or templates.2/goal Implement the login error reporting flow and make the test suite pass.

If you put it a little more practically, it goes like this.

1# Reading Guide: The blocks below are examples of commands, state flows, or templates.2/goal Implement the login error reporting flow.3Requirements:4- Add client-side error boundary reporting.5- Capture API 500 traces.6- Update tests for the new reporting behavior.7- Run lint and test.8- Summarize changed files and remaining risks.

If you give a goal like this, Codex is designed not to modify some files in one turn and then stop, but to continue with the next concrete action if it determines that the goal is not yet completed.

3.`/goal`vs`/plan`vs`/resume`

/goalis easy to confuse with the existing slash command. In particular, I am very confused with/planand/resume.

command	purpose	When to use	key differences
`/plan`	Establish a plan before implementation	When orienting yourself before implementation	Enters planning mode, but does not automatically repeat until the goal is completed
`/resume`	Resume previous session	When resuming a past conversation or task	This is a function to load transcripts, not a target loop.
`/goal`	Maintain active objective	When assigning a task that requires multiple turns	Maintain the goal state and continue if not completed

/planis closer to “Think about what to do first,” while/resumeis closer to “Let’s reopen the previous conversation.”

/goalis different. It is a unit of work that says, “Keep going until this goal is finished.”

1# Reading Guide: The blocks below are examples of commands, state flows, or templates.2/plan = pre-execution plan3/resume = resume previous conversation4/goal = goal-based continuous action

If you don't understand this difference, you will misunderstand/goalas simply a long prompt.

4. Actual usage example

Example 1. Fixing a test failure until the end

1# Reading Guide: The blocks below are examples of commands, state flows, or templates.2/goal Fix the failing test suite for this repository.3Requirements:4- Identify the failing tests.5- Explain the root cause before changing code.6- Apply the smallest safe fix.7- Run the failed test file again.8- Run the full relevant test suite.9- Stop only when tests pass or a clear blocker remains.

This goal is good. Because “what to do” and “when to stop” are clear.

Example 2. Entrusting function implementation and verification to others

1# Reading Guide: The blocks below are examples of commands, state flows, or templates.2/goal Implement CSV export for the admin user list.3Requirements:4- Add an export button to the admin user list page.5- Implement the API endpoint.6- Include user id, email, status, created_at columns.7- Add unit or integration tests for the export behavior.8- Run lint and relevant tests.9- Summarize changed files.

These tasks are well suited to/goal. This is because it takes several turns to implement features, modify files, run tests, fix errors, and finally summarize.

Example 3. Too bad goal

1# Reading Guide: The blocks below are examples of commands, state flows, or templates.2/goal Make this project better.

This is a bad goal. There are no completion criteria. No matter how well the Codex connects continuations, it cannot know what “better” is.

Example 4. Improved goal

1# Reading Guide: The blocks below are examples of commands, state flows, or templates.2/goal Improve the API error handling in this project.3Success criteria:4- Find all API routes that return unstructured 500 responses.5- Introduce a shared error response helper.6- Update at least the user and billing route handlers.7- Add tests for the changed routes.8- Run the relevant test command.9- Summarize any routes intentionally left unchanged.

A good goal includes the following elements:

element	explanation	example
Target	Which files/functions/areas to cover	admin user list, billing route
Requirements	must do	add tests, run lint
Completion criteria	When will you think it's over?	relevant tests pass
limits	What not to do	avoid schema migration
output	What to report at the end	changed files, risks

5. How to write a good goal

To use/goalwell, you need to write prompts as completeable objectives rather than “task instructions.”

Recommended templates are:

1# Reading Guide: The blocks below are examples of commands, state flows, or templates.2/goal [goal]3Context:4- [Current situation]5- [Work target]6 7Requirements:8- [Essential Requirement 1]9- [Essential Requirement 2]10- [Essential Requirement 3]11 12Constraints:13- [Areas that should not be touched]14- [Permission or Cost Restrictions]15 16Verification:17- [Command to be executed]18- [Files or results to check]19 20Final response:21- [Summary of changed files]22- [Test results]23- [Remaining Risk]

In practice, it is especially important to specifyVerification. Codex's goal continuation prompt is also designed to check evidence such as actual files, command output, and test results before completion. The more clearly the user enters the verification criteria in the goal, the better the quality of the termination decision.

tip: In/goal, “leave evidence to determine that it is finished” is more important than “do a lot of work.”

6. How does the work continue?

From a user perspective, the flow goes something like this:

1# Reading Guide: The blocks below are examples of commands, state flows, or templates.2User: /goal <goal>3↓4Codex saves the goal state5↓6Read files, modify them, run commands, and perform tests in the current turn.7↓8At the end of the turn, goal runtime checks the goal status9↓10If not completed yet, select next task with continuation prompt11↓12If the session is idle, execute the next continuation turn13↓14Repeat until one of the following: complete, pause, clear, interrupt, budget limit

The important thing here is that it is not an “infinite while loop”. The core runtime starts the continuation turn when the session is idle, and takes precedence over any user input or other tasks. Additionally, a defense device is included to suppress repeated continuations if the continuation turn ends without an actual tool call.

In other words,/goalis not a function that simply repeatedly inputs “Continue” to the model, but is a structure in which runtime manages the goal state and turn life cycle together.

7. What tasks is it suitable for?

/goalis not suitable for all tasks. It is especially suitable for “tasks that have clear completion criteria, require multiple steps, and can be verified.”

scenario	Recommendation	reason
Fix test failure	height	The failure to fix to rerun to verification loop is clear.
Function implementation + testing	height	Can provide clear deliverables and completion criteria
massive refactoring	medium to high	Task persistence is useful, but scope restrictions are important
PR summary preparation	middle	It's good for organizing changes, but it's better to separate it from the implementation goal.
Edit one simple file	lowness	Normal prompt is faster
Ambiguous product improvements	lowness	Risk of overwork due to unclear completion criteria
Automatic correction of security-sensitive code	lowness	Authorization, data transmission, and secret exposure must be reviewed first.

When recommended

Tasks that have a verification loop, such as “Fix until all tests pass”
Implementing the ability to touch multiple files
When step-by-step work is required, such as migration, refactor, or lint fix
When the cost of having a person enter “Continue” every now and then is high.
When final deliverables and test instructions are clear

When it's best to avoid

Planning work where requirements have not yet been determined
Company code base that is difficult to give permission to auto-correct
Operations that require strict limits on cost and token usage
A task that requires just one small change
Security, payment, and authorization codes that can cause significant damage if the model determines incorrectly.

8. Cost, permission, and security risks

/goalis convenient, but as it is a long-term operation, the risk also increases.

cost risk

Automatically continuing multiple turns increases token usage. Cost estimation can become difficult, especially when it involves exploring large codebases, iterative testing, and analyzing long logs.

Cost Note: /goalis a “continuing task” feature, so token usage may be greater than a regular one-shot prompt. For large repositories, it's a good idea to clearly state the target scope, tests to run, and stopping conditions.

authority risk

While Codex is an environment in which files can be read, modified, and commands executed,/goalcontinues that action over several turns. You must first check the approval policy and writable root settings.

1# Reading Guide: The blocks below are examples of commands, state flows, or templates.2Check:3- Current approval policy4- writable root scope5- Range of executable shell commands6- Does the test command call an external service or cost-incurring API?7- git working tree status

security risk

When applying AI coding tools to a company's codebase, you must check secret keys, environment variables, logs, and company policies./goalcan browse for long periods of time, so you should be especially careful about possible access to sensitive files.

Security Note: Before applying/goalto your company codebase, you must check the data transmission scope, secret key masking, log storage, permission settings, and automatic command execution policies.

Completion Judgment Risk

/goalinduces a completion audit, but since it is an early release feature, there may be edge cases. For example, in GitHub issue #19910, users reported that goal prompts and audit requirements were not sufficiently maintained after compaction, which could lead to early completion of goals.

This issue is user reported and cannot be guaranteed to reproduce in all environments. However, for long tasks, the following habits are good.

1# Reading Guide: The blocks below are examples of commands, state flows, or templates.2- Write clear success criteria in the goal.3- Directly specify important test commands.4- Check changed files and test results just before completion.5- After a long period of work, a person reviews the final diff.

9. Practical checklist

1# Reading Guide: The blocks below are examples of commands, state flows, or templates.2Checklist before application3 4[ ] Confirmed that the Codex CLI version is 0.128.0 or higher.5[ ] Checked the /goal help or slash command list in the current installed version.6[ ] The work goal is clear in one sentence.7[ ] Requirements were written as bullets.8[ ] Success criteria or Verification are specified.9[ ] I wrote down the test command to run.10[ ] Files or areas that should not be touched are written down.11[ ] The git working tree is clean or a separate branch has been created.12[ ] Approval policy and writable root were confirmed.13[ ] Considering that costs and token usage may increase.14[ ] Possibility of accessing security-sensitive files was confirmed.15[ ] There are plans to have a human review the diff and test results after completion.

10. Q&A

Q1. Is`/goal`the same function as`/resume`?

no./resumeis a function that reloads the saved session transcript and continues work./goalis a goal-based workflow that maintains the active objective and continues when incomplete.

Q2. Is`/goal`better than`/plan`?

Their roles are different./planis good for planning before implementation, and/goalis good when execution and verification must continue over several turns. For complex tasks, it is safe to first review the plan with/planand then use/goalin the execution stage.

Q3. Will it continue to run even if I close the terminal?

You shouldn't be so sure./goalhas a persisted goal state and is designed to maintain the state required for thread resume and client reconnect. However, this does not immediately guarantee that “even if you close the terminal, it will continue to run locally like an OS daemon.”

To be exact, it's closer to the following:

1# Reading Guide: The blocks below are examples of commands, state flows, or templates.2The state is saved.3If the session or app-server runtime is alive and idle, continuation can continue.4When you resume after stopping, you can see the goal status again.

Q4. Are the commands`/goal pause`,`/goal resume`,`/goal clear`?

The official changelog describes TUI controls as create, pause, resume, and clear. On the other hand, the TUI PR description says that/goal clear,/goal pause, and/goal unpausehave been added. Confirmed on 2026-05-02 I still don't see the/goalentry in the official CLI slash command documentation, and in GitHub issue #20536 there are users reporting that they have seen/goal pause,/goal resume, and/goal clearhelp strings on specific local installations.

Therefore, before actual publication, it is recommended to check/goalhelp directly in the installed Codex CLI version.

Q5. Is it safe to use in company code?

Settings and policies are more important than the tool itself. You must first check approval policy, writable root, data transmission scope, secret key masking, log storage, and company security policy. In particular,/goalcan read and modify files over several turns, making permission review more important than a regular one-shot prompt.

Q6. Which developer is best suited for you?

It is well suited to developers who want to develop with a CLI focus, verify work based on tests, and leave various stages of implementation, modification, and verification to AI. Conversely, if you're requesting one small fix quickly, a generic prompt is more efficient.

11. Part 2 preview

In this article, we summarize/goalfrom the user's perspective.

In the next article, we will look at the internal structure. In particular, it addresses the following questions:

1# Reading Guide: The blocks below are examples of commands, state flows, or templates.2- Where is the goal state stored?3- What permissions does the model tool have?4- When does the runtime start the continuation turn?5- How are budget limits handled?6- What does the completion audit prompt actually ask for?7-What design can I bring when creating my own AI Agent?

The key is this.

1# Reading Guide: The blocks below are examples of commands, state flows, or templates.2/goal is not a function that runs the agent while true.3It is a combination of Goal State + Runtime Event + Continuation Scheduler + Evidence Audit + Budget Guard.

12. References and uncertainty

References

OpenAI Codex changelog:https://developers.openai.com/codex/changelog
Codex CLI slash commands for checking document reflection status:https://developers.openai.com/codex/cli/slash-commands
OpenAI Codex GitHub repository:https://github.com/openai/codex
PR #18073 — goal persistence foundation:https://github.com/openai/codex/pull/18073
PR #18074 — app-server goal API:https://github.com/openai/codex/pull/18074
PR #18075 — model-facing goal tools:https://github.com/openai/codex/pull/18075
PR #18076 — core runtime goal loop:https://github.com/openai/codex/pull/18076
PR #18077 — TUI goal UX:https://github.com/openai/codex/pull/18077
Issue #19910 — User report regarding compaction:https://github.com/openai/codex/issues/19910
Issue #20536 —/goalDocumentation Request:https://github.com/openai/codex/issues/20536

confirmed facts

It is stated in the Codex CLI0.128.0changelog that persisted/goalworkflows have been added.
PR #18073–#18077 adds persistence, app-server API, model tools, core runtime, and TUI UX step by step.
The core runtime PR explains that it starts the continuation turn in idle state and gives priority to user input and mailbox work.
TUI PR describes/goalsummary rendering,/goal <objective>,/goal clear,/goal pause,/goal unpause.
As of confirmation on 2026-05-02, the/goalentry is not yet visible in the official CLI slash-command documentation.

Author's interpretation

/goalis closer to a goal-oriented agent runtime than a simple slash command.
The key to practical application is “writing good goals” and “verifiable completion criteria.”
Developers designing long-running agent workflows can get many hints from the structure of/goal.

uncertainty

Since this is a soon-to-be-released feature, CLI help, official slash-command documentation, and actual command aliases may vary depending on the version.
The issue of maintaining active goals after compaction is based on user reports and may be fixed in the future.
token budget options and display may look different depending on the API/tool-created goal and TUI-created goal.

finish

In summary, Codex CLI's/goalis a function that aims to reduce the “continue” loop at the runtime level, which is the most annoying thing when entrusting long development tasks to AI.

However, it is dangerous to accept this function as an “automatic developer that takes care of everything.” A good goal should have clear requirements, constraints, verification mandates, and completion criteria. And the final diff and test results still need to be verified by humans.

If you are an individual developer, it is a good idea to start by fixing test failures or implementing small features. For teams, it is safer to organize permissions, security, and cost policies first and then verify them in a restricted repository.

GitHub 계정으로 로그인하면 댓글을 남길 수 있습니다. 댓글은 GitHub Discussions를 통해 운영됩니다.