opencode-context-gauge-plugin

An OpenCode TUI sidebar plugin that shows a live context-window usage gauge for the active session.

🧠 ████████▋░░░░░░░░░░░░ 43%
18.4k / 200k · 💰 $0.53

Features

• Context gauge — eighth-block progress bar showing used tokens vs. the active model's context window
• Token accounting — uses the authoritative total from the latest assistant message, falling back to component totals and session aggregates
• Cost display — session spend alongside token counts (optional)
• Threshold colors — bar turns warning/danger colored as you approach the window limit (theme-aware)
• Configurable — label, bar width, thresholds, cost visibility

Install

opencode plugin --global @davidaayers/opencode-context-gauge-plugin

Or from inside OpenCode: press ctrl+p → "Install Plugin" → @davidaayers/opencode-context-gauge-plugin. The command patches tui.json for you; restart OpenCode and the gauge appears in the sidebar once the session has a completed assistant response.

Version 0.1.2 warning: npm 0.1.2 can overstate context when cache counters are added to an already-aggregated total. Upgrade to the latest release for the fix.

The npm package ships a compiled TUI entrypoint that shares OpenCode's Solid/OpenTUI renderer.

From source

OpenCode TUI plugins load from the plugin array in ~/.config/opencode/tui.json (or a project-level tui.json) — not from opencode.jsonc, whose plugin array is server-side only. Adding a TUI-only module to opencode.jsonc will make the server fail to load it.

// ~/.config/opencode/tui.json
{
  "plugin": [
    "file:///absolute/path/to/opencode-context-gauge-plugin/src/context-gauge.tsx"
  ]
}

Notes

OpenCode also ships a built-in context section in the sidebar. If you'd rather only see this one, press ctrl+p → Plugins and toggle the built-in context plugin off. The choice persists across restarts.

Configuration

Pass options using the [spec, options] tuple form (spec being the npm package name or a file:// path):

{
  "plugin": [
    [
      "@davidaayers/opencode-context-gauge-plugin",
      {
        "label": "Context",
        "barWidth": 20,
        "warnAt": 70,
        "dangerAt": 90,
        "showCost": true
      }
    ]
  ]
}

| Option | Type | Default | Description | | --------- | ----------------- | ---------- | ------------------------------------------------------------------ | | label | string \| false | "🧠" | Gauge label; set to false to hide | | barWidth| number | 20 | Bar width in cells (clamped 4–60) | | warnAt | number | 70 | Percent at which the bar switches to the warning color | | dangerAt| number | 90 | Percent at which the bar switches to the danger color (clamped > warnAt) | | showCost| boolean | true | Show session cost after token counts |

How It Works

• Used tokens: matches OpenCode's built-in context section: the most recent assistant message with output uses input + output + reasoning + cache.read + cache.write. Before any responses exist, session-level token/cost aggregates are used.
• Context window: resolved from the message's (or session's) provider/model via provider.models[modelID].limit.context. The widget hides itself if no context limit is known.
• Rendering: SolidJS JSX via @opentui/solid, registered into the sidebar_content slot through @opencode-ai/plugin/tui. Colors come from the active OpenCode theme (accent / warning / error).

Development

pnpm install
pnpm check
pnpm build

Plugin logic lives in src/context-gauge.tsx. build.mjs compiles its JSX to dist/tui.js for npm; prepack builds it automatically for publishing. From-source installs can still use the .tsx file directly.

Roadmap

Cross-repository follow-up work is tracked in the OpenCode Plugins project.

Releases

Releases are managed by Release Please from Conventional Commit messages. Merging a Release Please pull request bumps the version, updates CHANGELOG.md, creates the GitHub release and tag, and publishes the package to npm.

See CHANGELOG.md for release history.

Before the first automated release, configure npm Trusted Publishing for @davidaayers/opencode-context-gauge-plugin with:

• GitHub organization or user: davidaayers
• Repository: opencode-context-gauge-plugin
• Workflow filename: release-please.yml
• Environment: leave empty

The v0.1.1 baseline tag is already in place at commit 65f68a753babf7f12fe1618ff01ac14c20b5a77f.

Credits

Inspired by streetturtle/opencode-better-sidebar — a great collection of OpenCode sidebar plugins; its context-progress plugin planted the seed for this one.

License

MIT © 2026 David Ayers