OCX - A Config Manager for OpenCode - Scribblings of a Seeker

One of the problems I face with Opencode or any coding agent in general is the local configs or context MD files these agents generate, which is fine for a personal repo. But when you are working on a repo that is used by hundreds of developers, it can become tricky, and you are forced to add your local context files to .gitignore.

This is where OCX comes in handy. It is a config management tool for opencode. which means my configs and context files can live outside of my repo. They can be easily ported and kept agnostic of the project I am working on.

Getting Started with OCX#

Profiles#

To understand what a profile helps with, let’s first see what the configs we need so far are to run Opencode efficiently

Agents.md - When you first initialize opencode in a project, it creates this file to give it context of the project, so it does not have to analyze your project for every task.
opencode.json - your global opencode configuration. This usually lives in ~/.config/opencode (for Mac). This config dictates the opencode global context, your MCP server configuration, etc.
With every new tool you add to your AI development, it comes with its own config, too. In this case, we have our OCX config, that ocx.json

Profiles give you a global configuration system that lives outside your project directories. Instead of initializing .opencode/ in every repository, you define your settings once and bring them anywhere.

When to Use Profiles#

When you work across multiple repositories and want a consistent configuration.
When you contribute to open source projects and need a zero-footprint configuration.
When you need to control what OpenCode sees in untrusted repositories.
When you maintain separate configurations for work, personal, and client projects

In the quick start guide, we ran the following command

1
ocx profile add omo --source kit/omo --from https://ocx-kit.kdco.dev --global

This installs the oh-my-opencode profile from the OCX Kit registry. The --from flag uses an ephemeral registry reference (not saved to your config).

The omo (Oh-My-OpenCode) profile is a starter profile that gives you a lightweight, pre-configured multi-agent setup using free OpenCode Zen models. Here’s why you’d use it:

Multi-agent out of the box — It includes oh-my-opencode, which configures specialized agents:
- Big Pickle — Orchestrator (Sisyphus) and Executor (Atlas)
- GPT-5 Nano — Research, exploration, documentation, and planning
Free models — Uses OpenCode Zen models, so no extra API keys or costs with your Go subscription.
Portable — The profile travels with you across repos without modifying any project files.
Customizable — You can edit models or clone it for variations (ocx profile add work --clone omo --global).

It’s a great starting point to experience OCX’s profile system with a working multi-agent configuration right away.

But if you have a paid subscription or would like to configure your own AI models? simple. Let’s create an empty profile and configure it.

Here’s how to create your own profile:

Create an empty profile:

1
ocx profile add myprofile --global

Edit the OpenCode config to set your models (since you have Go subscription, you have access to Zen models):

1
$EDITOR ~/.config/opencode/profiles/myprofile/opencode.jsonc

Edit the OCX config for exclude/include patterns:

1
$EDITOR ~/.config/opencode/profiles/myprofile/ocx.jsonc

Add agent instructions:

1
$EDITOR ~/.config/opencode/profiles/myprofile/AGENTS.md

Launch it:

1
ocx oc -p myprofile

You can also clone an existing profile as a starting point:

1
ocx profile add myprofile --clone omo --global

Run opencode models to see available models for your Go subscription. Set a default with export OCX_PROFILE=myprofile.

I am going to clone the Omo profile as it gives me a good starting point to configure my own.

1
ocx profile add seeker --clone omo --global

Let’s open the profile we just cloned and see the config. I am Zed as my editor.

1
zed ~/.config/opencode/profiles/seeker/opencode.jsonc