Repository navigation
[FEATURE]: Disable or replace project AGENTS.md (instructions currently only adds) #47879
Description
Feature hasn't been suggested before.
- I have verified this feature I'm about to request hasn't been suggested before.
Describe the enhancement you want to request
Ask: a per-project way to either (1) skip loading AGENTS.md, or (2) let opencode.json instructions replace AGENTS.md instead of combining with it.
Why: AGENTS.md is becoming a shared filename across coding harnesses. In a repo that already uses it as another product's identity file, OpenCode cannot load a different instruction file as the sole source of truth. An override line in a second file is not the same as not loading the first file.
Current documented behavior (https://opencode.ai/docs/rules/ as of 2026-09-07):
You can provide custom instructions to opencode by creating an
AGENTS.mdfile.
When opencode starts, it looks for rule files in this order:
- Local files by traversing up from the current directory (
AGENTS.md,CLAUDE.md)- Global file at
~/.config/opencode/AGENTS.md- Claude Code file at
~/.claude/CLAUDE.md(unless disabled)The first matching file wins in each category. For example, if you have both
AGENTS.mdandCLAUDE.md, onlyAGENTS.mdis used.
You can specify custom instruction files in your
opencode.jsonor the global~/.config/opencode/opencode.json. This allows you and your team to reuse existing rules rather than having to duplicate them to AGENTS.md.
All instruction files are combined with your
AGENTS.mdfiles.
There is already OPENCODE_DISABLE_CLAUDE_CODE / OPENCODE_DISABLE_CLAUDE_CODE_PROMPT to skip Claude's files. There is no equivalent to skip project AGENTS.md.
What would fix it (any one of these):
- A config flag or env, analogous to
OPENCODE_DISABLE_CLAUDE_CODE, that skips projectAGENTS.md(for example"agents_md": falseorOPENCODE_DISABLE_AGENTS_MD=1). - An
instructionsmode that replaces auto-loadedAGENTS.mdinstead of combining, e.g."instructions": { "replace": ["OPENCODE.md"] }or"instructions_mode": "replace". - Documented per-project precedence so a named instruction file wins over
AGENTS.mdrather than being concatenated with it.
Claude Code compatibility already treats AGENTS.md as taking precedence over CLAUDE.md. The missing piece is a way for a project that must keep AGENTS.md for another tool to still give OpenCode its own exclusive instructions.
Verified against OpenCode 1.18.29: "instructions": ["OPENCODE.md"] is loaded in addition to repo-root AGENTS.md.
Activity
github-actions commentedon Sep 8, 2026
This issue might be a duplicate of existing issues. Please check:
AGENTS.override.mdsupport to override rather than merge AGENTS.md — same core ask of replacement/override semanticsjordandru commentedon Sep 9, 2026
Checked both. Neither covers this ask, though they're adjacent:
AGENTS.override.md, following Codex's convention — but Codex readsAGENTS.override.mdtoo, so in a repo shared by both harnesses it recreates the same collision under a different filename. The problem here is any file both products treat as theirs.~/.config/opencode/AGENTS.mdinheriting into projects, and documenting that order. A disable for the global file doesn't let a project stop loading its ownAGENTS.md.This one is specifically: per-project, either skip
AGENTS.mdor letopencode.jsoninstructionsbe the sole source instead of combining. Happy to fold it into whichever of the others maintainers prefer if there's a single design that covers all three, but as filed they're three different switches.opencodejr commentedon Oct 28, 2026
Thanks for the detailed write-up, @jordandru!
You tested this on OpenCode 1.18.29, which is v1. v1 (versions 0.x and 1.x, the
opencode-ainpm package) now only receives fixes for critical bugs, so new options like this are unlikely to be added there.Please consider upgrading to v2 (the
@opencode/clipackage,opencodecommand), where active development happens. As far as we can tell, v2 also has no dedicated per-project option yet to skipAGENTS.mdor to makeinstructionsreplace it rather than add to it. If you need this on v2, please reply here (or open a new issue) saying so, and it can be considered as a v2 feature request. Please also reply if you think this is critical for v1.opencodejr commentedon Oct 29, 2026
Closing this as not planned. The request was tested on OpenCode 1.18.29 (v1), and v1 now only gets fixes for critical bugs. We haven't heard that this is needed on v2.
If you move to v2 (
@opencode/cli) and still need a way to skip projectAGENTS.md, or to makeinstructionsreplace it rather than add to it, please open a new issue and mention that it's about v2. Thanks again for the clear write-up, @jordandru!