Project Awareness Without Prompt Sprawl

This chapter explains how OpenCode makes a selected model useful inside a real project without copying every rule, file, and reference into every request. The focus is the boundary between knowledge and capability: what becomes baseline context, what appears as a chronological update, what is loaded only when relevant, and what must still pass through an authorized tool. By the end, the reader can tell why a project-aware agent may know that a resource exists without automatically being allowed to change it.

Context has a lifecycle

A model needs a working picture of its environment, but “the context” is not one undifferentiated block. OpenCode’s source separates baseline system context from Session History. The baseline can contain environment facts, project instructions, and selected guidance. Session History contains the chronological conversation and durable updates that have been admitted after the baseline. A skill or external reference can contribute useful information without becoming permanent background for every turn.

The distinction starts with the active Location. A Location identifies the directory, project or worktree, and optional workspace context for the running session. It scopes the services that observe the project: configuration, filesystem and search, tools, permissions, skills, references, and the session runner. The same agent process can serve more than one project, but each Location can resolve a different set of instructions and capabilities. Project awareness is therefore a property of a scoped runtime, not a vague claim that the model has access to the user’s computer.

OpenCode’s V2 core models each context contributor as a typed Context Source. A source has a stable namespaced key, a codec for its value, a loader, and renderers for its initial baseline, an update, and, when appropriate, removal. The value itself is kept separate from the text shown to the model. That design lets the runtime compare structured state rather than comparing arbitrary strings, while still producing a clear model-facing explanation when the state changes.

The initial baseline is assembled before the first prompt becomes model-visible. Current built-in sources include environment information—such as the working directory, workspace root, version-control presence, and platform—and the host-local date. The V2 runner also composes selected-agent skill guidance and project-reference guidance. The repository describes global and upward project AGENTS.md discovery as an initial instruction slice. Other sources, including some configured, remote, nested, or plugin-defined instruction behavior, remain partial or deferred in the V2 parity table.

The baseline has an important stability property. OpenCode stores a Context Epoch with the exact baseline text and a hidden structured snapshot of the sources that produced it. During a later safe provider-turn boundary, the runtime observes the sources again. An unchanged source contributes nothing. A changed source can produce one chronological system message and advance the snapshot atomically. A removed source can emit an explicit removal message. The model is not expected to infer a file or rule change from an invisible mutation elsewhere in the host.

A safe boundary is the point immediately before a provider call, after eligible input and tool results have been handled. Sampling context there prevents a source update from changing a request in the middle of a provider turn. It also gives the Session a consistent order: newly promoted user input and settled tool results can be placed before a combined message describing changed context.