Codex Goal Mode: A Practical Guide

Last verified: September 14, 2026
Scope: Goal mode in the ChatGPT desktop app, Codex CLI, IDE extension, and Codex App Server

The short version

Goal mode gives one Codex chat a durable objective. Instead of treating the request as a normal one-turn task, Codex can keep working across turns: making a change, checking the result, diagnosing what failed, and trying again until it reaches a stated stopping condition or needs help.

The subsystem has a native token budget. It also records elapsed time, but it does not currently expose a native time-budget or timeout field. A request such as “stop after two hours” can be placed in the objective and followed by the agent, but that is an agent-enforced instruction rather than a hard scheduler cutoff.

The most useful mental model is:

objective + constraints + verification + token budget
                         ↓
             repeated work and checking
                         ↓
          complete, paused, cleared, or blocked

What changes when you set a goal

A normal prompt usually asks Codex to perform a bounded piece of work and respond. A goal adds persistent state to the chat: the objective remains attached while Codex continues working, and the client can display progress and usage.

The goal does not make the agent omnipotent. It keeps the chat’s existing sandbox, permissions, approval policy, workspace, and available tools. If the work requires a permission decision or missing information, the goal may still pause for the user.

Each chat has its own context, results, and goal. Parallel goals therefore belong in separate chats. If two coding goals could touch the same files, use separate Git worktrees or otherwise isolate their write targets.

The three surfaces

The same concept appears through three related interfaces:

The interfaces are related but not identical. The friendly /goal command emphasizes the objective and lifecycle controls. The structured interfaces reveal the accounting fields more explicitly.

Exact resource fields

At the App Server layer, setting a goal looks like this:

{
  "method": "thread/goal/set",
  "id": 13,
  "params": {
    "threadId": "thr_123",
    "objective": "Finish the migration and keep tests green",
    "status": "active",
    "tokenBudget": 40000
  }
}

The stored goal state includes usage telemetry:

{
  "threadId": "thr_123",
  "objective": "Finish the migration and keep tests green",
  "status": "active",
  "tokenBudget": 40000,
  "tokensUsed": 0,
  "timeUsedSeconds": 0
}

The distinction matters:

In an agent environment with a goal-creation tool, the create call may be simplified to the current chat:

{
  "objective": "Finish the migration and keep tests green",
  "token_budget": 40000
}

That interface likewise has no native time-budget parameter.

What a token budget is not

The goal token budget is not:

• a purchase of additional usage;
• an account rate-limit reset;
• the model’s context-window size; or
• proof that the objective was completed.

It is a budget attached to the goal’s work. Completion should still be determined by the objective’s verification criteria. If exact behavior at budget exhaustion matters, state the desired fallback in the goal—for example, “If the remaining budget is too small to complete safely, stop changing files and provide a verified handoff.”

The time-budget caveat

Codex records elapsed time, so the agent or client can report how long the goal has been active. However, the published goal schema does not contain a hard time-budget field.

You can still write:

Work toward the verified outcome below, but stop once elapsed time reaches
two hours. At that point, stop making changes and report the strongest
verified state, remaining failures, and the safest next step.

That is useful, but it is a soft, agent-enforced boundary. Do not use it as the only safety control for infrastructure charges, production mutations, external API spend, or anything else that requires an exact cutoff. Put a real timeout, spending cap, job deadline, or cancellation mechanism in the external system as well.

Starting and controlling a goal

In the ChatGPT desktop app, Codex CLI, or IDE extension:

/goal Finish the migration and keep tests green.

The documented controls are:

Goal objectives must be non-empty and no longer than 4,000 characters. For a larger specification, put the details in a file such as PLAN.md and make the goal point to it.

If /goal is missing, enable the feature in config.toml:

[features]
goals = true

Or enable it from the CLI:

codex features enable goals

Writing a goal that can succeed

A good goal is larger than one prompt but smaller than an open-ended backlog. It gives Codex enough room to make progress independently while making “done” objectively checkable.

Include four ingredients:

1. Outcome: the state that should exist when the work is finished.
2. Constraints: what must remain true and what must not be changed.
3. Verification: the tests, measurements, or artifacts that prove the outcome.
4. Stopping behavior: what counts as success, what counts as a genuine blocker, and what to do near a resource boundary.

A reusable template:

/goal Achieve [specific outcome].

First read [files, plan, issue, logs, or documentation].

Preserve [important invariants]. Do not [prohibited changes].

Work in checkpoints. After each checkpoint, run [verification commands]
and inspect [artifacts or behavior]. Keep a short progress record.

Complete the goal only when [verifiable completion criteria]. If progress
requires [missing authority, product decision, credentials, or unsafe action],
pause and explain the exact blocker.

Use a token budget of [N]. If the remaining budget is insufficient for a
safe completion, stop changing state and provide a verified handoff.

If elapsed time reaches [duration], stop and report the strongest verified
state. This is an agent-enforced time boundary, not a hard system timeout.

Examples

Code migration

/goal Migrate this project from JavaScript to TypeScript. Preserve current
behavior, compile in strict mode without explicit `any` types, and make the
full test suite pass. Work in reversible checkpoints. Complete only when the
build and test suite pass from a clean checkout; otherwise report the smallest
remaining blocker and the commands that reproduce it.

Measured improvement loop

/goal Improve the prompt in prompts/support.md until the fixed evaluation
suite reaches at least a 92% pass rate. After each targeted change, rerun the
same evaluation command and record the score. Do not alter the evaluator or
test cases. Stop if the target is met or further progress requires a product
or policy decision.

Time-bounded exploration

/goal Investigate the intermittent test failure, produce a reproducible case,
and implement the smallest verified fix. Stop once elapsed time reaches 90
minutes if the fix is not proven. At that point, leave the repository in a
safe state and report evidence, rejected hypotheses, and the next experiment.

The last example’s 90-minute boundary is instructional rather than a native hard timeout.

Good fits and poor fits

Goal mode works well when the work has a feedback loop: migrations, large refactors, deployment retry loops, experiments, prototypes, games, or prompt optimization against a fixed evaluation suite.

It is a poor fit for:

• a loose collection of unrelated tasks;
• work whose success criteria remain fundamentally undecided;
• irreversible operations without independent safety controls;
• two agents writing to the same working tree; or
• tasks that need a guaranteed wall-clock shutdown but have no external timeout.

If the outcome is still fuzzy, start with /plan. Ask Codex to identify the constraints and turn the result into measurable completion criteria before starting the goal.

Operational habits

• Ask status reports to name the current checkpoint, what has been verified, what remains, and whether work is blocked.
• Tighten a vague goal instead of piling on unrelated one-off instructions.
• Keep related work in the same chat so the goal retains its context.
• Pause before losing connectivity, then resume when the workspace is available again.
• For local long-running work, enable “Prevent sleep while running” if appropriate.
• Run independent goals in separate chats and isolate overlapping code changes with worktrees.
• Remember that a goal does not expand permissions or bypass approvals.

Frequently asked questions

Is the token budget the same as account usage?

No. It is goal-level accounting, separate from account usage views and rate limits.

Is elapsed time a time budget?

No. timeUsedSeconds is telemetry. The current published goal schema has no timeBudget field.

Can I still tell Codex to stop after a duration?

Yes. Put the duration and the desired handoff behavior in the objective. Treat it as an agent-enforced condition, not as a guaranteed process kill.

Does reaching the token budget mean the goal succeeded?

No. Success comes from satisfying the verification criteria. A depleted budget and a completed goal are different states.

Can a goal run without supervision?

The official guidance says goals can work independently for many hours when the objective and validation loop are clear. They can still pause for approvals, decisions, missing access, or genuine blockers.

Can I change a goal while it is running?

Yes. The user-facing controls support editing, pausing, resuming, and clearing. At the App Server layer, updating the current non-terminal objective or omitting it can preserve usage history while changing status or token budget; supplying a new objective replaces the goal and resets usage accounting.

A final preflight check

Before pressing Enter on /goal, ask:

Can the agent tell—using evidence available in this workspace—when this is done?

If the answer is no, add a test, measurement, artifact, review criterion, or explicit handoff condition. That improvement usually matters more than making the objective longer.

Official sources

• Follow a goal — OpenAI Docs
• Long-running work — OpenAI Docs
• Developer commands and /goal — OpenAI Docs
• Codex App Server goal schema — OpenAI Docs