cache-timer

library1.2.0jsnpmunverified

A TUI plugin for OpenCode that displays a live countdown timer until the prompt-cache expires, letting you know when your cache is hot, warning, cold, or busy-cold. It provides one-click buttons to refresh the cache (keeps it hot) or fork a new session (when cache is cold), reducing costly cold-write operations. Version 1.2.0, actively maintained. Differentiators: pre-emptive cache saving, smart cost-based button logic, minimal configuration.

productivity

npm install cache-timer

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CACHE-TIMER

cache-timer

productivityjavascriptv1.2.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import cacheTimerPlugin from 'cache-timer'

✗ const cacheTimerPlugin = require('cache-timer')

The package is ESM-only; CommonJS require will fail.

CacheTimerPlugin

✓ import { CacheTimerPlugin } from 'cache-timer'

✗ const { CacheTimerPlugin } = require('cache-timer')

Named export available for TypeScript users; can be used as the plugin class.

CacheTimerConfig

✓ import type { CacheTimerConfig } from 'cache-timer'

Type import for configuration object. Only needed in TypeScript.

Configure and enable the cache-timer plugin in an OpenCode config file, showing all options with defaults.

// file: opencode.config.js import cacheTimerPlugin from 'cache-timer' export default { plugins: [ cacheTimerPlugin({ hotThreshold: 300, // cache considered hot if >300 seconds remaining (default: 300) warningThreshold: 60, // warning color when <=60 seconds (default: 60) refreshMargin: 120, // auto-refresh when <=120 seconds left (default: 0, disabled) seedContext: { lastMessages: 2, // include last 2 user/assistant messages in new session (default: 1) recentFiles: 5, // include up to 5 recent read file paths (default: 3) }, summarizeContext: false, // experimental: summarize context before forking (default: false) }), ], }

Debug

Known issues

breakingVersion 1.0.0 changed the plugin interface from a plain object to a function that must be called with config.

fix

Update your config: replace `cacheTimerPlugin` with `cacheTimerPlugin({ ... })`.

affects: <1.0.0

gotchaThe plugin only works with OpenCode's TUI mode; it will not function in headless or CLI-only mode.

fix

Ensure you're running OpenCode with TUI enabled (opencode --tui).

affects: >=0.0.0

gotchaAuto-refresh (refreshMargin) may incur costs if the cache is already cold; the plugin does not check cache status before sending a no-op prompt.

fix

Set refreshMargin to 0 (default) and rely on manual refresh to avoid accidental cold writes.

affects: >=0.0.0

gotchaThe 'summarizeContext' option is experimental and may produce long summaries that negate cost savings.

fix

Leave summarizeContext disabled unless you have tested its impact on your workflows.

affects: >=1.2.0

gotchaSeeding a new session may fail if the source session has a model that is no longer available.

fix

Ensure the model from the source session is still supported before forking.

affects: >=1.0.0

Errors

Common errors & fixes

ERR_MODULE_NOT_FOUND: Cannot find package 'cache-timer'

Package not installed or installed in wrong location.

fix

Run `npm install cache-timer --save-dev` in your OpenCode plugin directory.

TypeError: cacheTimerPlugin is not a function

CommonJS require() used instead of ESM import, or mismatch between package exports.

fix

Use `import cacheTimerPlugin from 'cache-timer'` in an ESM context.

Plugin 'cache-timer' requires OpenCode TUI mode.

Running OpenCode without TUI (e.g., --cli flag).

fix

Start OpenCode with `opencode --tui` or without the --cli flag.

Upgrade

Version history

1.2.0latest on npm

Audit

Dependencies

opencodeoptionalRuntime peer dependency; plugin is a TUI extension for OpenCode.

Agent activity

29 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/ncejda-g2/opencode-cache-timer ↗

packagecache-timer ↗

homepagehttps://github.com/ncejda-g2/opencode-cache-timer#readme ↗