OpenAI Codex's /goal feature is changing how developers work: you give it a single high-level intent, and Codex automatically decomposes the tasks, spawns subagents, and completes the entire pipeline from planning to delivery on its own. One developer ran it unattended for 18 hours; it independently completed 14 features from a BACKLOG.md, at a cost of only about $4.20.

This guide walks you through setting up and using /goal from scratch, while steering clear of the pitfalls the community has already discovered.

Before You Start

• Codex CLI 0.128.0+: the /goal feature ships built in from this version
• An OpenAI API account: you need a valid API key with sufficient balance (at least $10 recommended)
• An existing project repository: the official advice is to get your project to a working prototype before using /goal — don't launch it on an empty project
• Estimated cost: simple tasks run about $0.5-2, while long autonomous runs can reach $5-10

Step 1: Enable /goal

/goal is disabled by default and requires manually editing the config file.

Find or create config.toml in your project root and add the following:

[features]
goals = true

Tip: If you use a global config (usually at ~/.codex/config.toml), you can enable it there too, but per-project configuration is recommended for easier management.

Step 2: Understand How /goal Works

/goal is fundamentally different from an ordinary conversational prompt. It plays two roles at once:

1. Starting instruction: it tells Codex what to do
2. Completion audit standard: after each round, Codex checks back against the goal and asks itself "what else should be done, and is it already done?"

This loop is known as the "Ralph loop": plan, execute, test, review, iterate — round after round, until the task is done, you manually stop it, or the token budget runs out.

The key principle: the goal must be verifiable. Codex needs to be able to judge whether it is "done or not."

Step 3: Write Your First /goal

A good goal has these traits: specific, verifiable, and bounded.

Bad examples (avoid writing this):

/goal improve the code quality a bit
/goal polish the user experience

These vague phrases leave Codex unable to judge completion status, sending it into an infinite loop.

Good example (recommended):

/goal Replace all moment.js calls in src/utils/date.ts with dayjs,
make sure all tests pass (npm test), and remove the moment.js dependency
(package.json should no longer include moment). When done, print the list of changed files.

Note the three elements of this goal: a clear task boundary, verifiable completion conditions (tests passing + dependency removed), and explicit output requirements.

Step 4: Let Codex Write Its Own /goal (Advanced)

This is the hottest trick in the community right now, demonstrated by Pietro Schirano, a former Anthropic member and current CEO of MagicPath.

Instead of hand-writing the goal, you give Codex a single high-level intent and let it generate the goal and spawn subagents itself:

Help me build a [THING] that includes [feature list],
styled after [description].
Let Codex plan the tasks and spawn the agents itself.

Codex will automatically do the following:

1. Write itself a detailed /goal
2. Split out the subtasks that need to run in parallel
3. Write a dedicated goal for each subagent
4. Create and dispatch these subagents
5. Aggregate the subagents' output

The Gibbs subagent is executing its own dedicated /goal, designing a mathematically-themed roller coaster track. One goal each is the core of this playbook.

Step 5: Control Token Consumption

The biggest risk of autonomous runs is a runaway token bill. Andrew Chen of a16z ran a real eGPU-powered project overnight (14 hours) and said bluntly that it can multiply token usage ten-thousand-fold.

The officially recommended way to control costs:

Add a token budget limit at the end of the goal:

/goal [your task description]
Token budget: no more than 500K tokens.
If you approach the budget, stop and report current progress.

Other cost-control tips:

• Don't launch /goal directly on an empty project; build the basic scaffolding by hand first
• Start with small tasks to test, and only hand it long tasks once the behavior matches expectations
• Check run logs regularly and stop immediately if it starts to drift

Verifying the Results

After the run finishes, check the following to confirm the task succeeded:

1. Do the tests pass: Codex should bake test verification into the goal itself
2. Is CI green: all changes should be able to merge in CI
3. Change log: Codex should output the complete list of changed files
4. Code self-review: you can have a GPT subagent do a round of code review

One developer's real-world log: they gave Codex the goal "deliver all 18 features in BACKLOG.md" and came back 18 hours later to find Codex had autonomously completed 14 of them, with every change passing tests and merging in CI — no human sign-off at any point, at a total cost of about $4.20.

FAQ

Q: What about goal drift?

Codex can drift away from the original goal over long runs. Community advice: split big tasks into several smaller goals and run them in batches, capping each goal at 2-4 hours instead of letting a single goal run for 18 hours.

Q: Will the agent get lazy and cut corners?

The risk exists. OpenAI officially recommends spelling out acceptance criteria in the goal, such as "every edge case must have a corresponding test case."

Q: How does this differ from Claude Code's multi-agent orchestration?

Claude's coordinator spawns at most 20 subagents and deliberately limits itself to a single layer (anything deeper than 1 is simply ignored). Codex's /goal allows freer parallel spawning, which suits complex multi-level tasks.

Q: Is there a ready-made tool to help me write better goals?

A developer known as RTK released the open-source project Infinite Skills, which includes a goal skill. Before you actually fire off /goal, it turns around and "interviews" you, interrogating a vague goal into a specific, verifiable contract.

GitHub address: https://github.com/Infinite-Labs-AI/infinite-skills