What Codex Knows: Threads, Context, and Project Instructions
In openai/codex, the active prompt is not the thread itself. The thread is the durable container for conversation and settings; the prompt is a bounded view assembled for one model step. This chapter explains how Codex turns stored history, current settings, environment information, and project guidance into that view, and why the distinction matters. The practical result is a way to judge what the model is actually being asked to act on—and what remains outside its context and outside its authority.
A model that works in a repository needs more than the latest user sentence. It may need the preceding decision, the current working directory, the tools selected for the turn, the project's local conventions, and the result of a command that just ran. At the same time, sending everything the runtime knows would be wasteful and could make the next action less coherent. Codex therefore treats context as a designed interface between durable state and a time-limited inference request.
A thread is durable; a prompt is selected
The repository gives threads a lifecycle that outlasts a single model request. The thread manager can create, resume, fork, and store threads using local or in-memory stores. A session holds the active turn, input queue, configuration, environment selections, and other services needed while work is running. The two levels answer different questions: the thread says where the work belongs, while the session and turn say what is happening now.
That distinction becomes visible when Codex builds a prompt. The prompt is made from conversation items selected for the current model request, base instructions, model-visible tool specifications, a setting governing parallel tool calls, and optional output constraints. Environment and permission context can also be represented in the assembled model context. The result is not a raw database dump. It is a request-specific representation of the state the model needs in order to choose its next step.
This selection has a strong systems consequence. The model should reason from the same state that the runtime uses to dispatch the resulting tool call. Codex captures a coherent step context before sampling so that history, settings, environment information, and the tool router describe one request view. A later change can be accepted for a future capture without silently rewriting the step already in flight.
Imagine a user changing the model or approval preference while a command is running. The current operation cannot simply be reinterpreted halfway through as if it had been launched under the new setting. The runtime keeps the captured step stable, then applies the update when a later step or turn is built. This is less convenient than treating configuration as a global mutable variable, but it prevents a single turn from having an unclear contract.
The same rule applies to provider state. Codex keeps session-scoped information such as provider selection and authentication separate from turn-scoped streaming state. A follow-up request within a turn can reuse the turn's provider connection and routing state. A new turn gets a new turn-scoped client state. The boundary prevents an optimization for one operation from becoming accidental context for the next.
Durable history still has a budget
A persisted thread can contain more material than a model can use in one request. Codex tracks the active context window and invokes compaction when the current or incoming material would exceed the relevant limit. Compaction can happen before a new turn is recorded or in the middle of a turn when tool output and continuation have increased the window. The turn then rebuilds the context needed to continue.
This is not the same as saying that history is disposable. Durable history supports resume and fork behavior, while compaction produces a manageable model-facing view. The tension is familiar in any stateful system: persistence favors completeness; inference favors a bounded working set. Codex makes that tension part of the turn lifecycle instead of leaving a provider error to define the user's experience.
The active window also includes more than prose. A tool result may be needed to interpret the next decision. An environment change may affect which path is meaningful. A structured output schema may constrain the final answer. A current set of tool specifications determines which actions the model can request. Because these pieces travel together in a step context, context management is also capability management.
That does not mean every context item has equal authority. A base instruction, a repository instruction, a tool description, a command result, and a user message may all appear in model-visible input, but their presence does not by itself grant the model permission to perform an external action. Context informs the proposal; the execution pipeline decides what may happen after the proposal. Keeping those roles separate is essential when the context includes material from a repository that the user did not author.
The diagram describes a filter, not a hierarchy of trust. History, instructions, environment information, and budget rules contribute to the prompt through context assembly. The model receives the resulting view. A later authorization stage still determines whether a proposed command or patch can cross into execution.
Project instructions are found along a path
Codex treats repository guidance as a location-sensitive input. It first determines a project root by walking upward from the current working directory until a configured marker is found; the packaged default marker is .git. It then searches from that root down to the current directory and collects applicable instruction files in order. The preferred local override filename is considered before the default AGENTS.md name, and additional fallback filenames can be configured.
The order matters. A repository-wide instruction can establish a convention, while a deeper directory can refine it for a subsystem. The resulting text is composed with user- and thread-scoped instructions, and the project entries retain provenance about where they came from. When more than one environment contributes instructions, Codex labels the environment rather than pretending that all directories belong to one undifferentiated workspace.
There is also a size boundary. Project documentation is subject to a total byte budget, and an individual contribution can be truncated when it would exceed the remaining allowance. Thread-provided instructions have their own validation limit. These constraints are not cosmetic. An instruction channel with no bound could crowd out the user request, the tool result that explains a failure, or the context needed to decide what to do next.
Consider a repository with an AGENTS.md at its root and a more specific override beneath a service directory. If the turn's working directory is inside that service, the model can receive both entries in their path order. If the turn moves to a different environment or directory, the instruction manager invalidates the repository cache and refreshes the selection. What the model knows is therefore a function of the active location, not a permanent property of the thread.
The manager also separates fetching from application. User and thread instruction providers can supply additional text, while the manager serializes overlapping refreshes, validates thread instruction size, and replaces the applied snapshot only after a coherent result is available. A refresh failure does not justify exposing a stale repository instruction set after the relevant environment or trust state has changed.
This is a useful form of hidden coupling to make explicit: changing a working directory can change both the files the model may inspect and the instructions that shape its interpretation. The runtime must update these together closely enough that the model does not receive guidance from one project context while tools operate in another.
Trust changes which context is eligible
Project instructions are model-visible guidance, not a permission grant. Codex makes that distinction operational through project trust. When the active project is explicitly marked untrusted, project instructions are not loaded; host- or user-supplied instructions may still remain. This protects the boundary between content found in a repository and instructions that the user or host has chosen to provide.
Trust can also participate in deriving default sandbox behavior when a project has a trust decision, although the exact result depends on configuration and platform conditions. That relationship should not be simplified into “trusted means unrestricted” or “untrusted means unusable.” The source supports a conditional trust input to configuration and instruction loading, not a universal promise about the final execution policy.
The distinction is easier to see in a concrete case. A repository document might tell Codex to run a particular setup script before editing a file. That document can help the model understand the project's workflow, but it does not make the script authorized. The proposed command still enters the command-policy, approval, permission, and sandbox paths. Conversely, a user may authorize a command while the model lacks the project-specific instruction that would have explained its expected arguments. Context and authority solve different problems.
Configuration layering reinforces the same idea. Codex can merge system, managed, user, project, and session sources into an effective configuration and retain information about which layer supplied a value. A disabled layer may remain visible to a client for explanation while being excluded from the effective configuration. The model should therefore be treated as operating under the resolved configuration, not under every piece of configuration text that happens to exist on disk.
This separation also helps with prompt injection. A repository can contain text that attempts to redirect the agent. The text may be relevant evidence about the codebase, or it may be project guidance loaded under the normal instruction rules, but neither status automatically changes the runtime's authority. The model may be influenced by what it reads; the host still owns the decision to expose a tool, approve an action, and enforce the resulting access boundary.
Context is the runtime's working memory
The most accurate description of Codex context is neither “the whole conversation” nor “whatever the model remembers.” It is a budgeted, request-specific working memory assembled from durable history and current state. The turn loop supplies new user input and tool results; the context manager selects what the next inference request can use; compaction keeps that request within a model's limits; and instruction discovery adds location-sensitive guidance when the trust and configuration conditions allow it.
That design provides continuity without pretending that continuity is free. A persistent thread can be resumed, but a resumed turn still needs a valid current environment and a prompt that fits the provider's window. A project instruction can be precise, but it consumes context budget and may become inapplicable after the working directory changes. A tool result can be essential, but its size and lifetime must be managed. The runtime's job is to keep these changes legible.
The key judgment is simple: ask what was selected for the current step, who supplied it, and what role it plays. If it is context, it can shape the model's proposal. If it is a capability, it describes an action the model may request. If it is authority, it comes from the policy and permission path that governs execution. Treating all three as interchangeable is how a useful instruction channel becomes an accidental privilege channel.
With that distinction in place, the turn and context models can be combined. A request enters a thread, a step context turns current state into a bounded prompt, and the model proposes the next action from that view. The remaining question is what the runtime does when that proposal is capable of changing the world: which decisions are made before execution, and how the host enforces them.