AGENTS.md

1# src/features/claude-code-agent-loader/ -- Claude Code Agent Compatibility Layer
2 
3**Generated:** 2026-05-18
4 
5## OVERVIEW
6 
7Sibling to `claude-code-mcp-loader`. Loads Claude Code agent definitions from `.opencode/agents/`, `~/.claude/agents/`, and inline `opencode.json` config, then translates them to OpenCode `AgentConfig`. Shared parsing and compatibility primitives are extracted to [`packages/claude-code-compat-core/`](../../../../../packages/claude-code-compat-core); this directory is the OpenCode adapter shim.
8 
9## LOAD PIPELINE
10 
11```
12loadUserAgents() / loadProjectAgents() / loadOpencodeGlobalAgents() / loadOpencodeProjectAgents()
13  -> loader.ts: discover .md files in agents/ directories
14  -> agent-definitions-loader.ts: parse YAML frontmatter + body, load from explicit paths
15  -> json-agent-loader.ts: parse .json / .jsonc agent definitions
16  -> opencode-config-agents-reader.ts: read inline agents from opencode.json
17  -> claude-model-mapper.ts: translate "sonnet" / "opus" / "haiku" -> OpenCode provider/model IDs
18  -> return Record<string, ClaudeCodeAgentConfig>
19```
20 
21## KEY FILES
22 
23| File | Purpose |
24|------|---------|
25| `index.ts` | Barrel: all exports |
26| `loader.ts` | `loadUserAgents()`, `loadProjectAgents()`, `loadOpencode*Agents()` main entry |
27| `agent-definitions-loader.ts` | `parseMarkdownAgentFile()`, `loadAgentDefinitions()` |
28| `json-agent-loader.ts` | `parseJsonAgentFile()` -- JSON/JSONC agent definitions |
29| `claude-model-mapper.ts` | Claude aliases -> OpenCode `providerID/modelID` |
30| `opencode-config-agents-reader.ts` | Reads inline `agents` and `agent_definitions` from `opencode.json` |
31| `types.ts` | `ClaudeCodeAgentConfig`, `AgentScope`, `LoadedAgent` |
32 
33## INTEGRATION
34 
35Phase 3 of config loading (`src/plugin-handlers/agent-config-handler.ts`) calls this loader to populate the agent registry before the plugin interface is built.
36 
37## COMPANION LOADERS
38 
39- **`claude-code-plugin-loader`**: full plugins with commands, skills, hooks, MCPs
40- **`claude-code-mcp-loader`**: Tier 2 MCPs from `.mcp.json`
41 
42## RELATED
43 
44- Phase 3 integration: `src/plugin-handlers/agent-config-handler.ts`
45- Plugin loader: `src/features/claude-code-plugin-loader/`
46- MCP loader: `src/features/claude-code-mcp-loader/`
47