Skip to content

README_EN.md

Latest commit

 

History

History
287 lines (206 loc) · 14.5 KB

README_EN.md

File metadata and controls

287 lines (206 loc) · 14.5 KB
Raw

OpenCode Visual Cache

Real-time Token Cache Hit Rate · TUI Sidebar Visualization
Adaptive Theme Colors · Auto-desaturated · Chinese / English

If you find this plugin useful, a ⭐ would mean a lot — thank you!

GitHub Stars License 中文 NPM Version

Interested in sub-agent monitoring? Check out opencode-subagent-magazine!

1. Screenshots

Collapsed 👇
Expanded 👇

2. Features

  • Cache Hit Rate: Real-time hit rate with adaptive-width progress bar and trend indicator
  • Token Detail: Cache read / write / miss / output, left-aligned labels, right-aligned values
  • Cost & Savings: Session cumulative cost plus cache-hit savings
  • Model Pricing: Input / cache-read / cache-write per-million rates (read from provider config dynamically)
  • Collapsible: Main title collapsed by default; click to expand. Detail, model, and distribution sections fold independently
  • Adaptive Colors: ≥85% green · ≥70% orange · <70% red, auto-desaturated from current theme
  • Token Distribution: Per-role (system / user / sub-agent instr / tool call / tool result) estimated token breakdown
  • Persistent State: Fold preferences and config remembered across restarts via api.kv
  • Language: Chinese / English / 日本語 / 한국어, auto-detects system locale, with /cache-lang for runtime switching — user preference takes priority over auto-detection
  • Multi-currency: Switch via /cache-currency — costs, savings, and per-million rates convert in real time
  • Balance Query: Query account balance across multiple AI providers, with auto-switch following the current session's provider
  • Slash Commands: /cache-session /cache-session-back /cache-rate /cache-section /cache-config /cache-lang for live panel configuration
  • Sub-Agent Cache View: /cache-session auto-scans and lists sub-agents; select one to switch the panel stats. Use /cache-session-back to return to the main session
  • Loaded Skills: Detects skill tool calls in the session and displays loaded skill names with estimated token footprint
  • Bottom Status Bar: single-line hit rate (with trend) · Tokens · Balance in the prompt hint row — visible even with the sidebar closed. Off by default on opencode 1.x (turning it on requires a TUI restart, see 4.3); shown by default on opencode 2.x

3. Installation

This plugin supports both opencode 1.x and 2.x.

3.1 opencode 2.x

opencode 2.x manages TUI plugins through the plugins array in cli.json; after adding an entry, it is installed and loaded automatically on the next start.

Create or edit ~/.config/opencode/cli.json and append the following entry to the plugins array:

{
  "plugins": [
    {
      "package": "opencode-visual-cache@latest",
      "options": {
        "enabled": true
      }
    }
  ]
}

If the file already contains other plugins or settings, just append this object entry to the existing plugins array.

Note: Do not install this plugin with opencode plugin add. That command writes the entry to opencode.jsonc (used for server plugins), which makes the server fail to load it:

Plugin must export a default definition with an id and an effect or setup function.

If you already installed it that way:

  1. Open ~/.config/opencode/opencode.jsonc and remove this plugin from the plugins array
  2. Declare it in the plugins array of cli.json as described above
  3. Restart opencode

Troubleshooting: If the plugin does not take effect, clear the plugin cache and restart. The V2 cache lives in ~/.cache/opencode/npm, and the V1 cache in ~/.cache/opencode/packages.

3.2 opencode 1.x

Option 1: Command (recommended)

Press Ctrl + P in OpenCode to open the command palette, search install plugin, then type:

opencode-visual-cache@latest

Press Enter to install and configure automatically.

Option 2: Manual

  1. Install the plugin
npm install -g opencode-visual-cache@latest
  1. Configure the TUI plugin — create or edit ~/.config/opencode/tui.jsonc:
{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": ["opencode-visual-cache@latest"]
}

3.3 Restart OpenCode

Open any session — the cache stats panel appears in the sidebar.

4. Usage Guide

4.1 Slash Commands

The plugin supports slash commands and command palette (Ctrl + P) for runtime configuration. Changes take effect immediately and are persisted (the Bottom Bar toggle is the exception on opencode 1.x — see 4.3 Section Visibility):

Command Function How to use
/cache-session View sub-agent cache stats Lists sub-agents automatically, or paste a Session ID to switch the panel data source
/cache-session-back Return to main session Switch back to main session from sub-agent cache view
/cache-currency Switch currency Pick from a list (USD / CNY / EUR / JPY / GBP / KRW); default exchange rate auto-filled
/cache-rate Adjust exchange rate Enter a custom rate (e.g. 7.2 for CNY)
/cache-section Toggle sections & border Independently show/hide Detail, Model & Pricing, Token Distribution, Loaded Skills, Balance, Bottom Bar, or the panel border (Bottom Bar is off by default on opencode 1.x; turning it on requires a TUI restart)
/cache-config View current config Displays currency, rate, and section visibility
/cache-lang Switch display language Pick Chinese or English from the dialog — takes effect immediately, no restart needed
/cache-balance Balance query settings Pick a balance provider (menu shows key source: user key / OpenCode / not set) / toggle auto-switch
/cache-balance-key Set balance API key Two-step flow: pick a provider → enter the API key
Slash command Ctrl+P command palette

Switching currency automatically applies a built-in approximate exchange rate (USD-based). Override it anytime with /cache-rate.

4.2 Currency & Exchange Rate

Cost display supports multiple currencies:

Code Symbol Default rate (1 USD = ?)
USD $ 1
CNY ¥ 7.2
EUR € 0.92
JPY JP¥ 150
GBP £ 0.79
KRW ₩ 1350

The rate applies to session cost, cache savings, and per-million pricing — consistently across the panel.

Base currency: The plugin assumes all provider pricing is in USD. Major AI APIs (OpenAI / Anthropic / Google / DeepSeek / xAI etc.) use USD for their international endpoints. If your provider bills in CNY or another currency, set the exchange rate to 1.

4.3 Section Visibility

Three sub-sections can be toggled independently to save sidebar space:

  • Token Detail: cache read / write / miss / output
  • Model & Pricing: cost / provider / model name / per-million rates
  • Estimated Token Dist.: per-role token breakdown
  • Loaded Skills: skill names the LLM actually loaded via the skill tool, with estimated token counts
  • Balance: the selected provider's account balance (multi-provider with auto-switch)
  • Bottom Status Bar: the single-line hit rate · Tokens · Balance stats in the prompt hint row (off by default on opencode 1.x)

Toggled via /cache-section — takes effect instantly with no restart (the Bottom Status Bar is the exception, see below). The same command also toggles the panel border; turning it off removes the outline and padding so content fills the full width.

The Bottom Bar is off by default on opencode 1.x; turning it on requires a TUI restart: on opencode 1.x the hint row can only carry the bar by rebuilding the host's session_prompt slot, and that slot uses replace mode — every rebuilder's output is rendered side by side. If another plugin rebuilds session_prompt as well (e.g. oh-my-openagent), you get duplicate input boxes. This plugin therefore does not claim that slot by default, and the hint row shows the host's default path.

Run /cache-section to turn the Bottom Bar on and restart the TUI to show the stats (this claims the slot and is mutually exclusive with such plugins). opencode 2.x uses a dedicated prompt.footer.status slot, so there is no such conflict and the bar is shown by default.

About Token Dist. values: "Reasoning" is an exact value from the API; the other rows (system / user / sub-agent instr / tool call / tool result) are estimates — the API only reports total token counts, not how they split across content types, so the plugin collects text per content type and approximates via character counting. Values are indicative only. OpenCode runtime-injected system prompt content (environment info, skill catalog, tool schema definitions — see system.ts, tools.ts) is not covered by these estimates.

4.4 Balance Query

The panel can display account balance from multiple AI providers. With auto-switch enabled, the balance query follows the model provider of the current session automatically.

Supported balance providers:

Provider Balance endpoint Currency Key prefix Status
DeepSeek https://api.deepseek.com/user/balance CNY / USD sk- ✅ Supported
SiliconFlow https://api.siliconflow.cn/v1/user/info CNY sk- ✅ Supported
OpenRouter https://openrouter.ai/api/v1/credits USD sk-or- ✅ Supported
Moonshot https://api.moonshot.cn/v1/users/me/balance CNY sk- ✅ Supported
Zhipu GLM Pending (community-reversed endpoint, unofficial) CNY — ⏳ Planned
xAI Pending (requires Management Key + Team ID) USD — ⏳ Planned

Key source: a key set manually via /cache-balance-key takes priority; otherwise the plugin reuses the credential OpenCode already authenticated (/connect-configured providers). Providers with neither cannot show a balance.

Key storage: manually configured API keys are stored in plaintext in the plugin's persistent KV — avoid using on shared devices.

Auto-switch: enabled by default; picking a provider manually disables it — re-enable anytime via /cache-balance. Auto-switch matches the current session's model provider; a provider without a key shows a "not set" hint when selected.

Planned: candidates confirmed feasible by research, not yet implemented. Zhipu GLM only has a community-reversed unofficial endpoint (no stability guarantee).

Metric semantics: hit rate = cache read / (fresh input + cache read + cache write), consistent with the industry (OpenAI / Anthropic / Bedrock). "Miss" in the detail view = fresh input + cache write. The bottom-bar Tokens is the input-side total (output excluded). Providers that do not report cache writes separately (e.g. DeepSeek) automatically fall back to the hit/miss formula.

Balance display: the sidebar and bottom bar share the same balance data, so both show identical values. When the current provider has no balance adapter, the sidebar shows a hint and the bottom bar hides the balance segment.

5. Update

Due to a known OpenCode issue #6774, the plugin cache locks to the version installed at first setup and does not auto-detect newer releases on npm.

To update:

1. Clear the OpenCode plugin cache

# Windows
Remove-Item -Recurse -Force "$env:USERPROFILE\.cache\opencode\packages\opencode-visual-cache@latest"
# macOS / Linux
rm -rf ~/.cache/opencode/packages/opencode-visual-cache@latest

2. Re-install the plugin

Press Ctrl + P in OpenCode → install plugin → opencode-visual-cache@latest → Enter

3. Restart OpenCode

6. Language Settings

The plugin provides three ways to control the display language, listed by priority (highest first):

6.1 Runtime Switching (recommended)

Type /cache-lang in the TUI and select Chinese / English / 日本語 / 한국어 from the dialog. The panel switches immediately without restarting. Your preference is persisted and takes priority over auto-detection on the next launch.

6.2 Environment Variable Override

Set the CACHE_TUI_LANG environment variable before launching to force a specific language (zh / en / ja / ko):

# Windows PowerShell
$env:CACHE_TUI_LANG="en"; opencode
# macOS / Linux
CACHE_TUI_LANG=en opencode

6.3 Auto Detection

Defaults to the system locale automatically. If it doesn't match, switch once with /cache-lang and the preference will be remembered.

7. 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.

8. License

MIT