use-cases/follow-goals.md +80 −0 added
1---
2name: Follow a goal
3tagline: Give Codex a durable objective for long-running work.
4summary: Use `/goal` when a task needs Codex to keep working across turns toward
5 a verifiable stopping condition.
6bestFor:
7 - Long-running coding work with a clear success condition and validation loop.
8 - Code migrations, large refactors, deployment retry loops, experiments,
9 games, and side projects where Codex can keep making scoped progress.
10 - Teams that need to run long experiments with clear success criteria.
11starterPrompt:
12 title: Set a Long-Running Goal
13 body: /goal Complete [objective] without stopping until [verifiable end state].
14relatedLinks:
15 - label: "`/goal` in CLI slash commands"
16 url: /codex/cli/slash-commands#set-an-experimental-goal-with-goal
17 - label: Codex workflows
18 url: /codex/workflows
19 - label: Run code migrations
20 url: /codex/use-cases/code-migrations
21 - label: Iterate on difficult problems
22 url: /codex/use-cases/iterate-on-difficult-problems
23---
24
25## Introduction
26
27Use `/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.
28
29`/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.
30
31## Choose the right work
32
33A 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.
34
35This works well for:
36
37- code migration where the target stack, parity checks, and constraints are clear
38- large refactors where Codex can run tests after each checkpoint
39- experiments, games, or prototypes where Codex can keep improving a working artifact
40
41Avoid using a goal for a loose list of unrelated work.
42
43## Set up the loop
44
45
46
471. Name one objective and one stopping condition.
482. Point Codex at the files, docs, issue, logs, or plan it must read first.
493. Define the commands or artifacts that prove progress.
504. Tell Codex to work in checkpoints and keep a short progress log.
515. Use `/goal` to inspect status while it runs.
526. Pause, resume, or clear the goal when the run is done, blocked, or changing direction.
53
54
55
56The 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.
57
58Ask Codex to help: start by having a conversation about what you want to
59 build, then ask it to directly set a goal and start working.
60
61## Let Codex work independently
62
63During 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.
64If 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.
65
66When 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.
67
68## Example goals
69
70### Migrations
71
72Whether 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:
73
74### Prototype creation
75
76Whether 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.
77
78### Prompt optimization
79
80When 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.