Instructions

Instructions are privileged context that guide an agent throughout a session. V2 combines built-in context, discovered AGENTS.md files, and dynamic sources such as skill, reference, MCP, and session context. It stores source values as durable deltas, then renders initial instructions and chronological updates when assembling each model request.

AGENTS.md

Use AGENTS.md for persistent guidance such as build commands, architecture, code conventions, and verification requirements. Commit project files so the whole team receives the same instructions.

V2 loads:

1. The global file at $XDG_CONFIG_HOME/opencode/AGENTS.md, normally ~/.config/opencode/AGENTS.md.
2. Every AGENTS.md from the current Location up to and including the project root.

For example, when the Location is packages/web, OpenCode can load all three project files below:

my-project/
├── AGENTS.md
└── packages/
    ├── AGENTS.md
    └── web/
        └── AGENTS.md

The files are combined rather than selecting a single winner. They are rendered in this order: global, then project files from the Location toward the project root. OpenCode does not resolve conflicts between their contents, so keep broad guidance global and put scoped guidance in the relevant project directory.

If the Location is outside the project root, only the global file is loaded. Setting OPENCODE_DISABLE_PROJECT_CONFIG=1 also skips project AGENTS.md discovery but does not disable the global file.

Nested instructions

An AGENTS.md below the Location is not part of the initial upward scan. When the read tool successfully reads a file or lists a directory, OpenCode discovers AGENTS.md files from that target upward to, but not including, the Location. It adds newly discovered files to the session in nearest-first order.

Each nested file is injected once per session and recorded in durable session history. Reading the same area again does not inject it again. Consequently, editing an already injected nested AGENTS.md does not replace its earlier session entry automatically; start a new session if the updated text must apply immediately.

Config entries

The V2 config schema accepts an instructions array of strings:

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines/*.md",
    "https://example.com/shared-instructions.md"
  ]
}

Configuration is loaded from global through project-local files. If more than one config defines instructions, the highest-precedence, closest config’s entire array is selected; arrays are not merged.

See Config for config locations and general precedence.

Ordering

The selected agent or provider system prompt is sent first. OpenCode then sends the session’s initial instructions, composed in this order:

1. Built-in environment and date context.
2. Ambient AGENTS.md discovery.
3. Available skill, reference, and MCP guidance.
4. Session-specific instruction entries supplied through the API.

These sources are combined; ordering is not an override mechanism. Nested AGENTS.md files discovered by reads are chronological session entries rather than part of the initial instructions.

Changes

Before promoting pending input, V2 compares live instruction sources with the latest admitted source values:

• A new or changed ambient AGENTS.md aggregate is announced as a system update that replaces the previous ambient aggregate.
• Removing all ambient files announces that the previous ambient instructions no longer apply.
• A temporary read or discovery failure preserves the session’s last known instructions instead of treating them as deleted. If no instruction epoch exists yet, pending input waits until every source is available.
• Completed conversation compaction advances the instruction epoch, making the currently admitted values initial without rereading sources or authoring an instruction event.
• Moving a session or committing a revert clears the instruction fold. The next safe boundary requires one complete source read before promoting input.

The durable event stores changed source keys and value hashes, not rendered prose. During request assembly, OpenCode renders the epoch’s initial values and interleaves later changes as chronological System messages. Clients see changed keys but never the privileged value bodies.