OpenCode Wrapper Integration
Relevant source files
The following files were used as context for generating this wiki page:
The OpenCode Wrapper Integration, primarily managed through the ocx CLI tool, serves as a sophisticated package manager and configuration orchestrator for OpenCode. Its primary purpose is to handle dependencies, Model Context Protocol (MCP) servers, and configuration merging automatically, allowing users to maintain isolated global profiles while working across different repositories.
The integration follows a "Copy. Paste. Own." philosophy (or ShadCN model), where components like agents, skills, and plugins are copied directly into a project's .opencode/ directory. This ensures that users have full ownership and auditability of the code running within their AI-enhanced development environment.
Sources: README.md:5-15, examples/registry-starter/AGENTS.md:7-12
Profile System and Configuration Cascade
The profile system allows for global configuration management that can be applied to any repository without modifying the project's own files. This system supports isolated profiles for different contexts, such as "work" or "personal".
Configuration Resolution Priority
When launching OpenCode via the wrapper, configurations are resolved and merged according to a strict hierarchy:
- Global Base Config: Located at
~/.config/opencode/ocx.jsonc. - Global Profile Configs: Settings from the active profile's
ocx.jsoncandopencode.jsonc. - Local Project Configs: Found in
.opencode/ocx.jsoncandopencode.jsonc, filtered by include/exclude patterns.
Sources: AGENTS.md:144-159, README.md:162-175
Profile Resolution Flow
The following diagram illustrates how the wrapper determines which configuration profile to activate during the ocx opencode command.
Sources: AGENTS.md:161-175, README.md:139-145
Component Architecture
OCX manages four primary component types that are integrated into the OpenCode environment. These components are defined in a registry.jsonc manifest and built into a versioned registry format.
| Type | Purpose | Implementation Detail |
|---|---|---|
ocx:skill | Instructions for AI behavior | Markdown files (e.g., SKILL.md) |
ocx:plugin | Code extending OpenCode | TypeScript files using hooks and tools |
ocx:agent | Specialized AI role definitions | Markdown files defining roles and permissions |
ocx:bundle | Collections of components | JSON manifest aggregating dependencies |
Sources: examples/registry-starter/AGENTS.md:100-105, README.md:204-213
Plugin Lifecycle Hooks
Plugins integrated via the wrapper can tap into various lifecycle events within the OpenCode session.
Workspace Orchestration and Rule Injection
The integration utilizes a specialized WorkspacePlugin to manage implementation plans and inject targeted system rules dynamically based on the active agent. This ensures strict boundaries between different agent roles.
Agent Routing Boundaries
The integration enforces specific scopes for different agents to prevent context leakage and ensure efficient task handling:
explore: Strictly for internal codebase files (finding files, tracing logic).researcher: Strictly for external resources (documentation, APIs, web search).coder: Handles all code modifications and bash execution proxying.scribe: Dedicated to human-facing content like documentation and PR descriptions.
Sources: workers/kdco-registry/files/plugin/workspace-plugin.ts:275-295, workers/kdco-registry/files/agent/researcher.md:104-115
Rule Injection Logic
The wrapper uses the experimental.chat.system.transform hook to inject rules into the AI's system prompt at runtime.
// Example from workspace-plugin.ts
"experimental.chat.system.transform": async (input: SystemTransformInput, output) => {
const agent = input.agent
const today = new Date().toISOString().split("T")[0]
// Universal date awareness
output.system.push(`<date-awareness>Today is ${today}...</date-awareness>`)
if (agent === "plan") {
output.system.push(PLAN_RULES)
} else if (agent === "build") {
output.system.push(BUILD_RULES)
}
}
Sources: workers/kdco-registry/files/plugin/workspace-plugin.ts:517-532
Git Worktree Integration
A key feature of the integration is the ability to spawn isolated git worktrees. This allows for zero-friction isolation where each worktree automatically opens its own terminal with OpenCode running inside.
Worktree Lifecycle
- Creation: The AI calls
worktree_create, triggering the creation of a physical directory at~/.local/share/opencode/worktree/. - Sync: Files are synchronized based on
.opencode/worktree.jsonc. - Terminal Spawn: A new terminal window (or
tmuxwindow) is opened specifically for that worktree. - Deletion: Calling
worktree_deletetriggers an auto-commit of changes and complete cleanup of the worktree directory.
Sources: facades/opencode-worktree/README.md:38-55, facades/opencode-worktree/README.md:105-125
Security and Verification
The wrapper integration emphasizes an "Auditable by Default" approach. Every component added is version-pinned and verified via SHA-256 hashes stored in an ocx.lock file.
- Integrity Verification: The CLI checks hashes before any update or installation.
- Diffing: Users can run
ocx diff [component]to see upstream changes before applying them to their project. - Sandboxing: Component-specific permissions can be defined, such as denying
webfetchglobally or restrictingresearcheragents to read-only MCP tools.
Sources: README.md:83-95, README.md:273-275, facades/opencode-workspace/README.md:52-65
Summary
OpenCode Wrapper Integration provides a structured layer over the OpenCode ecosystem, transforming it into a manageable and secure development platform. By combining a robust profile system, dynamic rule injection, and automated workspace management (like git worktrees), it enables complex multi-agent orchestration while maintaining local ownership and auditability of all AI instructions and tools.