Skip to main content

​
Usage

ocx opencode [options] [args...]
ocx oc [options] [args...]  # alias

​
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

FlagShorthandDefaultDescription
--profile <name>-pUse specific global profile
--no-renamefalseSkip automatic window/terminal renaming
Only -p/--profile and --no-rename are OCX flags. All other arguments and flags pass through to OpenCode. Use -- to pass flags that conflict with OCX (e.g., ocx oc -- --help forwards help to OpenCode).

​
Examples

​
Launch with Default Profile

ocx opencode

​
Launch with Specific Profile

ocx opencode -p work

​
Skip Window Renaming

ocx opencode --no-rename

​
Use Environment Variable

OCX_PROFILE=work ocx opencode

​
Use the Short Alias

ocx oc -p personal

​
Pass Flags to OpenCode

# Get help from OpenCode itself
ocx oc -- --help

​
Profile Resolution Priority

Profiles are resolved in this order (first match wins):
  1. profile field in .opencode/ocx.jsonc — Project-specific profile
  2. --profile / -p flag — Explicit CLI specification
  3. OCX_PROFILE environment variable — Session-level profile
  4. default profile — If it exists
  5. No profile — Base configurations only

​
How It Works

  1. Profile Resolution: Resolves profile using the priority order above.
  2. Instruction Discovery: Discovers instruction files in priority order.
  3. Pattern Filtering: Applies exclude/include patterns from profile.
  4. 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: 
{
  "bin": "/path/to/custom/opencode"
}
Resolution order:
  1. bin in profile’s ocx.jsonc
  2. OPENCODE_BIN environment variable
  3. opencode (system PATH)

​
See Also