config: instructions field does not load instruction files (v2.0.16)
Author: agilebeanCreated Sep 25, 2026Updated Oct 2, 2026
Summary
A file referenced from the global config's instructions array is never added to a session's context, so shared rule files cannot be loaded from the config at all. A file reachable through AGENTS.md loads fine in the same session, so the config path is the broken one.
Environment
- opencode version: 2.0.16 (homebrew
opencode-v2) - OS: Darwin 25.6.0 (macOS, arm64)
- Terminal: Unavailable: terminal environment variables are not set
- Shell: /opt/homebrew/bin/bash
- Install/channel: homebrew, release
- Active plugins:
@openchamber/[email protected]plus local openchamber plugins
Reproduction
- Put a marker file at
$HOME/agentkit/RULES.mdcontaining the single lineMARKER-7391. - In
~/.config/opencode/opencode.jsoncset"instructions": ["~/agentkit/RULES.md"]. - Restart opencode. Create a new session and ask: "Does your context contain the string MARKER-7391? Answer yes or no." -> No.
- Control in the same session: ask for a sentence from
~/.config/opencode/AGENTS.md-> Yes. Ask for a sentence from the agent definition -> Yes.
Path forms also tried, each after a restart, each negative: "$HOME/agentkit/RULES.md", an absolute path, and a config-dir-relative "RULES.md" with a symlink placed next to opencode.jsonc.
Expected Behavior
The referenced file's text is part of the session's instructions, exactly as AGENTS.md is.
Actual Behavior
The file is never loaded, for every path form tried. AGENTS.md from the same directory, and the agent prompt, are both present in the same session's context.
Additional Context
- Verified in freshly created sessions with a control question, so this is not the model failing to look: AGENTS.md=yes, agent prompt=yes, RULES.md=no in the same reply.
- Workaround that works: an explicit instruction in
AGENTS.mdtelling the model to read the file ("read RULES.md in this folder before you start a task"). The model-side reading path is fine; only the config-driven injection is missing. - Observation, possibly intended: editing
opencode.jsoncwhile the server runs has no effect on newly created sessions until opencode is restarted.
Source: anomalyco/opencode