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

Syntax	Example	Reference
# Header	Header	基本排版
- Unordered List	Unordered List
1. Ordered List	Ordered List
- [ ] Todo List	Todo List
> Blockquote	Blockquote
Bold font	Bold font
Italics font	Italics font
~~Strikethrough~~	~~Strikethrough~~
19^th^	19^th
H~2~O	H₂O
++Inserted text++	Inserted text
==Marked text==	Marked text
[link text](https:// "title")	Link
![image alt](https:// "title")	Image
`Code`	`Code`	在筆記中貼入程式碼
```javascript var i = 0; ```	`var i = 0;`
:smile:		Emoji list
{%youtube youtube_id %}	Externals
$L^aT_eX$	L^aT_eX
:::info This is a alert area. :::	This is a alert area.