OpenCode plugin that automatically injects AGENTS.md files from sub folders when an agent reads files
npm install @qforge/opencode-agents-explorerOpenCode plugin that automatically injects AGENTS.md files from nested folders when an agent reads files.
OpenCode automatically loads the root AGENTS.md file to give the AI context about your project. But what about folder-specific instructions?
Large codebases often have different conventions, patterns, or rules for different parts of the project:
- 📁 src/api/ - REST endpoint conventions, authentication patterns
- 📁 src/components/ - React component guidelines, styling rules
- 📁 src/database/ - Migration patterns, naming conventions
- 📁 tests/ - Testing standards, mocking strategies
Without this plugin, you'd need to either:
1. Cram everything into the root AGENTS.md (becomes unwieldy)
2. Manually tell the agent to read folder-specific docs (easy to forget and agents get confused)
This plugin solves that by automatically injecting relevant AGENTS.md files when the agent reads files in those directories similar to .cursorrules.
- 🎯 Automatic injection - No manual intervention needed
- 🚫 No duplicates - Each AGENTS.md is injected only once per session
- ⚡ Smart skipping - Ignores root AGENTS.md (OpenCode handles it)
- 📂 Hierarchical - Injects all parent AGENTS.md files up to (but not including) root
Add to your opencode.json:
``json`
{
"$schema": "https://opencode.ai/config.json",
"plugin": ["@qforge/opencode-agents-explorer"]
}
When an agent reads a file at path a/b/c.json, the plugin:
1. Searches for a/AGENTS.md and a/b/AGENTS.md
2. If any exist, reads their contents and injects them into the session context
3. Skips the root (OpenCode already handles it automatically)AGENTS.md
4. Tracks which files have been added to avoid duplicates within a session
Given this file structure:
`
project/
AGENTS.md # ⏭️ Skipped (handled by OpenCode)
src/
AGENTS.md # ✅ Injected when reading files in src/
components/
AGENTS.md # ✅ Injected when reading files in src/components/
Button.tsx
When the agent reads src/components/Button.tsx, the plugin will inject:
- src/AGENTS.md
-
`
monorepo/
AGENTS.md # General project context
packages/
api/
AGENTS.md # "Use Express patterns, validate with Zod"
src/
routes/
AGENTS.md # "All routes must have auth middleware"
web/
AGENTS.md # "Use Next.js App Router, Tailwind CSS"
src/
components/
AGENTS.md # "Components must be server-first"
Now when the agent works on packages/api/src/routes/users.ts, it automatically gets context about:
- Express patterns and Zod validation (packages/api/AGENTS.md)packages/api/src/routes/AGENTS.md`)
- Auth middleware requirements (
MIT