Claude Code is the provider.

Project numbers

• 85GitHub starsapi.github.com
• 6,675npm downloads, last 30 daysapi.npmjs.org
• 23,476npm downloads since 2026-04-25api.npmjs.org
• 1,078tests in the suitenpm test, this build
• 107tagged releasesapi.github.com
• 16contributorsapi.github.com
• 25forksapi.github.com
• 18Claude models registeredsrc/models.ts

Read at build time from the GitHub REST API and api.npmjs.org; nothing is requested from your browser. Rebuilt daily. This build: 2026-10-02.

what it does

One claude process per conversation, with opencode in charge of the machine.

The plugin spawns the official CLI headless, streams its output into opencode, and routes the tools that touch your files and shell back to opencode. Nothing in between holds a credential.

1. 01auth

   Your CLI's login, untouched

   The official claude binary authenticates: a subscription login, an API key, Bedrock or Vertex. The plugin never reads, stores or replays a token, so there is nothing here to lift.

   Which login bills what

2. 02tools

   opencode runs the tools

   Bash, Edit, Write, WebFetch and Task are proxied by default. Claude calls an in-process MCP tool and opencode executes it, behind its own permission prompts and audit log.

   "proxyTools": ["Bash", "Edit", "Write", "WebFetch", "Task"]Read more

3. 03claude

   Claude's own tools, MCP servers and skills

   Read, Grep, Glob and WebSearch run inside Claude Code. opencode's MCP servers are bridged into the spawn, and opencode's skills can be staged for Claude's native Skill tool.

   Read more

4. 04accounts

   Several accounts, with failover

   Declare accounts once and each becomes its own provider with its own CLAUDE_CONFIG_DIR. When one runs out of usage mid-task, opencode's question form offers the others. Nothing moves until you pick.

   "accounts": ["personal", "work"]Read more

5. 05subagents

   Your account, their model

   An agent file can pin forceModel, reasoningEffort and cacheTtl while inheriting the caller's account. task_batch dispatches several subagents at once, because the CLI serialises MCP calls.

   forceModel: claude-haiku-4-5Read more

6. 06hosts

   One package, opencode 1.x and 2.x

   The default export carries both entrypoints and the same config works on both majors. opencode 2's tool vocabulary (shell, subagent) is translated per model, never process-wide.

   Read more

Also in the box: /btw side questions on the live process, /claude-code-doctor with a redacted bundle for bug reports, a read-only permission preset, 18 registered models with reasoning variants and fast mode, and a fallback model chain.

why the CLI and not the API

The three objections, answered with what is measured.

“Just use the API.”

The API is pay as you go on a Platform key. This plugin inherits whatever the claude CLI already holds, so a subscription login runs on the plan's usage limits, and an API key, Bedrock or Vertex login bills exactly as that CLI would. The CLI reports which one is in effect on every session (apiKeySource), and the plugin warns when a stray ANTHROPIC_API_KEY would move the bill.

Billing: what a turn draws from

“Is this allowed? How is it billed?”

The official client does the authenticating, and driving claude is what claude is for. Proxy and token-reuse plugins lift the OAuth session out of the client, which Anthropic disallowed for third-party use in February 2026; this plugin cannot do that, structurally. Headless --print usage on a subscription draws from the plan's ordinary limits, per Anthropic's own page, which the docs link and date rather than paraphrase.

How this compares, with every claim sourced

“A CLI wrapper must be flaky.”

It is engineered like a transport, not a shell-out. An abort sends the CLI an interrupt. A proxied call ends on an event, never on a clock. Two watchdogs cover a child that is alive but wedged, and a child that dies without a result is an error, never a silent stop. The suite is 1,078 tests, a dozen of whose files drive a fake CLI through real turns, and every rule in AGENTS.md cites the measurement that produced it.

Internals: how a turn works

quickstart

Three steps. The second one is a single line.

1. Install and log in the Claude Code CLI. The plugin drives an existing claude; it does not bundle one.

   claude --version      # e.g. 2.1.284 (Claude Code)
   claude auth status    # which account you are signed in as
   claude auth login     # only if you are not signed in yet

2. Add the package to opencode’s global config. That spec is the whole install: opencode resolves and caches plugin packages itself, so do not npm install it.

   ~/.config/opencode/opencode.json

   {
     "plugin": ["@khalilgharbaoui/opencode-claude-code-plugin"]
   }

3. Quit opencode fully and relaunch. Plugins load once, at process start. The model picker now has a Claude Code (Default) provider with entries such as Claude Sonnet 5.5 (2×) and Claude Opus 5 (5×); the suffix is each model’s list price relative to Haiku.

Something missing from the picker? Troubleshooting is keyed on the first thing you see, and /claude-code-doctor in any session prints what the plugin thinks is happening without calling a model.

built from measurements

Every rule was learned from a measurement, and says so.

The project's engineering file does not contain opinions. Each rule names the probe, the version and the number that produced it, and the test that keeps it true.

1,078tests, across 62 files

A dozen of those files drive a fake claude through a real turn: the stream parser, the proxy broker, the watchdogs, abort, respawn, account failover and the model fallback chain are exercised end to end, not mocked at the edge. Two runtime dependencies in total.

How the suite is built

measuredevery rule in AGENTS.md cites the evidence that produced it

A finish's usage is context occupancy to opencode, so its input side is the turn's LAST real API call, never result.usage, which sums every call: a 14-call turn at 180K real context reported 2,050,806 cache read and opencode auto-compacted.

AGENTS.md, Tools and streaming (h #g169). Kept true by test-context-usage.ts.

Read the rulebook

16contributors, with authorship preserved

• @broskeestask_batch, the skill bridge, the usage fix that stopped early auto-compaction
• @jknlsnper-tool proxy timeouts, subagent dispatch steering, the question proxy
• @galvaniper-session working directory for opencode serve
• @willmcginnisauthentication on the proxy MCP endpoint
• @acastro2the opencode 2 tool-result name fix
• @bangnh1opencode 2's MCP config layout and Code Mode proxying

Everyone, with what they built

how this compares

Three ways to reach Claude from opencode. They are not interchangeable.

Where a cell names what another project does, the full comparison page quotes that project's own README.

	opencode’s native anthropic provider	This plugin	Proxy and token-reuse plugins
Authentication	An Anthropic Platform API key in opencode’s auth store.	Whatever the official claude CLI holds: a subscription login, an API key, Bedrock or Vertex. No token is read, stored or replayed.	The Claude OAuth session, lifted out of the official client and refreshed by the plugin itself.
What is billed	Pay as you go on the key’s Platform account.	Whatever the CLI’s own login bills: plan usage limits on a subscription, pay as you go on a key. The CLI’s apiKeySource says which, on every session.	The subscription the reused session belongs to.
Terms of service	The ordinary API route. Nothing unusual about it.	Sanctioned: the official client does the authenticating, and driving claude is what claude is for.	Disallowed. Anthropic disallowed reusing subscription authentication for third-party Claude use in February 2026, and each of those projects carries its own disclaimer.
Who runs Bash, Edit, Write	opencode, behind its permission prompts.	opencode, behind its permission prompts: those tools are proxied by default. Read, Grep and Glob run inside Claude Code.	opencode.
Claude Code’s tools, MCP servers, skills	Not involved: opencode’s own tools only.	Claude’s built-ins run in Claude Code, opencode’s MCP servers are bridged in, opencode’s skills can be staged for Claude’s Skill tool.	Not involved: the model call is an ordinary API call.
What it costs you	Baseline.	A claude child per conversation (about 250 MB idle) under a cap of 16, a local keyword title instead of a model-written one, and Claude Code’s own compaction happening behind opencode’s back.	One more moving part between you and Anthropic, plus the account risk in the terms row.

The full comparison has nine rows, names the projects in the third column, and links the policy sources with the date they were last read.

add it

One line in opencode.json.

~/.config/opencode/opencode.json

{
  "plugin": ["@khalilgharbaoui/opencode-claude-code-plugin"]
}

Get startedRead the comparisonOn npm