Introduction

Use /goal when you want Codex to keep working toward one durable objective instead of stopping after one normal turn. It is useful for work that has a clear target, a validation loop, and enough room for Codex to make progress without asking you to steer every step. When you use /goal, Codex can work independently for multiple hours without needing your input.

/goal is an experimental Codex CLI feature. Enable it from /experimental, or add goals = true under [features] in config.toml. Then set a goal with /goal <objective>, check the current goal with /goal, and use /goal pause, /goal resume, or /goal clear when you need to control the run.

Choose the right work

A good goal is bigger than one prompt but smaller than an open-ended backlog. It should define what Codex should achieve, what it should not change, how it should validate progress, and when it should stop.

This works well for:

• code migration where the target stack, parity checks, and constraints are clear
• large refactors where Codex can run tests after each checkpoint
• experiments, games, or prototypes where Codex can keep improving a working artifact

Avoid using a goal for a loose list of unrelated work.

Set up the loop

The important part is the contract. Codex should know what “done” means before it starts. If the goal is a migration, “done” might mean the new path passes contract tests and the legacy path still has a rollback. If the goal is a game or prototype, “done” might mean the app builds, launches, and matches the input reference or expected behavior.

Let Codex work independently

During a goal, ask for compact progress reports that make the run easy to trust. A useful status update names the current checkpoint, what was verified, what remains, and whether Codex is blocked. If the status becomes vague, tighten the goal rather than adding more ad hoc instructions. Tell Codex exactly which checkpoint matters next, which command proves it, and what should cause it to pause.

When Codex follows a goal, it can work independently for many hours without you having to check in. It will stop running when it is fairly confident it has reached the stopping condition, so you should think of /goal as a background task you don’t need to monitor.

Example goals

Migrations

Whether you’re migrating games to a new stack, mobile apps to a new platform, or a codebase to a new framework, you can use /goal to have Codex run the migration:

Prototype creation

Whether you’re creating a new app from scratch, a new game, or a new feature, you can use /goal to have Codex complete a polished first version. You can use a PLAN.md file to guide the creation of the first version, describing precisely what you want to build.

Prompt optimization

When you have an eval suite, you can use /goal to optimize prompts against the eval results. Codex can inspect failures, update the prompt, rerun the evals, and keep iterating until the score improves or it reaches your stopping condition.