Introduction to OCX
Relevant source files
The following files were used as context for generating this wiki page:
OCX is a specialized package manager and configuration orchestrator for OpenCode extensions. It is designed to manage component registries, handle dependency resolution, and provide a global profile system that allows developers to maintain portable configurations across different repositories without modifying project-specific files. Sources: README.md:1-12, AGENTS.md:5-7
The system follows a "Copy. Paste. Own." philosophy, inspired by the ShadCN model, where components are copied directly into a project's .opencode/ directory rather than being hidden in global modules. This ensures that every component is auditable, version-pinned, and fully customizable by the user. Sources: README.md:54-58, examples/registry-starter/AGENTS.md:6-8
Core Philosophy: The 5 Laws of Elegant Defense
OCX development and its component registries adhere to five core principles known as the "5 Laws of Elegant Defense" to ensure code reliability and predictability. Sources: examples/registry-starter/AGENTS.md:18-20, CONTRIBUTING.md:144-150
| Law | Principle | Description |
|---|---|---|
| 1. Early Exit | Guard Clauses | Handle edge cases and errors at the top of functions to reduce nesting depth. |
| 2. Parse, Don't Validate | Boundary Zod Schemas | Transform unknown data into typed data once at the boundary using tools like Zod. |
| 3. Atomic Predictability | Pure Functions | Ensure the same input always yields the same output with no hidden side effects. |
| 4. Fail Fast, Fail Loud | Clear Exceptions | Throw descriptive errors immediately instead of swallowing exceptions or returning ambiguous nulls. |
| 5. Intentional Naming | Self-Documenting Code | Use names that reveal intent, allowing logic to be read like a sentence. |
Sources: examples/registry-starter/AGENTS.md:22-60, CONTRIBUTING.md:144-150
Architecture and Component Types
OCX manages four primary types of components within a registry structure. These components are defined in a registry.jsonc manifest and served via a built index. Sources: examples/registry-starter/AGENTS.md:63-95
Component Classification
| Type | Purpose | Extension/Format |
|---|---|---|
ocx:skill | Instructions for AI behavior | Markdown (SKILL.md) |
ocx:plugin | Code extending OpenCode functionality | TypeScript (.ts) |
ocx:agent | Specialized AI role definitions | Markdown (.md) |
ocx:bundle | Collections of multiple components | JSON manifest |
Sources: examples/registry-starter/AGENTS.md:97-103, facades/opencode-workspace/README.md:10-25
Workspace Orchestration
The system utilizes a hierarchical orchestration model where high-level "Orchestrator" agents coordinate specialized "Specialist" agents to perform tasks. Sources: facades/opencode-workspace/README.md:30-45
The diagram shows the delegation flow from high-level planners/builders to technical specialist agents. Sources: facades/opencode-workspace/README.md:30-45
Global Profile System
OCX introduces a profile system located at ~/.config/opencode/ that enables configuration isolation. This allows users to apply personal configurations (registries, MCP servers, and instructions) to any repository without altering the project's own .opencode/ directory. Sources: README.md:65-80, AGENTS.md:118-125
Configuration Cascade
When launching OpenCode via ocx opencode, configurations are merged in a specific priority order: Sources: AGENTS.md:144-153
- Global
ocx.jsonc: Base settings applied to all sessions. - Profile Configs: Settings from the resolved profile (e.g.,
defaultor a named profile). - Local Project Config:
.opencode/ocx.jsonc(subject to profileexclude/includefilters).
Profile Resolution Flow
The resolution flow determines which profile settings take precedence during the initialization of an OpenCode session. Sources: README.md:103-108, AGENTS.md:139-142
CLI Commands and Operations
The OCX CLI provides tools for managing components, registries, and profiles. Sources: README.md:60-63, AGENTS.md:203-240
Primary CLI Commands
| Command | Alias | Description |
|---|---|---|
ocx add <name> | - | Install a component or npm plugin. |
ocx update | - | Update installed components to latest versions. |
ocx diff | - | Compare local component code against upstream registry. |
ocx profile add | ocx p add | Create a new global configuration profile. |
ocx config show | - | Display the final merged configuration with origin notes. |
ocx build | - | Compile a registry source into a distributable index. |
Sources: README.md:60-63, AGENTS.md:203-240, CONTRIBUTING.md:38-40
Technical Specifications
Directory Structure (Registry)
A standard OCX registry source follows this layout before being built:
my-registry/
├── registry.jsonc # Required manifest defining components
├── files/ # Source assets for components
│ ├── skill/ # AI instruction sets
│ ├── plugin/ # TypeScript logic
│ └── agent/ # Role definitions
└── dist/ # Generated output (index.json, .well-known/)
Sources: examples/registry-starter/AGENTS.md:63-75, CONTRIBUTING.md:12-18
Integrity and Auditing
Every component added via OCX is SHA-256 verified and version-pinned in an ocx.lock file. This prevents tampering and ensures that AI agents do not execute unreviewed code updates. Sources: README.md:46-52, README.md:255-257
Conclusion
OCX serves as the infrastructure layer for OpenCode, bridging the gap between static configurations and dynamic, reusable AI components. By leveraging a strict philosophy of ownership, auditable code, and portable profiles, it provides developers with a robust environment for orchestrating multi-agent workflows across diverse project environments. Sources: README.md:1-12, facades/opencode-workspace/README.md:5-15