Usage
Description
Launch OpenCode with resolved configuration and profile support. OCX merges profile settings, discovers instruction files, applies pattern filtering, and spawns OpenCode with the final configuration.
Flags
-p/--profile, -v/--verbose, and --no-rename are OCX-owned flags. Other arguments and flags pass through to OpenCode. Use -- to pass OpenCode flags that conflict with OCX (e.g., ocx oc -- --help forwards help to OpenCode).
Examples
Launch with Default Profile
Launch with Specific Profile
Skip Window Renaming
Use Environment Variable
Use the Short Alias
Pass Flags to OpenCode
Profile Resolution Priority
Profiles are resolved in this order (first match wins):
profile field in .opencode/ocx.jsonc — Project-specific profile--profile / -p flag — Explicit CLI specificationOCX_PROFILE environment variable — Session-level profiledefault profile — If it exists- No profile — Base configurations only
How It Works
- Profile Resolution: Resolves profile using the priority order above.
- Instruction Discovery: Discovers instruction files in priority order.
- Pattern Filtering: Applies exclude/include patterns from profile.
- Launch OpenCode: Spawns with profile configuration and discovered instructions.
Registry Isolation:
Global base config registries (~/.config/opencode/ocx.jsonc) are only used for downloading profiles, never for components. When using a profile, registries come from the profile config. This isolation prevents global registries from injecting components into all projects.
Custom OpenCode Binary
To use a custom OpenCode binary, set the bin option in your profile’s ocx.jsonc:
Resolution order:
bin in profile’s ocx.jsoncOPENCODE_BIN environment variableopencode (system PATH)
See Also
