What is /goal in Claude Code and Codex?
By Philipp Kant 6 min read
/goal is a command in Claude Code and in OpenAI’s Codex that keeps a
coding agent working across turns until a stated completion condition
holds. Instead of stopping after one answer and waiting for the next
prompt, the agent starts another turn, and a check after every turn
decides whether the goal is met.
It is the built-in successor of the Ralph loop, the 2025 trick of running
an agent in a Bash loop until the work was done. In October 2026 teams are
deleting their Ralph scripts and pointing to /goal as the native
replacement.
/goal all tests in test/auth pass and the lint step is cleanHow /goal works in Claude Code
Setting a goal starts a turn right away, with the condition as the directive. From then on, the cycle is fixed:
- Claude works for one turn: reads, edits, runs commands.
- When the turn ends, Claude Code sends the condition and the conversation so far to the small fast model.
- The evaluator returns one of three verdicts with a short reason: not yet met (Claude takes the reason as guidance and starts the next turn), met (the goal clears), or impossible (the goal clears and the reason is logged).
| Command | What it does |
|---|---|
/goal <condition> |
Sets the goal (up to 4,000 characters) and starts working; replaces an active goal |
/goal |
Shows the condition, runtime, turns evaluated, token spend, and the latest reason |
/goal clear |
Removes the goal before it resolves |
claude -p "/goal ..." |
Runs the whole loop in one non-interactive call |
Two details decide how it behaves in practice:
- It does not change the permission mode. In manual mode Claude still
asks before tool calls that are not allowed. Unattended goals need auto
mode, which approves tool calls;
/goaladds the turns. - It is a hook. Under the hood,
/goalis a session-scoped, prompt-based Stop hook. Where hooks are disabled by settings or limited to managed hooks,/goalis unavailable too.
How /goal works in Codex
Codex uses the same word for the same idea: one durable objective that Codex pursues across turns, for hours if needed. OpenAI’s guide names migrations, large refactors, deployment retry loops, and prompt optimization against an eval suite as typical goals.
/goal <objective>sets it,/goalshows it, and/goal pause,/goal resume, and/goal clearcontrol the run.- OpenAI’s template: Complete [objective] without stopping until [verifiable end state].
- If
/goaldoes not appear in the slash commands, it is behind a feature flag:features.goals = trueinconfig.toml, orcodex features enable goals.
The evaluator only sees the transcript
This is the part most guides skip. In Claude Code the evaluator “doesn’t run commands or read files independently”. It judges the condition against what the working agent has shown in the conversation.
That changes who decides when the work is done. In a Ralph loop the
stopping signal came from the toolchain: tests and type checkers either
passed or they did not. With /goal, a model reads the transcript and
decides. That is more flexible (it can judge “every call site migrated”)
and easier to fool (a confident summary that the tests pass is not a test
run).
So a good condition asks for proof that ends up in the transcript:
| Weak condition | Condition that holds |
|---|---|
| “Fix the auth module” | “npm test test/auth exits 0 and the output is shown” |
| “Migrate to the new API” | “No file imports legacy-client, shown by a grep with zero results, and the build exits 0” |
| “Clean up the code” | “Every file in src/ is under 400 lines, listed with wc -l, and no test file is changed” |
| “Keep going until it works” | “…or stop after 20 turns and report what is left” |
Claude Code’s own guidance matches: one measurable end state, a stated check that proves it, the constraints that must not break on the way, and a turn or time clause to bound the run.
From the Ralph loop to /goal
The idea is a year old; the tooling caught up.
| Stage | How the loop ran | Who decided “done” |
|---|---|---|
| Ralph loop (Geoffrey Huntley, July 2025) | while :; do cat PROMPT.md | claude-code ; done, a fresh agent per pass |
Tests and a plan file the agent updated |
ralph-wiggum plugin for Claude Code |
A Stop hook re-feeding the same prompt until a completion promise appeared | The agent printing an agreed string |
/goal in Codex (30 April 2026) and Claude Code (11 to 12 May 2026) |
Built in, with status, token spend, resume, and pause | A separate evaluator model in Claude Code; the stated end state in Codex |
Ralph’s lessons still apply inside a goal: keep state in files, work one item at a time, and let tests push back. What disappeared is the scaffolding. The same thing happened to most agent techniques of the last two years; the timeline of AI agent techniques shows which aged, which moved into the products, and what lasts.
What goals mean for business automation
A goal is three things: an end state written down, an independent check, and a loop with a limit. The same shape works outside code wherever the end state is verifiable:
- Product data. “Every SKU in the export passes the marketplace schema; the validator report shows zero errors.” One record per pass, the validator as the check.
- Document processing. “Every invoice in the folder is extracted, and each extracted total matches the sum of its line items.”
- Migration. “Every page of the old site exists on the new one, and the link checker reports no 404s.”
Where the end state is a judgment (“is this reply friendly enough?”), a loop only repeats the uncertainty. Those steps get a person, by rule. That rule belongs in the agent harness, not in the prompt.
FAQ
Is the Ralph loop dead?
As a Bash script, mostly. Teams that ran it are switching to /goal. The
ideas behind it (fresh context, state in files, tests as backpressure)
live on in how good goals are written.
What does /goal cost? The working turns cost what they always cost. Claude Code bills the evaluation on the small fast model and describes it as typically negligible next to the main turns. The real cost risk is a goal without a limit, which is why the condition should carry one.
Can a goal run overnight? Yes, with auto mode in Claude Code or full-auto in Codex, and with the limits that make it safe: a sandbox or a branch, no production credentials, and a turn or time bound in the condition.
What is the difference between /goal and /loop?
In Claude Code, /goal starts the next turn when the previous one ends,
until a condition holds. /loop re-runs a prompt on a time interval,
such as checking a deploy every five minutes.
Do Claude Code and Codex goals behave the same? The idea is the same; the controls differ. Codex adds pause and resume, Claude Code shows the evaluator’s reason after every turn and restores an active goal when a session resumes.
AI agents that work toward verifiable goals inside your CRM, PIM, or ERP, with the checks and limits a business process needs, are what we build. The structure around them is explained in what an agent harness is.
Ask an AI about this post
