Skip to content

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

@Qiiks

Description

@Qiiks

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

Metadata

Metadata

Assignees

Labels

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

Type

No type
No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions