anomalyco/opencode
1
0
Fork 0
mirror of https://github.com/anomalyco/opencode.git synced 2026-07-22 02:05:26 -04:00
Code Issues 5.9k Packages Projects Releases 19 Wiki Activity

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

New Issue
Closed
opened 2026-02-16 18:09:21 -05:00 by yindo · 3 comments
yindo commented 2026-02-16 18:09:21 -05:00
Owner
Copy Link
Copy Source

Originally created by @lgladysz on GitHub (Jan 31, 2026).

Originally assigned to: @rekram1-node on GitHub.

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

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.

Originally created by @lgladysz on GitHub (Jan 31, 2026). Originally assigned to: @rekram1-node on GitHub. # 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: ```typescript 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: ```bash echo "# Global Instructions" > ~/.config/opencode/AGENTS.md ``` 2. Create a work profile with its own AGENTS.md: ```bash 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): ```bash 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: ```typescript 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 - https://github.com/anomalyco/opencode/pull/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`.
yindo closed this issue 2026-02-16 18:09:21 -05:00
yindo commented 2026-02-16 18:09:22 -05:00
Author
Owner
Copy Link
Copy Source

@github-actions[bot] commented on GitHub (Jan 31, 2026):

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

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

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

@github-actions[bot] commented on GitHub (Jan 31, 2026): This issue might be a duplicate of existing issues. Please check: - #11532: AGENTS.md not loaded after /new - #11454: [FEATURE]: Support .opencode/AGENTS.md for environment-specific instructions Feel free to ignore if none of these address your specific case.
yindo commented 2026-02-16 18:09:22 -05:00
Author
Owner
Copy Link
Copy Source

@kehao95 commented on GitHub (Feb 1, 2026):

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

@kehao95 commented on GitHub (Feb 1, 2026): +1 for this issue. but not sure if this is the root cause. I suddently found that my AGENTS.md can be loaded reliably.
yindo commented 2026-02-16 18:09:22 -05:00
Author
Owner
Copy Link
Copy Source

@lgladysz commented on GitHub (Feb 3, 2026):

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
}
@lgladysz commented on GitHub (Feb 3, 2026): [Documentation states](https://opencode.ai/docs/config#custom-directory) 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. ```javascript 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 } ```
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
acp
bad
bug
discussion
docs
documentation
enhancement
extension
good first issue
growth
help-wanted
mcp
model-problem
needs:compliance
nix
opentui
perf
pull-request
Mirrored from GitHub Pull Request
 tui
web
windows
zen
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
yindo
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: anomalyco/opencode#8181
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?