tui-monthly-usage

An opencode TUI plugin that adds a monthly usage and cost breakdown widget to your sidebar.

Preview

Here is how the widget looks in the opencode sidebar:

Features

• Daily & Weekly Totals: Live spend tracking for today and the current week.
• Monthly Summary: Total cost and token usage for the active calendar month.
• Model Breakdown: Top models sorted by monthly spend or token count, highest first, with a configurable row count and friendly shortened model names.
• Local Database Discovery: Uses OpenCode's local data directory and respects OPENCODE_DB overrides.

Requirements

• sqlite3 CLI version 3.33 or newer installed and available in $PATH (JSON output is required)
• OpenCode with TUI plugin support

Installation

opencode plugin add @jurci/tui-monthly-usage

Configuration

Add the plugin to ~/.config/opencode/cli.json:

{
  "$schema": "https://opencode.ai/v2/cli.json",
  "plugins": [
    "@jurci/tui-monthly-usage"
  ]
}

To change the model count, ranking, estimated costs, or set a monthly budget, use an options object:

{
  "$schema": "https://opencode.ai/v2/cli.json",
  "plugins": [
    { "package": "@jurci/tui-monthly-usage", "options": { "maxModels": 10, "sortBy": "tokens", "monthlyBudget": 1500 } }
  ]
}

• maxModels: Non-negative integer. Defaults to 7; 0 hides model rows.
• sortBy: "cost" (default) or "tokens". The highest value is always first; ties use the other value, then the model name.
• costMultipliers: Optional provider-to-multiplier map for company discounts or markups. Costs use OpenCode's recorded estimate by default (1). For example, "openai": 0.8 applies a 20% discount to OpenAI rows before totals, rankings, and model costs are calculated. Token counts are unchanged.
• monthlyBudget: Optional positive USD amount. When set, the heading shows the rounded budget percentage, and the month row compares adjusted tracked spend with the budget. Monthly tokens move to their own row. OpenCode records cost estimates in USD; no currency conversion is performed.
• Totals always include all models, regardless of the row limit.

Local Development

Build with npm run build, then add the built dist directory to cli.json for local development or testing without publishing to npm:

{
  "$schema": "https://opencode.ai/v2/cli.json",
  "plugins": [
    "/path/to/tui-monthly-usage-plugin/dist"
  ]
}

Quit and restart OpenCode after changing the plugin configuration or rebuilding it.

The widget reads the local database, normally $XDG_DATA_HOME/opencode/opencode.db or ~/.local/share/opencode/opencode.db. OPENCODE_DB can be an absolute path or a path relative to the opencode data directory. For a channel-specific database, set OPENCODE_DB to that database's filename. A remote server's database and an in-memory database cannot be read by this local SQLite subprocess.

Cost and Token Limitations

This widget reports usage recorded by OpenCode in its local database, not your provider's billing statement. By default, its costs are OpenCode's estimates using OpenCode's configured standard model rates; company discounts, negotiated rates, and provider billing adjustments are not detected automatically. Use costMultipliers when you know a provider-specific adjustment. It only includes activity recorded by this local OpenCode installation.

For subscription-based access, such as signing in with a ChatGPT account, monetary costs may be zero or unavailable. $0.00 does not necessarily mean the usage was free. Token counts can still appear when the provider reports them and OpenCode stores them. ChatGPT subscriptions and API usage are billed separately.

The widget does not show subscription fees, remaining plan allowance, or reset times.

With the default cost sorting, zero-cost subscription models may fall below the displayed row limit. Set sortBy to "tokens" or increase maxModels to make them easier to find.

Development

Development requires Node.js, npm, and sqlite3. The build and TUI tests run Bun 1.3.3 through npx.

# Install dependencies
npm install

# Typecheck and build TypeScript to dist/
npm run build

# Run unit and integration tests
npm test

# Run only the TUI rendering test (after building)
npm run test:tui

# Typecheck without emitting
npm run typecheck

License

MIT