Claude Code Compatibility Layer
Relevant source files
The following files were used as context for generating this wiki page:
The Claude Code Compatibility Layer is a specialized subsystem within Oh-My-OpenCode designed to provide full interoperability with the Claude Code ecosystem. This layer enables OpenCode to utilize tools, Model Context Protocol (MCP) servers, and specialized instructions originally authored for Claude Code, effectively acting as an "oh-my-zsh" for OpenCode by aggregating these external capabilities.
The compatibility layer operates by discovering and loading specific configuration files (such as .mcp.json or CLAUDE.md) and translating them into the OpenCode plugin architecture. This allows users to leverage existing AI-driven workflows while benefiting from the multi-model agent orchestration provided by the Oh-My-OpenCode project.
Sources: AGENTS.md:126-128, AGENTS.md:167-172
Architecture and Discovery
The compatibility layer utilizes a three-tier architecture to integrate external capabilities into the OpenCode environment. It scans both the project root and user-level directories to find relevant configuration files and instruction sets.
Discovery Logic
The system actively searches for several types of configuration and instruction files. This includes project-specific instructions, global user rules, and tool-specific protocols.
| File Pattern | Source Type | Description |
|---|---|---|
.mcp.json | MCP Config | Defines external MCP servers with variable expansion support. |
CLAUDE.md | Instructions | Project-specific knowledge and conventions, similar to AGENTS.md. |
.claude/rules/*.md | Rules | Legacy instruction sets for specialized behaviors. |
.github/instructions/*.instructions.md | Instructions | Modern GitHub-based instruction discovery. |
.github/copilot-instructions.md | Global Rule | A single file containing global project instructions. |
Sources: src/hooks/rules-injector/finder.test.ts:40-100, src/hooks/rules-injector/finder.test.ts:160-190, AGENTS.md:167-172
Integration Flow
The following diagram illustrates how the compatibility layer discovers and transforms Claude Code configurations into active OpenCode components.
The system ensures that rules found in subdirectories are prioritized based on proximity to the file being edited, while global rules (like those in the user's home directory) act as a fallback.
Sources: src/hooks/rules-injector/finder.test.ts:240-270, AGENTS.md:170-172
MCP Server Compatibility
A core feature of the layer is the support for Model Context Protocol (MCP) servers defined in Claude Code format. The system processes the .mcp.json file to bridge external services into the OpenCode toolset.
Variable Expansion
Unlike static loaders, the Claude Code Compatibility Layer supports ${VAR} expansion within the MCP configuration. This allows for dynamic environment-aware tool paths and credentials, ensuring that local setups for Claude Code work seamlessly within OpenCode without manual reconfiguration.
Multi-Tier MCP Architecture
The project organizes MCPs into three distinct tiers:
- Built-in: Essential services like
websearchandcontext7. - Claude Code Compat: Dynamic loading from
.mcp.json. - Skill-embedded: Tools defined within YAML frontmatter in specialized skills.
Sources: AGENTS.md:167-172
Instruction and Rule Injection
The layer provides backward compatibility for various instruction formats used in different AI editors. This ensures that the agent's behavior is consistent across diverse project environments.
Rule Discovery and Prioritization
The findRuleFiles logic implements a distance-based discovery algorithm. Rules located closer to the active file have a lower "distance" score and are typically given higher priority in the agent's context.
- Project Rules: Discovered in
.github/instructions/,.claude/rules/, or.cursor/rules/. - Single-File Rules: Rules like
copilot-instructions.mdare marked withisSingleFile: trueand assigned a distance of0to ensure they are always included. - Global Rules: User-level rules from the home directory are marked
isGlobal: trueand assigned a high distance (9999) to serve as a base instruction layer.
Sources: src/hooks/rules-injector/finder.test.ts:102-140, src/hooks/rules-injector/finder.test.ts:238-274
Summary
The Claude Code Compatibility Layer serves as a critical bridge that allows Oh-My-OpenCode to adopt the rich ecosystem of Claude Code. By supporting .mcp.json variable expansion, diverse rule discovery paths (including legacy .claude and .cursor formats), and project-level instructions like CLAUDE.md, it provides a highly flexible environment for multi-model agent orchestration. This integration ensures that developers can transition between different AI coding tools while maintaining a unified set of project rules and external tool configurations.
Sources: AGENTS.md:126-128, AGENTS.md:167-172