Configuration Merging Strategy
Relevant source files
The following files were used as context for generating this wiki page:
The configuration merging strategy in OCX facilitates the "Copy. Paste. Own." philosophy by allowing components to inject settings into a user's local or global environment. OCX handles the complex task of deep-merging multiple configuration sources—including registries, profiles, and local project files—into a single, unified opencode.jsonc file. This ensures that dependencies, MCP servers, and agent-specific behaviors are correctly orchestrated without manual JSON editing by the user.
Sources: README.md:12-25, AGENTS.md:150-165
Core Merging Logic
OCX employs a specialized deep-merge utility designed to handle the unique data structures within an OpenCode configuration. Unlike standard object shallow merges, OCX selectively applies different merging behaviors (concatenation, deduplication, or overwriting) based on the field type.
Merging Behaviors by Field Type
| Field Category | Data Structure | Merge Behavior |
|---|---|---|
| Plugins | Array | Concatenation + Deduplication |
| Instructions | Array | Concatenation + Deduplication |
| MCP Servers | Object (Key-Value) | Deep Merge (New keys added, existing keys overwritten) |
| Tools | Object (Patterns) | Shallow Merge (Component patterns override existing) |
| Agents | Object (Nested) | Deep Merge (Settings like temperature or tools are merged) |
Sources: packages/cli/tests/merge.test.ts:13-186, packages/cli/src/registry/merge.ts
Configuration Cascade and Priority
Configurations are resolved and merged in a specific order. Sources appearing later in the cascade override earlier ones. This allows project-specific settings to override profile defaults, while still inheriting global base configurations.
- Global Base Config:
~/.config/opencode/ocx.jsoncis applied first. - Profile Configs: Resolved profile settings and
opencode.jsoncare merged next. - Local Project Config: Project-specific
.opencode/ocx.jsoncandopencode.jsoncare applied last, provided they are not excluded by profile patterns.
Sources: AGENTS.md:168-185, README.md:155-175
Component-Driven Updates
When a user adds a component (e.g., via ocx add), the updateOpencodeJsonConfig function is triggered. This function reads the existing opencode.json or opencode.jsonc and merges the new component's requirements into it while preserving user comments and formatting.
The diagram above illustrates the ShadCN-style update flow where the incoming component's configuration is treated as the authoritative source during conflicts.
Sources: packages/cli/tests/updaters.test.ts:32-150, README.md:144-148
Preservation of Formatting
A critical aspect of the merging strategy is the preservation of JSONC (JSON with Comments). The system uses jsonc-parser to ensure that developer comments and favorite themes are not lost during automated updates.
Sources: packages/cli/tests/updaters.test.ts:153-176, packages/cli/src/commands/init.ts:114-118
Implementation Details
MCP Server Merging
MCP (Model Context Protocol) servers are merged as objects. If a later component provides a server with the same name as an existing one, the later component's configuration (URL, environment variables, enabled status) overwrites the previous one. If the later component has no MCP definitions, existing ones are preserved.
Sources: packages/cli/tests/merge.test.ts:15-68, packages/cli/tests/updaters.test.ts:110-128
Plugin and Instruction Arrays
Arrays representing plugins and global instructions are merged through concatenation. To prevent bloat and redundancy, identical entries are automatically deduplicated during the merge process.
This sequence ensures that even if multiple components depend on the same plugin, it is only registered once in the final configuration.
Sources: packages/cli/tests/merge.test.ts:71-125
Agent-Specific Configuration
The agent section of the configuration supports deep merging for per-agent settings. This includes temperature, custom prompts, and specific tools enabled or disabled for that agent role (e.g., researcher vs scribe).
Sources: packages/cli/tests/merge.test.ts:161-186, packages/cli/tests/updaters.test.ts:245-260
Summary
The OCX Configuration Merging Strategy prioritizes user ownership and transparency. By employing a deep-merge approach that respects JSONC formatting and follows a strict priority cascade, OCX allows complex AI environments to be shared and installed as components without compromising the stability or readability of the user's primary configuration files.