@xtruder/opencode-claude-max-plugin 0.4.5 → 2.0.0-rc.2

package/README.md

@@ -1,106 +1,100 @@
 # @xtruder/opencode-claude-max-plugin
 
-An [OpenCode](https://opencode.ai/) plugin that enables Claude Pro/Max subscription access via the official [`@anthropic-ai/sdk`](https://github.com/anthropics/anthropic-sdk-typescript), using OAuth credentials from Claude Code (`~/.claude/.credentials.json`).
+Use Claude Pro/Max subscription credentials in OpenCode, with a subscription-usage sidebar and `/usage` dialog. The plugin uses the official Anthropic SDK through OpenCode's AI SDK adapter.
 
-![Usage sidebar and /usage command dialog](assets/example-with-usage.png)
-
-## Why?
-
-- **Use your Claude subscription** — Automatically reads OAuth credentials from Claude Code, no separate API key needed
-- **Matches Claude Code 2.1.220** — Same request format and behavior as the official CLI
-- **Prompt caching** — Multi-turn conversations cache properly, keeping costs and latency low
-- **Supported Claude models** — Opus 5, Sonnet 5, Fable 5, Opus 4.8, Opus 4.7, Opus 4.6, Sonnet 4.6, Haiku 4.5
-- **Extended / adaptive thinking** — Full reasoning support across models, including Claude 5 adaptive thinking
-- **Safety-refusal fallback** — Opus 5 and Fable 5 classifier refusals can fall back in the same request, with TUI notification
-- **Usage tracking** — Sidebar widget with live progress bars + `/usage` command
-- **Self-registering** — Models are registered automatically, no manual provider config needed
+**Requires OpenCode 2.0.16 or later. OpenCode v1 is not supported.** Model availability depends on your account.
 
 ## Installation
 
-Add the plugin to your `opencode.json` (project-level or `~/.config/opencode/opencode.json` globally):
+Sign in to Claude Code, then add the plugin to `~/.config/opencode/opencode.json` or your existing `opencode.jsonc`:
+
+```sh
+claude auth login
+```
 
 ```json
 {
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": ["@xtruder/opencode-claude-max-plugin"]
+  "plugins": ["@xtruder/opencode-claude-max-plugin"]
 }
 ```
 
-That's it. The plugin self-registers the `anthropic-sdk` provider and its models (Haiku 4.5, Sonnet 4.6, Sonnet 5, Opus 4.6, Opus 4.7, Opus 4.8, Opus 5, Fable 5) at startup via the OpenCode config hook. No separate `provider` block is needed.
-
-Then open OpenCode and models will automatically be available under `anthropic-sdk` provider.
+OpenCode installs the package and discovers both its provider and terminal UI. No separate provider configuration is needed. Restart OpenCode after changing the configuration; if you use a shared server, restart it and the terminal client.
 
-### TUI Plugin (sidebar + /usage command)
+When migrating from v1, replace the old `plugin` entry with the v2 `plugins` configuration and remove any separate registration of `src/tui.tsx`. Use a v2-compatible plugin release; version 0.4.6 predates this migration.
 
-The plugin includes a TUI component that shows subscription usage in the sidebar and registers a `/usage` slash command. To enable it, add the plugin to your `tui.json` as well:
+## Authentication
 
-**Project-level** (`.opencode/tui.json`):
+For subscription access, sign in with Claude Code:
 
-```json
-{
-  "plugin": ["@xtruder/opencode-claude-max-plugin"]
-}
+```sh
+claude auth login
 ```
 
-**Or globally** (`~/.config/opencode/tui.json`):
+The plugin reads `~/.claude/.credentials.json`. Credential refresh is deferred until an inference request needs it.
 
-```json
-{
-  "plugin": ["@xtruder/opencode-claude-max-plugin"]
-}
-```
-
-The TUI plugin provides:
+Authentication is selected in this order:
 
-- **Sidebar widget** — Compact progress bars for 5-hour session and 7-day weekly usage
-- **`/usage` command** — Opens a dialog with full usage breakdown (per-model, extra usage)
-- **Auto-refresh** — Polls the usage API every 60s and after each inference call
-- **Fallback indicator** — Toast when a classifier refusal falls back, plus a sidebar line showing which model served the latest turn
+1. An explicit `apiKey` plugin option.
+2. The `ANTHROPIC_API_KEY` environment variable.
+3. Claude Code's OAuth credentials.
 
-#### TUI Configuration
+If you intend to use your subscription, make sure an API key is not overriding it. API-key requests use API billing rather than subscription access.
 
-Options can be set in the `tui.json` plugin entry:
+For a custom credentials file, supply server plugin options:
 
 ```json
 {
-  "plugin": [
-    [
-      "@xtruder/opencode-claude-max-plugin",
-      {
-        "enabled": true,
-        "sidebar": true,
-        "poll_interval": 60
+  "plugins": [
+    {
+      "package": "@xtruder/opencode-claude-max-plugin",
+      "options": {
+        "credentialsPath": "/absolute/path/to/.credentials.json"
       }
-    ]
+    }
   ]
 }
 ```
 
-| Option          | Type    | Default | Description                               |
-| --------------- | ------- | ------- | ----------------------------------------- |
-| `enabled`       | boolean | `true`  | Enable/disable the TUI plugin entirely    |
-| `sidebar`       | boolean | `true`  | Show/hide sidebar usage widget            |
-| `poll_interval` | number  | `60`    | Seconds between usage API polls (min: 10) |
+The credentials must be accessible to the process running the provider. The usage TUI reads credentials on the machine running the terminal client.
+
+## Usage
+
+Choose a model from the `anthropic-sdk` provider in OpenCode, or run:
+
+```sh
+opencode run --standalone -m anthropic-sdk/claude-haiku-4-5 'Reply with exactly OK.'
+opencode run --standalone -m 'anthropic-sdk/claude-sonnet-5#high' 'Explain this code.'
+```
+
+Registered models (each row is a separate selectable entry):
 
-### Custom model options
+| Model            | OpenCode model ID  |
+| ---------------- | ------------------ |
+| Claude Haiku 4.5 | `claude-haiku-4-5` |
+| Claude Sonnet 5  | `claude-sonnet-5`  |
+| Claude Opus 4.8  | `claude-opus-4-8`  |
+| Claude Opus 5    | `claude-opus-5`    |
+| Claude Opus 5.5  | `claude-opus-5-5`  |
+| Claude Fable 5   | `claude-fable-5`   |
+| Claude Fable 5.1 | `claude-fable-5-1` |
 
-If you want to override model settings (e.g. thinking budgets, variants), you can add a `provider` block alongside the plugin:
+[Claude Opus 5](https://platform.claude.com/docs/en/models/opus-5/overview) remains available as a legacy model; it is not an alias for [Opus 5.5](https://platform.claude.com/docs/en/models/opus-5-5/overview). Anthropic names it “Claude Opus 5”, not “Claude Opus 5.0”.
+
+Sonnet 4.6, Opus 4.6 (including the `-1m` variant), and Opus 4.7 are no longer registered by this plugin. Select a supported model when continuing sessions that used them.
+
+Registration does not guarantee account access to a model. Use these OpenCode IDs rather than dated API aliases.
+
+### Model settings
+
+Use OpenCode v2's `providers` configuration for model overrides. For example, to disable refusal fallback for a model:
 
 ```json
 {
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": ["@xtruder/opencode-claude-max-plugin"],
-  "provider": {
+  "providers": {
     "anthropic-sdk": {
       "models": {
-        "claude-sonnet-4-6": {
-          "options": {
-            "thinking": { "type": "enabled", "budgetTokens": 1024 }
-          },
-          "variants": {
-            "high": { "thinking": { "type": "enabled", "budgetTokens": 10000 } },
-            "max": { "thinking": { "type": "enabled", "budgetTokens": 32000 } }
-          }
+        "claude-fable-5": {
+          "settings": { "refusalFallback": false }
         }
       }
     }
@@ -108,94 +102,85 @@ If you want to override model settings (e.g. thinking budgets, variants), you ca
 }
 ```
 
-Config-level settings are merged with plugin defaults — you only need to specify what you want to override.
+The provider supports model-specific prompts, prompt caching, thinking, tool calls, pause-turn continuation, and server-side refusal fallbacks. See [RESEARCH.md](RESEARCH.md) for request-format details.
+
+## Subscription usage
 
-### Claude Fable 5 and safety-refusal fallback
+The terminal sidebar shows available 5-hour and 7-day usage windows and reset times. Run `/usage` or select it from the command palette for additional model-specific windows and extra-usage status. Press Escape to close the dialog.
 
-Claude Fable 5 (`claude-fable-5`) ships with stricter safety classifiers that can refuse a request at the API level (`stop_reason: "refusal"`) — even for benign follow-ups if the conversation contains a flagged topic. To keep sessions usable, the plugin enables Anthropic's server-side fallback by default: when Fable 5 refuses, **Opus 4.8 answers the same request in the same round trip**. Tool loops keep running, thinking chains stay verified, and prompt caching is unaffected.
+Usage comes from subscription data, not estimates derived from token counts. It is separate from OpenCode's native token/cost statistics.
 
-When a fallback happens:
+The display checks its shared cache every 60 seconds by default. Usage API results are cached for five minutes; opening `/usage` does not bypass that cache or rate-limit backoff. Failed requests retain cached values with a status notice. Fetching usage does not send an inference request or launch Claude Code to refresh credentials.
 
-- The TUI shows a toast (`fable-5 refused — answered by opus-4-8`) on the first fallback turn
-- The sidebar shows a `Model Fallback` line while the latest turn was served by the fallback model
-- The served model is recorded in part metadata (`anthropic.servedBy`) — the model's own self-report will still say `claude-fable-5`, since identity comes from the prompt, not the serving model
+### TUI settings
 
-Configure via the `refusalFallback` model option:
+Defaults work with the server plugin registration alone. To customize the terminal UI, add an entry to `~/.config/opencode/cli.json`:
 
 ```json
 {
-  "provider": {
-    "anthropic-sdk": {
-      "models": {
-        "claude-fable-5": {
-          "options": {
-            "refusalFallback": false
-          }
-        }
+  "plugins": [
+    {
+      "package": "@xtruder/opencode-claude-max-plugin",
+      "options": {
+        "enabled": true,
+        "sidebar": true,
+        "poll_interval": 60
       }
     }
-  }
+  ]
 }
 ```
 
-Set it to another model ID to change the fallback target, or `false` to disable (refusals then surface as errors with the refusal category).
-
-Claude Opus 5 also has safety classifiers. Its `refusalFallback` defaults to `"default"`, which lets Anthropic select the recommended fallback for each refusal category. Override or disable it through the same model option on `claude-opus-5`.
+| Option            | Default                       | Description                                                |
+| ----------------- | ----------------------------- | ---------------------------------------------------------- |
+| `enabled`         | `true`                        | Enable the usage TUI.                                      |
+| `sidebar`         | `true`                        | Show sidebar usage. Disabling it keeps `/usage` available. |
+| `poll_interval`   | `60`                          | Cache polling interval in seconds; minimum 10.             |
+| `credentialsPath` | `~/.claude/.credentials.json` | Credentials file used by the usage TUI.                    |
 
-## Authentication
+Server plugin options are not automatically passed to the TUI. Set a custom TUI credentials path in `cli.json`, even if it is already configured for the server. The usage cache is shared within an XDG state directory, not separated by credentials file or account.
 
-Credentials are resolved in order:
+## Development
 
-1. **`ANTHROPIC_API_KEY` env var** or **`apiKey` provider option**
-2. **Claude Code credentials** — auto-read from `~/.claude/.credentials.json`
+Building and testing require **Node.js 26.4+ and npm**. Bun is not required for this workflow. Run these commands from a checkout of the repository:
 
-For Claude Code credentials, log in via `claude` CLI first (`claude auth login`).
+```sh
+npm ci
+npm run build
+npm run dev              # rebuild on changes
+npm run typecheck
+npm run lint
+npm run format:check
+npm test
+```
 
-## Features
+Vite builds three ESM entrypoints: `build/index.js` (AI SDK provider), `build/server.js` (OpenCode registration), and `build/tui.js` (terminal UI). It compiles Solid JSX for OpenTUI and embeds prompt `.txt` files into JavaScript. Keep the entire `build/` directory together, including shared chunks.
 
-- Streaming and non-streaming completions
-- Tool/function calling with Claude Code tool name mapping (`task` → `Agent`, `webfetch` → `WebFetch`, etc.)
-- MCP tool name remapping (`server_tool` → `mcp__server__tool`)
-- Extended thinking (Sonnet/Opus 4.6) and adaptive thinking (Opus 4.7+, Sonnet 5) with effort levels and multi-turn signature passthrough
-- Prompt caching that holds across long, tool-heavy conversations
-- Server-side safety-refusal fallback for Opus 5 and Fable 5 (configurable, on by default)
-- Subscription rate limit detection — fails fast with a clear message instead of hanging
-- Long-context auto-detection for large prompts
-- TUI sidebar with live usage bars + `/usage` slash command
+The build currently also runs TypeScript declaration generation for the exported provider API. `npm run typecheck` checks types without emitting files. `npm run dev` watches JavaScript and prompt changes; run the full build before packaging to refresh declarations.
 
-## With Vercel AI SDK
+The `aisdk:` prefix is applied internally to the provider's runtime file URL. Do not add it to the plugin name in your configuration. Runtime packages remain external to the bundle; the plugin uses OpenCode's adapter rather than maintaining a second transport implementation.
 
-The plugin also works as a standalone Vercel AI SDK provider:
+### Testing
 
-```typescript
-import { CLAUDE_CODE_SYSTEM_PROMPT, createAnthropicSDK } from "@xtruder/opencode-claude-max-plugin"
-import { streamText } from "ai"
+`npm test` builds the plugin and runs offline tests with Vitest. It does not perform Claude inference.
 
-// Uses ~/.claude/.credentials.json automatically
-const provider = createAnthropicSDK()
-const model = provider.languageModel("claude-sonnet-4-6")
+For a real terminal integration check:
 
-const result = streamText({
-  model,
-  system: CLAUDE_CODE_SYSTEM_PROMPT,
-  prompt: "Hello!",
-})
-for await (const chunk of result.textStream) {
-  process.stdout.write(chunk)
-}
+```sh
+npm run test:tui-smoke
 ```
 
-When using Claude Code OAuth credentials outside OpenCode, you must pass a Claude-compatible system prompt yourself. Exported `CLAUDE_CODE_SYSTEM_PROMPT` is the prompt used by the OpenCode plugin hook.
+This requires OpenCode, Python, and `uv`. It starts an isolated OpenCode instance with fixture usage data and checks the sidebar, dialog, resizing, polling, and error states. It does not attach to your running server or send model prompts.
 
-## Development
+Live Claude tests are explicit opt-in:
 
-```bash
-bun install
-bun run build
-bun test src/*.test.ts    # unit + integration tests (model tests require ANTHROPIC_API_KEY or Claude Code credentials)
+```sh
+npm run test:live
 ```
 
-See [RESEARCH.md](RESEARCH.md) for detailed reverse-engineering findings on how we matched Claude Code's request format.
+These tests can consume quota and refresh credentials.
+
+Native Node rendering uses OpenTUI's experimental `node:ffi` backend, which requires Node 26.4+ and may print an experimental warning. Standalone Node TUI harnesses must select Solid's reactive runtime with `--conditions=browser`. The plugin has also been tested in the Bun-compiled OpenCode 2.0.16 host; using npm to build the plugin does not change the host's runtime.
 
 ## License