How OpenAI's Top Codex Developers Use Codex

In Codex CLI, /goal sets, views, pauses, resumes, or clears a task goal. OpenAI describes it as a way to give Codex a persistent target to track while a larger task runs. That makes it different from a normal prompt: a prompt asks for the next answer; a goal defines the state Codex should keep working toward.

Most weak /goal runs fail before Codex starts. The prompt says “fix the backlog” or “finish the migration,” but it does not say what counts as finished. The better pattern is a contract. Give Codex the outcome, the first places to read, the allowed scope, the proof commands, and the stop rules.

/goal
Clear the Linear view "May cleanup" of all reproducible P0/P1 bugs.

Read first:
- Linear issues in the view, linked logs, recent CI failures, AGENTS.md, and test docs.

Scope:
- Fix only bugs with a clear repro or failing test.
- Do not change billing behavior, auth policy, or data deletion flows without asking.

Proof:
- For each fixed issue, run the targeted regression test.
- Run bun test and bun run typecheck before final handoff.

Checkpoints:
- Group related failures and report status after each group.
- Include issue id, files changed, test command, and result.

Stop if:
- A product decision is needed.
- Credentials are missing.
- The bug cannot be reproduced.
- The fix would require a risky migration.

The famous /goal shape is the overnight backlog run: point Codex at a queue, let it work through related failures, and wake up to a reviewed set of fixes, tests, blockers, and residual risk. The value is not that Codex can fix a bug. The value is that it can keep context across a queue instead of making you restart the investigation every fifteen minutes.

• Good backlog goal: fix every reproducible P0/P1 in one scoped view, with tests and a blocker list.
• Bad backlog goal: fix all bugs everywhere and make the app better.
• Good migration goal: move one package to the new API, preserve rollback, and pass contract tests.
• Bad migration goal: modernize the codebase.
• Good cleanup goal: classify stale issues, close duplicates, draft release notes, and list decisions for a human.

OpenAI's CLI docs describe /goal as a slash command for setting or viewing an experimental task goal. The same command family gives you the steering loop: inspect status, pause when the run needs review, resume after you answer, and clear the goal when the work is done or the direction changes.

Useful status prompts:
What checkpoint are you on?
What evidence says this bug is fixed?
Which issues are blocked and why?
What commands are still running?
Show me the diff summary before continuing.
Pause before touching auth, billing, deletes, migrations, or production config.

A long-running Codex goal is only as reliable as the computer underneath it. The official Codex cloud task model checks out a repo, runs setup, executes terminal commands in a loop, uses AGENTS.md when present, validates work, and returns a diff. That loop is also the reason local and remote environments matter: the agent needs the repo, test cache, browser sessions, credentials, simulators, logs, and desktop tools to still be there when the next checkpoint starts.

Recommended host layout:

Hyperbox Mac mini
  repo checkout
  AGENTS.md with project commands
  dedicated macOS user
  browser profile for Codex
  Xcode / simulator / desktop apps when needed
  SSH + VNC recovery
  persistent logs and screenshots

Your laptop
  review diffs
  steer /goal status
  pause/resume/clear the run
  approve product decisions

The best goals are boringly specific. They name a queue, a repo boundary, a proof loop, and a stop rule. Here are practical examples that are safer than “go fix everything.”

/goal
Migrate the dashboard package from the legacy REST client to the typed API client.
Read AGENTS.md, packages/dashboard/README.md, existing API tests, and the migration plan first.
Do not touch auth, billing, or analytics behavior.
For each migrated route, add or update a contract test.
Run bun test packages/dashboard and bun run typecheck.
Stop if an endpoint has no typed equivalent or if behavior differs from production logs.

/goal
Rebuild the public changelog for releases v0.18 through v0.23.
Read release tags, merged PRs, commit history, and existing changelog style.
First produce a candidate table: release, commit or PR, shipped change, confidence, include or skip.
Skip experiments, refactors, and feature-flagged work unless user-facing.
Then draft release notes and list any uncertain entries for review.

/goal
Record the live product demo and produce a timestamped transcript.
Open the event URL in the browser profile named codex-capture.
Verify the page is live, audio is present, and the recording file is growing.
Save the audio, transcript, speaker notes, and a five-bullet decision summary.
Stop if login, consent, or recording permission is unclear.

/goal is powerful precisely because it encourages autonomy. That is also why it is the wrong tool for fuzzy, high-risk, or decision-heavy work. Use a normal prompt, planning turn, or human review loop when the outcome is not measurable yet.

Codex cloud environment docs call out AGENTS.md as the place Codex can find project-specific lint and test commands. For /goal, that file is leverage. It keeps every long run from rediscovering how the repo works.

# AGENTS.md

## Project commands
- Install: bun install
- Typecheck: bun run typecheck
- Unit tests: bun test
- SEO files: bun run seo:generate

## Goal rules
- Start long tasks by reading linked issues, failing logs, and this file.
- Prefer targeted tests before full-suite tests.
- Never modify auth, billing, deletes, or production config without asking.
- For final handoff, include changed files, commands run, results, blockers, and residual risk.

## Visual work
- Run the local dev server.
- Capture desktop and mobile screenshots.
- Fix layout or image issues before calling the task done.

1. Write one objective and one stop condition.
2. Tell Codex what to read before editing.
3. Define in-scope and out-of-scope files, systems, and behaviors.
4. Name the proof commands and artifacts that count as progress.
5. Ask for checkpoints with files changed, tests run, and blockers.
6. Use /goal status to inspect progress instead of waiting blindly.
7. Pause before risky areas such as auth, billing, deletes, migrations, or production config.
8. Run the goal on a persistent machine when the task needs hours of tests, browsers, desktop apps, or Mac-only tools.
9. Make the final handoff reviewable: summary, diff, proof, failures, residual risk, and next steps.

What is Codex /goal?

Codex /goal is a Codex CLI slash command for setting, viewing, pausing, resuming, or clearing a durable task goal. It is useful when a coding task needs multiple checkpoints, tests, and iterations instead of one prompt-response cycle.

What should I include in a Codex /goal prompt?

Include one objective, one stop condition, read-first context, in-scope and out-of-scope areas, proof commands, checkpoint expectations, and stop rules for risky or ambiguous work.

When should I use /goal instead of a normal Codex prompt?

Use /goal for long-running work such as backlog cleanup, migrations, release notes, test repair, browser capture, and repo archaeology. Use a normal prompt for small fixes, questions, one-off edits, and tasks without a measurable finish line.

Why run Codex /goal on a remote Mac mini?

Long-running goals need a stable machine with the repo, build cache, browser sessions, logs, desktop apps, and SSH or VNC recovery. A persistent Mac mini keeps that environment available after your laptop sleeps or disconnects.