opencode-visual-cache 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hotakus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,72 @@
+<div align="center">
+<strong>
+    <h1>OpenCode Visual Cache</h1>
+    实时 Token 缓存命中率 · TUI 侧边栏可视化<br>
+    自适应主题色 · 自动低饱和设计语言 · 支持中/英双语
+</strong>
+<br>
+
+[![Stars](https://img.shields.io/github/stars/Hotakus/opencode-visual-cache?style=flat-square)](https://github.com/Hotakus/opencode-visual-cache/stargazers)
+[![License](https://img.shields.io/github/license/Hotakus/opencode-visual-cache?style=flat-square)](LICENSE)
+[![English](https://img.shields.io/badge/English-README-blue?style=flat-square)](README_EN.md)
+
+</div>
+
+---
+
+## 图片展示
+
+<div align="center"> 
+<strong>支持折叠，节省侧边栏占用👇</strong> <br>
+<img src="./assets/example2.png"></img>
+</div>
+<div align="center"> 
+<strong>展开👇</strong> <br>
+<img src="./assets/example1.png"></img>
+</div>
+
+---
+## 功能
+
+- **缓存命中率**：实时计算并显示缓存命中率，自适应宽度进度条
+- **Token 明细**：缓存读 / 缓存写 / 未命中 / 输出，标签左对齐 · 数据右对齐
+- **费用与节省**：Session 累计费用 + 缓存命中带来的费用节省
+- **模型定价**：显示当前模型的输入 / 缓存读单价（从 provider 配置动态读取）
+- **折叠面板**：点击标题折叠为一行，节省侧边栏空间
+- **颜色自适应**：命中率 ≥85% 绿 · ≥70% 橙 · <70% 红，颜色从主题色自动去饱和
+- **语言适配**：自动检测系统语言
+
+---
+
+## 安装
+
+> [!NOTE]
+> 安装方式待定 —— 本喵还在研究如何发布喵~
+> 发布后将更新此部分。
+
+```jsonc
+// TODO: 安装步骤
+```
+
+---
+
+## 调试
+
+强制英文（Windows PowerShell）：
+
+```powershell
+$env:CACHE_TUI_LANG="en"; opencode
+```
+
+---
+
+## 兼容性
+
+代码完全模型无关，支持所有 OpenCode 兼容的 AI 模型（DeepSeek / Claude / GPT 等）。
+Token 数据和定价信息均通过 OpenCode SDK 标准接口获取。
+
+---
+
+## License
+
+MIT

package/README_EN.md

@@ -0,0 +1,78 @@
+<div align="center">
+<strong>
+    <h1>OpenCode Visual Cache</h1>
+    Real-time Token Cache Hit Rate · TUI Sidebar Visualization<br>
+    Adaptive Theme Colors · Auto-desaturated · Chinese / English
+</strong>
+<br>
+
+[![Stars](https://img.shields.io/github/stars/Hotakus/opencode-visual-cache?style=flat-square)](https://github.com/Hotakus/opencode-visual-cache/stargazers)
+[![License](https://img.shields.io/github/license/Hotakus/opencode-visual-cache?style=flat-square)](LICENSE)
+[![中文](https://img.shields.io/badge/中文-README-red?style=flat-square)](README.md)
+
+</div>
+
+---
+
+## Screenshots
+
+<div align="center">
+<strong>Collapsed 👇</strong> <br>
+<img src="./assets/example2.png"></img>
+</div>
+<div align="center">
+<strong>Expanded 👇</strong> <br>
+<img src="./assets/example1.png"></img>
+</div>
+
+---
+
+## Features
+
+- **Cache Hit Rate**: Real-time `cache_read / total_input × 100%` with adaptive-width progress bar
+- **Token Breakdown**: Cache Read / Write / Miss / Output, left-aligned labels, right-aligned values
+- **Cost & Savings**: Session cost + cache savings (input_rate − cache_read_rate) × cache_read
+- **Model Pricing**: Current model's input / cache-read rates (from provider config)
+- **Collapsible**: Click title to fold into one line
+- **Adaptive Colors**: ≥85% green · ≥70% orange · <70% red, auto-desaturated from theme
+- **Language**: Auto-detects system locale, switches between Chinese and English
+
+---
+
+## Installation
+
+> [!NOTE]
+> Installation method TBD — will be updated after publishing.
+
+```jsonc
+// TODO: install steps
+```
+
+---
+
+## Debug
+
+Force English:
+
+```powershell
+# Windows PowerShell
+$env:CACHE_TUI_LANG="en"; opencode
+```
+
+```bash
+# macOS / Linux
+CACHE_TUI_LANG=en opencode
+```
+
+---
+
+## Compatibility
+
+Model-agnostic — works with all OpenCode-compatible AI models (DeepSeek / Claude / GPT etc.).
+Token data and pricing are read via OpenCode SDK standard interfaces.
+
+---
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+/** @jsxImportSource @opentui/solid */
+import type { TuiPluginModule } from "@opencode-ai/plugin/tui";
+declare const mod: TuiPluginModule & {
+    id: string;
+};
+export default mod;

package/dist/index.js

@@ -0,0 +1,313 @@
+import { jsx as _jsx, jsxs as _jsxs } from "@opentui/solid/jsx-runtime";
+import { createMemo, createSignal, Show } from "solid-js";
+// ── terminal-width helpers ────────────────────────────────────────
+// CJK characters occupy 2 terminal columns; padEnd/padStart count
+// string length (=1 per char), which breaks alignment with mixed text.
+function charColumns(c) {
+    const code = c.codePointAt(0) ?? 0;
+    if (code < 0x20)
+        return 0; // control
+    if (code < 0x7F)
+        return 1; // ASCII
+    if (code < 0xA0)
+        return 0; // C1 controls
+    // East-Asian wide / fullwidth ranges
+    if ((code >= 0x1100 && code <= 0x115F) || // Hangul Jamo
+        (code >= 0x2E80 && code <= 0xA4CF) || // CJK Radicals … Yi
+        (code >= 0xAC00 && code <= 0xD7A3) || // Hangul
+        (code >= 0xF900 && code <= 0xFAFF) || // CJK Compat
+        (code >= 0xFE10 && code <= 0xFE6F) || // Vertical / Compat
+        (code >= 0xFF01 && code <= 0xFF60) || // Fullwidth
+        (code >= 0xFFE0 && code <= 0xFFE6) || // Fullwidth signs
+        (code >= 0x1F300 && code <= 0x1F64F) || // Misc Symbols (emoji)
+        (code >= 0x20000 && code <= 0x3FFFD)) // SIP / TIP
+        return 2;
+    return 1;
+}
+function visualWidth(s) {
+    let w = 0;
+    for (const c of s)
+        w += charColumns(c);
+    return w;
+}
+function visualPadEnd(s, cols) {
+    const pad = cols - visualWidth(s);
+    return pad > 0 ? s + " ".repeat(pad) : s;
+}
+// ── debug: set CACHE_TUI_LANG=en|zh to override auto-detection ──
+const DEBUG_LANG = typeof process !== "undefined" ? process.env?.CACHE_TUI_LANG : undefined;
+// ── language ──────────────────────────────────────────────────────
+const LANG_ZH = DEBUG_LANG
+    ? DEBUG_LANG === "zh"
+    : (() => {
+        try {
+            return Intl.DateTimeFormat().resolvedOptions().locale.startsWith("zh");
+        }
+        catch {
+            return false;
+        }
+    })();
+const T = LANG_ZH ? {
+    title: "缓存统计",
+    hit: "命中率",
+    read: "缓存读:",
+    write: "缓存写:",
+    miss: "未命中:",
+    out: "输出:",
+    cost: "费用:",
+    saved: "累计节省:",
+    model: "模型:",
+    rate: "单价:",
+    hitFolded: "命中",
+    inputRate: "输入",
+    cacheRate: "缓存",
+    tok: "tok",
+} : {
+    title: "Token Cache",
+    hit: "Hit",
+    read: "Read:",
+    write: "Write:",
+    miss: "Miss:",
+    out: "Out:",
+    cost: "Cost:",
+    saved: "Total Saved:",
+    model: "Model:",
+    rate: "Rate:",
+    hitFolded: "hit",
+    inputRate: "in",
+    cacheRate: "cache",
+    tok: "tok",
+};
+// ── color helpers ────────────────────────────────────────────────
+/** Extract { r, g, b } (0–255) from a hex string or RGBA-like object. */
+function rgb(raw) {
+    if (typeof raw === "string" && raw.startsWith("#")) {
+        const h = raw.slice(1);
+        return {
+            r: parseInt(h.slice(0, 2), 16),
+            g: parseInt(h.slice(2, 4), 16),
+            b: parseInt(h.slice(4, 6), 16),
+        };
+    }
+    if (raw && typeof raw === "object") {
+        const o = raw;
+        if (typeof o.r === "number" && typeof o.g === "number" && typeof o.b === "number") {
+            // RGBA channels may be 0-1 floats; detect and upscale.
+            const scale = o.r > 1 || o.g > 1 || o.b > 1 ? 1 : 255;
+            return {
+                r: Math.round(o.r * scale),
+                g: Math.round(o.g * scale),
+                b: Math.round(o.b * scale),
+            };
+        }
+    }
+    return null;
+}
+/** HSL saturation of an RGB color (0–1). */
+function saturation(r, g, b) {
+    const max = Math.max(r, g, b) / 255;
+    const min = Math.min(r, g, b) / 255;
+    const delta = max - min;
+    if (delta === 0)
+        return 0;
+    const L = (max + min) / 2;
+    return L <= 0.5 ? delta / (max + min) : delta / (2 - max - min);
+}
+/**
+ * If the colour's saturation exceeds `maxSat`, pull it toward grey
+ * until saturation drops to maxSat.  Returns a hex string.
+ */
+function desaturateTo(raw, maxSat, fallback) {
+    const c = rgb(raw);
+    if (!c)
+        return fallback;
+    const sat = saturation(c.r, c.g, c.b);
+    if (sat <= maxSat) {
+        // already muted — return as hex
+        return "#" + [c.r, c.g, c.b].map((v) => v.toString(16).padStart(2, "0")).join("");
+    }
+    // binary search the right amount of grey to mix in
+    let lo = 0, hi = 1;
+    for (let i = 0; i < 12; i++) {
+        const mid = (lo + hi) / 2;
+        const nr = Math.round(c.r + ((c.r * 0.299 + c.g * 0.587 + c.b * 0.114) - c.r) * mid);
+        const ng = Math.round(c.g + ((c.r * 0.299 + c.g * 0.587 + c.b * 0.114) - c.g) * mid);
+        const nb = Math.round(c.b + ((c.r * 0.299 + c.g * 0.587 + c.b * 0.114) - c.b) * mid);
+        if (saturation(nr, ng, nb) > maxSat)
+            lo = mid;
+        else
+            hi = mid;
+    }
+    const grey = c.r * 0.299 + c.g * 0.587 + c.b * 0.114;
+    const nr = Math.round(c.r + (grey - c.r) * hi);
+    const ng = Math.round(c.g + (grey - c.g) * hi);
+    const nb = Math.round(c.b + (grey - c.b) * hi);
+    return "#" + [nr, ng, nb].map((v) => Math.max(0, Math.min(255, v)).toString(16).padStart(2, "0")).join("");
+}
+// Morandi fallbacks — used when a theme colour cannot be resolved
+const FALLBACK = {
+    primary: "#8B9DAF",
+    text: "#C5C5BB",
+    muted: "#7A7A72",
+    success: "#9CAF8B",
+    warning: "#C5B88D",
+    error: "#B08A8A",
+    border: "#6B6B63",
+};
+/** Morandi ceiling — colours above this saturation get pulled down. */
+const MAX_SAT = 0.28;
+function progressBar(percent, width) {
+    const clamped = Math.max(0, Math.min(100, percent));
+    const filled = Math.round((clamped / 100) * width);
+    const empty = Math.max(0, width - filled);
+    return "\u2588".repeat(filled) + "\u2591".repeat(empty);
+}
+function fmt(n) {
+    if (n >= 1_000_000)
+        return (n / 1_000_000).toFixed(1) + "M";
+    if (n >= 10_000)
+        return Math.round(n / 1_000) + "K";
+    return n.toLocaleString("en-US");
+}
+function num(v) {
+    return typeof v === "number" && Number.isFinite(v) ? v : 0;
+}
+function fmtCost(n) {
+    if (n >= 1)
+        return "$" + n.toFixed(2);
+    if (n >= 0.01)
+        return "$" + n.toFixed(3);
+    return "$" + n.toFixed(4);
+}
+// ---------------------------------------------------------------------------
+// Sidebar component
+// ---------------------------------------------------------------------------
+const MIN_PANEL_WIDTH = 20;
+const DEFAULT_PANEL_WIDTH = 26;
+/** Horizontal space eaten by border (1+1) + padding (2+2). */
+const GUTTER = 2 + 4;
+function TokenCachePanel(props) {
+    const [panelWidth, setPanelWidth] = createSignal(DEFAULT_PANEL_WIDTH);
+    const [open, setOpen] = createSignal(true);
+    // ── scan session messages reactively ──
+    // SolidJS createMemo re-evaluates whenever the underlying
+    // api.state.session state changes — no event listener needed.
+    const data = createMemo(() => {
+        const msgs = props.api.state.session.messages(props.sessionId);
+        let input = 0;
+        let read = 0;
+        let write = 0;
+        let output = 0;
+        let cost = 0;
+        let pid = "";
+        let mid = "";
+        for (const msg of msgs) {
+            if (msg.role !== "assistant")
+                continue;
+            const t = msg.tokens;
+            input += num(t.input);
+            read += num(t.cache?.read);
+            write += num(t.cache?.write);
+            output += num(t.output);
+            cost += num(msg.cost);
+            if (msg.providerID && msg.modelID) {
+                pid = msg.providerID;
+                mid = msg.modelID;
+            }
+        }
+        // cost savings from cache hits
+        let saved = 0;
+        let inputRate = 0;
+        let cacheReadRate = 0;
+        if (read > 0 && pid && mid) {
+            for (const provider of props.api.state.provider) {
+                if (provider.id !== pid)
+                    continue;
+                const model = provider.models[mid];
+                if (!model?.cost)
+                    continue;
+                inputRate = num(model.cost.input);
+                cacheReadRate = num(model.cost.cache?.read);
+                const diff = inputRate - cacheReadRate;
+                if (diff > 0)
+                    saved = (read * diff) / 1_000_000;
+                break;
+            }
+        }
+        // `input` from the API represents fresh (non-cached) tokens.
+        // Total context = fresh + cache.read.
+        const totalInput = input + read;
+        const hitRate = totalInput > 0 ? (read / totalInput) * 100 : 0;
+        const model = mid.split("/").pop() ?? mid;
+        const hasPricing = inputRate > 0 || cacheReadRate > 0;
+        return {
+            hitRate, read, write, freshInput: input, output,
+            cost, saved, model, inputRate, cacheReadRate, hasPricing,
+            hasData: read > 0 || write > 0 || cost > 0,
+        };
+    });
+    const d = () => data();
+    // ── colours ──
+    // Pull from the current theme, auto-desaturate if too punchy,
+    // fall back to Morandi when a key is missing from the theme.
+    const pal = createMemo(() => {
+        const t = props.theme;
+        const sat = (k, fb) => desaturateTo(t[k], MAX_SAT, fb);
+        return {
+            primary: sat("primary", FALLBACK.primary),
+            text: sat("text", FALLBACK.text),
+            muted: sat("textMuted", FALLBACK.muted),
+            success: sat("success", FALLBACK.success),
+            warning: sat("warning", FALLBACK.warning),
+            error: sat("error", FALLBACK.error),
+            border: sat("border", FALLBACK.border),
+        };
+    });
+    const hitColor = createMemo(() => {
+        const r = d().hitRate;
+        if (r >= 85)
+            return pal().success;
+        if (r >= 70)
+            return pal().warning;
+        return pal().error;
+    });
+    const sep = createMemo(() => "\u2500".repeat(Math.max(1, panelWidth() - GUTTER)));
+    const barW = createMemo(() => {
+        const overhead = visualWidth(T.hit) + 1 + 2 + 1 + /*pct*/ 5 + GUTTER;
+        return Math.max(3, panelWidth() - overhead);
+    });
+    const bar = createMemo(() => progressBar(d().hitRate, barW()));
+    const pct = createMemo(() => d().hitRate.toFixed(1) + "%");
+    // left-align label, right-align value — auto-fill space between
+    const justify = (label, value, unit = "") => {
+        const gauge = panelWidth() - GUTTER;
+        const used = visualWidth(label) + visualWidth(value) + (unit ? visualWidth(unit) + 1 : 0);
+        const gap = Math.max(1, gauge - used);
+        return label + " ".repeat(gap) + value + (unit ? " " + unit : "");
+    };
+    return (_jsx(Show, { when: d().hasData, children: _jsxs("box", { border: true, borderColor: pal().border, paddingTop: 0, paddingBottom: 0, paddingLeft: 2, paddingRight: 2, flexDirection: "column", gap: 0, onSizeChange: function () {
+                const w = Math.max(MIN_PANEL_WIDTH, this.width);
+                setPanelWidth((prev) => (prev === w ? prev : w));
+            }, children: [_jsxs("text", { onMouseUp: () => setOpen((o) => !o), children: [_jsx("span", { style: { fg: pal().muted }, children: open() ? "\u25bc " : "\u25b6 " }), _jsx("span", { style: { fg: pal().primary }, children: _jsx("b", { children: T.title }) }), _jsxs(Show, { when: !open(), children: [_jsx("span", { children: " ".repeat(Math.max(1, panelWidth() - GUTTER - 2 - visualWidth(T.title) - visualWidth(pct() + " " + T.hitFolded))) }), _jsxs("span", { style: { fg: hitColor() }, children: [pct(), " ", T.hitFolded] })] })] }), _jsxs(Show, { when: open(), children: [_jsx("text", { fg: pal().muted, children: sep() }), _jsxs("text", { children: [_jsxs("span", { style: { fg: pal().text }, children: [T.hit, " "] }), _jsxs("span", { style: { fg: hitColor() }, children: ["[", bar(), "] "] }), _jsx("span", { style: { fg: pal().text }, children: pct() })] }), _jsx("text", { fg: pal().muted, children: justify(T.read, fmt(d().read), T.tok) }), _jsx("text", { fg: pal().muted, children: justify(T.write, fmt(d().write), T.tok) }), _jsx("text", { fg: pal().muted, children: justify(T.miss, fmt(d().freshInput), T.tok) }), _jsx("text", { fg: pal().muted, children: justify(T.out, fmt(d().output), T.tok) }), _jsx("text", { fg: pal().muted, children: sep() }), _jsx("text", { fg: pal().text, children: justify(T.cost, fmtCost(d().cost)) }), _jsx(Show, { when: d().saved > 0, children: _jsxs("text", { children: [_jsx("span", { style: { fg: pal().muted }, children: T.saved }), _jsx("span", { children: " ".repeat(Math.max(1, panelWidth() - GUTTER - visualWidth(T.saved) - visualWidth("~" + fmtCost(d().saved)))) }), _jsxs("span", { style: { fg: pal().success }, children: ["~", fmtCost(d().saved)] })] }) }), _jsx("text", { fg: pal().muted, children: justify(T.model, d().model) }), _jsxs(Show, { when: d().hasPricing, children: [_jsx("text", { fg: pal().muted, children: justify(T.rate, "$" + d().inputRate.toFixed(2) + "/M " + T.inputRate) }), _jsx(Show, { when: d().cacheReadRate > 0, children: _jsx("text", { fg: pal().muted, children: justify("", "$" + d().cacheReadRate.toFixed(2) + "/M " + T.cacheRate) }) })] })] })] }) }));
+}
+// ---------------------------------------------------------------------------
+// Plugin entry
+// ---------------------------------------------------------------------------
+function createSidebarSlot(api) {
+    return {
+        order: 55,
+        slots: {
+            sidebar_content(ctx, input) {
+                return (_jsx(TokenCachePanel, { theme: ctx.theme.current, api: api, sessionId: input.session_id }));
+            },
+        },
+    };
+}
+const tui = async (api) => {
+    api.slots.register(createSidebarSlot(api));
+};
+const mod = {
+    id: "opencode-visual-cache",
+    tui,
+};
+export default mod;

package/install.mjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+
+/**
+ * Install script for opencode-visual-cache.
+ *
+ * Creates or updates `~/.config/opencode/tui.jsonc` so OpenCode loads
+ * the TUI sidebar plugin.  Also optionally adds the plugin to
+ * `opencode.jsonc` for forward compatibility.
+ *
+ * Usage:
+ *   node install.mjs
+ *   npm explore opencode-cache-hit-tui -- node install.mjs
+ */
+
+import { readFile, writeFile, mkdir, access } from "node:fs/promises"
+import { constants } from "node:fs"
+import { homedir, platform } from "node:os"
+import { join, dirname } from "node:path"
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const PLUGIN_SPEC = "opencode-visual-cache"
+
+function configDir() {
+  if (platform() === "win32") {
+    return join(process.env.APPDATA ?? join(homedir(), "AppData", "Roaming"), "opencode")
+  }
+  return join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "opencode")
+}
+
+async function exists(p) {
+  try { await access(p, constants.F_OK); return true }
+  catch { return false }
+}
+
+async function readJSONC(p) {
+  const raw = await readFile(p, "utf-8")
+  // Strip single-line comments (//) outside strings — simple heuristic.
+  const stripped = raw.replace(/^\s*\/\/.*$/gm, "")
+  return JSON.parse(stripped)
+}
+
+function formatJSONC(obj) {
+  return JSON.stringify(obj, null, 2) + "\n"
+}
+
+/** Merge plugin into an existing plugin array, avoiding duplicates. */
+function mergePlugin(existing, spec) {
+  const plugins = existing.plugin ?? []
+  if (plugins.some((p) => (typeof p === "string" ? p : p[0]) === spec)) {
+    return false // already present
+  }
+  existing.plugin = [...plugins, spec]
+  return true
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const dir = configDir()
+  await mkdir(dir, { recursive: true })
+
+  // ---- tui.jsonc ----
+  const tuiPath = join(dir, "tui.jsonc")
+  let tuiChanged = false
+
+  if (await exists(tuiPath)) {
+    const cfg = await readJSONC(tuiPath)
+    tuiChanged = mergePlugin(cfg, PLUGIN_SPEC)
+    if (tuiChanged) {
+      await writeFile(tuiPath, formatJSONC(cfg))
+      console.log(`[opencode-cache-hit-tui] Added to ${tuiPath}`)
+    } else {
+      console.log(`[opencode-cache-hit-tui] Already in ${tuiPath}`)
+    }
+  } else {
+    const cfg = {
+      $schema: "https://opencode.ai/tui.json",
+      plugin: [PLUGIN_SPEC],
+    }
+    await writeFile(tuiPath, formatJSONC(cfg))
+    console.log(`[opencode-cache-hit-tui] Created ${tuiPath}`)
+    tuiChanged = true
+  }
+
+  // ---- opencode.jsonc (forward compat) ----
+  const ocPath = join(dir, "opencode.jsonc")
+  let ocChanged = false
+
+  if (await exists(ocPath)) {
+    const cfg = await readJSONC(ocPath)
+    ocChanged = mergePlugin(cfg, PLUGIN_SPEC)
+    if (ocChanged) {
+      await writeFile(ocPath, formatJSONC(cfg))
+      console.log(`[opencode-cache-hit-tui] Also added to ${ocPath}`)
+    }
+  }
+
+  // ---- done ----
+  if (tuiChanged || ocChanged) {
+    console.log("\nDone! Restart OpenCode to see the Token Cache sidebar panel.")
+  } else {
+    console.log("\nAlready installed. Restart OpenCode if you haven't yet.")
+  }
+}
+
+main().catch((err) => {
+  console.error("Install failed:", err.message)
+  process.exit(1)
+})

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "opencode-visual-cache",
+  "version": "1.0.0",
+  "description": "OpenCode TUI plugin displaying real-time token cache hit rate in the sidebar",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./tui": {
+      "import": "./src/index.tsx",
+      "config": { "enabled": true }
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "install.mjs",
+    "README.md",
+    "README_EN.md"
+  ],
+  "bin": {
+    "opencode-visual-cache": "install.mjs"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "tsc"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "tui",
+    "token",
+    "cache-hit-rate",
+    "cost-tracking"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.14.0",
+    "@opencode-ai/sdk": ">=1.14.0",
+    "@opentui/core": ">=0.2.0",
+    "@opentui/solid": ">=0.2.0",
+    "solid-js": ">=1.9.0"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.14.50",
+    "@opencode-ai/sdk": "^1.14.50",
+    "typescript": "^5.8.0"
+  }
+}

package/src/index.tsx

@@ -0,0 +1,439 @@
+/** @jsxImportSource @opentui/solid */
+
+import type { JSX } from "@opentui/solid"
+import type {
+  TuiPlugin,
+  TuiPluginApi,
+  TuiSlotContext,
+  TuiSlotPlugin,
+  TuiPluginModule,
+  TuiThemeCurrent,
+} from "@opencode-ai/plugin/tui"
+import type { AssistantMessage, Message } from "@opencode-ai/sdk"
+import { createMemo, createSignal, Show } from "solid-js"
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+// Bun / Node globals — available at runtime in the OpenCode TUI process
+declare const process: { env: Record<string, string | undefined> } | undefined
+
+// ── terminal-width helpers ────────────────────────────────────────
+// CJK characters occupy 2 terminal columns; padEnd/padStart count
+// string length (=1 per char), which breaks alignment with mixed text.
+
+function charColumns(c: string): number {
+  const code = c.codePointAt(0) ?? 0
+  if (code < 0x20) return 0                              // control
+  if (code < 0x7F) return 1                              // ASCII
+  if (code < 0xA0) return 0                              // C1 controls
+  // East-Asian wide / fullwidth ranges
+  if ((code >= 0x1100 && code <= 0x115F) ||              // Hangul Jamo
+      (code >= 0x2E80 && code <= 0xA4CF) ||              // CJK Radicals … Yi
+      (code >= 0xAC00 && code <= 0xD7A3) ||              // Hangul
+      (code >= 0xF900 && code <= 0xFAFF) ||              // CJK Compat
+      (code >= 0xFE10 && code <= 0xFE6F) ||              // Vertical / Compat
+      (code >= 0xFF01 && code <= 0xFF60) ||              // Fullwidth
+      (code >= 0xFFE0 && code <= 0xFFE6) ||              // Fullwidth signs
+      (code >= 0x1F300 && code <= 0x1F64F) ||            // Misc Symbols (emoji)
+      (code >= 0x20000 && code <= 0x3FFFD))              // SIP / TIP
+    return 2
+  return 1
+}
+
+function visualWidth(s: string): number {
+  let w = 0; for (const c of s) w += charColumns(c); return w
+}
+
+function visualPadEnd(s: string, cols: number): string {
+  const pad = cols - visualWidth(s)
+  return pad > 0 ? s + " ".repeat(pad) : s
+}
+
+// ── debug: set CACHE_TUI_LANG=en|zh to override auto-detection ──
+const DEBUG_LANG = typeof process !== "undefined" ? process.env?.CACHE_TUI_LANG : undefined
+
+// ── language ──────────────────────────────────────────────────────
+
+const LANG_ZH = DEBUG_LANG
+  ? DEBUG_LANG === "zh"
+  : (() => {
+      try { return Intl.DateTimeFormat().resolvedOptions().locale.startsWith("zh") }
+      catch { return false }
+    })()
+
+const T = LANG_ZH ? {
+  title:      "缓存统计",
+  hit:        "命中率",
+  read:       "缓存读:",
+  write:      "缓存写:",
+  miss:       "未命中:",
+  out:        "输出:",
+  cost:       "费用:",
+  saved:      "累计节省:",
+  model:      "模型:",
+  rate:       "单价:",
+  hitFolded:  "命中",
+  inputRate:  "输入",
+  cacheRate:  "缓存",
+  tok:        "tok",
+} as const : {
+  title:      "Token Cache",
+  hit:        "Hit",
+  read:       "Read:",
+  write:      "Write:",
+  miss:       "Miss:",
+  out:        "Out:",
+  cost:       "Cost:",
+  saved:      "Total Saved:",
+  model:      "Model:",
+  rate:       "Rate:",
+  hitFolded:  "hit",
+  inputRate:  "in",
+  cacheRate:  "cache",
+  tok:        "tok",
+} as const
+
+// ── color helpers ────────────────────────────────────────────────
+
+/** Extract { r, g, b } (0–255) from a hex string or RGBA-like object. */
+function rgb(raw: unknown): { r: number; g: number; b: number } | null {
+  if (typeof raw === "string" && raw.startsWith("#")) {
+    const h = raw.slice(1)
+    return {
+      r: parseInt(h.slice(0, 2), 16),
+      g: parseInt(h.slice(2, 4), 16),
+      b: parseInt(h.slice(4, 6), 16),
+    }
+  }
+  if (raw && typeof raw === "object") {
+    const o = raw as Record<string, unknown>
+    if (typeof o.r === "number" && typeof o.g === "number" && typeof o.b === "number") {
+      // RGBA channels may be 0-1 floats; detect and upscale.
+      const scale = o.r > 1 || o.g > 1 || o.b > 1 ? 1 : 255
+      return {
+        r: Math.round(o.r * scale),
+        g: Math.round(o.g * scale),
+        b: Math.round(o.b * scale),
+      }
+    }
+  }
+  return null
+}
+
+/** HSL saturation of an RGB color (0–1). */
+function saturation(r: number, g: number, b: number): number {
+  const max = Math.max(r, g, b) / 255
+  const min = Math.min(r, g, b) / 255
+  const delta = max - min
+  if (delta === 0) return 0
+  const L = (max + min) / 2
+  return L <= 0.5 ? delta / (max + min) : delta / (2 - max - min)
+}
+
+/**
+ * If the colour's saturation exceeds `maxSat`, pull it toward grey
+ * until saturation drops to maxSat.  Returns a hex string.
+ */
+function desaturateTo(raw: unknown, maxSat: number, fallback: string): string {
+  const c = rgb(raw)
+  if (!c) return fallback
+  const sat = saturation(c.r, c.g, c.b)
+  if (sat <= maxSat) {
+    // already muted — return as hex
+    return "#" + [c.r, c.g, c.b].map((v) => v.toString(16).padStart(2, "0")).join("")
+  }
+  // binary search the right amount of grey to mix in
+  let lo = 0, hi = 1
+  for (let i = 0; i < 12; i++) {
+    const mid = (lo + hi) / 2
+    const nr = Math.round(c.r + ((c.r * 0.299 + c.g * 0.587 + c.b * 0.114) - c.r) * mid)
+    const ng = Math.round(c.g + ((c.r * 0.299 + c.g * 0.587 + c.b * 0.114) - c.g) * mid)
+    const nb = Math.round(c.b + ((c.r * 0.299 + c.g * 0.587 + c.b * 0.114) - c.b) * mid)
+    if (saturation(nr, ng, nb) > maxSat) lo = mid
+    else hi = mid
+  }
+  const grey = c.r * 0.299 + c.g * 0.587 + c.b * 0.114
+  const nr = Math.round(c.r + (grey - c.r) * hi)
+  const ng = Math.round(c.g + (grey - c.g) * hi)
+  const nb = Math.round(c.b + (grey - c.b) * hi)
+  return "#" + [nr, ng, nb].map((v) => Math.max(0, Math.min(255, v)).toString(16).padStart(2, "0")).join("")
+}
+
+// Morandi fallbacks — used when a theme colour cannot be resolved
+const FALLBACK = {
+  primary: "#8B9DAF",
+  text:    "#C5C5BB",
+  muted:   "#7A7A72",
+  success: "#9CAF8B",
+  warning: "#C5B88D",
+  error:   "#B08A8A",
+  border:  "#6B6B63",
+} as const
+
+/** Morandi ceiling — colours above this saturation get pulled down. */
+const MAX_SAT = 0.28
+
+function progressBar(percent: number, width: number): string {
+  const clamped = Math.max(0, Math.min(100, percent))
+  const filled = Math.round((clamped / 100) * width)
+  const empty = Math.max(0, width - filled)
+  return "\u2588".repeat(filled) + "\u2591".repeat(empty)
+}
+
+function fmt(n: number): string {
+  if (n >= 1_000_000) return (n / 1_000_000).toFixed(1) + "M"
+  if (n >= 10_000) return Math.round(n / 1_000) + "K"
+  return n.toLocaleString("en-US")
+}
+
+function num(v: unknown): number {
+  return typeof v === "number" && Number.isFinite(v) ? v : 0
+}
+
+function fmtCost(n: number): string {
+  if (n >= 1) return "$" + n.toFixed(2)
+  if (n >= 0.01) return "$" + n.toFixed(3)
+  return "$" + n.toFixed(4)
+}
+
+// ---------------------------------------------------------------------------
+// Sidebar component
+// ---------------------------------------------------------------------------
+
+const MIN_PANEL_WIDTH = 20
+const DEFAULT_PANEL_WIDTH = 26
+/** Horizontal space eaten by border (1+1) + padding (2+2). */
+const GUTTER = 2 + 4
+
+function TokenCachePanel(props: {
+  theme: TuiThemeCurrent
+  api: TuiPluginApi
+  sessionId: string
+}): JSX.Element {
+  const [panelWidth, setPanelWidth] = createSignal(DEFAULT_PANEL_WIDTH)
+  const [open, setOpen] = createSignal(true)
+
+  // ── scan session messages reactively ──
+  // SolidJS createMemo re-evaluates whenever the underlying
+  // api.state.session state changes — no event listener needed.
+  const data = createMemo(() => {
+    const msgs = props.api.state.session.messages(props.sessionId) as Message[]
+
+    let input = 0
+    let read = 0
+    let write = 0
+    let output = 0
+    let cost = 0
+    let pid = ""
+    let mid = ""
+
+    for (const msg of msgs) {
+      if (msg.role !== "assistant") continue
+      const t = (msg as AssistantMessage).tokens
+      input += num(t.input)
+      read   += num(t.cache?.read)
+      write  += num(t.cache?.write)
+      output += num(t.output)
+      cost   += num((msg as AssistantMessage).cost)
+      if ((msg as AssistantMessage).providerID && (msg as AssistantMessage).modelID) {
+        pid = (msg as AssistantMessage).providerID
+        mid = (msg as AssistantMessage).modelID
+      }
+    }
+
+    // cost savings from cache hits
+    let saved = 0
+    let inputRate = 0
+    let cacheReadRate = 0
+    if (read > 0 && pid && mid) {
+      for (const provider of props.api.state.provider) {
+        if (provider.id !== pid) continue
+        const model = provider.models[mid]
+        if (!model?.cost) continue
+        inputRate = num(model.cost.input)
+        cacheReadRate = num(model.cost.cache?.read)
+        const diff = inputRate - cacheReadRate
+        if (diff > 0) saved = (read * diff) / 1_000_000
+        break
+      }
+    }
+
+    // `input` from the API represents fresh (non-cached) tokens.
+    // Total context = fresh + cache.read.
+    const totalInput = input + read
+    const hitRate = totalInput > 0 ? (read / totalInput) * 100 : 0
+    const model = mid.split("/").pop() ?? mid
+    const hasPricing = inputRate > 0 || cacheReadRate > 0
+
+    return {
+      hitRate, read, write, freshInput: input, output,
+      cost, saved, model, inputRate, cacheReadRate, hasPricing,
+      hasData: read > 0 || write > 0 || cost > 0,
+    }
+  })
+
+  const d = () => data()
+
+  // ── colours ──
+  // Pull from the current theme, auto-desaturate if too punchy,
+  // fall back to Morandi when a key is missing from the theme.
+  const pal = createMemo(() => {
+    const t = props.theme as Record<string, unknown>
+    const sat = (k: string, fb: string) => desaturateTo(t[k], MAX_SAT, fb)
+    return {
+      primary:   sat("primary",   FALLBACK.primary),
+      text:      sat("text",      FALLBACK.text),
+      muted:     sat("textMuted", FALLBACK.muted),
+      success:   sat("success",   FALLBACK.success),
+      warning:   sat("warning",   FALLBACK.warning),
+      error:     sat("error",     FALLBACK.error),
+      border:    sat("border",    FALLBACK.border),
+    }
+  })
+
+  const hitColor = createMemo(() => {
+    const r = d().hitRate
+    if (r >= 85) return pal().success
+    if (r >= 70) return pal().warning
+    return pal().error
+  })
+
+  const sep = createMemo(() => "\u2500".repeat(Math.max(1, panelWidth() - GUTTER)))
+  const barW = createMemo(() => {
+    const overhead = visualWidth(T.hit) + 1 + 2 + 1 + /*pct*/5 + GUTTER
+    return Math.max(3, panelWidth() - overhead)
+  })
+  const bar = createMemo(() => progressBar(d().hitRate, barW()))
+  const pct = createMemo(() => d().hitRate.toFixed(1) + "%")
+
+  // left-align label, right-align value — auto-fill space between
+  const justify = (label: string, value: string, unit = ""): string => {
+    const gauge = panelWidth() - GUTTER
+    const used = visualWidth(label) + visualWidth(value) + (unit ? visualWidth(unit) + 1 : 0)
+    const gap = Math.max(1, gauge - used)
+    return label + " ".repeat(gap) + value + (unit ? " " + unit : "")
+  }
+
+  return (
+    <Show when={d().hasData}>
+      <box
+        border
+        borderColor={pal().border}
+        paddingTop={0}
+        paddingBottom={0}
+        paddingLeft={2}
+        paddingRight={2}
+        flexDirection="column"
+        gap={0}
+        onSizeChange={function () {
+          const w = Math.max(MIN_PANEL_WIDTH, this.width)
+          setPanelWidth((prev) => (prev === w ? prev : w))
+        }}
+      >
+        {/* collapsible header */}
+        <text onMouseUp={() => setOpen((o) => !o)}>
+          <span style={{ fg: pal().muted }}>{open() ? "\u25bc " : "\u25b6 "}</span>
+          <span style={{ fg: pal().primary }}><b>{T.title}</b></span>
+          <Show when={!open()}>
+            <span>
+              {" ".repeat(Math.max(1, panelWidth() - GUTTER - 2 - visualWidth(T.title) - visualWidth(pct() + " " + T.hitFolded)))}
+            </span>
+            <span style={{ fg: hitColor() }}>{pct()} {T.hitFolded}</span>
+          </Show>
+        </text>
+
+        <Show when={open()}>
+          <text fg={pal().muted}>{sep()}</text>
+
+          {/* hit rate + bar — inline to avoid box spacing */}
+          <text>
+            <span style={{ fg: pal().text }}>{T.hit} </span>
+            <span style={{ fg: hitColor() }}>[{bar()}] </span>
+            <span style={{ fg: pal().text }}>{pct()}</span>
+          </text>
+
+          {/* token breakdown */}
+          <text fg={pal().muted}>
+            {justify(T.read,  fmt(d().read),         T.tok)}
+          </text>
+          <text fg={pal().muted}>
+            {justify(T.write, fmt(d().write),        T.tok)}
+          </text>
+          <text fg={pal().muted}>
+            {justify(T.miss,  fmt(d().freshInput),   T.tok)}
+          </text>
+          <text fg={pal().muted}>
+            {justify(T.out,   fmt(d().output),       T.tok)}
+          </text>
+
+          <text fg={pal().muted}>{sep()}</text>
+
+          {/* cost */}
+          <text fg={pal().text}>
+            {justify(T.cost,  fmtCost(d().cost))}
+          </text>
+
+          {/* saved */}
+          <Show when={d().saved > 0}>
+            <text>
+              <span style={{ fg: pal().muted }}>{T.saved}</span>
+              <span>{" ".repeat(Math.max(1, panelWidth() - GUTTER - visualWidth(T.saved) - visualWidth("~" + fmtCost(d().saved))))}</span>
+              <span style={{ fg: pal().success }}>~{fmtCost(d().saved)}</span>
+            </text>
+          </Show>
+
+          {/* model */}
+          <text fg={pal().muted}>
+            {justify(T.model, d().model)}
+          </text>
+
+          {/* rates */}
+          <Show when={d().hasPricing}>
+            <text fg={pal().muted}>
+              {justify(T.rate, "$" + d().inputRate.toFixed(2) + "/M " + T.inputRate)}
+            </text>
+            <Show when={d().cacheReadRate > 0}>
+              <text fg={pal().muted}>
+                {justify("", "$" + d().cacheReadRate.toFixed(2) + "/M " + T.cacheRate)}
+              </text>
+            </Show>
+          </Show>
+        </Show>
+      </box>
+    </Show>
+  )
+}
+
+// ---------------------------------------------------------------------------
+// Plugin entry
+// ---------------------------------------------------------------------------
+
+function createSidebarSlot(api: TuiPluginApi): TuiSlotPlugin {
+  return {
+    order: 55,
+    slots: {
+      sidebar_content(ctx: TuiSlotContext, input: { session_id: string }): JSX.Element {
+        return (
+          <TokenCachePanel
+            theme={ctx.theme.current}
+            api={api}
+            sessionId={input.session_id}
+          />
+        )
+      },
+    },
+  }
+}
+
+const tui: TuiPlugin = async (api: TuiPluginApi) => {
+  api.slots.register(createSidebarSlot(api))
+}
+
+const mod: TuiPluginModule & { id: string } = {
+  id: "opencode-visual-cache",
+  tui,
+}
+
+export default mod