How to Use /goal Efficiently: An Autonomous Agent Is an Operating Contract, Not a Magic Button (2026)

- /goal is a Codex feature, currently feature-flagged and changing fast; the syntax and behavior here were cross-checked against the official docs at the time of writing - verify the live docs before you depend on them.

What /goal is (and isn't)

/goal is Codex's goal mode (OpenAI Codex CLI) for a long, mechanical objective with a verifiable stop condition. You enable it via /experimental or by adding goals = true under [features] in config.toml, then run /goal <objective>. While it runs, type /goal to check status; control it with /goal pause, /goal resume, /goal clear.

And here's the most important part: /goal is not a safety boundary, not a replacement for product decisions, and not a place to run an unbounded backlog. It's a persistent loop, nothing more. (Note: /goal is a Codex feature, not a native Claude Code command - don't conflate the two.) For the syntax, see the official goal-mode guide.

The hard truth: /goal only makes the agent more persistent, not smarter

People hype /goal like it's the "press once, app builds itself" button. I overused it for a week and got slapped clean every time. The conclusion is simple: /goal doesn't make the agent smarter, it makes the agent more persistent. Persistent in the right direction is great; persistent in the wrong direction is painful - it just charges down the wrong path without stopping to question itself.

The three "slaps" below are the most common failure modes, and the lesson from each.

Slap #1 - boundary drift after auto-compact (a production deploy)

I wrote the goal very clearly: only deploy to staging. But after a few auto-compacts, the agent drifted out of context, forgot the boundary, and deployed straight to production - even though there was a hook reminding it of the task after every compact.

Painful lesson: never give an agent privileged access to production. Don't trust "it'll remember." No - it won't remember as reliably as you think. This is exactly why goal mode is not a safety boundary: the safety line has to live in your permissions, not in a note inside a prompt. See how to tighten access in Claude Code permissions and AI coding security best practices.

Slap #2 - vague goals are a license to wander

"Make it prettier." "Improve the UX." Sounds human. But for an agent, that's a license to wander. It changed one thing, broke another, hallucinated a bit, and sometimes stopped early while nothing had clearly improved.

Lesson: a goal must define what "better" means. Prettier how?

• Tighter spacing?
• More readable contrast?
• Better mobile responsiveness?
• Fewer checkout steps?
• Higher completion rate?

If you don't know what you want, don't throw it at an agent and run /goal. Brainstorm first, plan, write acceptance criteria. When the requirements are still unclear, a quick round of asking an advisor to clarify (advisor/kongming) beats turning on autonomy. For writing a plan with concrete checks, see project planning for Claude Code.

Slap #3 - missing verification (a confident, fake "done")

I set a goal for a new frontend page but forgot to tell the agent to use agent-browser for visual verification. The result? It skipped real verification and confidently reported "completed successfully." Then I opened it and remembered life is not a fairy tale.

Lesson: don't trust anybody. Provide the right tools, and explicitly require the agent to use them before finishing. Green tests are not enough:

• The frontend must be looked at (screenshot/agent-browser).
• The workflow must be clicked through.
• The deploy must check the environment.
• The PR must review the diff.

The operating contract - the formula for a good /goal

In short: a good /goal is not a clever prompt. It's an operating contract with five parts:

This matches the "use test" for goal mode: only use it when the task is (1) longer than one turn and mostly mechanical, (2) has a verifiable stop condition, and (3) is scoped clearly enough to progress without a product decision at each checkpoint. Don't use /goal for exploratory work, vague improvement requests, production credential changes, destructive shared infrastructure, or a mixed backlog.

How I use /goal: separate day-planning from night-execution

My favorite way now is to separate the daytime thinking from the nighttime execution.

By day (thinking)

1. Create GitHub issues for each bug / feature / enhancement.
2. Use the brainstorm & plan skills to clarify each issue.
3. Reply on the issue with an implementation summary + a link to plan.md.
4. Add the ready to implement label.
5. Repeat until every issue is prepared.

By night (execution)

Before resting and spending time with family, I let /goal run: "Implement all issues tagged ready-to-implement based on the predefined plans." The loop per issue:

1. Sort issues by priority.
2. Implement one issue at a time.
3. Create a separate worktree and branch per issue.
4. ak:cook --auto (continuous execution against the plan).
5. ak:code-review.
6. ak:ship beta.
7. ak:review-pr --fix.
8. Add the ready to ship label, then move to the next issue.

This works much better. The agent no longer guesses "what do you want?" - it executes against a clarified plan, with its own branch, review, beta deploy, PR, and label. Wake up, make coffee, open the machine, and there's a stack of PRs waiting. My job is no longer typing "continue" like a micromanaging clown - it's to review with human eyes, test again, then merge. To run worktrees/PRs in parallel, see orchestrating subagents; place this loop inside the brainstorm → plan → cook → ship workflow.

Want the gate loop prebuilt? (AgentKit)

The night loop is strong because of its quality gates: ak:cook, ak:code-review, ak:ship, ak:review-pr. AgentKit ships those gates and runs on both Claude Code and Codex - so it fits Codex's /goal. To be straight: /goal is Codex and free; the kit just adds the prebuilt process + review so you don't assemble it yourself. For details, read the AgentKit review or the Engineer Kit review.

The real value of /goal

That's the real value of /goal: not letting the agent think for you, but letting it handle repetitive execution after you've already done the thinking. You do the thinking - spec, plan, acceptance criteria - then let it grind. Your job is to review with human eyes, test again, then merge.

Frequently asked questions (FAQ)

What is /goal, and which tool is it?

/goal is Codex's goal mode (OpenAI Codex CLI), currently feature-flagged: enable it via /experimental or goals = true under [features] in config.toml. It is NOT a native Claude Code command - don't conflate the two.

When should you NOT use /goal?

For exploratory work, vague requirements, production credential changes, destructive shared-infrastructure operations, or a mixed backlog with unclear scope. /goal fits mechanical, long-running tasks with a verifiable stop condition.

How do you write a good goal?

Treat it as a five-part operating contract: Outcome (what "done" means), Scope (what it may/may not touch), Constraints (boundaries not to break), Verification (how "done" is proven), and Stop rules (when to stop or ask a human).

Can /goal deploy to production safely?

It shouldn't. Don't give the agent production access; goal mode is not a safety boundary. The safety line belongs in your permissions (least-privilege), not in a prompt note - after a few auto-compacts the agent may forget the boundary.

Are green tests enough for the agent to report "done"?

No. The frontend must be looked at (screenshot/agent-browser), the workflow clicked through, the deploy environment checked, and the PR diff reviewed. Provide the right tools and require the agent to use them before finishing.

Do you need AgentKit to use /goal?

No. /goal is Codex and free. AgentKit just adds the ak:cook / ak:code-review / ak:ship / ak:review-pr gates to run inside the loop - handy if you want a prebuilt process instead of assembling one.

Conclusion

Don't mythologize /goal. It's a stubborn loop - useful once you've done the thinking and just need repetitive execution. Write the goal as an operating contract, lock down production access, require verification, and separate day-planning from night-execution. Need to clarify requirements before running it? See advisor vs kongming. Need a plan with acceptance criteria? See project planning for Claude Code.