Codex Goal Mode: Run Long-Horizon AI Coding Tasks for Hours or Days

OpenAI shipped three Codex updates on May 21, 2026 — internally called "Codex Thursday." The headline feature: Goal Mode exited experimental and went stable across the Codex app, VS Code and JetBrains extensions, and the CLI. It also shipped alongside Appshots and Locked Computer Use, making this the most significant Codex release since the platform launched.

If you've been using Codex as a smarter autocomplete or a one-shot code-change tool, Goal Mode changes what the tool is. You can now hand Codex a multi-hour objective, define a success condition, and come back when it's done.

This guide covers how Goal Mode works, how to set it up in the CLI and IDE, how to write goals that actually complete, and where the current limits are.

Why Goal Mode Is a Different Kind of Feature

Most LLM-based coding tools are request-response: you write a prompt, the model writes code, you review and iterate. This works well for isolated tasks — write a function, explain a bug, generate a test — but it breaks down for work that requires planning across many files, running tests, fixing failures, and repeating that cycle.

Codex has always been more agentic than a basic autocomplete, but it still reset between turns. Goal Mode adds persistence. A goal is a durable objective that survives across turns, interruptions, budget pauses, and resumptions. Codex tracks the goal's status in a local SQLite table, checks its own output against the success condition you defined, and keeps iterating until it's done or hits a stopping boundary you set.

The shift is from "tool that responds" to "agent with a mission." For the right kind of task, this removes a real bottleneck: you no longer need to re-prompt every cycle to keep Codex on track.

How Goal Mode Works Internally

Understanding the architecture helps you write better goals and debug unexpected stops.

Goal Mode runs as five separate layers:

State layer (SQLite): One goal per thread is stored in a local SQLite table with fields for the objective text, status (active, paused, budget_limited, complete), token budget (optional), and running usage counters. The thread can have only one active goal at a time.

App-server API (JSON-RPC): The Codex app server exposes thread/goal/set, thread/goal/get, and thread/goal/clear methods. These are what the TUI controls call when you run /goal pause or /goal clear.

Model tools: The model has access to three tools — create_goal, update_goal (including complete status), and get_goal. Critically, the model cannot pause or resume a goal — those transitions are system-controlled. This prevents a class of edge cases where a stuck model might try to loop forever or prematurely stop.

Runtime event bus: A lifecycle hook tracks token and wall-clock deltas per turn, auto-pauses when an interrupt is received, auto-reactivates paused goals on thread resume, and injects budget-limit steering into the model's response stream when you're approaching your set limit.

TUI controls: The /goal commands you type are the user-facing interface to all of the above.

Setup: CLI, IDE Extension, and App

CLI Setup

Goal Mode in the CLI requires version 0.128.0 or later. Install or upgrade:

npm install -g @openai/codex
codex --version   # should be 0.128.0+

Once installed, start a Codex CLI session in your project directory and use /goal in the prompt:

/goal Migrate all fetch() calls in src/api/ to use the centralized apiClient utility. Verify each file compiles and existing integration tests pass.

VS Code and JetBrains

Goal Mode is available in both IDE extensions without additional configuration. Open the Codex panel, start a session, and type /goal in the chat input. The goal lifecycle controls — pause, resume, clear — appear as buttons in the panel when a goal is active.

The IDE extension also surfaces goal status in the status bar, showing Codex: goal active or Codex: goal paused while a goal is running.

Codex App (macOS)

In the Codex app, use /goal in the composer. The app also shipped Appshots on the same release date: press both Command keys to attach a screenshot of your frontmost window to the current message. This is useful for giving Codex visual context about an error state or UI layout without leaving the composer.

Writing Goals That Work

The biggest predictor of a successful goal run is how precisely you define it. Codex is good at inferring reasonable sub-steps, but it can't infer success criteria that you haven't specified.

A well-structured goal has three parts:

1. The objective — what should be true when the goal is complete
2. The verification surface — how Codex should check its own work
3. The constraints — what it must not change

Here is the difference in practice:

Weak goal:

/goal improve the codebase

This gives Codex no completion condition. It will generate improvements indefinitely until it hits a budget or you clear the goal manually.

Strong goal:

/goal Replace all instances of the deprecated `createStore()` call in src/store/
with the new `configureStore()` API from @reduxjs/toolkit. Leave reducers
and middleware configs untouched. Verify the build passes and existing
Vitest tests in src/store/__tests__/ run green.

This is bounded, has a verification step (build + tests), and constrains the scope.

A few patterns that work well for Goal Mode:

• Migration tasks: "Migrate X from library A to library B, verify tests pass"
• Refactors with test coverage: "Extract the data-fetching logic from Component X into a custom hook, update all usage sites, tests should remain green"
• Documentation passes: "Write a JSDoc comment for every exported function in src/utils/ that currently lacks one, verify npm run docs builds without errors"
• Deployment retry loops: "Run the staging deploy script, parse any errors, fix the root cause, and re-run until it succeeds or you encounter an error you cannot resolve"

The Goal Lifecycle

Once a goal is active, Codex runs an autonomous loop:

while goal.status != complete:
    plan next step toward objective
    execute step (file edits, shell commands, tests)
    check output against success condition
    if success condition met:
        mark goal complete
    elif stuck or error:
        attempt recovery or ask for input
    elif budget_limit hit:
        pause goal, notify user

You can intervene at any point:

/goal          # check current goal and status
/goal pause    # pause after the current turn completes
/goal resume   # resume a paused or budget-limited goal
/goal clear    # abandon the current goal entirely

Budget-limited pauses happen automatically when the goal hits your configured token budget. You get a notification and can review work so far before resuming or abandoning.

Token Budgets and Cost

Goal Mode's cost model matters for any workflow where Codex might run for hours. As of May 2026, Codex pricing is token-based:

credits = (input_tokens × input_rate) +
          (cached_input_tokens × cached_rate) +
          (output_tokens × output_rate)

Cached input tokens — context repeated across turns — cost approximately 10% of the regular input rate. For long-running goals where the same file context appears in every turn, caching is the most significant cost reduction available.

You can set a per-goal budget when you define the goal:

/goal --budget 50000 Fix all TypeScript strict-mode errors in src/. Verify tsc --strict passes.

This caps the goal at 50,000 credits. When the budget runs out, Codex pauses and reports what it completed so far. You can review the diff, then /goal resume (continuing against a new budget allocation) or /goal clear if you want to take over.

OpenAI's own usage data suggests typical developer month costs run $100–$200, with significant variance based on model choice and goal complexity. Multi-hour autonomous goals will be on the higher end.

Goal Mode vs. Regular Codex Turns

Not every task benefits from Goal Mode. Here's a practical decision framework:

The key question: does the task have a verifiable done state, and is it bigger than one or two prompts? If yes, Goal Mode is worth using. If you're still figuring out what you want to build, stay in regular turns.

Locked Computer Use and Appshots

Two features shipped alongside Goal Mode that extend its usefulness for long-running tasks.

Locked Computer Use lets Codex continue working after your Mac locks, including when you're away from the machine. OpenAI's implementation uses short-lived authorization tokens, covers the display while Codex is active, relocks on local input, and falls back to manual unlock. The scope is limited to active, trusted computer use sessions — it doesn't grant persistent access.

For autonomous goal runs that take hours, this means you can start a goal, lock your machine, and come back to completed work. The practical constraint is that Locked Computer Use only applies to desktop app sessions, not the CLI or IDE extensions.

Appshots (double-Command) capture your frontmost window and send it to Codex as a screenshot plus extracted text. This is most useful at goal setup time: you can point Codex at an error message, a test runner output, or a UI screenshot and include it as context when defining the goal, without copy-pasting terminal output manually.

Common Mistakes

Setting goals too broad for the codebase size. "Refactor the entire codebase to use TypeScript strict mode" is technically bounded (tsc --strict passes) but will consume a very large budget on any non-trivial project. Scope goals to a directory or a module.

No verification surface. If the goal doesn't include a way to verify completion — a test command, a lint check, a build step — Codex will often mark the goal complete before it actually is. Explicitly include the check command in the goal text.

Clearing goals prematurely. /goal clear abandons the current objective and discards progress tracking. If you want to pause and review, use /goal pause first. You can always resume after inspection.

Running Goal Mode during active development. If other team members (or you) are making file changes while a goal is running, conflicts are likely. Goal Mode works best on isolated branches where Codex has exclusive write access to the relevant files.

Not monitoring the first goal run. Token costs for a novel goal type are hard to predict. Check the usage panel after the first run to calibrate your budget for similar goals in the future.

Frequently Asked Questions

Q: Does Goal Mode work with private repositories?

Yes. Codex operates within your local file system (CLI and IDE extension) or within your connected repository (Codex app). It does not send your codebase to a separate server beyond the model API calls. Goal state is stored locally in SQLite.

Q: Can I run multiple goals at once?

No. Each thread supports one active goal at a time. If you need parallel goal execution, you'd need to run separate Codex sessions in separate terminal windows or IDE panels.

Q: What happens if Codex gets stuck on a subtask?

If Codex cannot make progress (compilation errors it can't fix, a test it can't pass), it will surface the blocker and pause to ask for input rather than looping indefinitely. This is controlled by the model's update_goal tool — when it detects an unrecoverable state, it sets the goal status to paused and describes what it needs.

Q: Is the /goal command available on all Codex plans?

Goal Mode is available on Codex Pro, Team, and Enterprise plans as of the May 21, 2026 GA release. Check the Codex rate card at developers.openai.com/codex/pricing for current plan-level access details.

Q: How is Goal Mode different from Codex's existing agentic features?

Standard Codex tasks already involve multi-step execution within a single turn — running tests, reading files, writing code. Goal Mode adds cross-turn persistence: the goal state survives between turns, so Codex doesn't need you to re-prompt each cycle. It's a persistence layer on top of the existing agentic infrastructure.

Key Takeaways

• Goal Mode is generally available as of May 21, 2026 in the Codex app, VS Code/JetBrains extensions, and CLI (version 0.128.0+)
• Use /goal <objective> to start, /goal pause/resume/clear to manage lifecycle
• Effective goals include an objective, a verification surface (test command, build step), and constraints on what not to change
• Token budgets (--budget <credits>) are the primary cost guardrail for long-running goals
• Locked Computer Use lets goals continue while your Mac is locked — Codex app only
• Goal Mode is best for bounded, verifiable multi-hour tasks; use regular turns for exploration and single-file changes
• Monitor the first run of any new goal type to calibrate your budget expectations

Bottom Line

Codex Goal Mode is the feature that makes good on the promise of autonomous coding agents: it handles the boring, bounded, multi-hour work — migrations, refactors, documentation passes — while you stay focused on the decisions that actually require judgment. Set clear goals with verifiable completion conditions, and it delivers. Go in without a verification surface and you'll be reviewing a lot of half-finished work.