Relevant source files

The following files were used as context for generating this wiki page: - [AGENTS.md](https://github.com/kdcokenny/ocx/blob/main/AGENTS.md) - [README.md](https://github.com/kdcokenny/ocx/blob/main/README.md) - [CONTRIBUTING.md](https://github.com/kdcokenny/ocx/blob/main/CONTRIBUTING.md) - [packages/cli/src/commands/profile/index.ts](https://github.com/kdcokenny/ocx/blob/main/packages/cli/src/commands/profile/index.ts) - [packages/cli/src/profile/manager.ts](https://github.com/kdcokenny/ocx/blob/main/packages/cli/src/profile/manager.ts) - [packages/cli/src/profile/paths.ts](https://github.com/kdcokenny/ocx/blob/main/packages/cli/src/profile/paths.ts) - [packages/cli/src/profile/schema.ts](https://github.com/kdcokenny/ocx/blob/main/packages/cli/src/profile/schema.ts)

# Global Profiles The Global Profile system in OCX is a specialized configuration management framework that allows users to maintain portable, isolated OpenCode environments. It enables developers to work across multiple repositories without modifying project-specific files, keeping configurations for different contexts (e.g., work, personal, specific clients) entirely separate. This system provides a way to inject custom instructions, MCP servers, and plugins into any project directory through a global configuration overlay. Sources: [AGENTS.md:275-278](), [README.md:14-15](), [README.md:103-106]() ## Architecture and Configuration Storage Profiles are stored globally within the user's config directory, typically located at `~/.config/opencode/`. This centralized storage ensures that profiles are accessible regardless of the current working directory. ### Directory Structure ``` ~/.config/opencode/ ├── ocx.jsonc # Global base config └── profiles/ ├── default/ # Default fallback profile │ ├── ocx.jsonc # Profile-specific OCX settings │ ├── opencode.jsonc # Profile-specific OpenCode config │ └── AGENTS.md # Profile-specific instructions └── [profile-name]/ # Named custom profiles ├── ocx.jsonc ├── opencode.jsonc └── AGENTS.md ``` Sources: [AGENTS.md:290-302](), [README.md:120-132]() ### Configuration Components Each profile directory contains three primary files that define the environment: | File | Purpose | |------|---------| | `ocx.jsonc` | Defines registries, component installation paths, and include/exclude glob patterns for project files. | | `opencode.jsonc` | Contains the actual OpenCode configuration (model settings, agents, MCP servers). | | `AGENTS.md` | Provides the system instructions that the AI agent will follow when the profile is active. | Sources: [AGENTS.md:290-302](), [README.md:162-166]() ## Profile Resolution and Merging OCX employs a specific priority order to determine which profile is active and how configurations are merged before launching an OpenCode session. ### Resolution Priority When a command is executed, OCX resolves the active profile using the following hierarchy: 1. **Explicit Flag**: `--profile ` or `-p ` passed to the CLI. 2. **Environment Variable**: The `OCX_PROFILE` variable. 3. **Default Profile**: The profile named `default` if it exists in the global config directory. 4. **No Profile**: Fallback to base global configs only. Sources: [AGENTS.md:304-309](), [README.md:134-139]() ### Configuration Cascade The final configuration is built by merging multiple sources in a specific sequence, where later sources override earlier ones: ```mermaid flowchart TD A[Global ocx.jsonc] --> B[Profile ocx.jsonc] B --> C[Profile opencode.jsonc] C --> D{Filter Patterns} D --> E[Local .opencode/ocx.jsonc] E --> F[Local .opencode/opencode.jsonc] F --> G[Final Merged Config] ``` The diagram shows the sequence of configuration merging, where project-local files are only merged if they are not explicitly excluded by the profile's patterns. Sources: [AGENTS.md:311-318](), [README.md:154-156]() ## Instruction File Discovery and Visibility A key feature of the profile system is its ability to control which instruction files (like `AGENTS.md` or `CLAUDE.md`) are visible to the AI. By default, profiles isolate the environment by excluding project-level instructions. ### Include/Exclude Logic Profiles use a TypeScript/Vite-style glob pattern system. Include patterns override exclude patterns, allowing for granular control over which project files the AI can "see." ```jsonc { "exclude": [ "**/CLAUDE.md", "**/CONTEXT.md", "**/.opencode/**", "**/opencode.jsonc" ], "include": [ "**/AGENTS.md" ] } ``` Sources: [AGENTS.md:337-347](), [README.md:200-217]() ## CLI Management Commands The `ocx` CLI provides a dedicated suite of commands for managing the lifecycle of global profiles. ### Profile Lifecycle Commands | Command | Alias | Description | |---------|-------|-------------| | `ocx profile list` | `ocx p ls` | Lists all discovered global profiles. | | `ocx profile add ` | `ocx p add` | Creates a new profile directory and boilerplate. | | `ocx profile remove ` | `ocx p rm` | Deletes a profile and its associated files. | | `ocx profile show ` | `ocx p show` | Displays the current content of a profile's config. | | `ocx profile config ` | `ocx p config` | Opens the profile's `ocx.jsonc` in the default editor. | Sources: [AGENTS.md:364-372](), [README.md:143-149]() ### Execution Flow The following sequence diagram illustrates how OCX initializes a session using the profile system: ```mermaid sequenceDiagram participant User participant CLI as OCX CLI participant PM as ProfileManager participant OC as OpenCode User->>CLI: ocx opencode -p work CLI->>PM: Resolve Profile "work" PM->>PM: Load global & profile configs PM->>PM: Discover project instructions PM->>PM: Apply include/exclude filters CLI->>CLI: Merge final configuration CLI->>OC: Launch with merged config & instructions OC-->>User: Active Session (Isolated) ``` This diagram depicts the internal logic for resolving, merging, and launching an OpenCode environment via the profile system. Sources: [AGENTS.md:320-329](), [README.md:154-156]() ## Developer and Testing Integration For developers contributing to OCX or testing new features, the profile system provides a safe, non-destructive testing environment. ### Isolated Testing Developers are encouraged to use an `ocx-dev` profile for manual and AI-driven testing. This prevents the development process from polluting the user's primary configuration or the project's source code. Sources: [CONTRIBUTING.md:104-110]() ### Custom Binaries Profiles can be configured to use specific OpenCode binaries, which is useful for testing forks or unreleased versions. This is configured via the `bin` field in `ocx.jsonc` or the `OPENCODE_BIN` environment variable. Sources: [AGENTS.md:349-357](), [CONTRIBUTING.md:142-146]() ## Summary Global Profiles transform OCX from a simple project-level manager into a portable development environment. By leveraging global storage, hierarchical resolution, and glob-based file visibility, the system ensures that developers can maintain consistent AI behaviors and toolsets across diverse repositories while keeping project-specific modifications to a minimum.