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.

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

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
• all - Show all breakdowns

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

# Generate example config based on your usage
opencode-tokens config init

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

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 all models for a provider
2. Provider-specific model config - Custom pricing for the same model under different providers
3. User model config - Generic custom model pricing in config file
4. Built-in pricing - Default pricing table
5. Fallback - $1/M input, $4/M output

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

# Link for local testing
npm link
cd ~/.config/opencode
npm link opencode-token-tracker

License

MIT © tongsh6

Related

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