Setting OPENCODE_CONFIG_DIR prevents the global AGENTS.md from loading because the global instructions path and the config directory scan use different resolution strategies.
ConfigPaths.directories() in packages/opencode/src/config/paths.ts:26 always includes Global.Path.config (the static XDG path, ~/.config/opencode) in the directory list, so agents, commands, and skills from the XDG config dir are always discovered regardless of OPENCODE_CONFIG_DIR.
But instruction.ts:64 builds the global AGENTS.md path from global.config (the Service property), which resolves to OPENCODE_CONFIG_DIR when set. So the global instructions lookup skips ~/.config/opencode/AGENTS.md entirely.
The result: setting OPENCODE_CONFIG_DIR to add a secondary config directory (e.g. a workspace-level .opencode/) correctly picks up agents/commands/skills from both locations, but silently drops the global AGENTS.md unless you duplicate it into the override directory.
Steps to reproduce
- Have a global
AGENTS.md at ~/.config/opencode/AGENTS.md
- Set
OPENCODE_CONFIG_DIR to a different directory (e.g. /path/to/workspace/.opencode)
- Start opencode
- The global
AGENTS.md is not loaded; only $OPENCODE_CONFIG_DIR/AGENTS.md is checked
Expected behavior
instruction.ts should use Global.Path.config (the static XDG path) for the global AGENTS.md, consistent with how ConfigPaths.directories() handles config directory scanning. OPENCODE_CONFIG_DIR should add to the search path, not replace the global instructions source.
Relevant code
packages/core/src/global.ts:63 -- config: Flag.OPENCODE_CONFIG_DIR ?? Path.configpackages/opencode/src/session/instruction.ts:64 -- path.join(global.config, "AGENTS.md")packages/opencode/src/config/paths.ts:26 -- Global.Path.config (static, not overridden)
Version
opencode 1.15.6, Linux
Setting
OPENCODE_CONFIG_DIRprevents the globalAGENTS.mdfrom loading because the global instructions path and the config directory scan use different resolution strategies.ConfigPaths.directories()inpackages/opencode/src/config/paths.ts:26always includesGlobal.Path.config(the static XDG path,~/.config/opencode) in the directory list, so agents, commands, and skills from the XDG config dir are always discovered regardless ofOPENCODE_CONFIG_DIR.But
instruction.ts:64builds the globalAGENTS.mdpath fromglobal.config(the Service property), which resolves toOPENCODE_CONFIG_DIRwhen set. So the global instructions lookup skips~/.config/opencode/AGENTS.mdentirely.The result: setting
OPENCODE_CONFIG_DIRto add a secondary config directory (e.g. a workspace-level.opencode/) correctly picks up agents/commands/skills from both locations, but silently drops the globalAGENTS.mdunless you duplicate it into the override directory.Steps to reproduce
AGENTS.mdat~/.config/opencode/AGENTS.mdOPENCODE_CONFIG_DIRto a different directory (e.g./path/to/workspace/.opencode)AGENTS.mdis not loaded; only$OPENCODE_CONFIG_DIR/AGENTS.mdis checkedExpected behavior
instruction.tsshould useGlobal.Path.config(the static XDG path) for the globalAGENTS.md, consistent with howConfigPaths.directories()handles config directory scanning.OPENCODE_CONFIG_DIRshould add to the search path, not replace the global instructions source.Relevant code
packages/core/src/global.ts:63--config: Flag.OPENCODE_CONFIG_DIR ?? Path.configpackages/opencode/src/session/instruction.ts:64--path.join(global.config, "AGENTS.md")packages/opencode/src/config/paths.ts:26--Global.Path.config(static, not overridden)Version
opencode 1.15.6, Linux