Skip to content

Bug: Global AGENTS.md (~/.config/opencode/AGENTS.md) not loaded when project AGENTS.md exists #22020

Closed
#22317
Closed
Bug: Global AGENTS.md (~/.config/opencode/AGENTS.md) not loaded when project AGENTS.md exists#22020
#22317
Assignees
rekram1-node
Labels
coreAnything pertaining to core functionality of the application (opencode server stuff)windows

Description

@Qiiks
Qiiks
opened on Apr 11, 2026

Bug Report

Description

When both a global ~/.config/opencode/AGENTS.md and a project-level AGENTS.md exist, only the project-level file is loaded. The global rules are silently ignored.

Documentation Says

From https://opencode.ai/docs/rules/:

Global: You can also have global rules in a ~/.config/opencode/AGENTS.md file. This gets applied across all opencode sessions.

Precedence: The first matching file wins in each category.

The phrase "in each category" implies that local and global are separate categories that should both load. But in practice, only the project AGENTS.md is loaded.

Steps to Reproduce

  1. Create ~/.config/opencode/AGENTS.md with unique rules (e.g., "Always use rg instead of grep")
  2. Create a project-level AGENTS.md in a git repo with different rules
  3. Start opencode in that project
  4. Ask the agent to recite its instructions — only the project AGENTS.md content is present

Expected Behavior

Both files should be loaded:

  • Global rules apply to ALL sessions (personal preferences, tool preferences, communication style)
  • Project rules apply to the specific project (architecture, conventions, build commands)

They serve different purposes and should compose, not override.

Current Workaround

Adding @~/.config/opencode/AGENTS.md to the project AGENTS.md forces loading both, but this:

  1. Requires manual setup in every project
  2. Is not documented as necessary
  3. Defeats the purpose of "global" rules

Environment

  • OpenCode: latest
  • OS: Windows 11
  • Global AGENTS.md at: C:\Users\<user>\.config\opencode\AGENTS.md

Activity

  1. github-actions
    assigned
    rekram1-node
    on Apr 11, 2026
  2. github-actions
    added
    coreAnything pertaining to core functionality of the application (opencode server stuff)
    windows
    on Apr 11, 2026

  3. miguelgmcs commented on Apr 13, 2026

    @miguelgmcs
    miguelgmcs
    on Apr 13, 2026

    Same on behavior on Linux Fedora 43

  4. rekram1-node commented on Apr 13, 2026

    @rekram1-node
    rekram1-node
    on Apr 13, 2026
    Contributor

    Try running opencode through an http proxy and searching for Instructions from:

    I think youll find that the llm is just lying to you

  5. rekram1-node commented on Apr 13, 2026

    @rekram1-node
    rekram1-node
    on Apr 13, 2026
    Contributor

    I tested exact cases and added a test case. I don't think there is an issue here, if you can show me how you verified (not using llm) it'd be super helpful.

    If there were a bug maybe one on windows but unix should all work here.

  6. rekram1-node
    closed this as completedin #22317on Apr 13, 2026

  7. Qiiks commented on Apr 13, 2026

    @Qiiks
    Qiiks
    on Apr 13, 2026
    Author

    Verified: Windows-specific bug in globalFiles() path resolution

    I've identified the root cause. As you suspected, this is a Windows-only bug.

    The Bug

    Global.Path.config in packages/opencode/src/global/index.ts uses xdg-basedir:

    import { xdgConfig } from "xdg-basedir"
const config = path.join(xdgConfig!, "opencode")

    On Windows, xdgConfig resolves to %APPDATA% (C:\Users\<user>\AppData\Roaming), not ~/.config/.

    So globalFiles() in packages/opencode/src/session/instruction.ts (line 30) looks for:

    C:\Users\Sanve\AppData\Roaming\opencode\AGENTS.md  ← DOES NOT EXIST

    But my actual AGENTS.md is at:

    C:\Users\Sanve\.config\opencode\AGENTS.md  ← EXISTS

    Non-LLM Verification

    1. Read the source code — globalFiles() at line 30 does path.join(Global.Path.config, "AGENTS.md"), and Global.Path.config = path.join(xdgConfig!, "opencode") from global/index.ts line 6.

    2. Checked xdg-basedir resolution on Windows:

      APPDATA=C:\Users\Sanve\AppData\Roaming
→ xdgConfig = C:\Users\Sanve\AppData\Roaming
→ Global.Path.config = C:\Users\Sanve\AppData\Roaming\opencode

    3. Confirmed filesystem mismatch:

      • C:\Users\Sanve\AppData\Roaming\opencode\ exists but contains only runtime data (EBWebView, quotas-debug.log) — no AGENTS.md
      • C:\Users\Sanve\.config\opencode\AGENTS.md exists with my rules

    4. Confirmed in OpenCode logs — Config loading correctly reads from .config\opencode\ (logs show service=config path=C:\Users\Sanve\.config\opencode\opencode.json loading), meaning the config path resolution has special handling for opencode.json but NOT for AGENTS.md via globalFiles().

    Why it works on Unix

    On Linux/macOS, xdgConfig resolves to ~/.config/, which matches where users naturally place their config. On Windows, xdgConfig resolves to %APPDATA% instead, creating a mismatch with the ~/.config/opencode/ directory that OpenCode itself creates and uses for other config files.

    The Fix

    globalFiles() should search additional paths on Windows, or Global.Path.config should be consistent with where OpenCode actually stores its config. Since OpenCode already reads opencode.json from ~/.config/opencode/ on Windows, the AGENTS.md loading should check the same directory.

  8. Hona commented on Apr 13, 2026

    @Hona
    Hona
    on Apr 13, 2026
    Member

    Are you using any plugins? Specifically the xdg basedir package we use does as the docs say.

    example see a couple tiny repro scripts and the directories that opencode actually uses:

    Image

    It works on my windows machine with a clean opencode install.

    Desktop app or CLI?

  9. Qiiks commented on Apr 14, 2026

    @Qiiks
    Qiiks
    on Apr 14, 2026
    Author

    I'm on the CLI but I do have the desktop version installed I'm just not using it

  10. Qiiks commented on Apr 14, 2026

    @Qiiks
    Qiiks
    on Apr 14, 2026
    Author

    Correction: Issue is NOT valid — both AGENTS.md files ARE loaded

    I installed the opencode-system-prompt-logger plugin and ran it from my project directory (F:\ScienceQuest\Science-Quest). The output clearly shows:

    service=system-prompt-logger sessionID=ses_275244946ffetgMgARYo8dlvxH providerID=opencode modelID=minimax-m2.5-free
Instructions from: F:\ScienceQuest\Science-Quest\AGENTS.md
Instructions from: C:\Users\Sanve\.config\opencode\AGENTS.md

    Both the project AGENTS.md and global AGENTS.md are correctly loaded.

    My earlier analysis about xdg-basedir resolving to %APPDATA% on Windows was wrong — I tested with Node.js, but OpenCode runs on Bun where xdgConfig correctly resolves to ~/.config/. This was confirmed by both your screenshot and opencode debug paths on my machine:

    config     C:\Users\Sanve\.config\opencode

    Sorry for the noise. Closing this issue as not a bug.

  11. Hona commented on Apr 14, 2026

    @Hona
    Hona
    on Apr 14, 2026
    Member

    who would have thought blindly trusting AI and then asking an llm to do 'Non-LLM Verification' would cause issues

  12. Vlyn commented on May 25, 2026

    @Vlyn
    Vlyn
    on May 25, 2026

    Are you 100% sure this is not an issue? I just ran into the same thing on Windows.

    AGENTS.md in my user folder and AGENTS.md in my project folder (which has no reference to the global user file). Asking about the injected context my global AGENTS.md is totally missing. Until I added this to my global opencode.json config:

    "instructions": ["~/.config/opencode/AGENTS.md"],

    Now when I ask a model I do get the full context, my full global file and the project file on top. Using just "AGENTS.md" in the config didn't work, it probably pulled in the project file again.

  13. cjairm
    added a commit that references this issue on Aug 27, 2026

    feat(task): add dg task context-report (Step 7)

    5713d9f
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

coreAnything pertaining to core functionality of the application (opencode server stuff)windows

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions