opencode-with-claude

Use OpenCode with your Claude Max subscription.

What this is

An OpenCode plugin that runs Meridian (formerly opencode-claude-max-proxy) for you: start OpenCode once and the proxy comes up with it; quit OpenCode and the proxy stops. No separate proxy CLI or Docker container to manage.

Works with both OpenCode generations: the 1.x line (opencode) and OpenCode 2 (@opencode/cli), from the same package.

Compared to running the proxy yourself:

• One process to think about — OpenCode owns the proxy lifecycle (start/stop) instead of you juggling two things.
• Several OpenCode windows at once — each process gets its own proxy (port 3456 when available, otherwise an OS-assigned port). Project instances within the same process share that proxy, including concurrent plugin initialization.
• Explicit session headers — the plugin adds session tracking on outgoing API calls, so the proxy does not have to infer sessions from fingerprints alone. OpenCode's hidden title and summary requests are kept off the session's turn lease, so the first message of a fresh session does not race them.

How It Works

┌─────────────┐              ┌────────────────────┐       ┌─────────────────┐
│  OpenCode   │─────────────▶│  Claude Max Proxy  │──────▶│    Anthropic    │
│  (TUI/Web)  │ :3456 / auto │   (local server)   │  SDK  │    Claude Max   │
│             │◀─────────────│                    │◀──────│                 │
└─────────────┘              └────────────────────┘       └─────────────────┘

Quick Start

The plugin hooks into OpenCode's plugin system. When OpenCode launches, it starts the proxy, configures the Anthropic provider, and cleans everything up on exit.

1. Install the plugin

With npm:

npm install -g opencode-with-claude

Or with Homebrew (macOS/Linux), which keeps the plugin updated through brew upgrade instead of npm update -g:

brew install ianjwhite99/tap/opencode-with-claude

2. Authenticate with Claude (one-time)

npm install -g @anthropic-ai/claude-code   # or: brew install --cask claude-code
claude auth login

3. Add to your opencode.json

Global (~/.config/opencode/opencode.json) or project-level. The keys differ between OpenCode generations; a block written for the other generation is silently ignored, so make sure you use the right one.

OpenCode 1.x:

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

OpenCode 2 (plugins and providers.<id>.settings instead of plugin and provider.<id>.options):

{
  "$schema": "https://opencode.ai/config.json",
  "plugins": ["opencode-with-claude"],
  "providers": {
    "anthropic": {
      "settings": {
        "baseURL": "http://127.0.0.1:3456/v1",
        "apiKey": "dummy"
      }
    }
  }
}

In both examples, the configured baseURL is only a placeholder. The plugin uses the port its own proxy actually got, so several OpenCode instances can run side by side:

• OpenCode 1.x: the config hook replaces provider.anthropic.options.baseURL with the proxy origin, without /v1.
• OpenCode 2: the model.request hook replaces the entire request baseURL with the proxy origin plus /v1 for Anthropic requests. It does not append /v1 to providers.anthropic.settings.baseURL or preserve its configured path.

For OpenCode 2 requests that pass through this plugin's model.request hook, http://127.0.0.1:3456 and http://127.0.0.1:3456/v1 are equivalent placeholders; the configured /v1 suffix is not required. The example keeps /v1 to match OpenCode 2's Anthropic endpoint format: its transport uses a custom base URL as-is and adds /messages, not /v1/messages. This equivalence depends on the hook running; it does not apply to calls that bypass the hook or when the plugin is not loaded.

If you installed with Homebrew, point the plugin entry at the installed file instead of the package name (the path is stable across upgrades, and brew info opencode-with-claude prints it):

"plugin": ["file:///opt/homebrew/opt/opencode-with-claude/libexec/lib/node_modules/opencode-with-claude/dist/index.js"]

("plugins": [...] on OpenCode 2.) On Linux or Intel macOS replace /opt/homebrew with your Homebrew prefix (brew --prefix, usually /home/linuxbrew/.linuxbrew or /usr/local).

4. Run OpenCode

opencode

Updating

• Homebrew: brew upgrade opencode-with-claude. The release workflow bumps the formula in ianjwhite99/homebrew-tap after every npm publish, so brew update && brew upgrade tracks new releases.
• npm: npm update -g opencode-with-claude. Note that OpenCode caches plugins it installs by package name; if a new version is not picked up, clear ~/.cache/opencode/node_modules/opencode-with-claude and restart.

Profiles and SDK features

The plugin now reads the same Meridian configuration files the meridian CLI uses, so you can maintain multiple Claude accounts and tune SDK behavior without leaving OpenCode.

Profiles (~/.config/meridian/profiles.json)

Define one or more named profiles (for example, a personal Claude Max account, a work account, or an OAuth-token profile). The plugin forwards them to Meridian at startup.

[
  {
    "id": "personal",
    "claudeConfigDir": "/Users/me/.config/meridian/profiles/personal"
  },
  {
    "id": "work",
    "claudeConfigDir": "/Users/me/.config/meridian/profiles/work"
  },
  {
    "id": "headless",
    "type": "oauth-token",
    "oauthToken": "<token from claude setup-token>"
  }
]

Active profile (~/.config/meridian/settings.json)

{ "activeProfile": "work" }

activeProfile selects the default profile for any request that does not send an explicit x-meridian-profile header. If the saved id is not in profiles.json (or the file is missing), the plugin logs a warning and falls back to the first configured profile.

SDK features (~/.config/meridian/sdk-features.json)

Meridian reads this file lazily on every request, so overrides take effect without restarting the proxy. The plugin does not need to do anything special for it to work — just edit the file and the next request picks it up. See Meridian's documentation for the full list of adapter keys.

This plugin does not edit Meridian's SDK feature file. When Meridian's default client prompt pass-through is enabled, the plugin scrubs OpenCode-identifying prompt fingerprints with @rynfar/meridian-plugin-opencode-scrub before forwarding. User context such as AGENTS.md and configured instructions is preserved, while cwd is forwarded to Meridian through the process environment.

{
  "opencode": {
    "memory": true,
    "thinking": "enabled",
    "maxBudgetUsd": 0.5
  }
}

Environment overrides

For parity with the meridian CLI:

• MERIDIAN_PROFILES — JSON array of profile objects; wins over profiles.json.
• MERIDIAN_DEFAULT_PROFILE — profile id; wins over settings.activeProfile.
• MERIDIAN_PATH — run your own Meridian build instead of the bundled one (see Using your own Meridian build).

Malformed or missing files never crash the plugin; all parse/IO failures are logged via OpenCode's plugin log and the plugin falls back to no-profile mode.

Using your own Meridian build

Each plugin release pins one exact @rynfar/meridian version, and Meridian ships faster than this plugin does. Set MERIDIAN_PATH to follow Meridian's releases without waiting for a plugin release:

npm install -g @rynfar/meridian
MERIDIAN_PATH="$(npm root -g)" opencode

MERIDIAN_PATH accepts any of:

• the Meridian package root — .../node_modules/@rynfar/meridian
• any directory Node can resolve @rynfar/meridian from — a global node_modules, or a project that depends on it
• the entry file itself — .../@rynfar/meridian/dist/server.js

Auth, profiles, and the session cache already live on disk (~/.config/meridian, ~/.cache/meridian), so an external build shares all of them with the meridian CLI; only the code version changes.

The bundled copy stays the fallback. A path that does not exist, is not a Meridian install, or exposes no startProxyServer logs a warning and changes nothing else. Either way the plugin logs which build it is running, so a bug report can name it:

meridian 1.79.0 (bundled)
meridian 1.80.0 (external: /opt/homebrew/lib/node_modules/@rynfar/meridian)

A swapped build has to keep the surface the plugin uses: startProxyServer returning { server, config.port, close() }, and a /health response carrying status, error, version, and auth.{daysUntilRenewal,renewalRequiredSoon}.

Switching profiles at runtime

Profile switching through Meridian's HTTP API continues to work — call POST /profiles/active on the proxy URL the plugin prints at startup. The selection is persisted back to settings.json and survives restarts.

Troubleshooting

"Claude Code CLI not found"

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

"Claude not authenticated"

claude auth login
# or (depends of your version)
claude login

This opens a browser for OAuth. Your Claude Max subscription credentials are needed.

"Proxy failed to start"

1. Check Claude auth: claude auth status
2. Ensure your internet connection is working
3. If using a manual port override, check if it's in use: lsof -i :$CLAUDE_PROXY_PORT

Binding the proxy to a non-localhost interf