Local Agent Runtime 🧠
Scope: local desktop → app-server → agent runtime path for one turn. Not a complete map of every Codex surface or execution environment.
Context & History 👀
Incremental history management and compaction for the model context window.
Model Input Assembly 📚
Builds the model request. Base instructions (the system prompt), conversation items (world state + history), and tool definitions occupy different parts of the request — not one system prompt.
Sandbox & Execution ⚡️
Sandboxed command execution and permission/approval enforcement across platforms.
Tools 🛠️
Tool registry and handlers the model can invoke; exposure gated by the tool policy.
Desktop UI
MacOS App- The Codex desktop application
- Sends JSON-RPC requests (turn/start)
- renders streamed message deltas
- forwards approval responses.
openai/codex
Source · RustLightweight coding agent that runs in your terminal
OpenAI Responses API
Model backendExternal model backend streamed over WebSocket or SSE with retry and image-detail normalization.
App Server
JSON-RPC boundaryRust app-server: JSON-RPC boundary. stdio is the default transport; WebSocket is an optional experimental transport.
- Receives requests, routes via
MessageProcessor - hands turns to core via CodexThread
- Translates core events into UI notifications.
apply_patch
file editing- applies unified-diff patches via the apply_patch grammar
- a single patch can update multiple files.
Base Instructions
the system promptThe actual system prompt:
- the Responses
instructionsfield - resolved from user config override
- persisted session meta, or the model catalog template.
Compaction
run_auto_compactPre/mid/post-turn window resets:
- token-budget reset
- remote compaction V2, or local summarization via
replace_compacted.
Context Injection
build_initial_context_with_world_stateBuckets ContextualUserFragments into
- aggregated developer messages
- separate developer messages
- contextual user sections
then records them into history.
ContextManager
history.rsSingle write/read path for the conversation:
record_itemstruncates long outputs;for_promptnormalizes history and ensures tool calls have outputs.
Shell · exec_command
unified exec- runs terminal commands with sandbox permissions
- supports interactive processes, and intercepts apply_patch shell invocations.
Exec Handler
ExecCommandHandler- parses arguments
- resolves the target environment
- builds
ExecCommandRequestwith sandbox permissions and approval justification.
MCP · Web Search
extensions- MCP server tools/resources
- standalone web search
- extension tool executors
update_plan
planning- tracks multi-step plans surfaced to the user
- skipped for trivial tasks
Prompt Builder
build_promptCombines history input, tool specs, base instructions, parallel-tool flag, and output schema into the Prompt payload.
Prompt Templates
instructions_templateMarkdown assets that define agent identity and behavior:
models-manager/prompt.md,gpt-5.2-codex_prompt.md- model instruction templates with
{{ personality }}placeholders.
Request Builder
build_responses_requestFinal wire assembly:
- standard mode sends instructions + tools JSON
- Responses Lite injects
AdditionalToolsandBaseInstructionsFragmentdeveloper messages.
Sampling Request
run_sampling_request- assembles the Prompt (input + tools + base instructions)
- streams the Responses API
- handles output items, tool calls, compaction rollover, and retries.
Sandbox Manager
select_initialSelects an OS sandbox per the permission profile — Seatbelt (macOS), Landlock/bubblewrap (Linux), restricted tokens (Windows) — or no sandbox at all, depending on permissions and execution settings.
Session Loop
submission_loop- Receives user Ops (TurnInput, approvals, interrupt) and dispatches them to handlers
- Spawned at session startup.
Tool Registry
dispatch_any_with_state- IndexMap of registered tools with runtime + exposure
- runs pre/post-tool hooks, telemetry, and dispatches invocations to handlers.
Tool Call Runtime
ToolCallRuntime- turns function-call output items into invocations
- enforces read/write gates for parallel vs serial tools
- records results back into history.
Turn Loop
run_turnBrain 🧠 of the agent:
- captures step context
- injects context
- samples the model
- executes tool calls
- loops until the model produces a final assistant message and no pending input or further model call remains.
World State Builder
build_world_state_for_stepAssembles stable, keyed sections (model instructions, AGENTS.md, permissions, environment, tools, multi-agent) rendered as full text on first turn and diffs afterwards.