Codex CLI /goal — A Guide | Build Great Products

01

What is Codex CLI?

Codex CLI is OpenAI's lightweight, local-first coding agent that runs in your terminal — comparable in concept to Claude Code or Aider. It's an interactive REPL that reads and edits files, runs shell commands in a sandbox, and can sign in with a ChatGPT (Plus / Pro / Business / Edu / Enterprise) account or an API key.

Install it with whichever package manager you prefer:

bash

npm i -g @openai/codex

Repo: github.com/openai/codex · Docs: developers.openai.com/codex

02

What /goal actually does

/goal attaches a persisted objective to the session. Unlike a normal prompt (a one-shot instruction) or /plan (which scopes the approach before work begins), /goalkeeps an objective active across continuation, status, and completion checks — effectively a "task contract" with token / budget accounting and structured completion verification.

Use it when you have a bounded, audit-ready objective with deliverables, acceptance criteria, and a stop rule. Skip it for brainstorming, ambiguous problems, or tasks lacking verifiable completion.

03

The four subcommands

/goal <objective> — set / start a goal
/goal pause — pause the active goal
/goal resume — resume a paused goal
/goal clear — clear the goal

04

Lifecycle states

The TUI surfaces five states so you can tell at a glance where the agent is:

pursuing — actively working
paused — held via /goal pause
achieved — agent claims success; verify before trusting
unmet — agent gave up or could not complete
budget-limited — wrapped at the token / cost budget

05

A strong /goal in practice

A good objective is specific about scope, files, acceptance, verification, and stop conditions. It reads like a small task brief, not a wish:

codex

/goal Add CSV export to the billing table.
Acceptance: action button beside filters; columns = account ID, period,
model, tokens, cost, status. Edit app/billing and CSV utilities.
Verify: npm test -- billing and npm run lint pass.
Stop if billing API lacks raw row data.

Weak — avoid

/goal improve the dashboard
No scope, no acceptance criteria, no stop rule. The agent will either over-reach or wander.

Strong — ship-ready

Names the deliverable (CSV export), the surface (action button beside filters), the columns, the files (app/billing + CSV utils), the verification (npm test + npm run lint), and an explicit stop rule.

06

Workflow: Plan → Set → Monitor → Verify → Clear

If the work needs decomposition, run /planfirst — that is the exploration step, equivalent in spirit to Claude Code's plan mode. Then promote the resulting plan into a /goal. While the agent is pursuing, monitor the diff and intermediate tool calls. When it claims achieved, run a completion audit yourself before clearing.

07

Best practices

Make objectives audit-ready. Specific scope, files / modules, acceptance criteria, verification commands (tests, lint), evidence requirements, and an explicit stop rule.
Pair with /plan. /goal is for persistence, not exploration. Plan first, then commit.
Run a completion audit. Before accepting achieved: do diffs match declared scope? Did the promised tests actually run? Was budget-limited handled? Were unrelated refactors avoided?
Verify your version. codex --version should report ≥ 0.128.0; older builds predate the feature.
Don't use it unattended overnight. It supports budget-limited wrapping, not open-ended autonomy.

08

How /goal compares

Codex /plan vs /goal: /plan is pre-flight scoping (read-only exploration that produces a plan). /goal is the commit step that persists an objective during execution. They compose: plan first, then goal.

Claude Code plan mode is the closer analog to Codex /plan. Claude Code does not have a direct equivalent of /goal's persisted lifecycle with pursuing / paused / achieved / unmet / budget-limited states — it relies on the conversation thread plus task tracking, without an explicit pause / resume / clear contract or budget gate.

Aider has no equivalent persisted-goal primitive; it operates per-message with git-commit-per-edit semantics.

09

Codex CLI /goal.