Goal

Goal

Overview

Use Codex's native goal state to keep a thread oriented around a verifiable completion condition. This is the Codex adaptation of Claude Code's /goal: a persistent objective, explicit status, and disciplined completion/blocked marking.

Command Mapping

• /goal <condition> or "set a goal": call create_goal with a concrete objective, then start working toward it immediately.
• /goal or /goal status: call get_goal and report the current objective, status, budget, and remaining work.
• /goal clear, /goal stop, or /goal done: do not claim a native clear operation exists. If the goal is actually achieved, call update_goal(status="complete"); if not, explain that Codex exposes complete/blocked status but not a separate clear/pause operation.
• "pause goal" or "resume goal": report that native Codex goal tools do not expose pause/resume. Continue only if the user explicitly resumes the work in the conversation.
• A new /goal <condition> while an unfinished goal exists: call get_goal, explain the active goal, and do not replace it unless the active goal is already complete. Codex goal creation fails for unfinished goals.

Goal Quality

Before creating a goal, make the objective outcome-based and checkable. Prefer conditions with clear evidence: tests pass, named files exist, a report is written, an issue list is empty, a service health check passes, or a requested artifact is delivered.

If the user's condition is vague but the intent is inferable, convert it into a concrete objective without asking. Ask only when no safe completion condition can be inferred.

If the user provides an explicit token budget, pass it to create_goal as token_budget. Otherwise omit the budget.

Proactive Suggestions

When the user has not explicitly invoked /goal, suggest or use goal mode for tasks that have a clear finish line and would benefit from persistence. Keep the suggestion short and plain-language, especially for non-technical users.

Good proactive triggers:

• "Fix this until it works" or any task where tests/health checks define success.
• Multi-step audits, cleanup passes, or reconciliation work where findings must be closed.
• Building or updating a named artifact such as a report, spreadsheet, deck, script, or app until it is usable.
• Long-running debugging, scraping, ingestion, or migration tasks with retries and validation.
• Operational repairs where the endpoint, service, bot, cron, or workflow must be verified healthy.

Do not suggest goal mode for quick questions, one-off commands, brainstorming, status-only requests, or tasks where the user explicitly asks only for a plan or explanation.

Suggested phrasing:

This has a clear finish line and may take several checks. I can put it in goal mode so I keep working until [specific condition] is true.

Working Loop

When a goal is active, keep working toward it across turns until it is genuinely achieved, genuinely blocked under the runtime blocked rules, or the user redirects the thread. Use normal Codex tool practices: inspect state, edit conservatively, verify with commands/tests, and keep user updates concise.

Before claiming completion, verify the acceptance condition from real evidence. Call update_goal(status="complete") only when the objective is achieved and no required work remains. If the goal had a token budget, report the final usage returned by the tool.

Call update_goal(status="blocked") only after the same blocking condition has recurred for at least three consecutive goal turns and there is no meaningful progress possible without user input or external state change.

Safety Rules

• Do not treat a goal as permission to exceed the user's current scope.
• Do not override a newer user instruction with an older active goal.
• Do not convert an analysis-only request into file edits merely because a goal exists.
• Do not mark complete because the budget is nearly exhausted.
• Do not loop on tool errors. Investigate, try reasonable alternatives, and surface a blocker when the runtime blocked threshold is met.
• Do not fabricate verification. Completion must cite the command, file, output, or artifact that proves the condition.

Practical Pattern

For /goal all tests pass and the branch is ready:

1. Call create_goal with objective "All tests pass and the current branch is ready to hand off."
2. Inspect the repo, run the relevant tests, fix failures, and rerun verification.
3. If tests pass and no required cleanup remains, call update_goal(status="complete").
4. Final response: summarize the changes, verification, and goal completion status.

For /goal status, never do task work first. Read and report the goal state.