ocx opencode

Reference for the ocx opencode command — launch OpenCode with resolved configuration

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

Flag	Shorthand	Default	Description
--profile <name>	-p		Use specific global profile
--verbose	-v	false	Enable verbose OCX output
--no-rename		false	Skip automatic window/terminal renaming

-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

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

• Profiles Overview — Core profile concepts.
• Profile Configuration — Instruction discovery and pattern filtering details.
• ocx profile — Manage profiles.
• CLI Reference — All commands.