Note: This project is not built by the OpenCode team and is not affiliated with OpenCode in any way.
OpenCode plugin that allows users to define model aliases for consistent use across machines.
Add the plugin to your OpenCode config:
{
"plugin": ["opencode-model-alias"]
}OpenCode automatically installs npm plugins using Bun at startup.
When you create custom skills, agents, or commands in OpenCode, you can specify which model to use. However, sharing these configurations across multiple computers is problematic because each machine may use different models.
Imagine you have a custom command that uses GPT-4o Mini for cost efficiency:
{
"command": {
"my-command": {
"model": "openai/gpt-4o-mini"
}
}
}If you share this command with a colleague who uses Anthropic, or if you switch to a different provider on another computer, you need to manually update the model in your config. This becomes tedious and error-prone as you accumulate more commands.
With model aliases, you can use a consistent identifier across machines:
-
In your shared config: Use the alias
{ "command": { "my-command": { "model": "cheap" } } } -
On each machine: Define the alias in
~/.config/opencode/model-aliases.json{ "cheap": "openai/gpt-4o-mini" }
Now your command configuration is portable, and each computer maps "cheap" to whatever model that machine prefers.
Manage model aliases directly from OpenCode:
# List all aliases
/alias list
# Set a new alias
/alias set cheap openai/gpt-4o-mini
# Delete an alias
/alias delete cheap
# Show help
/alias help
# Show available models in correct format
!opencode modelsTip: type !opencode models in the TUI to list the currently available models in the correct provider/model format.
Important: Restart OpenCode after adding, updating, or deleting aliases so the new mappings load into your session.
In your OpenCode config (e.g., ~/.config/opencode/opencode.json):
{
"agent": {
"my-agent": {
"model": "cheap"
}
},
"command": {
"my-command": {
"model": "expensive"
}
}
}Or in markdown format:
---
description: Some agent
mode: subagent
model: cheap
---The plugin automatically resolves these aliases by looking up the model in your alias file.
Aliases are stored in ~/.config/opencode/model-aliases.json. The plugin auto-creates this file with an empty object {} if it doesn't exist.
Example model-aliases.json:
{
"cheap": "openai/gpt-4o-mini",
"expensive": "openai/gpt-4o",
"claude": "anthropic/claude-sonnet-4-20250514"
}