Plan Mode & Goals

When a task is small and obvious — "fix this typo", "rename this variable" — you just tell Codex and it does it. But the moment a task spans several files, touches code you don't fully understand, or could go several ways, letting the agent dive straight into edits is how you get a confident-looking change that solves the wrong problem.

The fix is a discipline borrowed from how good engineers actually work: separate research from execution. First understand the terrain and agree on an approach; then make changes. Codex gives you two purpose-built controls for exactly this split:

• /plan — switch into plan mode, where Codex investigates the codebase and drafts an approach without editing files, so you can read and correct its thinking before any code moves.
• /goal — pin down what done looks like as an explicit, persistent target the agent works toward and checks itself against.

Think of it like briefing a capable teammate on an unfamiliar codebase. You wouldn't say "go refactor the auth layer" and walk away. You'd ask them to look around, come back with a plan, and tell you how they'll know it worked. Plan mode and goals are how you have that conversation with Codex — and the payoff is that the actual editing run, once it starts, is far more likely to land on the first try.

/plan switches Codex into plan mode and optionally sends a prompt in the same step. In plan mode the agent does its usual context-gathering — reading files, searching the repo, exploring structure — but instead of jumping to edits it produces a proposed plan you can read, push back on, and refine. You stay in the driver's seat for the part that matters most: deciding what will happen before it happens.

/plan add rate limiting to the login endpoint and update the tests

For genuinely complex or ambiguous work, do one better than handing over a one-line prompt: ask Codex to interview you first. Tell it to ask clarifying questions before drafting anything — "Before you plan, ask me whatever you need about the rate-limit policy, where config lives, and how we test middleware." This turns a guess into a conversation and surfaces the assumptions that would otherwise become silent mistakes.

A good plan-mode loop looks like this:

1. /plan with a short description of the goal (or ask it to interview you).
2. Read the proposed plan; correct anything wrong about the approach, scope, or order.
3. Iterate until the plan is right — it's just text, so this is fast and cheap.
4. Hand off to execution and let Codex carry out the agreed plan.

The reason this works: a plan is text you can fully review, whereas a diff is the consequence of decisions you never saw. Catching a flawed approach in the plan costs one re-read; catching it in a finished diff costs an unwind and a restart.

A goal is a persistent statement of what you're trying to achieve, set with /goal. Its quiet superpower is that it does double duty: it's both direction (what to work toward) and completion criterion (how the agent knows it's done). A well-written goal is the thing that lets Codex stop when the work is actually finished — rather than when the code merely looks done.

/goal is a small state machine. You can:

The quality of a goal is mostly the quality of its done-when. Vague goals ("make auth better") give the agent nothing to check itself against. Effective goals have a specific outcome, a measurable target, or explicit test criteria:

The pattern to internalize is the done-when clause: a goal isn't finished until something true and checkable is true. Pair that with a runnable verifier (a test, a build, a lint) and Codex can close its own loop — running the check, reading failures, and iterating — instead of leaving you to be the verification step.

Planning is a tool, not a ritual. Forcing a plan onto a one-line fix just adds latency and ceremony; skipping a plan on a sprawling refactor invites a confident wrong turn. The judgment call is what separates fluent Codex users from frustrated ones.

Reach for /plan (and usually a /goal) when the work is:

• Multi-file — changes that ripple across modules, where order and blast radius matter.
• Uncertain — there are several reasonable approaches and you want to choose deliberately.
• Unfamiliar — you (or the agent) don't yet understand the code being changed.

Skip straight to execution when the work is small and clear — a typo, a rename, a one-line bug fix, a tweak to a value. The cost of a plan exceeds its benefit; just describe the change and let it run.

A reliable heuristic: if you can't predict the diff, plan first. When you already know roughly what the change looks like, planning is overhead. When you don't, the plan is the work — and getting it right on paper is far cheaper than getting it wrong in code.

Plan mode decides whether the agent thinks before acting; reasoning effort decides how hard it thinks on every turn. It's a separate dial, set with the config key model_reasoning_effort in ~/.codex/config.toml, or changed live in a thread via /model (which adjusts model and effort together).

# ~/.codex/config.toml
model_reasoning_effort = "high"   # minimal | low | medium | high | xhigh

Match the dial to the task:

Higher effort buys you more careful reasoning at the cost of latency and tokens, so spending it on a typo is pure waste — and starving a hard refactor of it is false economy. A practical rhythm: keep your session at medium, bump to high or xhigh when you hit a genuinely thorny step, then drop back down. Effort and plan mode work together — a hard task often deserves both a plan and elevated effort.

Two facts worth pinning, because they rot: xhigh ("Extra High") is model-dependent — not every model exposes it — and the exact per-model defaults shift release to release. Don't memorize a default; check the live model pages.

Planning and goals only pay off if the thread they live in stays coherent. The single most common mistake here is treating a Codex thread like a project-long chat window — pouring weeks of unrelated tasks into one ever-growing conversation. Don't. The rule is simple:

One thread per coherent unit of work — not one thread per project.

Why it matters: every turn shares the same context window. When you mix "add rate limiting," "fix the CSS bug," and "upgrade the test runner" into one thread, the agent drags irrelevant history into every reply — costing tokens, diluting focus, and inviting confusion between unrelated tasks. A goal is meant to scope a thread; when you /goal clear and the unit of work is done, that's usually your cue to start fresh.

Keep threads clean with a few habits:

• Start a /new conversation (or a fresh codex session) when you move to an unrelated task.
• /fork to branch off and explore a tangent without polluting the main thread, preserving the original transcript.
• /compact to summarize a long-but-still-relevant conversation and reclaim tokens when a single unit of work runs long.
• /goal clear when the unit is done — a natural boundary for wrapping up the thread.

This is the connective tissue of the whole workflow: plan sets the approach, goal sets the finish line and scopes the thread, reasoning effort sets the intensity, and session hygiene keeps each thread focused enough that the first three actually work.