Configuration Management

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• README.md
• examples/registry-starter/AGENTS.md
• workers/kdco-registry/files/plugin/workspace-plugin.ts
• CONTRIBUTING.md

Configuration Management in OCX is a multi-layered system designed to manage OpenCode extensions, environment settings, and AI agent behaviors. It utilizes a hierarchical merging strategy that spans from global user profiles down to project-specific local configurations. The system is built on the "Copy. Paste. Own." philosophy, where configurations and components are copied into local project directories (.opencode/) to ensure user ownership and auditability.

The primary goal of this system is to provide a seamless environment for AI agents and developers by managing dependencies, MCP (Model Context Protocol) servers, and plugin configurations without requiring manual editing of complex JSON files.

Sources: README.md:9-15, examples/registry-starter/AGENTS.md:5-9, AGENTS.md:129-135

Core Configuration Files

The OCX ecosystem relies on specific file types to define registry metadata, CLI behavior, and OpenCode environment settings.

Configuration File Types

File	Location	Purpose
ocx.jsonc	Global/Local/Profile	User-editable CLI settings, including registry lists and exclude/include patterns.
opencode.jsonc	Local/Profile	The primary configuration for the OpenCode environment (MCP, plugins, tools).
registry.jsonc	Registry Root	Defines registry metadata, namespaces, and component lists.
ocx.lock	Project Root	Auto-generated lockfile for version pinning and SHA-256 verification.

Sources: README.md:214-230, AGENTS.md:155-165, CONTRIBUTING.md:13-36

Registry Manifest (registry.jsonc)

The registry manifest defines the namespace and the specific components (skills, plugins, agents) available for installation. It requires a valid namespace identifier and semantic versioning.

{
  "name": "My Registry",
  "namespace": "my-namespace",
  "version": "0.0.1",
  "components": [
    {
      "name": "my-plugin",
      "type": "ocx:plugin",
      "files": ["plugin/my-plugin.ts"]
    }
  ]
}

Sources: examples/registry-starter/AGENTS.md:104-122, CONTRIBUTING.md:13-36

Profile System Architecture

OCX provides a global profile system that allows users to maintain separate configurations for different contexts (e.g., work, personal, or specific clients) without modifying the target project directories.

Configuration Cascade

OCX follows a specific priority order when merging configurations. Later sources in the list override earlier ones:

1. Global ocx.jsonc: Base settings applied to all sessions.
2. Profile Configs: Settings from the resolved profile (ocx.jsonc and opencode.jsonc).
3. Local .opencode/ocx.jsonc: Project-specific CLI settings.
4. Local .opencode/opencode.jsonc: Project-specific OpenCode configuration.

Sources: AGENTS.md:167-175, README.md:144-162

Profile Resolution Logic

The system resolves the active profile based on the following precedence:

The diagram shows the priority order for profile resolution in the CLI.
Sources: AGENTS.md:167-175, README.md:104-115

Component Management

Components are the building blocks of the OCX ecosystem. They inject specific configurations into the user's environment.

Component Types

Type	Format	Injection Behavior
ocx:skill	Markdown	Injects behavioral instructions for AI.
ocx:plugin	TypeScript	Adds tools and lifecycle hooks.
ocx:agent	Markdown	Defines specialized roles and permissions.
ocx:bundle	JSON	Aggregates multiple dependencies for batch installation.

Sources: examples/registry-starter/AGENTS.md:126-140, README.md:237-245

Config Merging for Plugins

When a plugin is added via ocx add, the CLI performs a deep merge of the component's configuration into the local opencode.jsonc. This includes MCP servers, tool permissions, and agent settings.

The sequence diagram illustrates the automated flow of adding a component and updating local configuration.
Sources: README.md:195-205, CONTRIBUTING.md:129-145, examples/registry-starter/AGENTS.md:214-225

Workspace Rules and Injection

The workspace-plugin facilitates targeted rule injection for different AI agents based on their operational mode (plan or build).

Rule Injection Flow

The system uses the experimental.chat.system.transform hook to inject context-aware rules into the AI session.

This diagram represents the logic within the WorkspacePlugin for dynamically modifying agent system prompts.
Sources: workers/kdco-registry/files/plugin/workspace-plugin.ts:474-489

Policy Level and Routing

Configurations define strict boundaries for agent routing to prevent "orchestrator" agents from performing forbidden actions like direct codebase modification or external searching.

Agent	Scope	Critical Constraints
explore	Internal Only	Cannot access external APIs or documentation.
researcher	External Only	Cannot search local codebase files.
scribe	Human-facing	Cannot execute bash or create code.
coder	Implementation	Cannot commit code or research externally.

Sources: workers/kdco-registry/files/plugin/workspace-plugin.ts:251-275, workers/kdco-registry/files/agent/researcher.md:104-118, workers/kdco-registry/files/agent/scribe.md:52-60

Validation and Data Integrity

The configuration system enforces the 5 Laws of Elegant Defense, prioritizing "Parse, Don't Validate" at system boundaries.

Schema Validation with Zod

OCX uses Zod schemas to ensure that configuration data is transformed into typed, trusted data before it enters internal logic. For example, implementation plans are validated against a specific PlanSchema before being persisted.

const PlanSchema = z.object({
  frontmatter: FrontmatterSchema,
  goal: z.string().min(10),
  phases: z.array(PhaseSchema).min(1),
})
// Sources: [workers/kdco-registry/files/plugin/workspace-plugin.ts:50-58](https://github.com/kdcokenny/ocx/blob/HEAD/workers/kdco-registry/files/plugin/workspace-plugin.ts#L50-L58)

Integrity Verification

The ocx.lock file ensures that all installed components match their upstream source via SHA-256 hashes. Users can use the ocx diff command to inspect upstream changes before applying updates.

Sources: README.md:65-72, AGENTS.md:112-115

Summary

Configuration Management in OCX is a robust, hierarchical system that prioritizes user ownership and auditability. By separating global profiles from local project settings and utilizing a structured component injection model, it allows developers to maintain portable, secure, and context-aware environments for AI-driven development. The integration of schema validation and integrity checks ensures that the configuration remains predictable and resilient across different registries and projects.