Context quality scoring, smart compaction, and session continuity for OpenCode. Full parity with the Claude Code Token Optimizer plugin.

Token Optimizer monitors your OpenCode sessions and helps you get the most out of your context window:

• 7-signal quality scoring with dual ResourceHealth (monotonic) + SessionEfficiency (rolling window) architecture
• Smart compaction with mode-aware PRESERVE/DROP guidance (code/debug/review/infra/general)
• Session continuity that restores context from prior sessions via keyword matching
• Quality nudges that warn when context health drops, fill exceeds thresholds, or retry loops are detected
• Dashboard with quality trends, session history, and daily aggregates
• token_status tool for on-demand quality reports
• token_dashboard tool to generate and open the visual dashboard

Add the plugin to your opencode.json (or .opencode/opencode.jsonc) plugin array. OpenCode resolves and installs it from npm on the next launch:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["token-optimizer-opencode"]
}

The plugin array holds npm package names as plain strings — that is OpenCode's config schema. No separate install command is needed.

If you can't (or don't want to) install from npm, clone the repo and run the bundled installer. It builds a single-file plugin and copies it into ~/.config/opencode/plugins/, which OpenCode auto-loads at startup:

git clone https://github.com/alexgreensh/token-optimizer.git
token-optimizer/install.sh --opencode

Requires bun (OpenCode's own runtime). Re-run after a git pull to update.

The npm plugin (token-optimizer-opencode) is runtime-only: it ships the hook bridge and tooling OpenCode loads at startup. The skill content (SKILL.md, references, scripts) lives in ~/.claude/skills/token-optimizer/, which OpenCode loads directly. Updating the npm plugin does NOT refresh that tree — they are independent channels.

To refresh the skill content (after a git pull, or if SKILL.md references look stale / [file not found]), re-run the standard installer — the Claude-side flow with no --opencode flag. It owns the ~/.claude/skills tree:

token-optimizer/install.sh

That flow verifies the skill payload is complete and repairs a partial checkout in place. (install.sh --opencode only rebuilds the OpenCode runtime bundle in ~/.config/opencode/plugins/ — it does not touch the skill tree.)

OpenCode's plugin array takes package-name strings only — it does not accept an inline options object, and a ["name", { … }] tuple will fail config validation and stop OpenCode from starting. Configure Token Optimizer through environment variables instead (full list below):

# Example: widen the quality window and disable loop detection
export TOKEN_OPTIMIZER_QUALITY_WINDOW=30
export TOKEN_OPTIMIZER_LOOP_DETECTION=false

All settings are optional; defaults are shown in the table below.

Override any threshold via environment variables:

The quality score uses a dual-composite architecture:

ResourceHealth (monotonic, can only decrease within a session):

• Context fill degradation (50%) - MRCR-curve-based quality estimate
• Compaction depth (30%) - information loss from repeated compaction
• Absolute waste tokens (20%) - stale reads + bloated results

SessionEfficiency (rolling window, can rise or fall):

• Stale reads (30%) - re-reading files after writing them
• Bloated results (30%) - large tool outputs never referenced
• Decision density (20%) - ratio of substantive messages
• Agent efficiency (20%) - agent dispatch result/prompt ratio

Grades: S (90+), A (80+), B (70+), C (55+), D (40+), F (<40)

Context window sizes are mapped for 30+ models across all major providers: Anthropic (Opus/Sonnet 1M, Haiku 200K), OpenAI (GPT-5.x, GPT-4.1, o3/o4), Google (Gemini 2.x/3.x), DeepSeek, Qwen, Mistral, xAI Grok, and more.

MRCR quality curves are calibrated per model family for accurate fill-degradation estimates.

PolyForm Noncommercial 1.0.0