BUG: AGENTS.md in OPENCODE_CONFIG_DIR is ignored when global AGENTS.md exists

[lgladysz]

BUG: AGENTS.md in OPENCODE_CONFIG_DIR is ignored when global AGENTS.md exists

Summary

When using OPENCODE_CONFIG_DIR environment variable to specify an alternate configuration directory (e.g., for profile-based workflows with OCX or other managed by OPENCODE_CONFIG_DIR env), the AGENTS.md file in OPENCODE_CONFIG_DIR is never loaded if a global AGENTS.md exists at ~/.config/opencode/AGENTS.md.

Root Cause

In packages/opencode/src/session/instruction.ts, the systemPaths() function iterates over globalFiles() which returns multiple potential AGENTS.md locations:

1. ~/.config/opencode/AGENTS.md (global)
2. ~/.claude/CLAUDE.md (Claude Code compatibility, if not disabled)
3. OPENCODE_CONFIG_DIR/AGENTS.md (via OPENCODE_CONFIG_DIR)

However, the loop has a break statement that exits after finding the first existing file:

for (const file of globalFiles()) {
  if (await Bun.file(file).exists()) {
    paths.add(path.resolve(file))
    break  // <-- This prevents loading additional AGENTS.md files
  }
}

Since globalFiles() returns the global config directory first, the profile-specific AGENTS.md is never reached.

Expected Behavior

When OPENCODE_CONFIG_DIR is set, OpenCode should load AGENTS.md from that directory instead of the global one. Profiles should be isolated environments with their own complete configuration.

Actual Behavior

Only the global ~/.config/opencode/AGENTS.md is loaded. The profile-specific AGENTS.md is silently ignored.

Steps to Reproduce

1. Create a global AGENTS.md:

   echo "# Global Instructions" > ~/.config/opencode/AGENTS.md

2. Create a work profile with its own AGENTS.md:

   mkdir -p ~/.config/opencode/profiles/work
   echo "# Work Profile Instructions" > ~/.config/opencode/profiles/work/AGENTS.md

3. Set up OCX profile (or manually set env):

   export OPENCODE_CONFIG_DIR="$HOME/.config/opencode/profiles/work"
   opencode

4. Observe that only the global AGENTS.md is loaded; the work profile AGENTS.md is ignored.

Environment

• OpenCode version: 1.1.48
• OS: Linux/macOS (any with XDG config directories)
• Use case: OCX profile management or other managed by OPENCODE_CONFIG_DIR env.

Suggested Fix

Put OPENCODE_CONFIG_DIR path first in globalFiles() array, so it takes priority but falls back to global if missing:

function globalFiles() {
  const files = []
  if (Flag.OPENCODE_CONFIG_DIR) {
    files.push(path.join(Flag.OPENCODE_CONFIG_DIR, "AGENTS.md"))
  }
  files.push(path.join(Global.Path.config, "AGENTS.md"))
  if (!Flag.OPENCODE_DISABLE_CLAUDE_CODE_PROMPT) {
    files.push(path.join(os.homedir(), ".claude", "CLAUDE.md"))
  }
  return files
}

This way profile AGENTS.md takes priority when it exists, but falls back to global AGENTS.md if profile file is missing. This matches how plugins/commands resolve.

Pull Request

• fix: prioritize OPENCODE_CONFIG_DIR for AGENTS.md #11536

Related Code References

• packages/opencode/src/session/instruction.ts - Lines 84-89
• packages/opencode/src/session/instruction.ts - globalFiles() function (lines 19-28)

Impact

This bug breaks profile-based workflows where users expect their profile-specific AGENTS.md to be loaded when using tools like OCX that set OPENCODE_CONFIG_DIR.

[github-actions]

This issue might be a duplicate of existing issues. Please check:

• AGENTS.md not loaded after /new #11532: AGENTS.md not loaded after /new
• [FEATURE]: Support .opencode/AGENTS.md for environment-specific instructions #11454: [FEATURE]: Support .opencode/AGENTS.md for environment-specific instructions

Feel free to ignore if none of these address your specific case.

[kehao95]

+1 for this issue. but not sure if this is the root cause.
I suddently found that my AGENTS.md can be loaded reliably.

[lgladysz]

Documentation states that custom directory override global config for commands, agents, plugins etc. but there is no mention of AGENTS.md. IMHO, it should also override global AGENTS.md.
Moving OPENCODE_CONFIG_DIR on top of the globalFiles function should address that.

function globalFiles() {
  const files = []
  if (Flag.OPENCODE_CONFIG_DIR) {
    files.push(path.join(Flag.OPENCODE_CONFIG_DIR, "AGENTS.md"))
  }
  files.push(path.join(Global.Path.config, "AGENTS.md"))
  if (!Flag.OPENCODE_DISABLE_CLAUDE_CODE_PROMPT) {
    files.push(path.join(os.homedir(), ".claude", "CLAUDE.md"))
  }
  return files
}