---
# System prepended metadata

title: Oh-My-OpenCode with OCX Profiles

---

# 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
   ```