OpenCode TUI sidebar plugin for prompt cache hit rate, token usage, and cost—with first-class sub-agent (child session) rollup. Standalone by default (main + sub-agents in one panel). Optional coexistence with opencode-visual-cache.

Languages: English (this file) · 简体中文 · Documentation

opencode-visual-cache already covers main-session cache visualization (token distribution, savings, slash-driven settings). This project exists because that scope does not fit several real workflows:

1. Sub-agent visibility — OpenCode spawns child sessions for Task / explore agents; you need rolled-up cache, tokens, and cost per sub-session, not only the main thread.
2. One panel for the whole session — Main session Hit/tokens/cost and a collapsible Agents section for sub-agent rollup.
3. Analysis off the TUI — Optional timeline JSONL (per assistant turn) for charts, jq, and billing post-mortems without scraping platform logs.
4. Shared TUI building blocks — src/tui-panel/ extracted so other sidebar plugins can reuse the same layout language as visual-cache.

Roadmap items (sidebar Timeline section, metric windows, nested sub-agents) are described in docs/en/timeline.md and docs/en/design.md.

This plugin is not part of opencode-visual-cache. Its sidebar layout, panel components (src/tui-panel/), and coexistence patterns are heavily inspired by opencode-visual-cache. visual-cache focuses on main-session context / token distribution; cache-hit focuses on per-turn metrics and sub-agent totals.

The cache TTL feature (elapsed time display with color-coded status) is inspired by opencode-cache-timer by nero-sensei. The original plugin provides a standalone sidebar countdown for prompt cache expiration; this plugin integrates the concept directly into the cache-hit panel.

• Cache hit rate: session total + per-turn rate with trend (↑ / ↓ / -) on the main block
• Token breakdown: cache read / write / miss / output (aligned rows with visual-cache)
• Cost: session cost with multi-currency config (USD, CNY, EUR, GBP, JPY); per-million rates and cache savings from provider config
• Sub-agents: Agents section rolls up child sessions only (scope labeled in UI); each row shows model name + session ID suffix with vendor-tinted label (cost in muted gray)
• Main + Agents: main block always shown; Agents section when sub-agents exist (foldable)
• Collapsible sections: Detail / Model (and Agents); theme-adaptive hit bar colors
• i18n: display.lang — en / zh / auto via config (no slash commands yet)
• Timeline (optional): daily JSONL per assistant turn for jq / scripts

Standalone use is the default (main + sub-agents in one panel). Layout patterns were inspired by visual-cache; that package is not required.

Ctrl+P → type install plugin → press Tab to switch scope to global (default is local) → type opencode-cache-hit@latest → press Enter.

Global plugins install to ~/.cache/opencode/packages/opencode-cache-hit@latest/. Create config at ~/.config/opencode/cache-hit.json:

Create or edit ~/.config/opencode/tui.json / tui.jsonc:

{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": ["opencode-cache-hit@latest"]
}

Local development: use "./plugins/opencode-cache-hit" instead of the npm name.

Copy cache-hit.config.example.json → ~/.config/opencode/cache-hit.json (recommended) or next to the plugin root. Restart OpenCode after changing plugin code or config.

Load errors: ~/.local/share/opencode/log/ (search cache-hit or failed to load tui plugin).

{
  "currency": "CNY",
  "costUnit": "USD",
  "rate": 7.2
}

Use "currency": "USD", "costUnit": "USD" when no conversion is needed.

Supported display currencies in config: USD, CNY, EUR, GBP, JPY (see cache-hit.config.example.json). Runtime slash switching like visual-cache’s /cache-currency is not implemented yet.

"display": {
  "lang": "en",
  "panelBorder": true
}

Agents totals sum child sessions only, not the main session (see agentsScopeHint). Main session metrics stay in the block above; collapse Agents to save space. Per-child rows use the same model slug as the main Model line (truncated when the sidebar is narrow); see docs/en/design.md § Sub-agent row display.

Per assistant turn → JSONL. docs/en/timeline.md · 中文.

"timeline": {
  "enabled": true,
  "dir": "",
  "rotateMaxBytes": 16777216,
  "retainRotated": 5,
  "maxAgeDays": 30,
  "maxLogFiles": 20
}

LOG=~/.config/opencode/plugins/opencode-cache-hit/logs/timeline-$(date +%Y-%m-%d).jsonl
tail -f "$LOG"
# time fields are ISO 8601 strings with local timezone (e.g. "2024-05-30T08:00:00.000+08:00")
jq -r 'select(.rootSessionId=="YOUR_ROOT") | [.created,.scope,.hitPercent,.cost]|@tsv' "$LOG"

Retention details: Rotation and retention. Charts: scripts/README.md.

Shows how long the prompt cache has been alive. Color changes when exceeding TTL:

• Green: elapsed < TTL
• Yellow: TTL ≤ elapsed < 2×TTL
• Red: elapsed ≥ 2×TTL

"cacheTTL": {
  "enabled": true,
  "providers": {
    "anthropic": "5m",
    "openai": "5m",
    "deepseek": "2h",
    "google": "1h"
  }
}

Built-in defaults (used when provider not in config):

Default TTL: 5 minutes for all providers not listed above. Color changes based on elapsed time vs TTL: green (< TTL), yellow (TTL-2x TTL), red (≥ 2x TTL).

OpenCode may cache plugins at first install and not auto-refresh npm versions.

rm -rf ~/.cache/opencode/packages/opencode-cache-hit@latest

Then reinstall via Ctrl+P → install plugin, and restart OpenCode.

Model-agnostic: any OpenCode provider that exposes assistant tokens / cost on messages (DeepSeek, Claude, GPT, etc.). Data comes from the OpenCode session API, same as visual-cache.

Requires OpenCode with TUI plugin slots (@opencode-ai/plugin ≥ 1.14). Works alongside visual-cache; no extra dependencies at runtime beyond peers in package.json.

index.tsx
cache-hit.config.example.json
src/
  plugin.tsx              # sidebar_content slot
  sidebar-host.tsx        # messages, child sync, timeline
  widget.tsx
  stats.ts / timeline/ / tui-panel/
tests/

bun test

See CONTRIBUTING.md for setup, PR notes, and npm publishing. Architecture: docs/en/design.md.

MIT