#51341·opencode

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

  1. Put a marker file at $HOME/agentkit/RULES.md containing the single line MARKER-7391.
  2. In ~/.config/opencode/opencode.jsonc set "instructions": ["~/agentkit/RULES.md"].
  3. Restart opencode. Create a new session and ask: "Does your context contain the string MARKER-7391? Answer yes or no." -> No.
  4. 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.md telling 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.jsonc while the server runs has no effect on newly created sessions until opencode is restarted.