opencode-cache-guard

An opencode plugin that warns you when sending a message on a session whose Anthropic prompt cache has likely expired.

The problem

Anthropic caches your prompt context for up to 60 minutes. When you return to a long-running session after that window, the next message silently re-sends the entire context as cache_write instead of the cheap cache_read — which can be 10-20x more expensive per token and adds latency. With large contexts (100K+ tokens on Opus or Sonnet) this can cost a few dollars you didn't intend to spend.

What this plugin does

On every send, it checks:

1. Is this an Anthropic model session?
2. Has it been more than 55 minutes since the last response?
3. Was there more than 10K tokens in cache (read + write from the last turn)?

If all three are true, it blocks the send, shows a warning with the idle time, token count, and estimated extra cost, and lets you hit Enter again to proceed (or /clear to start fresh).

Installation

// ~/.config/opencode/opencode.json
{
  "plugin": [
    "file:///home/you/.config/opencode/private_plugins/opencode-cache-guard"
  ]
}

Then bun install in this directory.

Current limitation

Ideally this plugin would warn the moment you switch to a stale session, not when you send. Unfortunately, the opencode SDK does not currently emit an event when the user switches sessions in the TUI — session navigation is handled internally without publishing to the plugin event bus.

This is a known gap tracked in anomalyco/opencode#5409. We've also submitted PR #20997 that wires up the existing tui.session.select bus event from the session dialog as a minimal step in that direction. Once either lands, this plugin will be updated to warn on session load instead.

How the warning looks

error: Cache expired (~73min idle, ~141K tokens at risk) — extra cost ~$1.27. Enter again to send, or /clear for fresh session.

The error line blocks the send. Hit Enter again and it goes through — warningSent is set for that idle window and won't fire again until a new response completes and resets it.

Configuration

Constants in src/constants.ts:

Constant	Default	Meaning
CACHE_TTL_MS	55 min	Warn threshold (Anthropic TTL is 60 min; 5 min headroom)
WARN_THRESHOLD	10,000 tokens	Below this, extra cost is negligible

Pricing table

Hardcoded in src/pricing.ts based on Anthropic's published rates:

Family	cache_read $/MTok	cache_write $/MTok
opus	$0.50	$10.00
sonnet	$0.30	$6.00
haiku	$0.10	$2.00

Cost estimate is skipped for Claude Max plan users (detected by checking if the model's cache_write cost is zeroed by the auth plugin).