Using goals in Codex (/goal)

Goals turn a single Codex thread into something that keeps chewing on one objective across many turns instead of forgetting what it was after each prompt. Here’s the short version, then the detail.

Set a goal in three steps

1. Update the CLI to 0.128.0 or newer, where goals shipped on April 30, 2026 (release notes). Check your version with codex --version, then update:

npm install -g @openai/codex@latest

2. Turn the feature on. If /goal doesn’t show in the slash menu, add it to ~/.codex/config.toml (official docs):

[features]
goals = true

Or run codex features enable goals and restart Codex.

3. Inside a session, state the outcome you want:

/goal Reduce p95 latency below 120 ms, verified by the checkout benchmark, while keeping the correctness suite green

A good goal names the finish line and how success gets checked, so Codex knows when to stop.

Checking and controlling a run

Type /goal on its own to see the current goal and its state. Three controls manage the run: /goal pause stops the loop, /goal resume picks it back up, and /goal clear drops the goal entirely (cookbook). Once a goal is set, Codex plans, runs, inspects its own results, and continues on its own. The docs say it can work for hours without more input and stops when it’s confident the stopping condition is met.

How persistence works

The goal is saved as thread state through the app-server APIs, scoped to the thread it was created in rather than shared globally or dropped into a project instruction file (cookbook). That state sticks, so the objective survives a dropped connection, a token wall, a deliberate pause, and even a machine reboot.

One catch worth being clear about: the goal persists, but execution only runs while the session is live. Close the terminal and the agent stops where it stood. The goal stays in whatever state it was in, pursuing or paused, until you reopen the thread. The lifecycle states Codex tracks are pursuing, paused, achieved, unmet, and budget-limited (issue #20536). Budget-limited means it burned through the token budget configured for the run. The docs don’t spell out a per-goal budget flag, so treat that as session or profile level for now.

If /goal doesn’t show up

• You’re below 0.128.0, or you updated but a stale process is still holding the old binary. Restart Codex.
• You enabled the flag but typed /goals with an s. The command is /goal, singular (easy to fat-finger).
• On Codex Windows Desktop there’s an open bug where the slash list won’t register /goal even with goals = true set (issue #25812). The CLI is the reliable surface for now.

Related

• Profiles: scope config per project or model setup, which a goal run inherits
• model.auto_compact_token_limit: controls compaction on the long runs goals produce
• approval-policy: decide how much a multi-hour goal run does unattended
• input exceeds context window: the error long goal runs hit most