@alex123bob/opencode-cache-stats 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander Li
+
+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,71 @@
+# opencode-cache-stats
+
+An [opencode](https://opencode.ai) plugin that displays a live **cache hit rate** widget
+in the TUI sidebar and writes per-turn stats to a JSONL file.
+
+## Install
+
+```bash
+npm i opencode-cache-stats
+```
+
+Then add to `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "plugin": ["opencode-cache-stats"]
+}
+```
+
+Restart opencode. After the first assistant response, the right-column sidebar shows:
+
+```
+── Cache ─────────────────────
+  Hit rate:  68.9%
+  Read:      1,240 tok
+  Written:     512 tok
+  Raw input:   308 tok
+  Output:      320 tok
+  Turns:           3
+```
+
+## Stats file
+
+Each completed turn appends one JSON line to:
+
+```
+~/.config/opencode/cache-stats.jsonl
+```
+
+Example record:
+
+```json
+{"ts":"2026-07-13T10:23:01.000Z","sessionID":"ses_abc123","providerID":"anthropic","modelID":"claude-sonnet-4-6","turn":3,"cacheRead":1240,"cacheWrite":512,"inputRaw":308,"output":320,"totalInput":2060,"hitRate":60.2}
+```
+
+## Cache hit rate definition
+
+```
+hitRate = cacheRead / (cacheRead + cacheWrite + inputRaw) × 100
+```
+
+This is the fraction of total input tokens served from cache rather than processed fresh.
+
+## Provider compatibility
+
+| Provider | cache read | cache write |
+|---|---|---|
+| Anthropic | Yes | Yes |
+| OpenAI | Yes | Conditional |
+| Google Vertex / Gemini | Yes | No |
+| Amazon Bedrock | Yes | Yes |
+| Groq | Yes | No |
+| xAI (Grok) | Yes | No |
+| Mistral | Yes | No |
+| Cohere | No | No |
+
+When cache data is unavailable the sidebar shows `No cache data` instead of a misleading 0%.
+
+## License
+
+MIT

package/dist/chunk-OFH6IIJI.js

@@ -0,0 +1,88 @@
+import { mkdirSync, appendFileSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+
+// src/shared.ts
+var STATS_FILE = join(homedir(), ".config", "opencode", "cache-stats.jsonl");
+function computeHitRate(cacheRead, totalInput) {
+  if (totalInput <= 0) return 0;
+  return Math.round(cacheRead / totalInput * 1e3) / 10;
+}
+function fmt(n) {
+  return n.toLocaleString();
+}
+function renderCacheStats(stats) {
+  if (!stats) return "";
+  const totalInput = stats.cacheRead + stats.cacheWrite + stats.inputRaw;
+  const sep = "\u2500\u2500 Cache " + "\u2500".repeat(20);
+  if (totalInput <= 0) {
+    return [
+      sep,
+      `  No cache data (turn ${stats.turnCount})`,
+      `  (provider may not report cache tokens)`
+    ].join("\n");
+  }
+  const hitRate = computeHitRate(stats.cacheRead, totalInput);
+  const lines = [
+    sep,
+    `  Hit rate:  ${hitRate.toFixed(1)}%`,
+    `  Read:      ${fmt(stats.cacheRead)} tok`
+  ];
+  if (stats.cacheWrite > 0) {
+    lines.push(`  Written:   ${fmt(stats.cacheWrite)} tok`);
+  }
+  lines.push(
+    `  Raw input: ${fmt(stats.inputRaw)} tok`,
+    `  Output:    ${fmt(stats.output)} tok`,
+    `  Turns:     ${stats.turnCount}`
+  );
+  return lines.join("\n");
+}
+var _statsDirEnsured = false;
+function appendJsonl(record) {
+  try {
+    if (!_statsDirEnsured) {
+      mkdirSync(join(homedir(), ".config", "opencode"), { recursive: true });
+      _statsDirEnsured = true;
+    }
+    appendFileSync(STATS_FILE, JSON.stringify(record) + "\n", "utf8");
+  } catch {
+  }
+}
+function extractTokens(info) {
+  return {
+    cacheRead: info?.tokens?.cache?.read ?? 0,
+    cacheWrite: info?.tokens?.cache?.write ?? 0,
+    inputRaw: info?.tokens?.input ?? 0,
+    output: info?.tokens?.output ?? 0,
+    providerID: info?.providerID ?? "unknown",
+    modelID: info?.modelID ?? "unknown"
+  };
+}
+function isCompletedAssistant(event) {
+  if (event?.type !== "message.updated") return false;
+  const info = event?.properties?.info;
+  return info?.role === "assistant" && !!info?.time?.completed && !!info?.sessionID;
+}
+function accumulateStats(prev, tokens) {
+  const base = prev ?? {
+    cacheRead: 0,
+    cacheWrite: 0,
+    inputRaw: 0,
+    output: 0,
+    turnCount: 0,
+    providerID: tokens.providerID,
+    modelID: tokens.modelID
+  };
+  return {
+    cacheRead: base.cacheRead + tokens.cacheRead,
+    cacheWrite: base.cacheWrite + tokens.cacheWrite,
+    inputRaw: base.inputRaw + tokens.inputRaw,
+    output: base.output + tokens.output,
+    turnCount: base.turnCount + 1,
+    providerID: tokens.providerID,
+    modelID: tokens.modelID
+  };
+}
+
+export { accumulateStats, appendJsonl, computeHitRate, extractTokens, isCompletedAssistant, renderCacheStats };

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+import { Plugin } from '@opencode-ai/plugin';
+import { TuiPlugin } from '@opencode-ai/plugin/tui';
+
+declare const server: Plugin;
+declare const tui: TuiPlugin;
+declare const id = "opencode-cache-stats";
+declare const _default: {
+    id: string;
+    server: Plugin;
+    tui: TuiPlugin;
+};
+
+export { _default as default, id, server, tui };

package/dist/index.js

@@ -0,0 +1,39 @@
+import { isCompletedAssistant, extractTokens, accumulateStats, computeHitRate, appendJsonl } from './chunk-OFH6IIJI.js';
+
+// src/index.ts
+var server = async (_input) => {
+  const sessionStats = /* @__PURE__ */ new Map();
+  return {
+    event: async ({ event }) => {
+      if (!isCompletedAssistant(event)) return;
+      const info = event.properties.info;
+      const sessionID = info.sessionID;
+      const tokens = extractTokens(info);
+      const next = accumulateStats(sessionStats.get(sessionID), tokens);
+      sessionStats.set(sessionID, next);
+      const totalInput = tokens.cacheRead + tokens.cacheWrite + tokens.inputRaw;
+      const record = {
+        ts: (/* @__PURE__ */ new Date()).toISOString(),
+        sessionID,
+        providerID: tokens.providerID,
+        modelID: tokens.modelID,
+        turn: next.turnCount,
+        cacheRead: tokens.cacheRead,
+        cacheWrite: tokens.cacheWrite,
+        inputRaw: tokens.inputRaw,
+        output: tokens.output,
+        totalInput,
+        hitRate: computeHitRate(tokens.cacheRead, totalInput)
+      };
+      appendJsonl(record);
+    }
+  };
+};
+var tui = async (...args) => {
+  const mod = await import('./tui.js');
+  return mod.tui(...args);
+};
+var id = "opencode-cache-stats";
+var src_default = { id, server, tui };
+
+export { src_default as default, id, server, tui };

package/dist/tui.d.ts

@@ -0,0 +1,5 @@
+import { TuiPlugin } from '@opencode-ai/plugin/tui';
+
+declare const tui: TuiPlugin;
+
+export { tui as default, tui };

package/dist/tui.js

@@ -0,0 +1,70 @@
+import { isCompletedAssistant, extractTokens, accumulateStats, renderCacheStats } from './chunk-OFH6IIJI.js';
+
+// src/tui.ts
+var tui = async (api) => {
+  const sessionStats = /* @__PURE__ */ new Map();
+  const listeners = /* @__PURE__ */ new Set();
+  const bump = () => {
+    for (const fn of listeners) fn();
+  };
+  const subscribe = (fn) => {
+    listeners.add(fn);
+    return () => listeners.delete(fn);
+  };
+  const offMessage = api.event.on("message.updated", (evt) => {
+    if (!isCompletedAssistant(evt)) return;
+    const info = evt.properties.info;
+    const sessionID = info.sessionID;
+    const tokens = extractTokens(info);
+    sessionStats.set(sessionID, accumulateStats(sessionStats.get(sessionID), tokens));
+    bump();
+  });
+  let offSlots;
+  try {
+    let CacheStatsText2 = function(props) {
+      const sessionID = props.sessionID;
+      const propApi = props.api;
+      const propSub = props.subscribe;
+      if (!propSub || !propApi) return null;
+      let textNode;
+      const sync = () => {
+        if (!textNode) return;
+        const content = renderCacheStats(sessionStats.get(sessionID));
+        textNode.content = content;
+        textNode.visible = content.length > 0;
+        textNode.height = content.length > 0 ? "auto" : 0;
+        propApi.renderer.requestRender();
+      };
+      onCleanup(propSub(sync));
+      return jsx("text", {
+        ref: (ref) => {
+          textNode = ref;
+          sync();
+        },
+        fg: propApi.theme.current.textMuted,
+        children: renderCacheStats(sessionStats.get(sessionID)) ?? ""
+      });
+    };
+    var CacheStatsText = CacheStatsText2;
+    const { jsx } = await import('@opentui/solid/jsx-runtime');
+    const { onCleanup } = await import('solid-js');
+    const registration = api.slots.register({
+      slots: {
+        sidebar_content: (_ctx, slotProps) => jsx(CacheStatsText2, {
+          sessionID: slotProps.session_id ?? "",
+          api,
+          subscribe
+        })
+      }
+    });
+    offSlots = typeof registration === "function" ? registration : void 0;
+  } catch {
+  }
+  api.lifecycle.onDispose(() => {
+    offMessage();
+    offSlots?.();
+  });
+};
+var tui_default = tui;
+
+export { tui_default as default, tui };

package/package.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "name": "@alex123bob/opencode-cache-stats",
+  "version": "1.0.1",
+  "description": "opencode plugin — live cache hit rate widget in the TUI sidebar + per-session JSONL stats log",
+  "type": "module",
+  "author": "Alexander Li",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alex123bob/opencode-cache-stats.git"
+  },
+  "homepage": "https://github.com/alex123bob/opencode-cache-stats#readme",
+  "bugs": {
+    "url": "https://github.com/alex123bob/opencode-cache-stats/issues"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./tui": {
+      "types": "./dist/tui.d.ts",
+      "import": "./dist/tui.js",
+      "default": "./dist/tui.js"
+    }
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "keywords": ["opencode", "plugin", "cache", "llm", "tui", "cache-hit-rate"],
+  "engines": { "node": ">=22.13" },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm run build"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.15.0 <2",
+    "@opentui/core": ">=0.4.0 <0.5",
+    "@opentui/solid": ">=0.4.0 <0.5",
+    "solid-js": ">=1.9.0 <2"
+  },
+  "peerDependenciesMeta": {
+    "@opentui/core": { "optional": true },
+    "@opentui/solid": { "optional": true },
+    "solid-js": { "optional": true }
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.17.18",
+    "@opentui/core": "^0.4.3",
+    "@opentui/solid": "^0.4.3",
+    "@types/node": "^24.0.0",
+    "solid-js": "^1.9.14",
+    "tsup": "^8.5.1",
+    "typescript": "^5.8.3"
+  }
+}