Getting started
Install the Claude Code CLI, add one line to opencode's config, relaunch.
1. Install and log in the Claude Code CLI
The plugin drives an existing Claude Code CLI; it does not bundle one. Check that claude is on your $PATH and authenticated:
claude --version # e.g. 2.1.263 (Claude Code)claude auth status # which account you are signed in asclaude auth login # run this if you are not signed in yetlogin, status and logout are the claude auth subcommands as of 2.1.263. Run claude auth --help if your install differs.
2. Add the plugin to your opencode config
opencode 1.x and 2.x both read a global config at ~/.config/opencode/opencode.json (or $XDG_CONFIG_HOME/opencode/ when that is set). A project-level opencode.json in your repo overrides the global one, and OPENCODE_CONFIG=/path/to/config.json points opencode at one specific file instead. Put the plugin in the global config so every project gets it:
{ "plugin": ["@khalilgharbaoui/opencode-claude-code-plugin"]}That package spec is the whole install. Do not npm install the package yourself: opencode resolves and caches plugin packages on its own. You do not need a provider block either, unless you want to change one of the options.
opencode 2 reads that plugin key too, and its native spelling is plugins. On opencode 2 you can also let opencode write the entry and install the package in one step:
opencode plugin add @khalilgharbaoui/opencode-claude-code-pluginOn opencode 1.x, add the same spec to ~/.config/opencode/tui.json as well, to get the Subagents section in the sidebar: opencode 1 loads TUI plugins from that file’s plugin array, not from opencode.json’s. opencode 2 needs nothing extra.
{ "plugin": ["@khalilgharbaoui/opencode-claude-code-plugin"]}3. Restart opencode and verify
Quit opencode fully and relaunch it: plugins are loaded once, at process start, so a reload is not enough.
In the model picker you should now see a provider called Claude Code holding entries such as Claude Haiku 4.5 (1×), Claude Sonnet 5.5 (2×) and Claude Opus 5 (5×). opencode 1.x has no name to show for it and labels it with its id, claude-code. The (N×) suffix is each model’s list price relative to Haiku; see Models. Pick one and send a message.
A model’s full id is the provider id, a slash and the model id, so you can also check from a terminal without opening the picker:
opencode run -m claude-code/claude-haiku-5-5 "reply with ok"opencode models | grep claude-codeWith accounts configured there is one provider per account instead, named after it (Claude Code (Default, Max 20x), Claude Code (Work)), and the ids become claude-code-default/<model> and claude-code-<name>/<model>.
opencode plugin list is not a check: on opencode 2.1.4 it prints No plugins found even while this plugin is loaded. /claude-code-doctor in a session, or opencode models | grep claude-code, is.
If the provider does not appear, if the models are there but a message fails, or if a version you just upgraded to is missing, go to Troubleshooting. It is keyed on the first thing you see and names one check per symptom.
Building from a checkout instead? See Development.
Free and MIT-licensed, made by @khalilgharbaoui. If the plugin saves you time, you can buy its maintainer a coffee.
