anomalyco / anomalyco/opencode

[FEATURE]: Make .opencode/AGENTS.md the standard location for project instructions

Open
#48,601 0 comments 0 reactions 1 assignee View on GitHub

@jlongster is already working on this.

Since Sep 12, 2026.

Dominant language
TypeScript
Stars
209k
Forks
27.5k
PR merge metrics
PR metrics pending

Description

  • I have verified this feature I'm about to request hasn't been suggested before.

Every other piece of project-local OpenCode configuration lives inside .opencode/: custom agents at .opencode/agent/, commands at .opencode/command/, plus skills/, plugins/, themes/, and tool/. Project instructions are the one exception still forced to sit at the repository root instead of inside that existing convention, in packages/opencode/src/session/instruction.ts, instructionFiles only ever looks at AGENTS.md/CLAUDE.md next to the project root.

Make .opencode/AGENTS.md the standard location OpenCode looks for first, with the current root-level AGENTS.md treated as the fallback for projects that haven't adopted the new location, not the other way around. This matters because project instructions frequently carry content someone doesn't want in a shared repository, ported personal preferences, working notes, disclosure-sensitive decisions, and putting the standard location inside the directory OpenCode already treats as its own local config namespace means a project's existing .opencode/.gitignore can cover it the same way it already covers other local-only OpenCode state. Right now the only way to keep a root AGENTS.md untracked is a workaround entirely outside OpenCode, a global git excludes file, or editing that repo's own .gitignore, which is awkward for anyone only contributing to a project rather than owning it.

If both .opencode/AGENTS.md and a root AGENTS.md exist, both should be loaded and concatenated as instructions rather than one silently winning. A root AGENTS.md is often also carrying OpenCode's own /init-generated codebase analysis, which is a different kind of content from hand-maintained or ported instructions and there's no reason a project can't have both, one for machine-generated codebase context, one for the standard-location instructions, at the same time.

For every existing project with only a root AGENTS.md and no .opencode/AGENTS.md, behavior is unchanged, current root-level discovery keeps working exactly as it does today.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.