[FEATURE]: Context Auto-Discovery: Load AGENTS.md from Directories When Accessing Files

[Ithril-Laydec]

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

Problem

In large monorepos, we have to choose what information to load into context. With a large AGENTS.md file, we load a lot of context that might not be necessary for all conversations.

Typical structure example:

monorepo/
├── AGENTS.md              # Global project rules
├── packages/
│   ├── backend/
│   │   ├── src/
│   │   └── AGENTS.md      # Backend-specific rules
│   ├── frontend/
│   │   ├── src/
│   │   └── AGENTS.md      # Frontend-specific rules
│   └── mobile/
│       ├── src/
│       └── AGENTS.md      # Mobile-specific rules

Current workaround: Manually list all instruction files in opencode.json:

{
  "instructions": [
    "AGENTS.md",
    "packages/backend/AGENTS.md",
    "packages/frontend/AGENTS.md",
    "packages/mobile/AGENTS.md"
  ]
}

Problem with this approach: This loads ALL instruction files at startup, overloading the context with irrelevant information (e.g., loading mobile rules when working on backend code). This doesn't scale and defeats the purpose of having per-module context.

---

Proposed Solution

Mimic Claude Code's auto-discovery so that when a file is read or written in a subdirectory, the relevant AGENTS.md is automatically loaded without the LLM having to manually decide to read it.

Features:

1. Loaded file cache to avoid duplicates in the same session
2. Configuration option to disable the feature if not desired
3. Two loading strategies:
   • "up": Search for AGENTS.md upward to the worktree (default)
   • "exact": Only load AGENTS.md from the exact file directory

---

Advanced Configuration

{
  "autoDiscovery": {
    "enabled": true,
    "patterns": ["AGENTS.md", "CLAUDE.md"],
    "strategy": "up" // "up" | "exact"
  }
}

---

Why This Matters

• ✅ Zero-config: Works without configuration for standard project structures
• ✅ Automatic scalability: No need to update config when adding modules
• ✅ Better context accuracy: LLM receives relevant instructions automatically
• ✅ Monorepo support: Essential for modern architectures (Next.js, Turborepo, Nx)
• ✅ Parity with Claude Code: Users expect similar behavior across AI coding tools

---

Step-by-Step Flow: "up" Strategy (Search Upward)

Structure:
monorepo/
├── AGENTS.md                    # [A] Global rules
├── packages/
│   └── backend/
│       ├── AGENTS.md            # [B] Backend rules
│       └── routes/
│           ├── AGENTS.md        # [C] Routes rules
│           └── auth.ts          # ← File being read

LLM: readFile("packages/backend/routes/auth.ts")

Step 1: Detect directory → "packages/backend/routes/"
Step 2: Search upward:
  → packages/backend/routes/AGENTS.md  ✅ [C] Found! → Load
  → packages/backend/AGENTS.md         ✅ [B] Found! → Load
  → packages/AGENTS.md                 ❌ Does not exist
  → AGENTS.md                          ✅ [A] Already loaded by system

Result: LLM receives context from [C] + [B] + [A]

---

Step-by-Step Flow: "exact" Strategy (Current Directory Only)

Same structure as before:
monorepo/
├── AGENTS.md                    # [A] Global rules
├── packages/
│   └── backend/
│       ├── AGENTS.md            # [B] Backend rules
│       └── routes/
│           ├── AGENTS.md        # [C] Routes rules
│           └── auth.ts          # ← File being read

LLM: readFile("packages/backend/routes/auth.ts")

Step 1: Detect directory → "packages/backend/routes/"
Step 2: Search ONLY in that directory:
  → packages/backend/routes/AGENTS.md  ✅ [C] Found! → Load
  → (Does NOT search in parent directories)

Result: LLM receives context from [C] + [A] (root already loaded)

When to use each strategy?

• "up" (recommended): When you want the LLM to have full module + submodule context
• "exact": When each subdirectory has completely independent context and you don't want to "inherit" rules from parent folders

---

Difference with #4479

I've read issue #4479 and consider this proposal to be complementary but not the same:

• [FEATURE]: Configurable instruction file search boundary and file types #4479: Vertical search outside the git root (for monorepos with AGENTS.md in parent folders)
• This proposal: Horizontal search within the project (for modules with their own context)

Both features can coexist and solve different use cases in complex monorepos.

---

Implementation Offer

If this sounds good, I'd like to implement it myself or help implement it.

---

[github-actions]

This issue might be a duplicate of existing issues. Please check:

• [FEATURE]: Configurable instruction file search boundary and file types #4479: Configurable instruction file search boundary and file types - proposes similar functionality for searching AGENTS.md upward within git root or filesystem root
• Issue Report: Custom instruction files in opencode.jsonc not being loaded #4758: Custom instruction files in opencode.jsonc not being loaded - relates to loading multiple instruction files from configuration
• Automatically load @ referenced files in AGENTS.md into context #2225: Automatically load @ referenced files in AGENTS.md into context - proposes auto-loading of files referenced in instructions

The main difference with your proposal is that you're suggesting automatic discovery based on file access patterns (when a file is read/written), while #4479 focuses on configurable search boundaries and file types. Your approach complements and extends these existing proposals by adding dynamic, context-aware loading rather than just configuration-based approaches.

Feel free to ignore if your specific use case differs from these issues.

[ragnsan]

Yes, this would be sick. Was just looking for this. Claude Code does this and it's super valuable. We also have a lot of nested AGENTS.md in packages and apps in our monorepos and don't want to pollute the context window with files that are not needed in a session

[WilliamsHoward]

Couldn't agree more. In practical applications, project structures are frequently large and complex, significantly increasing token overhead. This feature allows for more efficient token utilization. can't wait to have this feature in opencode.

[YourTechBud]

This is such an important feature to have. I work in a monorepo and its extremely tiring to reference all relevant AGENTS.md file by hand. This is supposed to be a part of the Agents.md spec as well.

4. Large monorepo? Use nested AGENTS.md files for subprojects

Place another AGENTS.md inside each package. Agents automatically read the nearest file in the directory tree, so the closest one takes precedence and every subproject can ship tailored instructions. For example, at time of writing the main OpenAI repo has 88 AGENTS.md files.

[ragnsan]

This is such an important feature to have. I work in a monorepo and its extremely tiring to reference all relevant AGENTS.md file by hand. This is supposed to be a part of the Agents.md spec as well.

4. Large monorepo? Use nested AGENTS.md files for subprojects

Place another AGENTS.md inside each package. Agents automatically read the nearest file in the directory tree, so the closest one takes precedence and every subproject can ship tailored instructions. For example, at time of writing the main OpenAI repo has 88 AGENTS.md files.

Yeah, agreed. Have made a plugin to have the agent read nested AGENTS.md files in subdirs until this (hopefully) becomes a built-in!

[YourTechBud]

@ragnsan would ve lovely uf you could share some details about the plugin. Maybe a github repo link?