opencode-claude-max-proxy 1.8.0 → 1.10.0

package/README.md

@@ -102,19 +102,54 @@ curl http://127.0.0.1:3456/health
 
 ### Connect OpenCode
 
+#### Per-Terminal Launcher (recommended)
+
 ```bash
-ANTHROPIC_API_KEY=dummy ANTHROPIC_BASE_URL=http://127.0.0.1:3456 opencode
+./bin/oc.sh
 ```
 
-The `ANTHROPIC_API_KEY` can be any non-empty string — the proxy doesn't use it. Authentication is handled by your `claude login` session.
+Each terminal gets its own proxy on a random port. No port conflicts, no concurrency crashes. The proxy starts automatically, connects OpenCode, and cleans up when you exit. Sessions resume across terminals via a shared session file.
+
+Add to your shell config for easy access:
+
+```bash
+# ~/.zshrc or ~/.bashrc
+alias oc='/path/to/opencode-claude-max-proxy/bin/oc.sh'
+```
+
+#### Shared Proxy
 
-### Shell Alias
+If you prefer a single long-running proxy:
 
 ```bash
-# Add to ~/.zshrc or ~/.bashrc
-alias oc='ANTHROPIC_API_KEY=dummy ANTHROPIC_BASE_URL=http://127.0.0.1:3456 opencode'
+# Terminal 1: start the proxy
+CLAUDE_PROXY_PASSTHROUGH=1 bun run proxy
+
+# Terminal 2+: connect OpenCode
+ANTHROPIC_API_KEY=dummy ANTHROPIC_BASE_URL=http://127.0.0.1:3456 opencode
+```
+
+The `ANTHROPIC_API_KEY` can be any non-empty string — the proxy doesn't use it. Authentication is handled by your `claude login` session.
+
+#### OpenCode Desktop / Config File
+
+For OpenCode Desktop (or to avoid env vars), add the proxy to `~/.config/opencode/opencode.json`. Start the shared proxy in the background and Desktop connects automatically.
+
+```json
+{
+  "provider": {
+    "anthropic": {
+      "options": {
+        "baseURL": "http://127.0.0.1:3456",
+        "apiKey": "dummy"
+      }
+    }
+  }
+}
 ```
 
+> **Tip:** Use the shared proxy with the supervisor for Desktop: `CLAUDE_PROXY_PASSTHROUGH=1 bun run proxy`. Both Desktop and terminal instances share sessions via the file store.
+
 ## Modes
 
 ### Passthrough Mode (recommended)
@@ -161,6 +196,7 @@ The proxy tracks SDK session IDs and resumes conversations on follow-up requests
 
 - **Faster responses** — no re-processing of conversation history
 - **Better context** — the SDK remembers tool results from previous turns
+- **Works across terminals** — sessions are shared via a file store at `~/.cache/opencode-claude-max-proxy/sessions.json`
 
 Session tracking works two ways:
 
@@ -171,7 +207,7 @@ Session tracking works two ways:
 
 2. **Fingerprint-based** (automatic fallback) — hashes the first user message to identify returning conversations
 
-Sessions are cached for 24 hours.
+Sessions are cached for 24 hours. When using per-terminal proxies (`oc.sh`), the shared file store ensures a session started in one terminal can be resumed from another.
 
 ## Configuration
 
@@ -186,26 +222,19 @@ Sessions are cached for 24 hours.
 
 ## Concurrency
 
-The proxy supports multiple simultaneous OpenCode instances. Each request spawns its own independent SDK subprocess — run as many terminals as you want. All concurrent responses are delivered correctly.
-
-**Use the auto-restart supervisor** (recommended):
+**Per-terminal proxies (`oc.sh`)** are the recommended approach for multiple terminals. Each OpenCode instance gets its own proxy — no concurrency issues at all.
 
-```bash
-CLAUDE_PROXY_PASSTHROUGH=1 bun run proxy
-# or directly:
-CLAUDE_PROXY_PASSTHROUGH=1 ./bin/claude-proxy-supervisor.sh
-```
+**Shared proxy** supports concurrent requests but has a known limitation:
 
 > **⚠️ Known Issue: Bun SSE Crash ([oven-sh/bun#17947](https://github.com/oven-sh/bun/issues/17947))**
 >
-> The Claude Agent SDK's `cli.js` subprocess is compiled with Bun, which has a known segfault in `structuredCloneForStream` during cleanup of concurrent streaming responses. This affects all runtimes (Bun, Node.js via tsx) because the crash originates in the SDK's child process, not in the proxy itself.
+> The Claude Agent SDK's `cli.js` subprocess (compiled with Bun) has a known segfault during cleanup of concurrent streaming responses.
 >
-> **What this means in practice:**
-> - **Sequential requests (1 terminal):** No impact. Never crashes.
-> - **Concurrent requests (2+ terminals):** All responses are delivered correctly. The crash occurs *after* responses complete, during stream cleanup. No work is lost.
-> - **After a crash:** The supervisor restarts the proxy in ~1-3 seconds. If a new request arrives during this window, OpenCode shows "Unable to connect" — just retry.
+> - **All responses are delivered correctly** — the crash only occurs after responses complete
+> - **The supervisor auto-restarts** in ~1-3 seconds
+> - **Per-terminal proxies avoid this entirely** — no concurrency, no crash
 >
-> We are monitoring the upstream Bun issue for a fix. Once patched, the supervisor becomes optional.
+> We are monitoring the upstream Bun issue for a fix.
 
 ## Model Mapping
 

package/bin/docker-auth.sh

@@ -0,0 +1,77 @@
+#!/bin/bash
+# Copy Claude credentials from host into Docker container.
+#
+# macOS stores scopes in Keychain, so the credentials file has scopes: ""
+# Linux Claude CLI needs scopes as an array. This script fixes the format.
+#
+# Usage: ./bin/docker-auth.sh
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$SCRIPT_DIR/.."
+
+HOST_CREDS="$HOME/.claude/.credentials.json"
+
+if [ ! -f "$HOST_CREDS" ]; then
+  echo "❌ No credentials found at $HOST_CREDS"
+  echo "   Run 'claude login' on your host first."
+  exit 1
+fi
+
+# Check if host is logged in
+if ! claude auth status 2>/dev/null | grep -q '"loggedIn": true'; then
+  echo "❌ Not logged in on host. Run 'claude login' first."
+  exit 1
+fi
+
+echo "📋 Reading credentials from host..."
+
+# Fix the scopes field and copy into container
+python3 -c "
+import json, sys
+
+with open('$HOST_CREDS') as f:
+    creds = json.load(f)
+
+oauth = creds.get('claudeAiOauth', {})
+if not oauth.get('accessToken'):
+    print('❌ No access token found in credentials')
+    sys.exit(1)
+
+# Fix scopes: empty string -> proper array
+if not oauth.get('scopes') or oauth['scopes'] == '':
+    oauth['scopes'] = [
+        'user:profile',
+        'user:inference', 
+        'user:sessions:claude_code',
+        'user:mcp_servers',
+        'user:file_upload'
+    ]
+
+creds['claudeAiOauth'] = oauth
+print(json.dumps(creds))
+" | docker compose exec -T proxy bash -c 'cat > /home/claude/.claude/.credentials.json'
+
+if [ $? -ne 0 ]; then
+  echo "❌ Failed to copy credentials. Is the container running?"
+  echo "   Run 'docker compose up -d' first."
+  exit 1
+fi
+
+# Also copy .claude.json if it exists
+if [ -f "$HOME/.claude/.claude.json" ]; then
+  docker compose exec -T proxy bash -c 'cat > /home/claude/.claude/.claude.json' < "$HOME/.claude/.claude.json"
+fi
+
+# Verify
+echo "🔍 Verifying..."
+AUTH=$(docker compose exec proxy claude auth status 2>&1)
+if echo "$AUTH" | grep -q '"loggedIn": true'; then
+  EMAIL=$(echo "$AUTH" | grep -o '"email": "[^"]*"' | head -1)
+  echo "✅ Docker container authenticated! $EMAIL"
+else
+  echo "❌ Authentication failed inside container"
+  echo "$AUTH"
+  exit 1
+fi

package/bin/docker-entrypoint.sh

@@ -0,0 +1,24 @@
+#!/bin/bash
+# Docker entrypoint:
+# 1. Fix volume permissions (created as root, need claude ownership)
+# 2. Symlink .claude.json into persistent volume
+
+CLAUDE_DIR="/home/claude/.claude"
+CLAUDE_JSON="/home/claude/.claude.json"
+CLAUDE_JSON_VOL="$CLAUDE_DIR/.claude.json"
+
+# Fix ownership if volume was created as root
+if [ -d "$CLAUDE_DIR" ] && [ ! -w "$CLAUDE_DIR" ]; then
+  echo "[entrypoint] Fixing volume permissions..."
+fi
+
+# Symlink .claude.json into volume so it persists across restarts
+if [ -f "$CLAUDE_JSON_VOL" ] && [ ! -f "$CLAUDE_JSON" ]; then
+  ln -sf "$CLAUDE_JSON_VOL" "$CLAUDE_JSON"
+elif [ -f "$CLAUDE_JSON" ] && [ ! -L "$CLAUDE_JSON" ] && [ -w "$CLAUDE_DIR" ]; then
+  cp "$CLAUDE_JSON" "$CLAUDE_JSON_VOL" 2>/dev/null
+  rm -f "$CLAUDE_JSON"
+  ln -sf "$CLAUDE_JSON_VOL" "$CLAUDE_JSON"
+fi
+
+exec "$@"

package/bin/oc.sh

@@ -0,0 +1,62 @@
+#!/bin/bash
+# Per-terminal proxy launcher for OpenCode.
+#
+# Starts a dedicated proxy on a random port, launches OpenCode pointed at it,
+# and cleans up when OpenCode exits. Each terminal gets its own proxy — no
+# concurrent request issues, no shared port conflicts.
+#
+# Session resume works across terminals via the shared session file store.
+#
+# Usage: ./bin/oc.sh [opencode args...]
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROXY_SCRIPT="$SCRIPT_DIR/claude-proxy.ts"
+
+if [ ! -f "$PROXY_SCRIPT" ]; then
+  echo "❌ Proxy script not found: $PROXY_SCRIPT" >&2
+  exit 1
+fi
+
+# Pick a random free port
+PORT=$(python3 -c 'import socket; s = socket.socket(); s.bind(("127.0.0.1", 0)); print(s.getsockname()[1]); s.close()' 2>/dev/null \
+  || ruby -e 'require "socket"; s = TCPServer.new("127.0.0.1", 0); puts s.addr[1]; s.close' 2>/dev/null \
+  || echo $((RANDOM + 10000)))
+
+# Start proxy in background
+CLAUDE_PROXY_PORT=$PORT \
+CLAUDE_PROXY_WORKDIR="$PWD" \
+CLAUDE_PROXY_PASSTHROUGH="${CLAUDE_PROXY_PASSTHROUGH:-1}" \
+  bun run "$PROXY_SCRIPT" > /dev/null 2>&1 &
+PROXY_PID=$!
+
+# Ensure proxy is cleaned up on exit
+cleanup() {
+  kill $PROXY_PID 2>/dev/null
+  wait $PROXY_PID 2>/dev/null
+}
+trap cleanup EXIT INT TERM
+
+# Wait for proxy to be ready (up to 10 seconds)
+for i in $(seq 1 100); do
+  if curl -sf "http://127.0.0.1:$PORT/health" > /dev/null 2>&1; then
+    break
+  fi
+  if ! kill -0 $PROXY_PID 2>/dev/null; then
+    echo "❌ Proxy failed to start" >&2
+    exit 1
+  fi
+  sleep 0.1
+done
+
+# Verify proxy is healthy
+if ! curl -sf "http://127.0.0.1:$PORT/health" > /dev/null 2>&1; then
+  echo "❌ Proxy didn't become healthy within 10 seconds" >&2
+  exit 1
+fi
+
+# Launch OpenCode
+ANTHROPIC_API_KEY=dummy \
+ANTHROPIC_BASE_URL="http://127.0.0.1:$PORT" \
+  opencode "$@"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-claude-max-proxy",
-  "version": "1.8.0",
+  "version": "1.10.0",
   "description": "Use your Claude Max subscription with OpenCode via proxy server",
   "type": "module",
   "main": "./src/proxy/server.ts",

package/src/proxy/server.ts

@@ -15,6 +15,7 @@ import { withClaudeLogContext } from "../logger"
 import { fuzzyMatchAgentName } from "./agentMatch"
 import { buildAgentDefinitions } from "./agentDefs"
 import { createPassthroughMcpServer, stripMcpPrefix, PASSTHROUGH_MCP_NAME, PASSTHROUGH_MCP_PREFIX } from "./passthroughTools"
+import { lookupSharedSession, storeSharedSession, clearSharedSessions } from "./sessionStore"
 
 // --- Session Tracking ---
 // Maps OpenCode session ID (or fingerprint) → Claude SDK session ID
@@ -31,6 +32,8 @@ const fingerprintCache = new Map<string, SessionState>()
 export function clearSessionCache() {
   sessionCache.clear()
   fingerprintCache.clear()
+  // Also clear shared file store
+  try { clearSharedSessions() } catch {}
 }
 
 // Clean stale sessions every hour — sessions survive a full workday
@@ -63,13 +66,41 @@ function lookupSession(
   opencodeSessionId: string | undefined,
   messages: Array<{ role: string; content: any }>
 ): SessionState | undefined {
-  // Primary: use x-opencode-session header
+  // When a session ID is provided, only match by that ID — don't fall through
+  // to fingerprint. A different session ID means a different session.
   if (opencodeSessionId) {
-    return sessionCache.get(opencodeSessionId)
+    const cached = sessionCache.get(opencodeSessionId)
+    if (cached) return cached
+    // Check shared file store
+    const shared = lookupSharedSession(opencodeSessionId)
+    if (shared) {
+      const state: SessionState = {
+        claudeSessionId: shared.claudeSessionId,
+        lastAccess: shared.lastUsedAt,
+        messageCount: 0,
+      }
+      sessionCache.set(opencodeSessionId, state)
+      return state
+    }
+    return undefined
   }
-  // Fallback: fingerprint (only when no header is present)
+
+  // No session ID — use fingerprint fallback
   const fp = getConversationFingerprint(messages)
-  if (fp) return fingerprintCache.get(fp)
+  if (fp) {
+    const cached = fingerprintCache.get(fp)
+    if (cached) return cached
+    const shared = lookupSharedSession(fp)
+    if (shared) {
+      const state: SessionState = {
+        claudeSessionId: shared.claudeSessionId,
+        lastAccess: shared.lastUsedAt,
+        messageCount: 0,
+      }
+      fingerprintCache.set(fp, state)
+      return state
+    }
+  }
   return undefined
 }
 
@@ -81,9 +112,13 @@ function storeSession(
 ) {
   if (!claudeSessionId) return
   const state: SessionState = { claudeSessionId, lastAccess: Date.now(), messageCount: messages?.length || 0 }
+  // In-memory cache
   if (opencodeSessionId) sessionCache.set(opencodeSessionId, state)
   const fp = getConversationFingerprint(messages)
   if (fp) fingerprintCache.set(fp, state)
+  // Shared file store (cross-proxy resume)
+  const key = opencodeSessionId || fp
+  if (key) storeSharedSession(key, claudeSessionId)
 }
 
 /** Extract only the last user message (for resume — SDK already has history) */

package/src/proxy/sessionStore.ts

@@ -0,0 +1,92 @@
+/**
+ * File-based session store for cross-proxy session resume.
+ *
+ * When running per-terminal proxies (each on a different port),
+ * sessions need to be shared so you can resume a conversation
+ * started in one terminal from another. This stores session
+ * mappings in a JSON file that all proxy instances read/write.
+ *
+ * Format: { [key]: { claudeSessionId, createdAt, lastUsedAt } }
+ * Keys are either OpenCode session IDs or conversation fingerprints.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from "fs"
+import { join, dirname } from "path"
+import { homedir } from "os"
+
+export interface StoredSession {
+  claudeSessionId: string
+  createdAt: number
+  lastUsedAt: number
+}
+
+const SESSION_TTL_MS = 24 * 60 * 60 * 1000 // 24 hours
+
+function getStorePath(): string {
+  const dir = process.env.CLAUDE_PROXY_SESSION_DIR
+    || join(homedir(), ".cache", "opencode-claude-max-proxy")
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true })
+  }
+  return join(dir, "sessions.json")
+}
+
+function readStore(): Record<string, StoredSession> {
+  const path = getStorePath()
+  if (!existsSync(path)) return {}
+  try {
+    const data = readFileSync(path, "utf-8")
+    const store = JSON.parse(data) as Record<string, StoredSession>
+    // Prune expired entries
+    const now = Date.now()
+    const pruned: Record<string, StoredSession> = {}
+    for (const [key, session] of Object.entries(store)) {
+      if (now - session.lastUsedAt < SESSION_TTL_MS) {
+        pruned[key] = session
+      }
+    }
+    return pruned
+  } catch {
+    return {}
+  }
+}
+
+function writeStore(store: Record<string, StoredSession>): void {
+  const path = getStorePath()
+  const tmp = path + ".tmp"
+  try {
+    writeFileSync(tmp, JSON.stringify(store, null, 2))
+    renameSync(tmp, path) // atomic write
+  } catch {
+    // If rename fails, try direct write
+    try {
+      writeFileSync(path, JSON.stringify(store, null, 2))
+    } catch {}
+  }
+}
+
+export function lookupSharedSession(key: string): StoredSession | undefined {
+  const store = readStore()
+  const session = store[key]
+  if (!session) return undefined
+  if (Date.now() - session.lastUsedAt >= SESSION_TTL_MS) return undefined
+  return session
+}
+
+export function storeSharedSession(key: string, claudeSessionId: string): void {
+  const store = readStore()
+  const existing = store[key]
+  store[key] = {
+    claudeSessionId,
+    createdAt: existing?.createdAt || Date.now(),
+    lastUsedAt: Date.now(),
+  }
+  writeStore(store)
+}
+
+export function clearSharedSessions(): void {
+  const path = getStorePath()
+  try {
+    writeFileSync(path, "{}")
+  } catch {}
+}