Inside the Codex CLI /goal Runtime Architecture

AI Agent · 2026-05-02 · 8 min read

View`thread_goals`, continuation runtime, and completion audit at the code level

In Part 1, we looked at Codex CLI/goalfrom the user's perspective. In this article, we look at the internal structure.

The key is simple.

1# Reading Guide: The blocks below are examples of commands, state flows, or templates.2/goal is not a single command.3It is a function that combines target state storage, app-server API, model tool, runtime continuation, and TUI control.

This article was written based on Codex GitHub PR and publicly available source files. This is a soon-to-be-released feature, so actual implementation may vary in future versions.

Analysis base date: 2026-05-02 Base version: Codex CLI0.128.0 Main reference materials: OpenAI Codex changelog, GitHub PR #18073–#18077,thread_goalsmigration,continuation.md,budget_limit.md

Key takeaways

/goalis a five-layer function leading to TUI command to app-server API to model tools to core runtime to state DB.
The goal status is stored in thethread_goalstable, and the status is limited toactive,paused,budget_limited, andcomplete.
The model tool cannot manipulate goals arbitrarily.update_goalis limited to completion processing, and pause/resume/clear/budget-limited transitions remain under user or runtime control.
The core runtime processes turn start, tool completion, turn finish, interrupt, resume, and idle continuation throughGoalRuntimeEvent.
The continuation prompt asks you to perform a completion audit based on the “current actual state” before completion.
From a good agent design perspective, the key to/goalis evidence event-driven continuation + audit + budget guard, notwhile true.

1. Overall structure: View in 5 layers

Based on the code,/goalis close to the structure below.

1# Reading Guide: The blocks below are examples of commands, state flows, or templates.2TUI /goal command3↓4app-server thread/goal API5↓6model tools: get_goal / create_goal / update_goal7↓8core runtime: continuation / accounting / interrupt / resume9↓10state DB: thread_goals table

Each layer has a different role.

layer	role	key points
TUI	UI for users to create, stop and erase`/goal`	Command and status display
app-server	API where the client controls the thread goal state	get/set/clear, notification, resume snapshot
model tools	A tool that allows the model to view, create, and complete goals	Permission restrictions are important
core runtime	Continue, accounting, interrupt, resume processing	Central to creating real “keeps going”
state DB	Save goal objective/status/usage	Thread-level persistence

Looking at this structure, it is clear that/goalis not simply a “prompt telling the model to continue.” The target state is in the DB, and the runtime updates the state according to the turn life cycle.

2. State DB:`thread_goals`table

At the very bottom is thethread_goalstable. On a public migration basis, this table stores the following information:

column	meaning
`thread_id`	Thread identifier with goal
`goal_id`	Identifier of the goal itself
`objective`	User-specified goals
`status`	One of`active`,`paused`,`budget_limited`,`complete`
`token_budget`	Optional token budget
`tokens_used`	Cumulative token usage during goal execution
`time_used_seconds`	Accumulated time during goal execution
`created_at_ms`	creation time
`updated_at_ms`	update time

If you write it as a pseudo type, you can see it like this.

1// Reading Guide: This is not an actual API, but pseudocode that explains the structure.2type ThreadGoal = {3  thread_id: string4  goal_id: string5  objective: string6  status: "active" | "paused" | "budget_limited" | "complete"7  token_budget?: number8  tokens_used: number9  time_used_seconds: number10  created_at_ms: number11  updated_at_ms: number12}

The important thing here isthread_id. A goal is not a simple memory flag, but is attached to thread state. So it can be connected to functions like resume, reconnect, and app-server snapshot.

Another important one isgoal_id. According to the description of PR #18073, stale update protection has been included. In other words, it is a device that prevents old goal updates from overwriting new goals.

1# Reading Guide: The blocks below are examples of commands, state flows, or templates.2problem:3- Goal A is in progress.4- The user replaces it with goal B.5- The goal A update that arrives late overwrites the state of goal B.6 7solve:8- Check expected goal_id when updating.9- If it is different from the current goal_id, it is considered a stale update and blocked.

This protection is important in AI agent runtime. This is because when multiple async tasks, tool results, and user mutations are mixed, “late-arriving updates” can break the state.

3. App-server API: thread goal control plane

The second layer is the app-server API. PR #18074 explains that the following RPC and notification were added to the v2 API.

1# Reading Guide: The blocks below are examples of commands, state flows, or templates.2RPC:3- thread/goal/get4- thread/goal/set5- thread/goal/clear6 7Notification:8- thread/goal/updated9- thread/goal/cleared

The reason this API is needed is because the client needs to reliably read and control the goal state.

API elements	role
`thread/goal/get`	Check the goal status of the current thread
`thread/goal/set`	Set goal or change state
`thread/goal/clear`	remove goal
`thread/goal/updated`	Notify the client of goal changes
`thread/goal/cleared`	Notify the client of goal deletion
resume/snapshot wiring	Allows the reconnected client to view the current goal status.

With this layer, not only TUI but also other clients can see the same goal status. In other words,/goalis not a TUI-specific hack, but a structure that handles materialized thread goals through the app-server.

4. Model tools: Limited model permissions

The third layer is the model-facing tool. According to PR #18075, there are three goal-related tools:

1# Reading Guide: The blocks below are examples of commands, state flows, or templates.2get_goal3create_goal4update_goal

This is where the design gets interesting. The model does not allow unlimited manipulation of the goal.

Tool	Allowed Roles	limits
`get_goal`	Check current goal	read center
`create_goal`	Create an explicitly requested goal	Restrict creation to only when there is no existing goal
`update_goal`	Goal completion processing	Limited to center on completion

The PR description explains that thepause,resume,clear, andbudget_limitedtransitions are not handled by the model at will, but are left user- or runtime-controlled.

This design is important.

Giving all state control to the model can cause problems like this.

1# Reading Guide: The blocks below are examples of commands, state flows, or templates.2- The model pauses itself to avoid work.3- The model arbitrarily releases the budget exceeding state.4- The model clears the goal created by the user.5- Marked as complete even though it is not completed.

So/goalallows the model to perform tasks and declare completion, but separates user control from runtime control.

1# Reading Guide: The blocks below are examples of commands, state flows, or templates.2Model permissions: lookup, explicit creation, completion processing3User permissions: pause, resume/unpause, clear, replacement4runtime permissions: budget_limited, accounting, continuation scheduling

This separation of rights is worth referring to when creating an agent system.

5. Core runtime: continuation state machine

The fourth layer is the most important. PR #18076 views long-running goals as a core runtime concern, not as a client. This is because the core manages turn lifecycle, tool completion boundaries, interruptions, resume behavior, and token usage.

Looking at thegoals.rsannotation in the public code, this module connects the core session and the state DB goal table and is responsible for goal mutation verification, protocol conversion, goal-update event issuance, and lifecycle hook.

Key events can be viewed as follows:

1# Reading Guide: The blocks below are examples of commands, state flows, or templates.2GoalRuntimeEvent3- TurnStarted4- ToolCompleted5- ToolCompletedGoal6- TurnFinished7- MaybeContinueIfIdle8- TaskAborted9- ExternalMutationStarting10- ExternalSet11- ExternalClear12- ThreadResumed

Summarized in pseudocode, it is as follows.

1// Reading Guide: This is not an actual API, but pseudocode that explains the structure.2on TurnStarted:3  capture token usage baseline4  if current thread has active goal:5    mark goal active for this turn6 7on ToolCompleted:8  account token/time usage9  reset no-tool continuation suppression10  if token budget exceeded:11    mark goal as budget_limited12    inject budget wrap-up steering13 14on TurnFinished:15  account final usage16  if this was a continuation turn and tool_calls == 0:17    suppress next automatic continuation18 19on MaybeContinueIfIdle:20  if session is idle and active goal exists:21    start continuation turn22 23on TaskAborted with interrupt:24  account usage25  pause active goal26 27on ThreadResumed:28  reactivate paused goal outside plan mode

Here, the true nature of/goalis revealed. The reason Codex “appears to continue working” is not because the model runs in an infinite loop by itself, but because it schedules a continuation turn while the core runtime is idle.

1# Reading Guide: The blocks below are examples of commands, state flows, or templates.2active goal exists3+ session is idle4+ not suppressed5+ budget not exhausted6= start continuation turn

6. Continuation prompt: The key to completion auditing

continuation.mdtemplate is the key to/goalquality.

This prompt instructs you to continue executing the active thread goal first. At the same time, it specifies that the objective should be treated as “user-provided data.” In other words, the goal statement is not promoted like a system instruction.

Also, the following information is included in each continuation.

1# Reading Guide: The blocks below are examples of commands, state flows, or templates.2Time spent pursuing goal3Tokens used4token budget5Tokens remaining

The most important part is the completion audit. The prompt asks you to do the following before declaring completion:

request	meaning
Reorganize objectives into concrete deliverables/success criteria	Convert your goals into testable form
Mapping all explicit requirements to evidence checklist	Avoid missing requirements
View real evidence including files, command output, test results, PR status, etc.	Judge based on current status, not words
Do not complete with proxy signal alone	“Passing the test” is only evidence if it covers the entire goal
If you are uncertain, keep working instead of completing.	Prevent premature completion in ambiguous states

This part is very important in AI agent design.

This is how a bad agent loop ends:

1# Reading Guide: The blocks below are examples of commands, state flows, or templates.2One test passed3to It's probably okay4→ complete

A good goal runtime should end like this.

1# Reading Guide: The blocks below are examples of commands, state flows, or templates.2List your target requirements3to map each requirement to actual evidence4to Check missing/unverified items5to complete if all are met6to or select the next concrete action

This is the difference between/goaland a simple repeat prompt.

7. Budget limit: soft stop design

/goalhas the concept of token budget. Public migrations includetoken_budgetandtokens_used, and runtime PR explains that token budget exhaustion is treated as a soft stop.

The important thing is that active turns are not forced to abort when the budget is reached. Instead, we mark the goal asbudget_limitedand inject wrap-up steering.

The intention ofbudget_limit.mdis as follows:

1# Reading Guide: The blocks below are examples of commands, state flows, or templates.2- The active thread goal has reached the token budget.3- Objective is treated as user-provided data.4-Do not start new substantive work.5- Organize progress, remaining tasks, blockers, and next steps.6- Do not call update_goal complete unless it is actually completed.

This is a good design. Just because the budget is over doesn't mean the goal is complete.

1# Reading Guide: The blocks below are examples of commands, state flows, or templates.2budget exhausted!= goal complete

If the budget limit is designed incorrectly in a practical agent, two problems arise.

bad design	problem
Immediate hard abort when budget is exceeded	Remaining tasks and status are not communicated to users
Treat budget exceedance as complete	Unfinished tasks appear complete

Codex's direction is somewhere in between.

1# Reading Guide: The blocks below are examples of commands, state flows, or templates.2over budget3to budget_limited state transition4to prevent starting new tasks5to Summary of progress and reporting of remaining work6to complete only when it is actually completed

8. Loop guard and safety device

The most dangerous thing about long-running goals is endless repetition./goalcontains devices to reduce this.

8.1 No-tool continuation suppression

PR #18076 explains that automatic continuations are suppressed when the continuation turn ends without a tool call.

The meaning is this:

1# Reading Guide: The blocks below are examples of commands, state flows, or templates.2Start continuation turn3The to model just talks without actually reading/editing files/executing commands.4→ tool_calls == 05to suppress next automatic continuation

This device is important. Otherwise, your model can get stuck in a loop where it just says things like “I’ll keep going.”

8.2 Interrupt pause

When the user stops, the active goal is paused. This is a structure to prevent the goal from continuing even if the user stops.

1# Reading Guide: The blocks below are examples of commands, state flows, or templates.2user interrupt3→ active goal accounting4→ goal status paused

8.3 Resume auto-reactivation

According to the description of PR #18076, when thread resumes, an action has been taken to automatically reactivate paused goals if they are not in plan mode. In other words, it treats interruption and resumption as part of the goal lifecycle.

8.4 Stale goal_id protection

In the state layer, there is stale update protection based ongoal_id. Prevents old updates from overwriting new goals.

8.5 Objective privilege separation

The continuation prompt treats the objective as user-provided data rather than a “higher-priority instruction”. This is a structure to prevent it from being promoted to a system/developer instruction even if the user enters a strong command in the goal.

9. Apply to your own Agent design

The most important thing to learn from/goalis the separation of “auto-repeat” into runtime events.

Bad implementations usually end up like this.

1// Reading Guide: This is not an actual API, but pseudocode that explains the structure.2while (true) {3  const result = await agent.run(goal)4  if (result.done) break5}

This method is simple but risky.

1# Reading Guide: The blocks below are examples of commands, state flows, or templates.2- The completion judgment is weak.3- Cost restrictions are poor.4- Difficult to stop/resume.5- Difficult to handle user input priorities.6- It is difficult to prevent repetition without tool calls.7- A previous goal update may overwrite the new goal.

A better structure would be like this:

1// Reading Guide: This is not an actual API, but pseudocode that explains the structure.2interface GoalRuntime {3  state: GoalStateStore4  scheduler: ContinuationScheduler5  auditor: CompletionAuditor6  accounting: UsageAccounting7  controls: UserControls8  guards: LoopGuards9}

The responsibilities of each component are separated.

component	responsibility
`GoalStateStore`	Save objective, status, usage, timestamps
`ContinuationScheduler`	Next turn starts only in idle state
`CompletionAuditor`	Mapping requirements and evidence to determine completion
`UsageAccounting`	token/time budget accumulation
`UserControls`	pause, resume, clear, replace
`LoopGuards`	no-tool suppression, stale update protection, interrupt handling

The actual implementation pseudocode can be captured as follows.

1// Reading Guide: This is not an actual API, but pseudocode that explains the structure.2async function maybeContinueIfIdle(session: Session) {3  if (!session.isIdle()) return4  if (session.hasPendingUserInput()) return5 6  const goal = await goalStore.get(session.threadId)7  if (!goal || goal.status !== "active") return8  if (goalRuntime.isContinuationSuppressed(goal.goal_id)) return9  if (goal.token_budget && goal.tokens_used >= goal.token_budget) return10 11  await session.startContinuationTurn({12    prompt: renderContinuationPrompt(goal),13    goal_id: goal.goal_id,14  })15}

It is recommended that completion judgments be separated by a separate auditor.

1// Reading Guide: This is not an actual API, but pseudocode that explains the structure.2async function auditCompletion(goal: Goal, evidence: Evidence[]) {3  const checklist = buildChecklist(goal.objective)4  const coverage = mapEvidenceToChecklist(checklist, evidence)5 6  if (coverage.hasMissingItems()) {7    return { complete: false, nextAction: coverage.suggestNextAction() }8  }9 10  if (coverage.hasWeakVerification()) {11    return { complete: false, nextAction: "collect stronger evidence" }12  }13 14  return { complete: true }15}

The key is not whether the agent worked hard, but whether the requirements were met with actual evidence.

10. Implementation Checklist

If you are creating your own goal-based agent, it is recommended to check the following.

1# Reading Guide: The blocks below are examples of commands, state flows, or templates.2Goal State3[ ] Place goal_id.4[ ] Save the objective.5[ ] Limit status to active/paused/budget_limited/complete, etc.6[ ] Accumulate token/time usage.7[ ] Enable stale update protection.8 9Runtime10[ ] separates the turn started/finished events.11[ ] Count usage from tool completed events.12[ ] The continuation starts only in idle state.13[ ] User input takes precedence over continuation.14[ ] Pauses the active goal when interrupted.15[ ] Restores the goal state when resumed.16 17Completion Audit18[ ] Reorganize objectives into success criteria.19[ ] Make requirements into a checklist.20[ ] Map each item to a file/command/test result.21[ ] Do not complete processing with proxy signal alone.22[ ] If uncertain, proceed with continue rather than complete.23 24Budget25[ ] A token budget can be set.26[ ] If the budget is exceeded, it is not processed as complete.27[ ] Provides wrap-up in budget_limited state.28[ ] Steering so as not to start a new substantive task.29 30User Controls31[ ] pause is supported.32[ ] Supports resume or unpause.33[ ] Clear is supported.34[ ] When replacing, distinguish between the existing goal and the new goal.35 36Loop Guards37[ ] A continuation without a tool call is not repeated.38[ ] Set a long-running command timeout.39[ ] Record history to avoid repeating the same failure.40[ ] Limit permissions and writable scope.

11. References and uncertainty

References

OpenAI Codex changelog:https://developers.openai.com/codex/changelog
OpenAI Codex GitHub repository:https://github.com/openai/codex
PR #18073 — goal persistence foundation:https://github.com/openai/codex/pull/18073
PR #18074 — app-server goal API:https://github.com/openai/codex/pull/18074
PR #18075 — model-facing goal tools:https://github.com/openai/codex/pull/18075
PR #18076 — core runtime goal loop:https://github.com/openai/codex/pull/18076
PR #18077 — TUI goal UX:https://github.com/openai/codex/pull/18077
thread_goalsmigration:https://raw.githubusercontent.com/openai/codex/main/codex-rs/state/migrations/0029_thread_goals.sql
continuation.md:https://raw.githubusercontent.com/openai/codex/main/codex-rs/core/templates/goals/continuation.md
budget_limit.md:https://raw.githubusercontent.com/openai/codex/main/codex-rs/core/templates/goals/budget_limit.md
Issue #19910 — User report regarding compaction:https://github.com/openai/codex/issues/19910
Issue #20536 —/goalDocumentation Request:https://github.com/openai/codex/issues/20536

confirmed facts

Thethread_goalstable storesthread_id,goal_id,objective,status,token_budget,tokens_used,time_used_seconds, timestamps.
statusis limited toactive,paused,budget_limited,complete.
thread/goal/get,thread/goal/set,thread/goal/clearRPC and goal updated/cleared notification have been added to app-server.
The model-facing tools areget_goal,create_goal, andupdate_goal, andupdate_goalis limited to the center of completion.
The core runtime handles idle continuation, usage accounting, budget limit, interrupt pause, resume reactivation, and no-tool suppression.

Author's interpretation

/goalcan be seen as an example of incorporating the “goal-based runtime” of an AI coding agent into a popular product.
The most important design point is the completion audit rather than the continuation scheduler.
This structure can be applied not only to Codex CLI but also to its own AI Agent, CI repair bot, and long-running coding assistant.

uncertainty

As this is a feature immediately after release, CLI help, command alias, and documentation may be subject to change.
The compaction failure mode mentioned in GitHub issue #19910 is based on user reports and may be modified in the future.
This is based on open source analysis, so internal runtime details or product behavior may vary across versions.

finish

In summary, Codex CLI/goalis not a simple slash command, but a function that configures the agent runtime around the goal state.

The most important lesson is this:

1# Reading Guide: The blocks below are examples of commands, state flows, or templates.2If you want to run the AI Agent for a long time, do not create a while loop first,3Status, events, auditing, budget, and user controls must be designed first.

/goalshows that direction well. It stores goals, continues with runtime events, audits completion with actual evidence, and handles budgets and interrupts as state transitions.

If you are creating your own AI coding agent, this structure is worth referring to. In particular, theGoal State + Evidence Checklist + Continuation Scheduler + Budget Stop + User Controlcombination is a much safer starting point than simple repetition.

GitHub 계정으로 로그인하면 댓글을 남길 수 있습니다. 댓글은 GitHub Discussions를 통해 운영됩니다.