File Structure & Paths
Relevant source files
The following files were used as context for generating this wiki page:
The OCX ecosystem utilizes a structured approach to file organization, spanning global configuration directories, local project folders, and specialized registry source structures. This architecture ensures that OpenCode extensions, profiles, and components remain isolated yet portable across different development environments.
Local Project Structure
When OCX is initialized within a project, it manages a dedicated .opencode/ directory. This directory follows a "copy-and-own" philosophy where component source files are placed directly into the project for transparency and customization.
The .opencode Directory
This directory serves as the local root for all OpenCode-related assets and configurations.
| Path | Purpose |
|---|---|
.opencode/agent/ | Contains specialized AI role definitions (.md files). |
.opencode/skill/ | Contains reusable instruction sets, often structured as name/SKILL.md. |
.opencode/plugin/ | Stores TypeScript-based plugins that extend OpenCode functionality. |
.opencode/command/ | Stores custom TUI (Terminal User Interface) commands. |
.opencode/tool/ | Contains custom tool implementations. |
opencode.jsonc | The project-specific OpenCode configuration file. |
ocx.jsonc | The local OCX configuration and registry settings. |
Sources: README.md:278-285, AGENTS.md:162-165
Workspace Persistence Paths
Specific plugins, such as the workspace-plugin, utilize standardized paths within the user's home directory for persisting data like implementation plans and research findings.
The diagram shows the hierarchical path used by the workspace-plugin to store session-specific planning data.
Sources: workers/kdco-registry/files/plugin/workspace-plugin.ts:401-447
Global Profile Architecture
OCX provides a global profile system located in the user's system configuration directory. This allows users to maintain portable configurations that can be applied to any repository without modifying the repository's own files.
Configuration Locations
Profiles are stored in ~/.config/opencode/ (or the directory defined by $XDG_CONFIG_HOME).
| File/Folder | Description |
|---|---|
ocx.jsonc | Global base configuration applied to all sessions. |
profiles/ | Sub-directory containing individual named profiles. |
profiles/{name}/ocx.jsonc | Profile-specific settings (registries, component paths). |
profiles/{name}/opencode.jsonc | The OpenCode configuration used when this profile is active. |
profiles/{name}/AGENTS.md | Profile-specific AI instructions. |
Sources: AGENTS.md:144-155, README.md:144-156
Configuration Cascade & Merging
OCX resolves the final configuration by merging multiple sources. Later sources in the list override earlier ones.
- Global
ocx.jsonc: The base layer. - Profile Configs: If a profile is selected (via
-p, env var, or default), itsocx.jsoncandopencode.jsoncare applied. - Local
.opencode/ocx.jsonc: Project-specific settings (unless excluded by the profile). - Local
.opencode/opencode.jsonc: Project-specific OpenCode config (unless excluded).
Sources: AGENTS.md:167-175, README.md:168-175
Registry Source Structure
For developers creating or contributing to registries, OCX enforces a specific directory structure to ensure valid builds and distribution.
Source Layout
A registry source contains the metadata and the raw files for various components.
my-registry/
├── registry.jsonc # Registry manifest (required metadata)
├── files/ # Component source files
│ ├── skill/
│ │ └── {name}/
│ │ └── SKILL.md
│ ├── plugin/
│ │ └── {name}.ts
│ └── agent/
│ └── {name}.md
├── dist/ # Built output (generated by ocx build)
│ ├── index.json # Compiled registry index
│ └── .well-known/
│ └── ocx.json # Discovery endpoint
Sources: examples/registry-starter/AGENTS.md:76-88, CONTRIBUTING.md:11-18
Build Output
When the ocx build command is executed, it transforms the source files into a distribution-ready format, typically in a dist/ folder. This includes a registry.json (or index.json) that acts as the manifest for the built registry.
Sources: examples/registry-starter/AGENTS.md:301-310, CONTRIBUTING.md:115-117
External Worktree Isolation
The opencode-worktree plugin manages isolated development environments outside the main repository to prevent context contamination during AI-driven tasks.
Worktree Path Resolution
Isolated worktrees are created in a standardized location to ensure they do not clutter the primary working directory or the global configuration space.
- Storage Root:
~/.local/share/opencode/worktree/{project-id}/{branch}/
The diagram illustrates how the worktree plugin spawns isolated environments in a specific local path based on project identifiers and branch names.
Sources: facades/opencode-worktree/README.md:43-52
Summary of Key Paths
| Entity | Primary Path |
|---|---|
| Local Config | ./.opencode/ |
| Global Profiles | ~/.config/opencode/profiles/ |
| Workspace Data | ~/.local/share/opencode/workspace/ |
| Isolated Worktrees | ~/.local/share/opencode/worktree/ |
| Built Registries | ./dist/ |
Sources: AGENTS.md:144-165, README.md:144-156, facades/opencode-worktree/README.md:43-52