Repository navigation
Issue Report: Custom instruction files in opencode.jsonc not being loaded #4758
Description
Description
The instructions array in opencode.jsonc configuration file is not being loaded into the agent's context at session start. Only the AGENTS.md file appears to be loaded automatically.
Configuration
File: ~/.config/opencode/opencode.jsonc
{
"$schema": "https://opencode.ai/config.json",
"model": "github-copilot/claude-sonnet-4.5",
"autoupdate": true,
"instructions": [
"SUPEROPENCODE.md",
"COMMANDS.md",
"FLAGS.md",
"PRINCIPLES.md",
"RULES.md",
"MCP.md",
"PERSONAS.md",
"ORCHESTRATOR.md",
"MODES.md",
"KIRO.md"
]
}Expected Behavior
All instruction files listed in the instructions array should be automatically loaded and available in the agent's context at the start of each session.
Actual Behavior
Only AGENTS.md is loaded into the agent's context. The agent confirms it can only see:
- Instructions from
<project>/AGENTS.md(project-level) - Instructions from
~/.config/opencode/AGENTS.md(global)
None of the files specified in the instructions array are loaded.
Verification
All instruction files exist in the config directory:
~/.config/opencode/
✓ AGENTS.md
✓ SUPEROPENCODE.md
✓ COMMANDS.md
✓ FLAGS.md
✓ PRINCIPLES.md
✓ RULES.md
✓ MCP.md
✓ PERSONAS.md
✓ ORCHESTRATOR.md
✓ MODES.md
✓ KIRO.md
Additional Context
The MCP servers defined in the same config file (context7 and sequential-thinking) appear to be loading correctly, suggesting the config file itself is being read, but the instructions array is not being processed. The default model is also correctly loaded.
OpenCode version
1.0.112
Steps to reproduce
- Create custom instruction files in
~/.config/opencode/ - Add them to the
instructionsarray inopencode.jsonc - Start a new OpenCode session
- Ask the agent if it has access to the custom instructions
- Agent confirms it only has access to
AGENTS.md
Screenshot and/or share link
No response
Operating System
macOS 14 (Darwin 24.5.0, ARM64)
Terminal
No response
Activity
github-actions commentedon Nov 26, 2025
This issue might be a duplicate of existing issues. Please check:
Feel free to ignore if none of these address your specific case.
rekram1-node commentedon Nov 26, 2025
@coolehs the files are resolved relative to where opencode runs. You should use absolute paths here instead
berenar commentedon Jan 19, 2026
I had the same exact issue (#9368): I assumed that the paths in
instructionsare relative, but they are clearly not. I feel this is important information that should be in the docs.docs(instructions): explain that the instructions array paths are rel…
berenar commentedon Jan 19, 2026
@rekram1-node Sent a PR already
github-actions commentedon Mar 26, 2026
To stay organized issues are automatically closed after 90 days of no activity. If the issue is still relevant please open a new one.
research-0013: add opencode's static instructions-field mechanism (so…
research-0013: add opencode's static instructions-field mechanism (so…