Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -16,4 +16,4 @@ jobs:
node-version: 22
- run: npm ci
- run: npm run typecheck
- run: npm run build
- run: npm test
88 changes: 74 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,24 @@ Use your Claude Pro/Max subscription in [OpenCode](https://opencode.ai). If you'

## Install

### OpenCode v2 (recommended)

Install via CLI:

```bash
opencode plugin add opencode-claude-bridge
```

Or add to `~/.config/opencode/opencode.json`:

```json
{
"plugins": ["opencode-claude-bridge"]
}
```

### OpenCode v1 (1.18.29 – 1.x)

Add to `~/.config/opencode/opencode.json`:

```json
Expand All @@ -14,15 +32,12 @@ Add to `~/.config/opencode/opencode.json`:

OpenCode auto-installs the plugin from npm on next launch.

If you're logged into the Claude CLI (`claude login`), the plugin auto-syncs your credentials — just select an Anthropic model and start chatting. If not, you'll be prompted to authenticate via browser OAuth or enter an API key.
If you're logged into the Claude CLI (`claude login`), the plugin auto-syncs your credentials — just select an Anthropic model and start chatting. If not, you'll be prompted to authenticate via browser OAuth (or `/connect` → Anthropic) or enter an API key.

**Upgrade:**

OpenCode pins the installed version. To upgrade to the latest:

```bash
cd ~/.cache/opencode && npm install opencode-claude-bridge@latest
```
- **OpenCode v2:** `opencode plugin update opencode-claude-bridge`
- **OpenCode v1:** `cd ~/.cache/opencode && npm install opencode-claude-bridge@latest`

Then restart OpenCode.

Expand All @@ -34,13 +49,20 @@ git clone https://github.com/dotCipher/opencode-claude-bridge.git ~/opencode-cla
cd ~/opencode-claude-bridge && npm install && npm run build
```

Then reference the full path in your config:

```json
{
"plugin": ["/Users/YOU/opencode-claude-bridge/dist/index.js"]
}
```
Then reference the local path in your config:

- **OpenCode v2** (must be the **directory**, not `dist/index.js`):
```json
{
"plugins": ["/Users/YOU/opencode-claude-bridge"]
}
```
- **OpenCode v1**:
```json
{
"plugin": ["/Users/YOU/opencode-claude-bridge/dist/index.js"]
}
```
</details>

## How the bridge works
Expand Down Expand Up @@ -145,9 +167,45 @@ SHA256(salt + message[4] + message[7] + message[20] + CLI_VERSION).slice(0, 3)

The salt is hardcoded in Claude Code's source. This changes per conversation because the user's message text changes.

## OpenCode v2 compatibility

OpenCode 2.0 loads plugins through a new contract (`id` + `setup()`), and V1
hooks never run there — older releases fail with *"Plugin must export a default
definition with an id and an effect or setup function"*. This package supports
both generations from a single entrypoint (`{ id, setup, server }`):

- **OpenCode ≥ 2.0** — uses `setup()`.
- Registers an OAuth method on the built-in `anthropic` integration with
keychain fast-path, browser PKCE (`mode: "auto"` + remote redirect-URL
paste with CSRF `state` verification), and layered refresh (keychain →
stored → CLI) persisted atomically by OpenCode.
- **Seamless sync:** when no Anthropic connection exists yet (neither a
stored credential nor `ANTHROPIC_API_KEY`) and you are logged into
`claude login`, the bridge automatically persists your keychain credential
on startup so Anthropic models appear immediately without running `/connect`.
Existing API keys are never overridden.
- Rewrites OAuth requests and SSE tool-call responses through
provider-scoped `http.request` / `http.response` and system prompt
(`context`, `compaction`, `generate`, `title`) hooks. Requests to
non-Anthropic hosts or with API-key auth pass through untouched.
- No model injection: the v2 catalog already lists Claude models.
- No inline 429 token rotation: Claude refresh tokens are single-use, so
rotation is restricted to OpenCode's persisted integration `refresh`
callback; OpenCode's native retry policy handles 429 backoff.
- **OpenCode 1.18.29 – 1.x** — uses the V1 `server()` implementation as before.

> **Note on OpenCode v2's built-in Claude Agent provider:** OpenCode v2 also
> ships a native `claude-agent` provider that shells out to the local `claude`
> CLI binary. Use this bridge if you want direct Anthropic API traffic through
> OpenCode's native `anthropic` provider with Claude Code wire parity, tool
> schema & SSE translation, and seamless coexistence with API-key configs.

OpenCode < 1.18.29 is not supported by `main` (the `{ id, server }` entrypoint
shape requires 1.18.29); use the 1.10.x releases there.

## Requirements

- [OpenCode](https://opencode.ai) v1.2+
- [OpenCode](https://opencode.ai) v1.18.29+ (v2 supported)
- For OAuth: [Claude CLI](https://docs.anthropic.com/en/docs/claude-code) installed and logged in (`claude login`)
- macOS (Keychain) or Linux (`~/.claude/.credentials.json` fallback)
- For API key: just configure a `provider` with `apiKey` in your OpenCode config as usual
Expand Down Expand Up @@ -240,6 +298,8 @@ Anthropic's own Claude Code docs say third-party integrations should use API key

## Credits

OpenCode v2 plugin port initiated by [@TomasRichtr](https://github.com/TomasRichtr) in [#37](https://github.com/dotCipher/opencode-claude-bridge/pull/37).

Combines approaches from [shahidshabbir-se/opencode-anthropic-oauth](https://github.com/shahidshabbir-se/opencode-anthropic-oauth), [ex-machina-co/opencode-anthropic-auth](https://github.com/ex-machina-co/opencode-anthropic-auth), [vinzabe/PERMANENT-opencode-anthropic-oauth-fix](https://github.com/vinzabe/PERMANENT-opencode-anthropic-oauth-fix), and [lehdqlsl/opencode-claude-auth-sync](https://github.com/lehdqlsl/opencode-claude-auth-sync).

## License
Expand Down
4 changes: 2 additions & 2 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

8 changes: 7 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,10 +1,16 @@
{
"name": "opencode-claude-bridge",
"version": "1.10.12",
"version": "1.11.0",
"description": "OpenCode ↔ Claude bridge — keychain sync + PKCE OAuth + request transformation",
"type": "module",
"main": "dist/index.js",
"types": "dist/index.d.ts",
"exports": {
".": {
"types": "./dist/index.d.ts",
"default": "./dist/index.js"
}
},
"files": [
"dist"
],
Expand Down
14 changes: 12 additions & 2 deletions src/constants.ts
Original file line number Diff line number Diff line change
Expand Up @@ -75,11 +75,21 @@ export const USER_AGENT =
process.env.ANTHROPIC_USER_AGENT ||
`claude-cli/${CLI_VERSION} (external, ${ENTRYPOINT})`;

// Exact beta flags from Claude Code 2.1.178 (confirmed via request interception)
// Beta flags matching Claude Code 2.1.x (confirmed via request interception).
// oauth-2025-04-20 is added separately only for OAuth auth.
//
// 2026-10-16: added thinking-binding-controls-2026-08-01 (present in Claude
// Code ≥2.1.2xx). It legalizes the `thinking.block_binding` request field,
// which OpenCode v2 sends natively for models flagged
// supportsThinkingBlockBinding (claude-haiku-5-5, opus/sonnet/fable 5.x).
// Without this flag those requests fail validation with:
// "thinking.adaptive.block_binding: Extra inputs are not permitted"
// To refresh this list against a newer Claude Code install:
// grep -aoE '"[a-z]+(-[a-z]+)*-20[0-9]{2}-[0-9]{2}-[0-9]{2}"' \
// "$(readlink -f "$(command -v claude)")" | sort -u
export const BETA_FLAGS =
process.env.ANTHROPIC_BETA_FLAGS ||
"interleaved-thinking-2025-05-14,thinking-token-count-2026-05-13,context-management-2025-06-27,prompt-caching-scope-2026-01-05,claude-code-20250219,advisor-tool-2026-03-01,effort-2025-11-24,extended-cache-ttl-2025-04-11";
"interleaved-thinking-2025-05-14,thinking-token-count-2026-05-13,context-management-2025-06-27,prompt-caching-scope-2026-01-05,claude-code-20250219,advisor-tool-2026-03-01,effort-2025-11-24,extended-cache-ttl-2025-04-11,thinking-binding-controls-2026-08-01";

export const OAUTH_BETA_FLAG = "oauth-2025-04-20";

Expand Down
Loading