> ## Documentation Index
> Fetch the complete documentation index at: https://ocx.kdco.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# ocx opencode

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

## Usage

```bash theme={null}
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 |

<Note>
  `-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).
</Note>

## Examples

### Launch with Default Profile

```bash theme={null}
ocx opencode
```

### Launch with Specific Profile

```bash theme={null}
ocx opencode -p work
```

### Skip Window Renaming

```bash theme={null}
ocx opencode --no-rename
```

### Use Environment Variable

```bash theme={null}
OCX_PROFILE=work ocx opencode
```

### Use the Short Alias

```bash theme={null}
ocx oc -p personal
```

### Pass Flags to OpenCode

```bash theme={null}
# 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`:

```jsonc theme={null}
{
  "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](/docs/profiles/overview) — Core profile concepts.
* [Profile Configuration](/docs/profiles/configuration) — Instruction discovery and pattern filtering details.
* [ocx profile](/docs/cli/profile) — Manage profiles.
* [CLI Reference](/docs/cli/commands) — All commands.