Codex CLI Goal Mode: Define Done, Not Next | by Daniel Vaughan | May, 2026 | MediumSitemapOpen in appSign up<br>Sign in

Medium Logo

Get app<br>Write

Search

Sign up<br>Sign in

Codex CLI Goal Mode: Define Done, Not Next

Daniel Vaughan

12 min read·<br>Just now

Listen

Share

Press enter or click to view image in full size

Codex CLI Goal ModeBefore v0.128.0, every Codex CLI interaction ended the same way: the agent finished a turn, and you typed the next prompt. For a single-file bug fix that works fine. For a 47-file test migration or a performance campaign that needs iterative benchmarking, the re-prompting becomes the bottleneck.<br>Goal mode, shipped experimentally in v0.128.0 on 30 April 2026 and enabled by default since v0.133.0 on 21 May 2026, replaces that manual loop with a persistent agentic one. You state an objective. Codex keeps working until the job is done, the token budget runs out, or it hits a wall it cannot solve alone.<br>This is not a cosmetic slash command. It changes Codex from a request-response assistant into a runtime-managed objective loop. The important part is not that the agent keeps going. The important part is how it stores the objective, budgets the run, audits completion, and stops without pretending partial progress is success.<br>Is this a Ralph loop?<br>Yes, in the important sense. Goal mode is Codex’s built-in version of the core Ralph loop idea.<br>A Ralph loop is the folk name for a long-running agent pattern: keep launching an AI coding agent against the same objective, or the next task in a plan, until the work is done, blocked or no longer worth continuing. The simplest version is a shell loop around a CLI agent. More serious versions add task files, verification commands, retries, logs, commits and reviewer agents.<br>Goal mode moves that loop inside Codex. Instead of wrapping Codex in an external script, you give it a persistent objective and let the runtime handle continuation, pause/resume state, token budgeting and completion status.<br>That makes goal mode simpler but less customisable. Use /goal when one Codex thread can finish one well-specified job. Use a Ralph-style harness when you need multiple agents, fresh sessions per iteration, Docker isolation, commit-per-task workflows, cross-model review or a PRD split into many atomic tasks.<br>What goal mode does<br>A standard Codex prompt follows a request-response cycle: you describe a task, the agent executes it, and control returns to you. The /goal command replaces that cycle with a persistent agentic loop:<br>/goal "Migrate the auth module from JWT to PASETO"Codex then:<br>Persists the objective as a first-class runtime entity, not a chat message that drifts out of context<br>Decomposes the objective into concrete deliverables<br>Executes work in turns, evaluating progress after each one<br>Continues autonomously until the goal is achieved, the token budget is exhausted, or a blocker is encountered<br>The objective survives context compaction, terminal crashes, session restarts and machine reboots. Resume the session, and the agent picks up where it left off.<br>Goals vs prompts<br>A standard prompt is an ask-work-result loop. A goal is a work-check-continue loop. That changes the operating model in six ways:<br>Continuation: prompts require manual re-prompting; goals continue automatically when the thread is idle<br>Objective persistence: prompts rely on the conversation; goals persist the objective throughout the thread<br>Completion decision: prompts leave completion to the user; goals require evidence-based verification by the agent<br>State survival: prompts are fragile under context compaction; goals use dedicated storage<br>Budget awareness: prompts have no explicit budget; goals track token use and trigger wrap-up behaviour near the limit<br>Failure mode: prompts tend to end with a conversational answer; goals can end as achieved, blocked or budget-limited<br>Architecture: how the loop works<br>Goal mode has five moving parts:<br>Persisted goal state: thread-scoped storage for the objective<br>Goal management API: structured handlers for goal operations<br>Model tools: get_goal and update_goal<br>Core runtime: token accounting and continuation logic<br>User interface: /goal commands and status display<br>The key distinction is ownership. In a normal prompt loop, the user owns continuation. In goal mode, the runtime owns it. The model still reasons about what to do next, but the runtime decides when to present the goal context again, when to account for tokens, when to inject the budget-limit instructions, and when the lifecycle changes state.<br>The continuation engine<br>Two internal prompts drive the loop.<br>The continuation prompt is injected at turn boundaries while the goal is in pursuing state. It instructs the agent to:<br>Decompose the objective into testable deliverables<br>Audit each requirement against concrete evidence: file inspection, command output, test results<br>Avoid marking completion on proxy signals alone<br>Track four metrics in real time: elapsed wall-clock time, tokens consumed, total...