Codex System Handbook

State-flow registers

State Flow Overview

State registerSemanticsStages touched
reg-effective-configThe final set of settings Codex runs with after combining files, policies, profiles, cloud settings, thread overrides, and command-line flags.Process entrypoints and binary dispatch, Configuration, feature resolution, and startup policy assembly, Backend clients, remote catalogs, and startup refreshes, Frontend session startup and user-facing initialization, Main event loop and request dispatch, Thread and session orchestration, Prompt, context, and extension assembly, Turn execution and model interaction, Tool execution, approvals, and guarded side effects, Result persistence, projection, and user-visible state updates, Cross-cutting persistence abstractions and data stores, Cross-cutting utility and support libraries
reg-feature-flagsThe shared list of enabled or disabled experimental and product features that changes what the app exposes.Configuration, feature resolution, and startup policy assembly, Backend clients, remote catalogs, and startup refreshes, Frontend session startup and user-facing initialization, Main event loop and request dispatch, Thread and session orchestration, Prompt, context, and extension assembly, Tool execution, approvals, and guarded side effects, Result persistence, projection, and user-visible state updates, Cross-cutting observability, analytics, and feedback, Cross-cutting persistence abstractions and data stores
reg-install-home-contextThe discovered Codex home folder, install location, bundled resources, and stable local installation identity.Early process hardening and runtime bootstrap, Installation context, home discovery, and local environment probing, Configuration, feature resolution, and startup policy assembly, Authentication, identity, and account readiness, Persistence and local runtime services startup, Frontend session startup and user-facing initialization, Thread and session orchestration, Result persistence, projection, and user-visible state updates, Cross-cutting observability, analytics, and feedback, Cross-cutting persistence abstractions and data stores, Cross-cutting utility and support libraries
reg-shell-workspace-environmentThe current machine, shell, PATH, working directory, project root, Git state, and environment variables used to make commands behave like the user’s terminal.Early process hardening and runtime bootstrap, Installation context, home discovery, and local environment probing, Configuration, feature resolution, and startup policy assembly, Frontend session startup and user-facing initialization, Thread and session orchestration, Prompt, context, and extension assembly, Turn execution and model interaction, Tool execution, approvals, and guarded side effects, Result persistence, projection, and user-visible state updates, Cross-cutting utility and support libraries
reg-auth-identityThe signed-in user or service identity, including account facts such as email, plan, workspace, and login mode.Configuration, feature resolution, and startup policy assembly, Authentication, identity, and account readiness, Backend clients, remote catalogs, and startup refreshes, Frontend session startup and user-facing initialization, Main event loop and request dispatch, Thread and session orchestration, Turn execution and model interaction, Result persistence, projection, and user-visible state updates, Cross-cutting transport, networking, and client infrastructure, Cross-cutting observability, analytics, and feedback, Cross-cutting persistence abstractions and data stores
reg-credential-storeThe saved tokens, API keys, OAuth credentials, MCP tokens, and other secrets used to authenticate later requests.Configuration, feature resolution, and startup policy assembly, Authentication, identity, and account readiness, Backend clients, remote catalogs, and startup refreshes, Frontend session startup and user-facing initialization, Thread and session orchestration, Turn execution and model interaction, Tool execution, approvals, and guarded side effects, Cross-cutting transport, networking, and client infrastructure, Cross-cutting persistence abstractions and data stores, Cross-cutting utility and support libraries
reg-rate-limit-quotaThe current account limits, credit status, token usage, and reset information used to avoid overusing backend services.Authentication, identity, and account readiness, Backend clients, remote catalogs, and startup refreshes, Frontend session startup and user-facing initialization, Thread and session orchestration, Turn execution and model interaction, Result persistence, projection, and user-visible state updates, Cross-cutting observability, analytics, and feedback, Cross-cutting persistence abstractions and data stores
reg-state-databasesThe opened local SQLite stores and migration state that hold structured runtime data for threads, agents, goals, jobs, and summaries.Persistence and local runtime services startup, Frontend session startup and user-facing initialization, Thread and session orchestration, Multi-agent, collaboration, and background workflows, Result persistence, projection, and user-visible state updates, Shutdown, cleanup, and teardown, Cross-cutting observability, analytics, and feedback, Cross-cutting persistence abstractions and data stores
reg-rollout-thread-storeThe durable conversation log and searchable thread index used to resume, rebuild, archive, restore, and display sessions.Persistence and local runtime services startup, Frontend session startup and user-facing initialization, Thread and session orchestration, Turn execution and model interaction, Multi-agent, collaboration, and background workflows, Result persistence, projection, and user-visible state updates, Shutdown, cleanup, and teardown, Cross-cutting observability, analytics, and feedback, Cross-cutting persistence abstractions and data stores
reg-cloud-config-cacheThe cached and refreshed cloud-delivered configuration bundles that can alter settings, requirements, and available features.Configuration, feature resolution, and startup policy assembly, Backend clients, remote catalogs, and startup refreshes, Frontend session startup and user-facing initialization, Thread and session orchestration, Result persistence, projection, and user-visible state updates, Cross-cutting persistence abstractions and data stores
reg-model-provider-catalogThe combined menu of usable model providers and models from bundled data, cache, live services, local servers, and account access.Configuration, feature resolution, and startup policy assembly, Backend clients, remote catalogs, and startup refreshes, Frontend session startup and user-facing initialization, Main event loop and request dispatch, Thread and session orchestration, Prompt, context, and extension assembly, Turn execution and model interaction, Result persistence, projection, and user-visible state updates, Cross-cutting persistence abstractions and data stores
reg-http-network-clientThe shared network client setup, including retries, streaming, cookies, proxy settings, TLS handling, and request failure reporting.Early process hardening and runtime bootstrap, Authentication, identity, and account readiness, Backend clients, remote catalogs, and startup refreshes, Transport and server runtime initialization, Turn execution and model interaction, Tool execution, approvals, and guarded side effects, Cross-cutting transport, networking, and client infrastructure, Cross-cutting observability, analytics, and feedback, Cross-cutting utility and support libraries
reg-tls-crypto-providerThe one process-wide cryptography provider chosen early so HTTPS and other TLS connections use the same security engine.Early process hardening and runtime bootstrap, Backend clients, remote catalogs, and startup refreshes, Transport and server runtime initialization, Turn execution and model interaction, Cross-cutting transport, networking, and client infrastructure
reg-app-server-runtimeThe live app-server or daemon state, including open transports, connected clients, request routing, and server lifecycle status.Process entrypoints and binary dispatch, Transport and server runtime initialization, Frontend session startup and user-facing initialization, Main event loop and request dispatch, Thread and session orchestration, Result persistence, projection, and user-visible state updates, Shutdown, cleanup, and teardown, Cross-cutting transport, networking, and client infrastructure, Cross-cutting observability, analytics, and feedback
reg-remote-control-relayThe remote-control, relay, socket, WebSocket, and encrypted connection state used to connect clients and helper processes.Process entrypoints and binary dispatch, Transport and server runtime initialization, Main event loop and request dispatch, Tool execution, approvals, and guarded side effects, Shutdown, cleanup, and teardown, Cross-cutting transport, networking, and client infrastructure, Cross-cutting observability, analytics, and feedback
reg-network-proxy-policyThe managed proxy and network-forwarding state that decides what network traffic is allowed, forwarded, or blocked.Configuration, feature resolution, and startup policy assembly, Transport and server runtime initialization, Prompt, context, and extension assembly, Tool execution, approvals, and guarded side effects, Cross-cutting transport, networking, and client infrastructure, Cross-cutting observability, analytics, and feedback, Cross-cutting utility and support libraries
reg-permission-sandbox-policyThe shared rules for file access, command execution, network access, approvals, and sandbox modes.Configuration, feature resolution, and startup policy assembly, Authentication, identity, and account readiness, Frontend session startup and user-facing initialization, Main event loop and request dispatch, Thread and session orchestration, Prompt, context, and extension assembly, Turn execution and model interaction, Tool execution, approvals, and guarded side effects, Result persistence, projection, and user-visible state updates, Cross-cutting observability, analytics, and feedback, Cross-cutting utility and support libraries
reg-exec-environmentThe active command-execution setup, including local or remote executor choice, sandbox helper paths, runtime paths, and process execution capabilities.Process entrypoints and binary dispatch, Installation context, home discovery, and local environment probing, Configuration, feature resolution, and startup policy assembly, Transport and server runtime initialization, Main event loop and request dispatch, Thread and session orchestration, Tool execution, approvals, and guarded side effects, Result persistence, projection, and user-visible state updates, Cross-cutting transport, networking, and client infrastructure, Cross-cutting utility and support libraries
reg-process-registryThe shared record of running or tracked external processes, their identifiers, input/output streams, terminal sizes, and completion state.Transport and server runtime initialization, Main event loop and request dispatch, Tool execution, approvals, and guarded side effects, Result persistence, projection, and user-visible state updates, Shutdown, cleanup, and teardown, Cross-cutting transport, networking, and client infrastructure, Cross-cutting observability, analytics, and feedback
reg-mcp-server-sessionsThe configured and connected MCP tool servers, their tools, resources, login state, approval rules, and active sessions.Configuration, feature resolution, and startup policy assembly, Authentication, identity, and account readiness, Backend clients, remote catalogs, and startup refreshes, Transport and server runtime initialization, Main event loop and request dispatch, Thread and session orchestration, Prompt, context, and extension assembly, Tool execution, approvals, and guarded side effects, Result persistence, projection, and user-visible state updates, Cross-cutting transport, networking, and client infrastructure, Cross-cutting persistence abstractions and data stores
reg-plugin-marketplace-catalogThe installed, built-in, workspace, and marketplace plugin information that controls extra tools, hooks, connectors, and prompt additions.Configuration, feature resolution, and startup policy assembly, Backend clients, remote catalogs, and startup refreshes, Frontend session startup and user-facing initialization, Thread and session orchestration, Prompt, context, and extension assembly, Tool execution, approvals, and guarded side effects, Result persistence, projection, and user-visible state updates, Cross-cutting observability, analytics, and feedback, Cross-cutting persistence abstractions and data stores, Cross-cutting utility and support libraries
reg-extension-host-stateThe shared extension runtime state and contributor hooks that let add-ons react to threads, turns, tools, prompts, events, and MCP setup.Configuration, feature resolution, and startup policy assembly, Thread and session orchestration, Prompt, context, and extension assembly, Turn execution and model interaction, Tool execution, approvals, and guarded side effects, Multi-agent, collaboration, and background workflows, Result persistence, projection, and user-visible state updates, Cross-cutting observability, analytics, and feedback, Cross-cutting persistence abstractions and data stores
reg-skills-catalogThe available skills list, including where each skill came from, whether it is enabled, and the instructions it can add to a session.Configuration, feature resolution, and startup policy assembly, Backend clients, remote catalogs, and startup refreshes, Thread and session orchestration, Prompt, context, and extension assembly, Multi-agent, collaboration, and background workflows, Result persistence, projection, and user-visible state updates, Cross-cutting persistence abstractions and data stores
reg-memory-storeThe saved long-term user memories and memory search results that can be loaded, updated, and inserted into future conversations.Thread and session orchestration, Prompt, context, and extension assembly, Tool execution, approvals, and guarded side effects, Multi-agent, collaboration, and background workflows, Result persistence, projection, and user-visible state updates, Cross-cutting persistence abstractions and data stores
reg-live-session-servicesThe toolbox attached to one running session, such as model access, auth, telemetry, approvals, tools, extensions, networking, and MCP connections.Frontend session startup and user-facing initialization, Main event loop and request dispatch, Thread and session orchestration, Prompt, context, and extension assembly, Turn execution and model interaction, Tool execution, approvals, and guarded side effects, Multi-agent, collaboration, and background workflows, Result persistence, projection, and user-visible state updates, Shutdown, cleanup, and teardown, Cross-cutting observability, analytics, and feedback
reg-thread-session-stateThe live state of a conversation thread, including its identity, workspace, selected model, history, permissions, listeners, and lifecycle status.Frontend session startup and user-facing initialization, Main event loop and request dispatch, Thread and session orchestration, Prompt, context, and extension assembly, Turn execution and model interaction, Tool execution, approvals, and guarded side effects, Multi-agent, collaboration, and background workflows, Result persistence, projection, and user-visible state updates, Shutdown, cleanup, and teardown, Cross-cutting observability, analytics, and feedback, Cross-cutting persistence abstractions and data stores
reg-turn-stateThe shared clipboard for one active assistant turn, tracking the current task, pending replies, granted permissions, cancellations, and bookkeeping.Main event loop and request dispatch, Thread and session orchestration, Prompt, context, and extension assembly, Turn execution and model interaction, Tool execution, approvals, and guarded side effects, Multi-agent, collaboration, and background workflows, Result persistence, projection, and user-visible state updates, Cross-cutting observability, analytics, and feedback
reg-conversation-history-budgetThe accumulated messages, compacted summaries, token counts, and trimming decisions that determine what conversation context still fits.Frontend session startup and user-facing initialization, Thread and session orchestration, Prompt, context, and extension assembly, Turn execution and model interaction, Multi-agent, collaboration, and background workflows, Result persistence, projection, and user-visible state updates, Cross-cutting observability, analytics, and feedback, Cross-cutting persistence abstractions and data stores
reg-prompt-context-stackThe assembled prompt ingredients, including project instructions, permissions text, goals, memories, skills, plugin text, IDE details, warnings, and changed context.Configuration, feature resolution, and startup policy assembly, Thread and session orchestration, Prompt, context, and extension assembly, Turn execution and model interaction, Tool execution, approvals, and guarded side effects, Multi-agent, collaboration, and background workflows, Result persistence, projection, and user-visible state updates, Cross-cutting observability, analytics, and feedback
reg-tool-catalogThe current set of tools the model may call, with schemas, names, MCP conversions, plugin additions, and execution handlers.Configuration, feature resolution, and startup policy assembly, Backend clients, remote catalogs, and startup refreshes, Thread and session orchestration, Prompt, context, and extension assembly, Turn execution and model interaction, Tool execution, approvals, and guarded side effects, Result persistence, projection, and user-visible state updates, Cross-cutting observability, analytics, and feedback
reg-hook-rulesThe configured hooks and hook schemas that let external commands inspect or affect session starts, turns, tool calls, and other lifecycle events.Configuration, feature resolution, and startup policy assembly, Main event loop and request dispatch, Thread and session orchestration, Prompt, context, and extension assembly, Tool execution, approvals, and guarded side effects, Result persistence, projection, and user-visible state updates, Cross-cutting observability, analytics, and feedback, Cross-cutting utility and support libraries
reg-agent-registry-graphThe live and persisted map of parent agents, child agents, thread names, statuses, and which helper agents are still open.Thread and session orchestration, Multi-agent, collaboration, and background workflows, Result persistence, projection, and user-visible state updates, Shutdown, cleanup, and teardown, Cross-cutting observability, analytics, and feedback, Cross-cutting persistence abstractions and data stores
reg-background-work-queuesThe shared set of background tasks such as cloud refreshes, cleanup jobs, memory jobs, skill watchers, agent jobs, update checks, and session maintenance.Persistence and local runtime services startup, Backend clients, remote catalogs, and startup refreshes, Main event loop and request dispatch, Multi-agent, collaboration, and background workflows, Result persistence, projection, and user-visible state updates, Shutdown, cleanup, and teardown, Cross-cutting observability, analytics, and feedback, Cross-cutting persistence abstractions and data stores
reg-tui-visible-stateThe current terminal user-interface state, including visible transcript cells, inputs, popups, keymaps, headers, status lines, notifications, and restored history.Configuration, feature resolution, and startup policy assembly, Frontend session startup and user-facing initialization, Main event loop and request dispatch, Thread and session orchestration, Turn execution and model interaction, Result persistence, projection, and user-visible state updates, Cross-cutting observability, analytics, and feedback, Cross-cutting persistence abstractions and data stores, Cross-cutting utility and support libraries
reg-observability-telemetryThe shared logs, traces, metrics, analytics facts, rollout tracing, debug captures, and feedback evidence used to understand what happened.Authentication, identity, and account readiness, Persistence and local runtime services startup, Backend clients, remote catalogs, and startup refreshes, Transport and server runtime initialization, Main event loop and request dispatch, Thread and session orchestration, Turn execution and model interaction, Tool execution, approvals, and guarded side effects, Multi-agent, collaboration, and background workflows, Result persistence, projection, and user-visible state updates, Shutdown, cleanup, and teardown, Cross-cutting transport, networking, and client infrastructure, Cross-cutting observability, analytics, and feedback, Cross-cutting persistence abstractions and data stores
reg-goal-stateThe live and persisted user goals, goal progress, and goal-thread associations synchronized into prompts, storage, analytics, and UI indicators.Thread and session orchestration, Prompt, context, and extension assembly, Result persistence, projection, and user-visible state updates, Cross-cutting persistence abstractions and data stores
reg-update-check-stateCached update notices, downloaded-or-pending update metadata, and daemon restart/update status produced by update checks and consumed by UI or teardown restart logic.Backend clients, remote catalogs, and startup refreshes, Result persistence, projection, and user-visible state updates, Shutdown, cleanup, and teardown, Cross-cutting persistence abstractions and data stores
reg-code-mode-runtime-stateThe live code-mode execution sessions, V8 isolates, loaded modules, pending calls, timers, and shutdown state for JavaScript/code-cell execution.Turn execution and model interaction, Tool execution, approvals, and guarded side effects, Shutdown, cleanup, and teardown
reg-realtime-stream-stateActive realtime conversation state, including audio/text stream sessions, WebSocket transport state, buffers, and stop/cancel lifecycle data.Transport and server runtime initialization, Main event loop and request dispatch, Prompt, context, and extension assembly, Turn execution and model interaction, Shutdown, cleanup, and teardown
reg-external-import-ledgerThe persisted ledger of external-agent sessions already imported, used to avoid duplicate imports and track import provenance.Thread and session orchestration, Result persistence, projection, and user-visible state updates, Cross-cutting persistence abstractions and data stores
reg-request-serialization-gatesThe in-flight RPC/session request admission gates, per-resource serialization queues, and shutdown blockers that control when handlers may start or must drain.Main event loop and request dispatch, Shutdown, cleanup, and teardown
reg-connector-directory-cacheCached ChatGPT/app connector directories, workspace connector settings, local connector metadata, and fallback lookup results used when exposing connectors to sessions and prompts.Backend clients, remote catalogs, and startup refreshes, Thread and session orchestration, Prompt, context, and extension assembly, Cross-cutting persistence abstractions and data stores
reg-cloud-task-stateCloud task lists, task details, submission attempts, selected task environments, and polling/refresh status shared by cloud task commands and clients.Process entrypoints and binary dispatch, Backend clients, remote catalogs, and startup refreshes, Frontend session startup and user-facing initialization, Result persistence, projection, and user-visible state updates, Cross-cutting persistence abstractions and data stores
reg-filesystem-watch-subscriptionsActive file and directory watch subscriptions, invalidation signals, and watcher-to-client mappings used for skills, plugin/config refreshes, and app-server file APIs.Transport and server runtime initialization, Main event loop and request dispatch, Multi-agent, collaboration, and background workflows, Cross-cutting transport, networking, and client infrastructure, Cross-cutting utility and support libraries
reg-terminal-runtime-stateLive terminal control state such as raw mode, alternate screen ownership, resize/suspend handling, input streams, and restoration obligations.Frontend session startup and user-facing initialization, Main event loop and request dispatch, Shutdown, cleanup, and teardown, Cross-cutting utility and support libraries
reg-collaboration-mode-catalogBuilt-in and configured collaboration-mode presets/templates that clients can list and apply to choose model, mode, reasoning, and prompt behavior.Configuration, feature resolution, and startup policy assembly, Frontend session startup and user-facing initialization, Prompt, context, and extension assembly, Protocol schemas, shared types, and generated contracts
reg-windows-sandbox-readinessPrepared Windows sandbox accounts, helper readiness, setup status, and client-visible sandbox availability separate from the policy rules themselves.Authentication, identity, and account readiness, Transport and server runtime initialization, Tool execution, approvals, and guarded side effects, Protocol schemas, shared types, and generated contracts
reg-attestation-stateClient or host attestation provider state and generated proof metadata used to attach optional attestation headers to upstream requests.Authentication, identity, and account readiness, Transport and server runtime initialization, Turn execution and model interaction, Cross-cutting transport, networking, and client infrastructure
reg-launch-invocation-contextThe raw launch context, including invoked binary/arg0, selected subcommand or runtime mode, startup flags, and output/interaction mode chosen before dispatch.Process entrypoints and binary dispatch, Early process hardening and runtime bootstrap, Configuration, feature resolution, and startup policy assembly, Frontend session startup and user-facing initialization, Cross-cutting observability, analytics, and feedback
reg-process-hardening-stateProcess-wide hardening status and OS security settings applied at bootstrap, such as dump/inspection/tamper restrictions that affect the rest of the run.Early process hardening and runtime bootstrap, Transport and server runtime initialization, Turn execution and model interaction, Tool execution, approvals, and guarded side effects, Shutdown, cleanup, and teardown
reg-project-trust-storePersisted and effective trust decisions for workspaces/projects that influence onboarding, permission assembly, sandbox behavior, and session startup.Configuration, feature resolution, and startup policy assembly, Frontend session startup and user-facing initialization, Thread and session orchestration, Tool execution, approvals, and guarded side effects, Cross-cutting persistence abstractions and data stores
reg-ide-integration-stateActive IDE-link state such as connected IDE clients, workspace metadata, open file or selection context, and IDE details injected into prompts or server notifications.Transport and server runtime initialization, Prompt, context, and extension assembly, Cross-cutting transport, networking, and client infrastructure
reg-workspace-change-setLive and saved workspace change information, including file diffs, patch outcomes, reviewable changes, and rollback/snapshot data used by tools, UI, and persistence.Main event loop and request dispatch, Tool execution, approvals, and guarded side effects, Result persistence, projection, and user-visible state updates
reg-local-model-runtime-stateLive readiness, endpoint, health, and launch/connect status for local model backends such as Ollama, LM Studio, and OSS helpers, separate from the model catalog itself.Backend clients, remote catalogs, and startup refreshes, Turn execution and model interaction, Cross-cutting transport, networking, and client infrastructure
reg-memory-write-safety-stateCached or in-flight safety decisions for whether proposed long-term memory writes should be allowed before they update the memory store.Backend clients, remote catalogs, and startup refreshes, Tool execution, approvals, and guarded side effects, Multi-agent, collaboration, and background workflows, Cross-cutting persistence abstractions and data stores
reg-session-connector-selectionPer-session selected or enabled app/ChatGPT connectors used to decide which connector context and tools are exposed to the model.Thread and session orchestration, Prompt, context, and extension assembly, Tool execution, approvals, and guarded side effects, Result persistence, projection, and user-visible state updates
reg-outgoing-transport-buffersQueued outbound protocol messages, write buffers, and backpressure state for app-server, daemon, exec-server, and remote transports.Transport and server runtime initialization, Main event loop and request dispatch, Shutdown, cleanup, and teardown, Cross-cutting transport, networking, and client infrastructure