# Oh-My-OpenCode with OCX Profiles
This document describes the architecture of oh-my-opencode when used with OCX profiles and provides guidance on creating new profiles.
## Architecture Overview
### OCX and Profile System
OCX (OpenCode eXtensions) is a package manager for OpenCode that provides global profiles for portable, isolated configurations. Profiles allow you to work in any repository without modifying the project, using your own complete configuration.
```
┌─────────────────────────────────────────────────────────────────┐
│ Your Development Machine │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ~/.config/opencode/ │
│ ├── opencode.jsonc # Global base configuration │
│ └── profiles/ # Profile configurations │
│ ├── omooss/ # Your primary oh-my-opencode │
│ │ ├── ocx.jsonc # OCX isolation settings │
│ │ ├── opencode.jsonc # OpenCode config + plugin │
│ │ ├── oh-my-opencode.json # Agent definitions │
│ │ └── AGENTS.md # Profile instructions │
│ └── other-profile/ # Additional profiles │
│ ├── ocx.jsonc │
│ └── opencode.jsonc │
│ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Any Repository │
│ │
│ /home/user/oss/some-project/ │
│ ├── src/ │
│ ├── AGENTS.md # Isolated - not loaded by profile │
│ └── .opencode/ # Isolated - not loaded by profile │
│ │
│ When you run: ocx opencode -p omooss │
│ OpenCode launches HERE with your profile config │
└─────────────────────────────────────────────────────────────────┘
```
### Profile Resolution Priority
When launching OpenCode, the profile is resolved in this order:
1. `--profile <name>` / `-p <name>` flag (explicit override)
2. `OCX_PROFILE` environment variable
3. `default` profile (if it exists)
4. No profile (uses base configs only)
### Configuration Isolation Model
OCX implements a strict isolation model for security and portability:
**Registry Isolation:**
- Global registries (in `~/.config/opencode/ocx.jsonc`) - only for downloading profiles
- Profile registries (in profile's `ocx.jsonc`) - only available when using that profile
- Local registries (in project's `.opencode/ocx.jsonc`) - only for that project
This prevents global registries from injecting components into all projects.
**OpenCode Config Merging:**
- Profile's `opencode.jsonc` merges with local (if not excluded by patterns)
- Profile's exclude/include patterns control which project instruction files OpenCode can see
- Include patterns override exclude patterns (TypeScript/Vite style)
**Default Exclude Patterns:**
```jsonc
{
"exclude": [
"**/AGENTS.md", // Don't load project's AGENTS.md
"**/CLAUDE.md", // Don't load project's CLAUDE.md
"**/CONTEXT.md", // Don't load project's CONTEXT.md
"**/.opencode/**", // Don't load project's .opencode/
"**/opencode.jsonc", // Don't load project's opencode.jsonc
"**/opencode.json" // Don't load project's opencode.json
]
}
```
### Profile File Structure
Each profile contains these core files:
```
~/.config/opencode/profiles/<profile-name>/
├── ocx.jsonc # OCX-specific settings
├── opencode.jsonc # OpenCode configuration
├── oh-my-opencode.json # Oh-My-OpenCode agent definitions (optional)
└── AGENTS.md # Profile-specific instructions (optional)
```
#### ocx.jsonc
The OCX configuration file for the profile:
```jsonc
{
"$schema": "https://ocx.kdco.dev/schemas/ocx.json",
"registries": {}, // Profile-specific registries
"renameWindow": true, // Rename terminal window with profile info
"bin": "/path/to/opencode", // Custom OpenCode binary (optional)
"exclude": [...], // Exclude patterns for file discovery
"include": [], // Include patterns (override excludes)
"componentPath": ".opencode" // Where to install components
}
```
#### opencode.jsonc
The OpenCode configuration for the profile:
```jsonc
{
"model": "cliproxy/claude-sonnet-4-5-thinking",
"permission": { "question": "allow" },
"plugin": ["oh-my-opencode@latest"], // Load oh-my-opencode
"provider": { ... } // AI provider configuration
}
```
#### oh-my-opencode.json
The core configuration defining agents, categories, and skills with their models and behavior. This is a complex JSON structure that maps:
- **Agents**: Specialized AI agents (Sisyphus, Oracle, Librarian, Explore, etc.)
- **Categories**: Task categories (visual-engineering, ultrabrain, quick, etc.)
- **Skills**: Reusable task-specific instructions (playwright, git-master, etc.)
```jsonc
{
"agents": {
"sisyphus": {
"model": "cliproxyoss/minimaxai/minimax-m2.1",
"temperature": 0.1,
"prompt_append": "Additional instructions..."
},
"oracle": { ... },
"librarian": { ... }
},
"categories": {
"quick": { ... },
"visual-engineering": { ... }
},
"skills": {
"playwright": { ... },
"git-master": { ... }
}
}
```
## Creating Profiles
### Method 1: Create a Blank Profile
Create a new profile from scratch:
```bash
# Initialize global profiles first (one-time)
ocx init --global
# Create a new blank profile
ocx profile add myprofile
# Edit the profile configuration
ocx config edit -p myprofile
```
This creates:
```
~/.config/opencode/profiles/myprofile/
├── ocx.jsonc # With default settings
└── opencode.jsonc # Empty config
```
### Method 2: Clone from Existing Profile
Copy an existing profile as a starting point:
```bash
# Clone from your omooss profile
ocx profile add work --from omooss
# Customize it
ocx config edit -p work
```
### Method 3: Install from Registry
Use a pre-configured profile from a registry:
```bash
# Add a registry with profiles
ocx registry add https://registry.kdco.dev --name kdco --global
# Install a profile from the registry
ocx profile add minimal --from kdco/minimal
```
### Method 4: Manual Creation
Create a profile manually by creating the directory structure:
```bash
mkdir -p ~/.config/opencode/profiles/myprofile
```
Then create the required files manually (see File Structure Reference below).
## Profile Configuration Guide
### Setting Up AI Providers
In `~/.config/opencode/profiles/<name>/opencode.jsonc`:
```jsonc
{
"model": "cliproxy/claude-sonnet-4-5-thinking",
"permission": { "question": "allow" },
"plugin": ["oh-my-opencode@latest"],
"provider": {
"cliproxy": {
"name": "Cliproxy",
"npm": "@ai-sdk/cli",
"options": {
"baseURL": "http://localhost:8317/v1"
},
"models": {
"claude-sonnet-4-5-thinking": {
"name": "Claude Sonnet 4.5 Thinking"
}
}
}
}
}
```
### Configuring Oh-My-OpenCode Agents
In `~/.config/opencode/profiles/<name>/oh-my-opencode.json`:
```jsonc
{
"agents": {
"sisyphus": {
"model": "cliproxyoss/minimaxai/minimax-m2.1",
"temperature": 0.1,
"prompt_append": "Your custom instructions here"
},
"oracle": {
"model": "cliproxyoss/z-ai/glm4.7",
"temperature": 0.1
}
},
"categories": {
"quick": {
"model": "cliproxyoss/z-ai/glm4.7",
"temperature": 0.2
},
"ultrabrain": {
"model": "cliproxyoss/moonshotai/kimi-k2-thinking",
"temperature": 0.1
}
},
"skills": {
"playwright": {
"mcp": "playwright"
},
"git-master": {
"mcp": null
}
}
}
```
### Customizing File Visibility
Modify `exclude` and `include` patterns in `ocx.jsonc`:
```jsonc
{
"exclude": [
"**/AGENTS.md",
"**/CLAUDE.md",
"**/CONTEXT.md",
"**/.opencode/**",
"**/opencode.jsonc",
"**/opencode.json"
],
"include": [
"./docs/AGENTS.md",
".opencode/skills/**"
]
}
```
### Using Custom OpenCode Binary
```jsonc
{
"bin": "/usr/local/bin/opencode-dev"
}
```
### Adding Profile-Specific Instructions
Create or edit `~/.config/opencode/profiles/<name>/AGENTS.md`:
```markdown
# Profile-Specific Instructions
These instructions apply when using this profile.
## Project Context
- This profile is configured for [purpose]
- Uses [model] as primary model
## Special Instructions
- [Your custom instructions here]
```
## File Structure Reference
### Complete Profile Structure
```
~/.config/opencode/
├── opencode.jsonc # Global base config
└── profiles/
└── <profile-name>/ # Profile directory
├── ocx.jsonc # OCX settings
│ ├── registries # Profile-specific registries
│ ├── renameWindow # Terminal window naming
│ ├── bin # Custom OpenCode binary path
│ ├── componentPath # Component installation path
│ ├── exclude # File exclusion patterns
│ └── include # File inclusion patterns (override exclude)
│
├── opencode.jsonc # OpenCode configuration
│ ├── model # Default model
│ ├── permission # Permission settings
│ ├── plugin # npm plugins
│ └── provider # AI provider configuration
│
├── oh-my-opencode.json # Oh-My-OpenCode configuration
│ ├── agents # Agent definitions
│ ├── categories # Task category assignments
│ └── skills # Skill configurations
│
├── AGENTS.md # Profile-specific instructions
│
└── .opencode/ # Profile components (optional)
├── agent/ # Installed agents
├── skill/ # Installed skills
└── plugin/ # Installed plugins
```
### Your Current Setup (omooss)
```
~/.config/opencode/
├── opencode.jsonc # 4 AI providers via local proxy
└── profiles/
└── omooss/
├── ocx.jsonc # Empty registries, full isolation
├── opencode.jsonc # Includes oh-my-opencode plugin
├── oh-my-opencode.json # Complete agent/category/skill definitions
├── AGENTS.md # Custom instructions (empty)
└── node_modules/ # Dependencies (@opencode-ai, zod)
```
## Profile Management Commands
### Essential Commands
```bash
# List all profiles
ocx profile list
ocx p ls
# Create new profile
ocx profile add <name>
# Clone from existing profile
ocx profile add <name> --from <source-profile>
# Install from registry
ocx profile add <name> --from <registry>/<profile>
# Delete profile
ocx profile remove <name>
ocx p rm <name>
# Display profile contents
ocx profile show <name>
ocx p show <name>
# Edit profile config
ocx config edit -p <name>
# Launch with profile
ocx opencode -p <name>
```
### Configuration Commands
```bash
# Show current configuration
ocx config show
# Show config with source annotations
ocx config show --origin
# Edit global config
ocx config edit --global
# Edit local config (in current project)
ocx config edit
```
## Quick Start: Creating Your Own Profile
1. **Initialize global profiles:**
```bash
ocx init --global
```
2. **Create a new profile:**
```bash
ocx profile add myprofile
```
3. **Configure AI providers** in `opencode.jsonc`:
```bash
ocx config edit -p myprofile
```
4. **Add oh-my-opencode** plugin (optional):
```jsonc
{
"plugin": ["oh-my-opencode@latest"]
}
```
5. **Configure agents** in `oh-my-opencode.json` (create if needed):
```bash
cat > ~/.config/opencode/profiles/myprofile/oh-my-opencode.json << 'EOF'
{
"agents": {
"sisyphus": {
"model": "your-provider/your-model",
"temperature": 0.1
}
}
}
EOF
```
6. **Launch OpenCode:**
```bash
ocx opencode -p myprofile
```
7. **Set as default** (optional):
```bash
export OCX_PROFILE=myprofile
```
Sign in with Wallet
Connect another wallet