ModelDeck

Switch model profiles for OpenCode agents.

Define model settings once, then switch between providers such as OpenAI and Anthropic with one profile name.

Quick start

1. Enable the plugin

Add ModelDeck to your OpenCode config:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-modeldeck"]
}

If another plugin defines the agents you want to change, list it before opencode-modeldeck.

2. Create a config

Create .opencode/modeldeck.jsonc in your project, or create the global file ~/.config/opencode/modeldeck.jsonc:

{
  "$schema": "https://unpkg.com/opencode-modeldeck/schema.json",
  "activeProfile": "openai",
  "profiles": {
    "openai": {
      "agents": {
        "oracle": {
          "model": "openai/gpt-5.6-sol",
          "variant": "medium"
        }
      }
    },
    "anthropic": {
      "agents": {
        "oracle": {
          "model": "anthropic/claude-opus-4-6"
        }
      }
    }
  }
}

Replace oracle with an agent that already exists in your OpenCode setup. ModelDeck changes existing agents; it does not create them.

3. Start OpenCode

Restart OpenCode after changing ModelDeck configuration. Only agents listed in the active profile are changed; all other agents keep their current settings.

Switch profiles

Install the CLI if you want a convenient command for switching profiles:

npm install -g opencode-modeldeck

Then use:

modeldeck list
modeldeck current
modeldeck doctor
modeldeck use anthropic

Check which installed CLI version your shell is using:

modeldeck --version

modeldeck use saves the selected profile as activeProfile in your config file. Without --config, it updates the project config when one exists; otherwise it updates the global config. The change applies to future OpenCode sessions:

modeldeck use openai
modeldeck use anthropic

To update a specific config file, use --config:

modeldeck use anthropic --config ./config/modeldeck.jsonc

Without the CLI, set a profile for one OpenCode process with:

OPENCODE_MODELDECK_PROFILE=anthropic opencode

Check configuration

Run modeldeck doctor to validate the discovered configuration and selected profile. It reports the active profile, inheritance chain, affected agent count, and config files used:

modeldeck doctor
modeldeck doctor --config ./config/modeldeck.jsonc

To validate ModelDeck before starting OpenCode in a shell script or CI job:

modeldeck doctor && opencode

Configuration

ModelDeck automatically looks for these files in order:

1. ~/.config/opencode/modeldeck.jsonc
2. .opencode/modeldeck.jsonc

Project settings override global settings. An agent entry from the project replaces the complete entry from the global config.

Use environment variables to override the config file or selected profile:

OPENCODE_MODELDECK_CONFIG=./config/modeldeck.jsonc opencode

Relative config paths are resolved from the current OpenCode worktree. An explicit config path disables automatic global/project discovery. Models use the provider/model format, such as openai/gpt-5.4-mini.

Inheritance

A profile can extend one parent and replace selected agents:

{
  "profiles": {
    "openai-high": {
      "extends": "openai",
      "agents": {
        "oracle": {
          "model": "openai/gpt-5.6-sol",
          "variant": "high"
        }
      }
    }
  }
}

Inheritance can span multiple levels. A child entry replaces the whole parent entry, so omitting variant removes the previous variant.

Troubleshooting

• ModelDeck displays a TUI error notification and writes an error log when its configuration cannot be loaded. Run opencode --print-logs for the full log.
• No modeldeck.jsonc found: create a global or project config file.
• Profile not found: check activeProfile or the profile passed to use.
• Missing OpenCode agents are skipped so other agents in the profile can still be applied. ModelDeck shows a warning notification and writes the skipped names to the log. Enable the agent or remove it from the profile to clear the warning.
• Invalid JSONC or schema errors: check the file syntax and model format.

Development

make install
make verify

Publish to npm

Make sure you are logged in to npm and update the package version before each release:

npm login
npm version patch
make pack
make publish

Use npm version minor or npm version major when appropriate. make pack previews the package contents, while make publish runs the checks, tests, and build before uploading it. If npm asks for a one-time password, enter the OTP from your authenticator. You can also pass it explicitly:

NPM_OTP=123456 make publish

License

MIT