opencode-model-alias

⚠️ DEPRECATED — do not port, do not revive

This plugin does not work on OpenCode V2 and cannot be ported. It has been removed from the OpenCode config and ~/.config/opencode/model-aliases.json has been deleted. The repository is kept for history only. See Deprecation notice below before touching anything.

Note: This project is not built by the OpenCode team and is not affiliated with OpenCode in any way.

OpenCode plugin that allowed users to define model aliases for consistent use across machines. Superseded by native OpenCode V2 mechanisms.

Deprecation notice

What this repo was for

Per-machine model selection with a shared dotfiles config. The goal was never plain model refs (V2 has always supported those) — it was indirection: a single name committed to shared config that resolves to a different model on each machine, so the same opencode.jsonc works everywhere without per-PC edits.

Why the plugin can't do it under V2

• Bare aliases are rejected before any plugin runs. V2's config schema (Config.ModelSelection) requires model refs to match ^[^/#]+\/[^#]+(?:#[^#]+)?$, so an alias name like git-model fails decode and never reaches plugin code. Verified: git-model FAILs, kiro-cli/qwen3-coder-next passes.
• ctx.agent.transform can't see the right agents. The documented V2 replacement for the old config hook only exposes the ~7 built-in agents. Config- and markdown-defined agents (the ones that actually use aliases) are invisible to its editor. Verified via a spike: a probe agent ran but never appeared in editor.list() and fell back to the default model.
• ctx.model.transform can't help either. ModelEditor.update cannot create an unavailable provider, so a synthetic alias/ provider is impossible.

The native replacement (this is the important part)

Per-machine model selection is done with config variable substitution — no plugin needed. Put the model reference on the agent in config (not markdown frontmatter), pointing at a machine-local file:

// shared config, identical on every machine (e.g. dotfiles opencode.jsonc)
"agent": {
  "git-agent": { "model": "{file:~/.config/opencode/git-model}" }
}

# machine-local, NOT synced — set per PC. printf avoids a trailing newline,
# which would break the model-ref regex.
printf 'kiro-cli/qwen3-coder-next' > ~/.config/opencode/git-model

Each machine writes whatever model it wants into its own git-model file; the shared config stays byte-identical everywhere. Verified end-to-end 2026-09-18: with the model removed from git-agent.md frontmatter and set only via the {file:} config override, git-agent streamed the file's model (kiro-cli/qwen3-coder-next), confirming the config override reaches a markdown-defined agent and that ~ expands in {file:} paths.

Gotchas:

• The model must be set in config (agent.<name>.model), not in agent markdown frontmatter — {file:} / {env:} are not substituted in frontmatter and the agent fails to load entirely (Agent not found).
• A missing or malformed machine-local file yields an empty string → an invalid model ref → a silent fallback to the default model, with no error. This is the same failure mode that ran git-agent on the wrong model unnoticed for a day. Add a loud check if that matters to you.

---

The original documentation below is retained for historical reference only. None of it applies under OpenCode V2.

Installation

Clone the repo to a local workspace:

git clone https://github.com/mattaschmann/opencode-model-alias.git ~/workspace/opencode-model-alias

Then add the plugin to your OpenCode config (opencode.jsonc):

{
  "plugin": ["~/workspace/opencode-model-alias"]
}

Why This Plugin?

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.

The Problem

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.

The Solution

With model aliases, you can use a consistent identifier across machines:

1. In your shared config: Use the alias

   {
     "command": {
       "my-command": {
         "model": "cheap"
       }
     }
   }

2. 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.

Usage

The /alias Command

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 models

Tip: 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.

Using Aliases

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.

Alias File Location

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"
}

References

• OpenCode Plugins Documentation
• GitHub Issue #3439

Credit/Inspirations

• https://gist.github.com/krystofrezac/7f16ba252279f889eb750a866b257a1d
• https://github.com/toninho09/opencode-usage