Codex Goal Mode: Write /goal Tasks That Actually Finish

Codex Goal Mode works best when you give it one durable objective, evidence it can check, boundaries it must preserve, and a stopping condition. Do not use /goal as a longer to-do list. Use it as a testable contract.

Start with this structure:

/goal Complete [one outcome].

Context:
- Read [files, issue, docs, or logs] first.

Constraints:
- Preserve [interfaces, files, budgets, approvals, or environments].
- Do not [irreversible or unrelated actions].
- Pause if [decision or blocker that needs a person].

Validate:
- Run [exact checks] after each checkpoint.

Done when:
- [Observable end state] is true and [evidence] passes

The important change is the final section. "Finish the migration" is open to interpretation. "The new implementation passes the original contract tests, the public API remains compatible, and the differences are documented" gives Codex evidence it can use to decide whether to continue or stop.

What Goal Mode Does

Goal Mode gives Codex a durable objective for work that may continue across multiple turns or run for hours. OpenAI recommends it for migrations, large refactors, deployment retry loops, experiments, games, and other projects with a clear validation loop.

The core commands are:

/goal <objective>  Set a goal
/goal              Check the current goal
/goal pause        Pause work
/goal resume       Resume work
/goal clear        Clear the goal

If /goal is missing from the command list, enable it in the CLI:

codex features enable goals

The equivalent config.toml setting is:

[features]
goals = true

OpenAI announced Goal Mode as generally available across the Codex app, IDE extension, and CLI on May 21, 2026. The feature can keep working independently, but it still needs a bounded assignment and a result you can review.

Prerequisites for a Safe Long-Running Goal

Before starting, make the environment easier to verify and recover:

1. Start from a known repository commit and inspect the working tree.

2. Use a dedicated branch or worktree for changes.

3. Identify the smallest checks that prove progress.

4. Decide which files, systems, and environments are out of scope.

5. Name actions that require approval, especially publishing, messaging, billing, deployments, database changes, and destructive operations.

6. Write down what should make Codex pause instead of guessing.

For example:

git status --short --branch
git rev-parse HEAD

Expected result: you know the starting commit and whether tracked changes already exist. If the tree contains unrelated work, preserve it or create a separate worktree before the goal begins.

Step 1: Choose One Outcome, Not a Backlog

A good goal is larger than one normal prompt but smaller than an open-ended queue.

Weak:

/goal Improve this repo, fix bugs, update dependencies, and clean up the docs.

Stronger:

/goal Upgrade the HTTP client in packages/api without changing its public API.
Read the migration issue and packages/api/README.md first. Keep unrelated
packages unchanged. Run the package's unit tests after each checkpoint.
Pause before adding a dependency or changing generated types. Done when the
existing tests pass, the deprecated client is absent from packages/api, and
the compatibility differences are documented in packages/api/README.md

The stronger version gives Codex one result, a scope, evidence, and two explicit reasons to pause.

Step 2: Give Codex Evidence It Can Recheck

A goal needs checks that are stable enough to survive a long run. Prefer exact commands, files, URLs, screenshots, or structured outputs over phrases such as "looks good."

Useful evidence includes:

• a focused unit-test command;

• a contract or snapshot test;

• a linter for the changed package;

• an expected HTTP status and response field;

• a before-and-after screenshot with named visual criteria;

• a structured API result with required records;

• a clean git diff --check result.

Keep the validation proportional. A small documentation task does not need the entire monorepo test suite. A compatibility migration should not stop after a single happy-path test.

Step 3: Set Boundaries and Stop Conditions

Goal Mode is persistent, so boundaries matter more than extra procedural detail.

Name:

• what must remain unchanged;

• which writes are allowed;

• which external environments are allowed;

• the maximum time, attempts, or spend for a retry loop;

• the decisions that require human judgment;

• the exact condition that means the goal is complete.

For a deployment retry loop, do not say "retry until it works." Say how often to check, how many failed attempts are allowed, which logs to capture, and when to pause. For an external integration, allow read-only discovery first and require schema inspection and approval before any write.

Step 4: Use Checkpoints and a Compact Progress Ledger

Ask Codex to report four facts at each checkpoint:

Checkpoint:
- Changed:
- Verified:
- Remaining:
- Blocked or needs approval:

This makes status review concrete and helps prevent a long run from repeating completed checks after context changes. If the update becomes vague, tighten the next checkpoint or the proof command instead of adding a second unrelated objective.

Use /goal to inspect the current state. Use /goal pause when the next step needs a decision, a credential, or a risky action. Resume only after supplying the missing input. Clear the goal when the objective has changed enough that the old completion contract no longer applies.

Step 5: Test Goal Mode With a Read-Only Aident Task

Aident Loadout gives Goal Mode a useful multi-source task without asking you to paste provider API keys into the prompt.

Install or refresh the Aident skill in Codex:

Follow https://aident.ai/SETUP.md

Confirm authentication and connected services:

aident account auth status
aident vault vault --action status

Then use this bounded goal:

/goal Create docs/capability-inventory.md with one current read-only Aident
Action for GitHub issue search, web analytics, and recent video search.

Context:
- Read AGENTS.md and the current docs folder instructions first.
- Use `aident capabilities search` to discover Actions.
- Inspect each selected Action with `aident capabilities get`.

Constraints:
- Do not execute a provider Action, change Vault state, send messages, publish,
  deploy, or modify remote records.
- Keep all repository changes inside docs/capability-inventory.md.
- Pause if authentication fails or an Action schema cannot be inspected.

Validate:
- Confirm the three Action names are distinct and each current schema supports
  the stated read-only task.
- Run `git diff --check`.

Done when:
- The file lists exactly three Action IDs, required input fields, provider,
  read-only purpose, and access date, and `git diff --check` passes

Expected result: Codex produces one reviewable file, inspects three current schemas, makes no provider write, and stops after the named evidence passes. That is a better Goal Mode test than an unbounded request to "research useful integrations."

Common Goal Mode Failure Modes

Why Verifiable Goals Work

OpenAI's long-running-work guidance makes the distinction directly: a weak goal asks Codex to implement a plan, while a stronger goal gives it expected behavior, review criteria, constraints, or a clear definition of done. Those signals turn progress into a loop Codex can evaluate:

1. inspect the current state;

2. make a scoped change;

3. run the agreed check;

4. compare the evidence with the stopping condition;

5. continue, pause, or finish.

The goal does not need to prescribe every step. It needs to make the outcome testable and keep irreversible decisions visible to a person.

For a related way to preserve progress during long runs, see Codex Keeps Compacting Context? Break the Loop Safely. For project-wide boundaries, see How to Make Codex Review Code the Way Your Team Does.

Sources

• Follow a goal, OpenAI, accessed July 28, 2026

• Codex updates: goal mode generally available, OpenAI release notes, May 21, 2026

• Codex-maxxing for long-running work, OpenAI, accessed July 28, 2026

• Codex prompting guide, OpenAI, accessed July 28, 2026

• Codex for Faculty and Researchers: prompt formula, OpenAI Academy, June 9, 2026

• /goal is a joke, r/codex, posted July 25, 2026

• How long should a Codex goal run?, r/codex, posted July 6, 2026

• Aident setup instructions, accessed July 28, 2026