opencode-token-tracker

Real-time token usage and cost tracking plugin for OpenCode.

English | 简体中文

Features

• Real-time Toast notifications - See token usage and cost after each AI response
• Budget control - Set daily/weekly/monthly spending limits with warnings
• Session statistics - Track cumulative usage across your entire session
• CLI statistics tool - Query usage by day/week/month with breakdowns by model/agent
• Cost calculation - Automatic cost estimation based on model pricing
• JSONL logging - All usage data saved locally for analysis
• Multi-model support - Claude, GPT, DeepSeek, Gemini, and more

AI Engineering Framework

This project uses the AI Engineering Framework (AIEF) to organize AI collaboration context and conventions.

• AGENTS.md defines repository-level collaboration rules
• context/ stores technical snapshots, coding conventions, and business semantics

If you are building AI-assisted engineering workflows, we strongly recommend adopting AIEF in your own repositories for clearer context management and more consistent agent outputs.

Accuracy & Limitations

• Costs are estimates, computed locally from your token logs and the built-in (or user-configured) pricing table. They may differ from your provider's official invoice — for example, when promotional credits, discounts, or enterprise pricing structures apply.
• Budgets are warnings, not enforcement. This plugin does not block API calls, throttle requests, or interrupt active sessions. It is designed purely as an observability and tracking tool.
• Subscription or bundled providers (such as GitHub Copilot, Cursor, etc.) or free local models should be configured with zero-cost overrides in your configuration file (see Configuration).
• Pricing freshness: The built-in pricing table is manually maintained. Please run opencode-tokens models to inspect which of your used models currently fall back to the default pricing, and configure overrides if necessary.

Installation

Add to your OpenCode config file (~/.config/opencode/opencode.json):

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

Restart OpenCode and the plugin will be automatically installed.

Usage

For an end-to-end setup and verification path, see walkthrough.md.

Toast Notifications

Once installed, you'll see Toast notifications after each AI response:

12.5K tokens
$0.023 | Session: $0.156

When budget limits are configured, you'll see warnings:

⚠️ Budget exceeded!
Daily: $5.50/$5.00 (110%)

When a session becomes idle, you'll see a summary:

Session: 45.2K tokens
$0.156 | 8 msgs | 5min

Budget Control

Set spending limits to avoid unexpected costs:

# Check current budget status
opencode-tokens budget

Example output:

  Budget Status
  ══════════════════════════════════════════════════════════════════

  🟢 Daily
    $3.50 / $10.00  [███████░░░░░░░░░░░░░] 35%
    Remaining: $6.50

  🟡 Weekly
    $42.00 / $50.00  [████████████████░░░░] 84%
    Remaining: $8.00

  🟢 Monthly
    $120.00 / $200.00  [████████████░░░░░░░░] 60%
    Remaining: $80.00

  Legend: 🟢 OK  🟡 Warning (>80%)  🔴 Exceeded

Configure budget in ~/.config/opencode/token-tracker.json:

{
  "budget": {
    "daily": 10,      // $10 per day
    "weekly": 50,     // $50 per week
    "monthly": 200,   // $200 per month
    "warnAt": 0.8     // Warn at 80% usage
  }
}

CLI Statistics

Query your token usage from the command line:

# All-time summary
opencode-tokens

# Today's usage
opencode-tokens today

# This week's usage with model breakdown
opencode-tokens week --by model

# This month with all breakdowns
opencode-tokens month --by all

# Day-by-day breakdown
opencode-tokens --by daily

Example output:

  Today's Usage
  ──────────────────────────────────────────────────
  Total Tokens:           2.81M
    Input:                2.74M
    Output:               72.9K
    Reasoning:             7.1K
  Cache Read:            12.62M
  Total Cost:            $32.93
  Messages:                 230

  By Model
  ─────────────────────────────────────────────────────
  Model                Tokens        Cost    Msgs
  ---------------  ----------  ----------  ------
  claude-opus-4.5       2.70M      $32.93     206
  deepseek-chat         23.4K     $0.0025       6
  gpt-5.2               86.9K     $0.0000      18

Breakdown options (--by):

• model - Group by model (e.g., claude-opus-4.5)
• agent - Group by agent (e.g., sisyphus, coder)
• provider - Group by provider (e.g., anthropic, openai)
• daily - Show day-by-day breakdown
• session - Group by session ID
• all - Show all breakdowns

Trend Chart

Visualize your daily token usage and cost over time:

# 30-day cost trend (default)
opencode-tokens trend

# 7-day token count trend
opencode-tokens trend --days 7 --metric tokens

# Compact chart
opencode-tokens trend --width 40

Options:

• --days N — Number of days to chart (default 30)
• --metric — cost (default), tokens, or messages
• --width W — Chart width in characters (default 60)

Data Export

Export your token usage data for analysis:

# Export all data as CSV
opencode-tokens export

# Export this month as JSON
opencode-tokens export --format json --period month

# Export to file
opencode-tokens export --format csv --output usage.csv

Options:

• --format — csv (default) or json
• --period — today, week, month, all (default)
• --output FILE — Write to file instead of stdout

Config Management

Manage budget and toast settings directly from the CLI:

# Show current config
opencode-tokens config

# Set daily budget to $10
opencode-tokens config set budget.daily 10

# Disable toast notifications
opencode-tokens config set toast.enabled false

# Check a value
opencode-tokens config get budget.warnAt

# Reset to default
opencode-tokens config unset budget.daily

Settable keys:

• budget.daily, budget.weekly, budget.monthly, budget.warnAt
• toast.enabled, toast.duration, toast.showOnIdle

Config changes are automatically backed up to token-tracker.json.bak.

Pricing & Config Commands

# Check budget status
opencode-tokens budget

# Show built-in pricing table
opencode-tokens pricing

# Show your used models and their pricing status
opencode-tokens models

# Show current config
opencode-tokens config

# Print clean example JSON to stdout without writing a file
opencode-tokens config init

# Write example config to ~/.config/opencode/token-tracker.json
# Existing config is backed up to token-tracker.json.bak
opencode-tokens config generate

Example models output:

  Model                     Provider              Msgs  Pricing     
  ------------------------  ----------------  --------  ------------
  claude-opus-4.5           github-copilot         379  provider cfg
  deepseek-chat             deepseek                 6  built-in    
  gpt-5.2                   openai                  18  built-in    

This helps you understand:

• Which models/providers you're using
• Whether pricing is from built-in table, your config, or default fallback
• What to add to your config file

config init is safe for piping because stdout contains only valid JSON and no file is written. config generate is the file-writing path: stdout stays empty, guides and status messages go to stderr, the parent directory is created when needed, and an existing config is backed up before overwrite.

Log Files

Token usage is logged to:

~/.config/opencode/logs/token-tracker/tokens.jsonl

Each line is a JSON object:

{
  "type": "tokens",
  "sessionId": "ses_xxx",
  "messageId": "msg_xxx",
  "agent": "build",
  "model": "claude-opus-4.5",
  "provider": "github-copilot",
  "input": 1500,
  "output": 350,
  "reasoning": 0,
  "cacheRead": 5000,
  "cacheWrite": 0,
  "cost": 0.0234,
  "_ts": 1234567890123
}

Supported Models

Unknown models use a default pricing estimate.

Configuration

Create a config file at ~/.config/opencode/token-tracker.json:

{
  "providers": {
    "github-copilot": { "input": 0, "output": 0 }
  },
  "models": {
    "my-custom-model": { "input": 1, "output": 2 }
  },
  "toast": {
    "enabled": true,
    "duration": 3000,
    "showOnIdle": true
  },
  "budget": {
    "daily": 10,
    "weekly": 50,
    "monthly": 200,
    "warnAt": 0.8
  }
}

Budget Settings

When you exceed a budget limit:

• Toast notifications change to warning/error style
• Use opencode-tokens budget to check detailed status
• Budgets reset at midnight (daily), Monday (weekly), or 1st of month (monthly)

Pricing Fields Explained

All prices are in USD per 1 million tokens:

How to find pricing for your model:

1. Check the provider's official pricing page:

   • Anthropic Claude
   • OpenAI
   • DeepSeek
   • Google Gemini

2. Or run opencode-tokens pricing to see built-in prices

Common scenarios:

Pricing Override

Pricing is resolved in this order (first match wins):

1. Provider-level override - Override all models for a provider
2. Exact user model config - Custom pricing for a specific model or provider-specific model entry
3. Built-in exact match - Exact key in the built-in pricing table
4. Built-in partial match - Longest matching built-in key for variant model names
5. User model partial match - Longest matching user config key
6. Fallback - $1/M input, $4/M output

Exact user config is intentionally checked before built-ins, while broad partial user keys are checked after built-ins so a generic key like "claude" does not accidentally override a precise built-in model price.

Example: Free providers

If you're using GitHub Copilot or other subscription-based services, set their cost to $0:

{
  "providers": {
    "github-copilot": { "input": 0, "output": 0 },
    "cursor": { "input": 0, "output": 0 }
  }
}

Example: Custom model pricing

Override or add pricing for specific models (prices in USD per 1M tokens):

{
  "models": {
    "claude-opus-4.5": { "input": 12, "output": 60, "cacheRead": 1.2 },
    "my-local-model": { "input": 0, "output": 0 }
  }
}

Example: Same model, different provider pricing

If the same model has different prices under different providers, nest provider names under the model key:

{
  "models": {
    "deepseek/deepseek-v4-flash": {
      "openrouter": { "input": 0.14, "output": 0.28, "cacheRead": 0.0028 },
      "siliconflow": { "input": 0.2, "output": 0.4 }
    }
  }
}

You can still mix this with the original flat model pricing format.

Toast Settings

Development

# Clone the repo
git clone https://github.com/tongsh6/opencode-token-tracker.git
cd opencode-token-tracker

# Install dependencies
npm install

# Build
npm run build

# Unit and CLI tests
npm test

# Real local OpenCode CLI dogfood
node scripts/real-opencode-cli-smoke.mjs --use-temporary-link --model deepseek/deepseek-chat

The dogfood script is repo-only and is not published as an npm command. It verifies the real local opencode run path, including OpenCode's cache package directory, and restores any temporary package links after the run.

License

MIT © tongsh6

Related

• OpenCode - The AI coding assistant
• OpenCode Plugins - Plugin documentation
• oh-my-opencode - OpenCode enhancement plugin