opencode-with-claude: run OpenCode against a Claude Max or Pro subscription

What opencode-with-claude actually solves

OpenCode is a terminal and web coding agent. A Claude Max or Pro subscription is billed through Anthropic's consumer plans, not through an API key you paste into a config file. The README describes the gap plainly: the plugin exists so you can "Use OpenCode with your Claude Max subscription." Something has to sit between the two and translate OpenCode's Anthropic provider calls into whatever the subscription accepts. That something is Meridian, described in the README as "formerly opencode-claude-max-proxy."

Meridian is a local HTTP proxy. You could run it yourself as a CLI or a Docker container. The plugin's pitch is lifecycle ownership: "start OpenCode once and the proxy comes up with it; quit OpenCode and the proxy stops." The audience is individual developers on a Max or Pro plan who want OpenCode's TUI and do not want a second terminal window. It is not aimed at teams provisioning API keys, and it is not a way to get Claude access for free.

The proxy lifecycle and why each window gets its own port

The README's diagram shows OpenCode on the left, a local proxy in the middle, and Anthropic on the right. OpenCode speaks to the proxy over HTTP, the proxy speaks to Anthropic through the Claude Agent SDK. The plugin hooks into OpenCode's plugin system, starts the proxy on launch, configures the Anthropic provider, and cleans up on exit.

The interesting design choice is per-instance ports. The README states each OpenCode instance "gets its own proxy on an OS-assigned port, so ports do not collide and you avoid session issues from sharing one proxy across instances." The diagram labels the default as `:3456 / auto`, and the config example hardcodes `http://127.0.0.1:3456`. So the fixed port in the sample config is the simple path, while the auto-assignment is what protects you when you open several windows. If you run multiple instances and pin a manual port, you are opting out of the feature that makes multiple instances safe.

The second mechanism is session attribution. The README says the plugin "adds session tracking on outgoing API calls, so the proxy does not have to infer sessions from fingerprints alone." That is a real difference from running Meridian bare: explicit headers beat fingerprint guessing when several conversations are in flight.

Installing opencode-with-claude and getting one request through

Install the plugin globally with npm, or use the Homebrew tap if you prefer `brew upgrade` to `npm update -g`:

npm install -g opencode-with-claude

The plugin shells out to the Claude Code CLI for authentication, so that has to be present and logged in before anything works:

npm install -g @anthropic-ai/claude-code
claude auth login

`claude auth login` opens a browser for OAuth. According to the troubleshooting section, an unauthenticated state surfaces as "Claude not authenticated," and a missing CLI surfaces as "Claude Code CLI not found."

Next, register the plugin and point the Anthropic provider at the proxy. The README gives this example for `~/.config/opencode/opencode.json` or a project-level file:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-with-claude"],
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "http://127.0.0.1:3456",
        "apiKey": "dummy"
      }
    }
  }
}

The `apiKey` value is literally `dummy`; the real credential lives in the Claude Code login, not in this file. Then run `opencode` and send a prompt. The plugin prints the proxy URL at startup, which is also the address you would use to call `POST /profiles/active` later.

Homebrew users are told to point the `plugin` entry at an installed file path instead of the package name, because the path is stable across upgrades and `brew info opencode-with-claude` prints it. That is a macOS and Linux path detail people miss on first install.

Profiles, SDK features and the files Meridian already reads

The plugin does not invent its own configuration format. It reads the same Meridian files the `meridian` CLI uses, which means an existing Meridian setup carries over. Profiles live in `~/.config/meridian/profiles.json` and take a `claudeConfigDir` for a normal account or `type: "oauth-token"` with an `oauthToken` for a headless one. The active profile is a single key in `~/.config/meridian/settings.json`:

{ "activeProfile": "work" }

That selection applies to any request without an explicit `x-meridian-profile` header. If the saved id is missing from `profiles.json`, the README says the plugin logs a warning and falls back to the first configured profile. Silent fallback to the wrong account is the failure mode worth knowing about, and the warning is the only signal you get.

SDK behaviour is tuned in `~/.config/meridian/sdk-features.json`, which Meridian reads lazily on every request, so edits apply without restarting the proxy. The README's example sets `memory`, `thinking` and `maxBudgetUsd` under an `opencode` key. Two environment overrides exist for parity with the CLI: `MERIDIAN_PROFILES` wins over `profiles.json`, and `MERIDIAN_DEFAULT_PROFILE` wins over `settings.activeProfile`. Malformed files never crash the plugin; parse and IO failures are logged and it falls back to no-profile mode.

Prompt scrubbing and where the plugin deliberately stays out

When Meridian's default client prompt pass-through is enabled, the plugin runs `@rynfar/meridian-plugin-opencode-scrub` over outgoing prompts to strip OpenCode-identifying fingerprints. The README is explicit that user context such as `AGENTS.md` and configured instructions is preserved, and that the working directory reaches Meridian through the process environment rather than through the prompt text.

That is a narrow, honest scope. The plugin also states it does not edit Meridian's SDK feature file, so if you expect the plugin to manage those keys for you, it will not. Profile switching goes through Meridian's HTTP API with `POST /profiles/active` on the proxy URL printed at startup, and the selection is persisted back to `settings.json` so it survives restarts. If you bind the proxy to a wildcard interface, the plugin still uses loopback internally for health checks and provider requests, which keeps local calls working when you expose the proxy on `0.0.0.0`.

Limits: cached plugins, thin rollback docs, and CI

The most concrete limitation is caching. The README warns that OpenCode caches plugins installed by package name, and that when a new version is not picked up you should clear `~/.cache/opencode/node_modules/opencode-with-claude` and restart. That is a manual step on every update that misses, and it is exactly the kind of thing that makes a version look broken when it is merely stale.

The second limit is documentation depth. The README covers install, profiles, SDK features and four troubleshooting entries, but it does not document a rollback procedure, a way to pin the plugin to a specific version, or what happens to in-flight requests when OpenCode exits and the proxy is torn down with it. Uninstall steps are not in the README either; the npm and Homebrew install commands imply the reverse, but the README does not state it.

The third is the authentication dependency. Everything routes through a logged-in Claude Code CLI. A CI runner or a fresh container has no browser for `claude auth login` unless you use an `oauth-token` profile, and the README frames that profile type as a Meridian feature rather than as a documented CI recipe. If your environment cannot complete an interactive OAuth flow, this plugin is the wrong tool.

Finally, the plugin ties the proxy's lifetime to OpenCode's. That is the whole point, but it means you cannot keep the proxy running for another client while you restart the editor.

Running Meridian yourself instead of through the plugin

The obvious alternative is the one the README names: run Meridian directly. The README describes the difference as "One process to think about" versus "you juggling two things," and notes that running the proxy yourself means sharing one proxy across instances, which is where the session issues come from.

The real trade is control against convenience. A standalone Meridian process survives editor restarts, can be supervised by whatever you already use, and its lifecycle is not coupled to a plugin hook. In exchange you manage the port, the startup order, and the session attribution that the plugin handles with explicit headers. If you only ever run one OpenCode window and you want the proxy to outlive it, the standalone route is the more predictable one. If you open several windows and want them isolated, the plugin's per-instance port assignment is the feature that justifies the dependency.

Licence, maintenance and the cost of keeping up

The package is MIT licensed, per both the README badge and the `license` field in `package.json`. MIT is permissive, so the practical implication is that you can vendor or modify it, but you inherit no warranty and no support obligation from the author. Nothing here is legal advice; read the LICENSE file if the distinction matters to you.

The repository is not archived, and the last push was on 2026-09-15, the same day as the most recent release line. Releases v1.10.0 and v1.10.1 both landed on 2026-09-08, with v1.9.5 shortly before. That cadence suggests active iteration, and it also means the upgrade path matters: the plugin pins `@rynfar/meridian` at 1.68.0 and `@rynfar/meridian-plugin-opencode-scrub` at 0.2.0, so a Meridian change that alters the config files can land underneath you. Homebrew users get the formula bumped automatically after each npm publish, so `brew update && brew upgrade` tracks releases without the cache-clearing dance that npm users may hit.

Editorial conclusion

Adopt it if you already pay for Claude Max or Pro, want OpenCode's interface, and do not want to babysit a proxy process or a Docker container. Skip it if you need a documented rollback path, run in CI without a logged-in Claude Code CLI, or want the proxy decoupled from the editor's lifetime. Verify first that `claude auth status` reports an authenticated account and that your OpenCode version loads plugins by package name, because the README notes OpenCode caches plugins under `~/.cache/opencode/node_modules/opencode-with-claude` and a stale copy will not pick up a new release.

Frequently asked questions

Official sources

1. ianjwhite99/opencode-with-claude on GitHub
2. License: MIT
3. Project website
4. README
5. Releases