ocmm — OpenCode Multi-Model Auto-Router

A small OpenCode plugin that auto-routes per-agent models, translates a single "variant" knob into provider-specific reasoning settings, attaches workflow-specific prompts declaratively at config time, and reactively falls back to the next model in a chain when the active model fails at runtime.

Concepts (model tiering, per-model specialized prompts, intent gating, proactive + reactive fallback) are inspired by oh-my-opencode; naming and code are independent.

What it does

The plugin does not change the model on a per-call basis via chat.params. OpenCode's chat.params output schema has no model field. Per-agent routing happens via the config hook (the only safe seam for model selection), and reactive re-routing happens via the event hook + client.session.prompt.

DSMM submodule

DSMM is an independent DeepSeek Harness project, linked here at dsmm/ as a Git submodule. Its dependencies, tests, npm package and GitHub Releases are maintained in its own repository; it is not part of the OCMM pnpm workspace or release pipeline.

To check out the pinned DSMM revision:

git submodule update --init dsmm

Run DSMM development commands from dsmm/ and follow its own README and contributor instructions. Commit and push DSMM changes in that repository before updating the submodule pointer in OCMM.

Workflows

OpenCode uses the skill-driven v1 workflow by default. The config/path label stays v1, but model-facing prompt text calls it deepwork. The default prompt is a concise local controller, and skills are injected on the first message per session through chat.message + system.transform.

The Codex adapter is a separate generated surface. It packages Codex-native prompts, skills, agents, and MCP configuration without changing the OpenCode runtime.

{ "workflow": "v1" }

Install

For Codex, build from source with your own project configuration and install through the local marketplace at .codex/local-plugin/. Follow Codex adapter for configuration, generation, and installation. Rebuild and regenerate that same local source when updating.

For OpenCode, npmjs.org remains the default installation source. npm packages and GitHub Release archives are also supported Codex distribution options when you want the packaged defaults rather than a custom build.

From npmjs.org

The main ocmm package is published to npmjs.org as ocmm. Native LSP binaries are per-platform optional dependencies — npm installs the matching platform package for your system automatically. Use --omit=optional to skip native binaries if you only need the plugin logic:

pnpm add ocmm
# or: npm install ocmm

The npm tarball excludes native LSP binaries to keep it platform-agnostic. When installed with default options, the matching ocmm-lsp- optional package is fetched from npmjs.org alongside the main package. Runtime resolution: optional platform package first, then bundled dist/bin fallback (GitHub Release/Codex tarballs only), then local build / PATH.

// opencode.json
{ "plugin": ["./node_modules/ocmm/dist/index.js"] }

For Codex with packaged defaults, add the installed package root as a local marketplace:

codex plugin marketplace add ./node_modules/ocmm --json
codex plugin add deepwork@deepwork-local --json

GitHub Release assets (optional distribution)

Main package releases (vX.Y.Z) publish self-contained OpenCode/Codex plugin tarballs and their checksums. Standalone native ocmm-lsp-* executables and platform package .tgz assets belong to the separate ocmm-lsp-vA.B.C release lane.

A main vX.Y.Z release contains:

• ocmm-opencode-plugin-.tgz — package-manager install package for the OpenCode plugin, CLI wrappers, Codex bundle, and bundled native binaries.
• deepwork-codex-plugin-.tgz — direct Codex plugin package root for local marketplace installation.
• SHA256SUMS.txt — checksums for every release asset.

The release tarball bundles the OpenCode plugin, the ocmm, ocmm-profiles, and ocmm-lsp CLI wrappers, plus platform-suffixed native ocmm-lsp binaries under dist/bin/.
It also includes the Codex marketplace file and a self-contained generated plugin bundle under .agents/plugins/marketplace.json and plugins/deepwork/; the Codex bundle carries its own plugin-local dist/cli, dist/shared, and dist/bin runtime so Codex's plugin cache can run the default lsp MCP.

For OpenCode installation or upgrades, use the npm instructions above. For a customized Codex installation, use the source-build instructions below. The release archives remain available for offline or self-contained distribution.

From GitHub Packages

The release workflow can also publish the same package contents to GitHub Packages as @/ocmm. This still avoids npmjs.org, but installs through npm.pkg.github.com and normally requires a GitHub personal access token with read:packages in .npmrc:

@:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=

pnpm add @/ocmm

// opencode.json
{ "plugin": ["./node_modules/@/ocmm/dist/index.js"] }

For Codex, use the scoped package root as the marketplace root:

codex plugin marketplace add ./node_modules/@/ocmm --json
codex plugin add deepwork@deepwork-local --json

In GitHub Actions, ${GITHUB_TOKEN} can be used instead of a personal token when the workflow has package read permission.

Native LSP Support

ocmm ships the ocmm-lsp native binary in multiple forms:

• npm optional platform packages: 8 per-platform packages published to npmjs.org (ocmm-lsp-linux-x64-gnu, ocmm-lsp-linux-arm64-gnu, ocmm-lsp-linux-x64-musl, ocmm-lsp-linux-arm64-musl, ocmm-lsp-darwin-x64, ocmm-lsp-darwin-arm64, ocmm-lsp-windows-x64, ocmm-lsp-windows-arm64). npm installs the matching one automatically based on your OS, CPU, and libc.
• bundled inside GitHub Release tarballs under dist/bin/ and plugins/deepwork/dist/bin/;
• standalone release assets named ocmm-lsp-* for direct download or custom OCMM_LSP_COMMAND setups.

Runtime resolution priority (first match wins):

1. Optional npm platform package (node_modules/ocmm-lsp-/bin/ocmm-lsp-)
2. Bundled release binary (dist/bin/ocmm-lsp-) — GitHub Release tarballs only
3. Local Cargo release/debug build
4. cargo run from crates/ocmm-lsp/
5. PATH ocmm-lsp

Linux builds cover both glibc (GNU) and musl libc targets, so Alpine and other musl-based distributions are now fully supported out of the box.

Native binaries are built for:

ocmm registers the built-in OpenCode MCP named lsp with the project-owned ocmm-lsp mcp server by default. Resolution prefers optional npm platform package first, then bundled release binaries in dist/bin/, then local Cargo release/debug builds, then cargo run from crates/ocmm-lsp/, then a PATH ocmm-lsp. Set OCMM_LSP_COMMAND to force a custom command, add disabledMcps:["lsp"] to disable it, or define mcp.servers.lsp to override the built-in.

For direct external-program use, download the matching standalone asset from the ocmm-lsp-vA.B.C release and point OCMM_LSP_COMMAND at it:

LSP_VERSION=0.3.2
curl -L -o ~/.local/bin/ocmm-lsp "https://github.com//ocmm/releases/download/ocmm-lsp-v${LSP_VERSION}/ocmm-lsp-x86_64-unknown-linux-gnu"
chmod +x ~/.local/bin/ocmm-lsp
OCMM_LSP_COMMAND="$HOME/.local/bin/ocmm-lsp" opencode run "check diagnostics"

Plain OCMM_LSP_COMMAND values automatically receive the mcp argument. Use a JSON array, for example ["/path/to/ocmm-lsp","mcp"], only when you need exact argument control.

From source

pnpm install
pnpm run build

Then point your OpenCode config at the built plugin:

// opencode.json
{ "plugin": ["./node_modules/ocmm/dist/index.js"] }

Or use the ocmm shim binary (see below) to launch opencode with automatic plugin loading and config isolation.

Nix

Run ocmm without adding it to a profile, or build either primary package:

nix run github:hugefiver/ocmm
nix build github:hugefiver/ocmm#ocmm
nix build github:hugefiver/ocmm#ocmm-lsp

The default package and app wrap the nixpkgs OpenCode package, so the shim always has a known OpenCode executable. ocmm-unwrapped contains the plugin and native LSP only; OpenCode selection is then left to the CLI, configuration, environment, or PATH.

Unfree policy

The direct flake packages and apps carry only a narrow internal AAAPL allowUnfreePredicate allowance for ocmm's own derivations, so ordinary nix run github:hugefiver/ocmm does not need an ambient NIXPKGS_ALLOW_UNFREE. Because AAAPL is non-free, downstream overlay, factory, Home Manager, and NixOS consumers must configure the same narrow predicate in their own pkgs:

nixpkgs.config.allowUnfreePredicate = package:
builtins.elem (lib.getName package) [
"ocmm-lsp"
"ocmm-unwrapped"
"ocmm"
];

Overlay

Add the overlay to the package set that installs ocmm. This complete NixOS flake example keeps ocmm and the consumer on the same nixpkgs input and applies the narrow predicate before selecting pkgs.ocmm:

{
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
ocmm = {
url = "github:hugefiver/ocmm";
inputs.nixpkgs.follows = "nixpkgs";
};
};

outputs = inputs@{ nixpkgs, ... }: {
nixosConfigurations.example = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
modules = [
({ lib, pkgs, ... }: {
nixpkgs.config.allowUnfreePredicate = package:
builtins.elem (lib.getName package) [
"ocmm-lsp"
"ocmm-unwrapped"
"ocmm"
];
nixpkgs.overlays = [ inputs.ocmm.overlays.default ];
environment.systemPackages = [ pkgs.ocmm ];
system.stateVersion = "24.11";
})
];
};
};
}

Package factory

lib.mkOcmmPackage creates a wrapper around a chosen base ocmm package. Select either an OpenCode derivation:

inputs.ocmm.lib.mkOcmmPackage {
inherit pkgs;
opencodePackage = pkgs.opencode;
}

or an executable command:

inputs.ocmm.lib.mkOcmmPackage {
inherit pkgs;
opencodeCommand = "/opt/opencode/bin/opencode";
}

opencodePackage and opencodeCommand are mutually exclusive. Configure the narrow predicate above in the pkgs passed to the factory.

The shim resolves OpenCode in this exact order:

1. --opencode
2. non-empty OCMM_OPENCODE
3. ocmm.json or ocmm.jsonc shim.opencode
4. non-empty OCMM_NIX_OPENCODE
5. non-empty OCMM_PROGRAMS_OPENCODE
6. opencode from PATH

Home Manager

For standalone Home Manager, construct the pkgs passed to homeManagerConfiguration with the same narrow predicate. The configuration imports the default module and enables both programs:

{
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
home-manager.url = "github:nix-community/home-manager";
home-manager.inputs.nixpkgs.follows = "nixpkgs";
ocmm = {
url = "github:hugefiver/ocmm";
inputs.nixpkgs.follows = "nixpkgs";
};
};

outputs = inputs@{ nixpkgs, home-manager, ocmm, ... }:
let
system = "x86_64-linux";
lib = nixpkgs.lib;
pkgs = import nixpkgs {
inherit system;
config.allowUnfreePredicate = package:
builtins.elem (lib.getName package) [
"ocmm-lsp"
"ocmm-unwrapped"
"ocmm"
];
};
in {
homeConfigurations."user@example" = home-manager.lib.homeManagerConfiguration {
inherit pkgs;
modules = [
{
imports = [ ocmm.homeManagerModules.default ];
home.username = "user";
home.homeDirectory = "/home/user";
home.stateVersion = "24.11";
programs.ocmm.enable = true;
programs.opencode.enable = true;
}
];
};
};
}

When both programs are enabled and programs.opencode.package is non-null, the wrapper reuses that package and appends ocmm's store plugin path to the end of the existing OpenCode plugin list.

Both modules also accept programs.ocmm.opencode.command for an explicit OpenCode executable path or command name. programs.ocmm.opencode.package and programs.ocmm.opencode.command are mutually exclusive; in Home Manager, leaving both unset allows the module to reuse the enabled programs.opencode.package.

NixOS module

After configuring the same predicate in the NixOS package set, import the default NixOS module and set the OpenCode package explicitly:

{
imports = [ inputs.ocmm.nixosModules.default ];

programs.ocmm = {
enable = true;
opencode.package = pkgs.opencode;
};
}

The NixOS module installs only the package and wrapper. It never creates a service or user configuration.

CI cache

The repository's Nix workflow always uses a GitHub Actions Nix store cache. Cachix is optional: set the repository variable CACHIX_CACHE_NAME to enable it and the repository secret CACHIX_AUTH_TOKEN to authenticate writes. Without the variable, Cachix is not configured; without the token, it is read-only. Pull requests never receive the token, and only trusted pushes to master or manual workflow runs can use it to push.

Codex adapter

Recommended: custom source build and local marketplace

Run the following from the OCMM repository root, with Node.js 22 or newer and pnpm available. Install source dependencies with pnpm install if needed. Put your model, agent, and MCP choices in .codex/ocmm.jsonc (or .codex/ocmm.json). The generator checks that directory first, falling back to .opencode/ocmm.jsonc or .opencode/ocmm.json only when no Codex project config is found; .jsonc takes precedence over .json within either directory. Without a project config, it uses defaults.

The generator doesn't read user-global OCMM config or Codex's config.toml. Copy the OCMM settings you want into the project config before generating. Normal generation also includes the project's .mcp.json, so review generated MCP settings before sharing the bundle.

Build the TypeScript runtime, then call the existing generator API to keep your custom marketplace separate from the committed release bundle:

pnpm run build:ts
node --experimental-strip-types --input-type=module -e 'import { generateCodexPlugin } from "./src/codex/plugin-generator.ts"; await generateCodexPlugin({ pluginRoot: ".codex/local-plugin/plugins/deepwork", marketplacePath: ".codex/local-plugin/.agents/plugins/marketplace.json", projectAgentsRoot: false });'
codex plugin marketplace add ./.codex/local-plugin --json
codex plugin add deepwork@deepwork-local --json

build:ts supplies the plugin-local JavaScript wrappers. If you need to build the native LSP binary locally, use pnpm run build instead (requires Cargo) before generating; the generator copies available dist/bin/ binaries into the plugin. Don't assume a TypeScript-only build makes the cached plugin's default lsp MCP self-contained: without a bundled binary, provide an available ocmm-lsp on PATH or configure OCMM_LSP_COMMAND for the MCP.

The API call uses the same project-config loading as pnpm run gen:codex-plugin without --release. Its output is .codex/local-plugin/plugins/deepwork/, with the marketplace manifest under .codex/local-plugin/.agents/plugins/. projectAgentsRoot: false leaves .codex/agents/ untouched. It doesn't overwrite plugins/deepwork/ or the root .agents/plugins/marketplace.json. Treat .codex/local-plugin/ as generated local output, not a release bundle to commit.

If deepwork-local is already registered from another directory, inspect codex plugin marketplace list --json, then switch its source with the supported CLI commands:

codex plugin marketplace remove deepwork-local --json
codex plugin marketplace add ./.codex/local-plugin --json
codex plugin add deepwork@deepwork-local --json

If it already points to this same local source, there's no need to remove it each time. Regenerate in place and run the add commands above. Don't delete user configuration or edit Codex's plugin cache to switch sources.

Repository and release bundle generation

The repository-default output layout is:

.agents/plugins/marketplace.json
plugins/deepwork/
.codex-plugin/plugin.json
.mcp.json
package.json
agents/*.toml
dist/{cli,shared,bin}/
skills/*

pnpm run gen:codex-plugin reads project configuration and writes this repository-default layout, including .codex/agents/. The CLI has no output-directory option; use the API call above for isolated custom output.

Release generation uses source defaults and the bundled Codex model table, ignoring local OCMM config, profiles, and project .mcp.json:

pnpm run build:ts
pnpm run gen:codex-plugin --release

For a release, regenerate after the version bump and include the generated files in the same commit as that bump. Don't use --release to build your customized installation.

Install into an isolated Codex home for testing:

$env:CODEX_HOME = "$env:LOCALAPPDATA\Temp\codex\ocmm-test"
mkdir.exe -p $env:CODEX_HOME
codex plugin marketplace add ./.codex/local-plugin --json
codex plugin add deepwork@deepwork-local --json
codex plugin list --available --json

The Codex plugin exposes:

• copied ocmm shared skills plus flattened deepwork-* skills from skills/v1/;
• a deepwork skill that maps ocmm's planning/delegation semantics to Codex tools;
• plugin-scoped MCP servers generated from ocmm's MCP config, including the default lsp MCP served by the plugin-local ocmm-lsp wrapper;
• generated dw-* Codex agent TOML files under the generated plugin's agents/ directory for installers or local agent registration, including functional agents such as dw-oracle, dw-oracle-2nd, and dw-creative; configured review variants can also emit logical tier profiles such as dw-oracle-high and dw-oracle-2nd-low.

OpenCode still uses dist/index.js and its OpenCode hook surface. The Codex adapter does not import or mutate the OpenCode plugin module at runtime.

Configure

Drop a config file in either of these locations (project wins on conflicts):

• /.opencode/ocmm.jsonc
• ~/.config/opencode/ocmm.jsonc (all platforms, including Windows — follows opencode's convention)

Schema (Zod-validated; unknown object keys are stripped). Declared invalid fields fail direct schema parsing and are pruned locally by runtime loading so valid siblings and lower-priority values can survive. All fields optional:

{
"workflow": "v1", // OpenCode default

"disabledAgents": ["media-reader"],
"disabledSkills": ["debugging"],
"disabledCommands": ["ralph-loop"],
"disabledMcps": [],

"skills": {
"sources": [],
"enable": [],
"disable": []
},

// Opt in per provider before --fast / OCMM_FAST can promote a route.
"fastModels": {
"defaultRules": true,
"providers": ["openai"],
"mappings": {
"openai/": ""
},
// Rules are a fallback after model promotion. Later matches override earlier ones.
"rules": [
{
"match": { "provider": "openai" },
"options": { "telemetry": { "fast": true } }
},
{
"match": { "model": "gpt-5.*", "sdk": "@ai-sdk/openai" },
"options": { "serviceTier": "priority", "telemetry": { "sampled": true } }
},
{
"match": { "model": "gpt-5.*", "sdk": "@ai-sdk/openai-compatible" },
"options": { "service_tier": "priority", "telemetry": { "sampled": true } }
}
]
},

"agents": {
"reviewer": {
"model": "/",
"variant": "max",
},
"orchestrator": {
"reasoning": "high",
"models": [
"openai/gpt-5.6-sol:high",
{
"model": "anthropic/claude-sonnet-4-6:max",
"reasoning": "max",
"temperature": 0.2,
"top_p": 0.8,
"max_tokens": 8192
}
],
},
"builder": {
"requirement": {
"variant": "high",
"requiresProvider": [""],
"fallbackChain": [
{ "providers": [""], "model": "", "variant": "high" },
],
},
},
},

"categories": {
"hard-reasoning": {
"models": ["openai/gpt-5.6-sol:xhigh"],
},
},

"runtimeFallback": {
"enabled": true,
"dispatch": true,
"maxAttempts": 3,
"cooldownSeconds": 60,
"retryOnStatusCodes": [402, 429, 500, 502, 503, 504],
"retryOnPatterns": [
"rate.?limit",
"too.?many.?requests",
"usage.?quota.{0,20}?(?:exceeded|exhausted|reached)",
"quota.?exceeded",
"(?:exceeded|exhausted|reached).{0,20}?quota",
"free.?usage.{0,20}?(?:exceeded|exhausted|limit)",
"usage.?exceeded",
"(?:usage|quota)\\s+limit\\s+exhausted",
"exhausted\\s+your\\s+capacity",
"all\\s+credentials\\s+for\\s+model",
"cool(?:ing)?\\s+down",
"model.{0,20}?not.{0,10}?supported",
"model_not_supported",
"service.?unavailable",
"temporarily.?unavailable",
"overloaded",
"internal server error",
"gateway timeout",
"bad gateway",
"try\\s+again\\s+(?:later|shortly|in\\s+\\d+\\s*(?:seconds?|minutes?))",
"\\b429\\b",
"\\b503\\b",
"\\b529\\b",
"使用上限",
"频率限制",
"请求过于频繁",
"暂时不可用",
"服务不可用",
"请稍后重试",
],
"subagent429": {
"enabled": true,
"maxRetries": 5,
"providerScopes": {
"anthropic": "provider",
"openai": "model"
}
}
},

"subagent": {
"maxDepth": 3
},

"idleContinuation": {
"enabled": false,
"maxContinuations": 20,
"prompt": "Your todo list has unfinished items. Continue with the next pending or in-progress task. Do not ask for confirmation — proceed."
},

"mcp": {
"enabled": true,
"envAllowlist": ["EXA_API_KEY", "CONTEXT7_API_KEY"],
"websearch": { "provider": "exa" }, // "exa" or "tavily"
"servers": {
// Explicit entries override built-ins. Use this to replace or pin lsp.
// "lsp": { "type": "local", "command": "custom-lsp", "args": ["mcp"] }
}
},

"shim": {
"mode": "none", // none|inline|config-file|config-dir|xdg (default: none)
"configDir": "/custom", // target dir for config-dir/xdg modes
"configFile": "/path.json", // target file for config-file mode
"opencode": "/usr/local/bin/opencode",
"keepOmo": false,
"noProviders": false,
"noPlugins": false,
},

"registerBuiltinAgents": true,
"debug": false,
}

OpenCode host subagent depth compatibility

OpenCode commit 285d315b4e5355e0a94608acc0678a11b720079e added the top-level subagent_depth setting. Its implicit default is 1. ocmm's subagent.maxDepth default remains 3.

When both guards are active, the effective Task limit is the lower value. ocmm never copies its value into host config and never changes either default. If the host field is observable in the plugin config hook, OCMM_DEBUG=1 logs the host and local combination once: an info message when they agree, or a warn message that identifies the stricter guard when they differ. If ocmm's guard is disabled, the same debug setting logs an info message for the host-only limit.

An absent subagent_depth field does not identify the host version. It can mean an older host without the capability or a newer host using its implicit default of 1, and neither runtime case produces a compatibility log. On a newer host with the field omitted, the actual host limit is 1, the local limit is 3, and the effective limit is 1; this documentation is the only way to explain that case at runtime.

Both controls apply only to OpenCode task dispatches. ocmm does not classify a tool named execute as task, so neither depth guard applies to execute.

Canonical review-slot configuration

{
"agents": {
"oracle": {
"model": "openai/gpt-5.6-terra",
"variant": "xhigh",
"variants": {
"low": "high",
"high": "max",
"max": { "model": "openai/gpt-5.6-sol", "variant": "max" }
}
},
"oracle-2nd": {
"model": "anthropic/claude-opus-4-7",
"variant": "xhigh",
"variants": { "max": "max" }
},
"oracle-3rd": { "model": "google/gemini-3.1-pro" },
"reviewer": {
"model": "openai/gpt-5.6-sol",
"variants": { "high": { "variant": "max" } }
},
"planner": {
"variants": {
"low": { "model": "openai/gpt-5.5", "variant": "high" },
"high": "max",
"max": { "model": "openai/gpt-5.6-sol", "variant": "max" }
}
},
"plan-critic": {
"variants": {
"low": { "model": "openai/gpt-5.5", "variant": "low" },
"high": "xhigh",
"max": { "model": "openai/gpt-5.6-sol", "variant": "max" }
}
}
}
}

• Unsuffixed slot names (oracle, oracle-2nd, oracle-3rd, reviewer) mean logical normal tier.
• Logical tier (-low/-high/-max) and native provider model variant are separate controls.
• Review slots are priority order, not capability ranking.
• Slots oracle-3rd through oracle-9th require explicit config.
• Multiple configured review profiles do not fan out automatically; dispatch still uses one selected profile.
• reviewer has no ordinal slot naming.
• reviewer is primary-model or primary-lane self-review; Oracle slots are external-model cross-checks by default. Explicit user model configuration may remove that heterogeneity.
• Reviewer and Oracle profiles are reserved for software implementation acceptance or focused code-quality verification after an implementation diff exists, not research, ideation, architecture design, root-cause debugging, general-answer validation, or routine confidence.
• xhigh-equivalent review floors still apply even when a logical low tier is selected.
• Unsuffixed planner and plan-critic are their logical normal profiles. Their -low, -high, and -max suffix profiles are materialized only for explicitly configured variants; examples or generated files do not prove that a profile is currently callable.
• Before dispatching a planning role, inspect current callable/registered names and select the first available candidate: explicit cost/latency request uses low then normal; small/clear uses normal; complex/cross-module uses high then normal; security/performance/data-loss/release-safety/runtime-safety/critical-migration work uses max then high then normal. Never invent an absent suffix.
• Every generated planning tier inherits its canonical role's prompt, mode, permissions, registration policy, routing behavior, and receipt semantics. A tier changes the configured model route only.
• plan-critic-low may select a lower-cost or lower-latency model, but it is not lower-effort review: the xhigh-equivalent floor remains mandatory.
• agents.oracle-high is a deprecated config spelling migrated to agents.oracle-2nd, while runtime oracle-high remains the first-slot logical high tier.
• Alias/canonical collisions fail validation.
• schema.json and direct OcmmConfigSchema parsing remain strict. Runtime loadConfig() is tolerant: a schema-mismatched review field or entry is discarded locally while valid siblings and lower-priority values remain loaded. Only ambiguous alias/canonical migration collisions fall back to defaults.

Disabling review slots and interruption recovery

{
"disabledAgents": ["oracle-2nd", "oracle-high"],
"disabledHooks": ["subagent-interruption-recovery"]
}

• oracle-2nd disables that entire second review slot, including its logical tier profiles.
• oracle-high disables only the first-slot logical high tier profile; it does not disable oracle normal or other slots.
• subagent-interruption-recovery is optional evidence correlation + resume-note behavior layered on top of existing fallback flow.

Interruption recovery behavior:

1. Reuses the existing dedicated 429/generic fallback controller and retry budgets.
2. Keys correlation by child session and deduplicates parent message.part.updated evidence.
3. Treats child session.error as provider-error evidence.
4. Never retries explicit abort, permission denial, unknown agent, deletion, or ordinary empty output outcomes.
5. May append one manual continuation notice only when an explicit task identifier is observed in task input/output or correlated parent-part evidence; it never substitutes childSessionID for task_id, dispatches from tool.execute.after, or synthesizes a parent prompt.

Shorthand vs full form

Both agents.* and categories.* accept either shape:

models[0] is the primary model; the remaining entries are ordered runtime fallbacks. Internally, ocmm normalizes the array to the existing route/fallback chain. Direct model-source precedence is models → requirement chain → model plus fallbackModels → alias; chains are never merged. When models and requirement coexist, ocmm replaces only fallbackChain while preserving cloned requirement guards and defaults. Explicit top-level reasoning/variant overrides requirement defaults; per-entry fields remain local. provider_options is unsupported and, like other unknown object fields, is stripped before runtime. Legacy forms remain supported.

Hook defaults

disabledHooks in config controls which hooks are active. Default: ["directory-readme-injector"] — only the directory README injector is disabled out of the box; all other hooks are enabled. The full list:

Variant policy

variant is a routing hint, not a portable provider API. ocmm normalizes it by model family before writing chat.params:

History cache mitigation

historyCacheMitigation is disabled by default. It is an opt-in workaround for existing long OpenCode histories where large completed tool outputs were already persisted before OpenCode's native tool_output truncation limits were configured. It uses OpenCode's experimental.chat.messages.transform hook to truncate older completed tool outputs before history is converted to model messages, while preserving recent tool results intact.

{
"historyCacheMitigation": {
"enabled": false,
"models": ["gpt-5.6-sol"],
"maxToolOutputChars": 16000,
"preserveRecentToolResults": 24
}
}

Enable it explicitly with "historyCacheMitigation": { "enabled": true } only when native tool_output truncation and compaction pruning are insufficient for old long sessions. Increase preserveRecentToolResults or maxToolOutputChars if a workflow depends on large older tool outputs staying verbatim in model history.

Built-in agents

orchestrator    primary reasoning lane          variant=max     main coordinator
builder         implementation lane             variant=high    autonomous implementer
reviewer        primary review lane             xhigh floor     implementation self-review
oracle          review slot 1 (logical normal) xhigh floor     external-model cross-check
oracle-high     review slot 1 logical high     derived profile runtime tier profile (from variants)
oracle-2nd      review slot 2 (logical normal) xhigh floor     second-priority external cross-check
doc-search      lightweight lookup lane         (none)          external docs / OSS lookup
code-search     lightweight lookup lane         (none)          internal codebase grep
planner         primary reasoning lane          variant=max     work-plan author
clarifier       analysis lane                    (none)          pre-plan analysis
plan-critic     primary review lane             variant=xhigh   plan QA
media-reader    multimodal-capable lane         variant=high    multimodal analysis

Built-in categories (also registered as subagents)

frontend        UI/multimodal-capable lane   variant=high    UI/UX, layout, styling, visual QA
creative        creative-capable lane        variant=high    concepts, naming, narrative, framing
hard-reasoning  primary reasoning lane       variant=xhigh   ultrabrain-style decisions and tradeoffs
research        research-capable lane        variant=high    missing-fact investigation and evidence gathering
quick           lightweight lane             (none)          fully specified mechanical edits
coding          implementation lane          (none)          determined code edits and bug fixes
normal-task     implementation lane          (none)          ordinary bounded tasks
complex         coordinated-work lane        variant=high    coordinated multi-step ordinary tasks
deep            primary reasoning lane       variant=max     autonomous system development and delivery
documenting     prose-capable lane           (none)          standalone documentation and prose

Rows above describe built-in selection lanes, not required provider channels or model IDs. Example model names elsewhere in the repository are references only; explicit user configuration and the currently available model catalog decide the actual model. Agent rows show source defaults or enforced review floors; category rows show the raw source values from src/data/categories.ts. At runtime the variant policy normalizes categories from coding upward to model-appropriate max unless the user explicitly overrides them; see the variant policy table above. Entries marked (none) carry no built-in variant and rely on this normalization.

New GPT defaults use GPT-6.1 Sol for former Terra and high/xhigh Sol assignments, GPT-6 Astra for maximum-tier assignments, and GPT-6 Luna for lightweight lookup roles. Existing Astra heads remain Astra-first; GPT-5.5 and GPT-5.4 (including mini) remain compatibility fallbacks rather than new primary defaults. Runtime upgrades use only observed provider catalog keys in the declared lane: newer Astra versions such as 6.1/6.2 are eligible, but Sol, Luna, and unlabelled GPT models are not Astra successors. Provider tie order and fallback tuning are preserved.

Codex generation is offline: its confirmed-model table and project .codex/ocmm.jsonc are build inputs, not a live release monitor. Future Codex defaults require an explicit configuration/table update and regeneration; user-selected models are never globally migrated. This checkout's local Codex config was explicitly updated to GPT-6.1 Sol while retaining its variants and existing Astra/Luna selections. Codex preserves Sol/Luna low/medium effort in the new assignments, with the existing reviewer/Oracle/plan-critic xhigh floors still enforced.

The primary review structure is primary-model or primary-lane self-review through reviewer, plus external-model cross-checks through canonical Oracle slots (oracle, oracle-2nd, optional oracle-3rd ... oracle-9th when explicitly configured). Runtime logical tier names such as oracle-high and oracle-max are derived from configured variants and stay within slot 1; they are not separate slot registrations. oracle is the first external cross-check slot and shares implementation-review semantics via promptSource: "reviewer"; oracle-2nd is the second-priority external slot. Explicit user model configuration remains authoritative and may remove model heterogeneity. agents.oracle-high is a deprecated config spelling migrated to agents.oracle-2nd during config load so legacy config keeps working while canonical keys remain slot-based. Supporting utility agents (builder, doc-search, code-search, media-reader) still use the workflow/model-family deepwork prompt without an additional role prompt. builder is registered with mode:"primary"; planner is registered with mode:"all" so it can be selected directly and used as a delegated task agent. Each category has a prompt under prompts//category/.md that is set as the category-subagent's system prompt. Callers invoke categories via task(category="deep", ...) or direct subagent names such as @deep and @quick. The upstream-style compatibility alias @explore maps to local code-search; @oracle selects the independent local oracle agent rather than aliasing reviewer.

Category model-availability diagnostics

With OCMM_DEBUG=1, the config hook emits one deduplicated availability diagnostic for each successfully registered built-in or custom category and each distinct observed diagnostic state. Every message includes the category name, requirement/primary provenance, selected model, candidate summaries, and routePreserved=true.

These diagnostics are read-only. target.provider[*].models is observation evidence, not proof of credentials or runtime access, and catalog absence never disables a category. A dead or unknown category remains registered; diagnostics do not change selected primaries, catalog upgrades, provider defaults, canonical models[], effective-route snapshots, or runtime fallback. Messages contain provider IDs and model keys only—never provider options, API keys, URLs, response bodies, or the full host config. The existing logger keeps all of this output silent unless OCMM_DEBUG is enabled.

Prompt architecture

OpenCode sources and the independent Codex adapter are organized separately:

prompts/
v1/                               # OpenCode deepwork prompts
deepwork/{default,gpt,claude-opus-5,gemini,gemini-4,glm,codex,planner,kimi,swe-2}.md
agents/{orchestrator,reviewer,planner,clarifier,plan-critic}.md
category/*.md (11 sources; 10 default categories, cross-cutting opt-in)
codex/                            # Codex adapter sources
deepwork/ agents/ category/
skills/
ast-grep/                          # shared skills registered as OpenCode skills + slash commands
coding-agent-sessions/             # local session-history finder shared skill
debugging/
frontend/
git-master/
init-deep/
v1/                               # forked superpowers skills (v1 only)
brainstorming/SKILL.md
writing-plans/SKILL.md
subagent-driven-development/SKILL.md
requesting-code-review/SKILL.md
receiving-code-review/SKILL.md

Model-family variant selection (pickDeepworkVariantForAgent):

• planner agent -> planner.md
• GPT family -> gpt.md
• Gemini family -> gemini.md
• GLM family -> glm.md
• Codex family -> codex.md
• others (Claude/Kimi/Minimax/unknown) -> default.md

Variant is selected at config time using the final selected agent model after explicit user configuration, inherited aliases, and catalog-confirmed upgrades are considered. Built-in functional agents compose their authoritative agents/.md role before subordinate workflow/model calibration. Each adapter's deepwork/gpt.md is the sole GPT/Codex behavioral calibration, applied once to detected GPT/Codex models, including planners and categories. Planner retains its planning doctrine; codex.md contains only host tool compatibility. Category roles remain authoritative, with no Astra-only inline addenda. Opus calibration remains orchestrator-only. Kimi uses one current-generation calibration shared across Kimi names; Gemini 4.x receives the guarded gemini-4 layer, and SWE-2 retains its own layer. These prompt selections do not change provider, effort, or model routing. Explicit prompt overrides retain priority.

Codex profiles carry one guarded shared GPT layer ahead of runtime selection: GPT/Codex-family models apply it, non-GPT models ignore it without ignoring their role, planner, embedded skills, or adapter tool instructions. GPT generations share prompt behavior, not parameter capabilities: runtime model detection, native max support, effort translation, and review floors remain model-dependent. Generated profiles are refreshed only through the generator. Prompts are attached declaratively, not selected by conversation keywords.

For OpenCode, a short brainstorming orientation is injected on the first message per session via chat.message (queue) + system.transform (prepend). Full brainstorming guidance is loaded only when needed through the skill catalog or /brainstorming. Codex profiles embed the short orientation and expose the full deepwork-brainstorming skill on demand. Role, safety, authorization, and workflow rules remain authoritative without loading the full skill.

Slash Commands

ocmm registers OpenCode config.command entries for:

• Shared skills under skills/, available as /git-master, /ast-grep, /coding-agent-sessions, /frontend, /debugging, and /init-deep by default.
• On-demand deepwork skills when workflow:"v1" is active, available as /brainstorming, /writing-plans, /subagent-driven-development, /requesting-code-review, and /receiving-code-review. In v1, ocmm also adds skills/v1 to OpenCode skill paths so native skill slash resolution works without "skill not found" noise.
• Loop protocol commands /ralph-loop, /audit-loop, and /dwloop (/dwloop is the deepwork-loop alias for /audit-loop).

Interactive OpenCode uses its native slash-command parser. For noninteractive opencode run "/command args" calls, OpenCode 1.17.9 passes the first message directly and does not parse project commands; ocmm compensates by expanding bare ocmm command text during chat.message and injecting the expanded command once through system.transform.

The loop commands are command-template entry points only. They explicitly tell the model to run the loop in the current session and not claim hidden auto-continuation. The Ralph Loop runtime and related hooks are tracked as follow-up work in docs/kb/omo-features/loops.md.

ocmm does not ship a separate /lsp-setup command. OpenCode already provides LSP setup guidance, while ocmm's responsibility is to register and distribute the default lsp MCP backed by ocmm-lsp. Configure external language servers through .opencode/ocmm-lsp.json, .opencode/lsp.json, or .codex/lsp-client.json when overrides are needed.

Coding-agent session search

/coding-agent-sessions searches local coding-agent session stores, including Aside, through its bundled finder. It supports JSON list, search/find, and get/read output with child-session linkage; it reads local stores only and implies no network request. Runtime needs Python 3.11+ and the standard library only; the source retains pytest development tests, but they are not distributed.

Use explicit platform and root constraints when reading history. Omitting either broadens known-store discovery and may inspect local session history:

$sessionRoot = "C:\exports\coding-agent-session-fixture"
python skills/coding-agent-sessions/scripts/find-agent-sessions.py find "ambassador" --platform aside --root "$sessionRoot"

The imported subtree has its separate license in skills/coding-agent-sessions/LICENSE-UPSTREAM.md.

Profiles

A profile is a named partial overlay on the base config. It can override any top-level field (agents, categories, runtimeFallback, subagent, debug, etc.) except profiles and activeProfile themselves. At load time, after merging user + project configs, the active profile is deep-merged over the result — profile wins over both.

Selecting a profile

Ambient selection remains, in priority order: OCMM_NO_PROFILE, then OCMM_PROFILE, then config activeProfile.

1. OCMM_NO_PROFILE=1 or OCMM_NO_PROFILE=true disables profile selection for that process.
2. OCMM_PROFILE env var selects a profile for the shell without persisting it:

OCMM_PROFILE=gpu opencode run "..."

Empty string is treated as unset — falls back to the config's activeProfile.

3. activeProfile in the config file is the persisted fallback:

{ "activeProfile": "gpu" }

If the named profile doesn't exist, the OpenCode plugin facade warns and preserves the base config.

OpenCode plugin profile facade and qualified aliases

Directory profile descriptors and qualified aliases are an OpenCode plugin facade feature. Only loadOpenCodePluginConfig materializes them; ordinary programmatic loadConfig calls — including loadConfig({ host: "opencode" }) — and the Codex adapter remain non-materializing.

For each profile name, descriptor precedence is inline profiles. < user ocmm-profiles/ directory < project .opencode/ocmm-profiles/ directory. When both extensions exist for one basename, .jsonc wins before parsing. An invalid inactive descriptor is inert. An invalid selected descriptor at higher precedence makes the plugin atomically use defaults; it does not fall through to a lower-precedence descriptor.

An alias containing a colon uses first-colon grammar, :. For example, a base agent can import the reviewer requirement from the precision profile while retaining its own behavior:

{
"agents": {
"oracle": {
"alias": "precision:reviewer",
"description": "Local Oracle behavior remains local",
"promptAppend": "Use this role's local review instructions."
}
}
}

The import is requirement-only: it copies the normalized ModelRequirement — fallbackChain; its requirement-level native variant; each fallback entry's providers, model, native variant, and model-control metadata; and requiresModel, requiresAnyModel, and requiresProvider. Agent-level logical review variants remain local and are not imported. Permissions, prompts, tools, description, other agent controls, and profile-wide fields also stay on the source agent.

When a profile agent specifies alias without a direct model, models, fallbackModels, or requirement, the alias replaces inherited model selectors and inherited requirement-level reasoning/variant from the base agent. An explicit reasoning or variant beside the alias overrides the imported requirement default (reasoning wins when both are present); entry-local controls inside the imported fallback chain remain unchanged. Other inherited and profile-local controls remain merged normally. If the same profile agent explicitly supplies both an alias and a direct selector, the existing direct-selector precedence is preserved and the alias is not materialized.

Profile merge semantics