opencode-token-tracker 1.0.0 → 1.2.0

package/README.md

@@ -8,6 +8,7 @@ Real-time token usage and cost tracking plugin for [OpenCode](https://opencode.a
 
 - **Real-time Toast notifications** - See token usage and cost after each AI response
 - **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
@@ -27,6 +28,8 @@ Restart OpenCode and the plugin will be automatically installed.
 
 ## Usage
 
+### Toast Notifications
+
 Once installed, you'll see Toast notifications after each AI response:
 
 ```
@@ -41,6 +44,56 @@ Session: 45.2K tokens
 $0.156 | 8 msgs | 5min
 ```
 
+### CLI Statistics
+
+Query your token usage from the command line:
+
+```bash
+# 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
+
 ## Log Files
 
 Token usage is logged to:
@@ -82,12 +135,66 @@ Unknown models use a default pricing estimate.
 
 ## Configuration
 
-Currently the plugin works out of the box with no configuration needed.
+Create a config file at `~/.config/opencode/token-tracker.json`:
+
+```json
+{
+  "providers": {
+    "github-copilot": { "input": 0, "output": 0 }
+  },
+  "models": {
+    "my-custom-model": { "input": 1, "output": 2 }
+  },
+  "toast": {
+    "enabled": true,
+    "duration": 3000,
+    "showOnIdle": true
+  }
+}
+```
+
+### Pricing Override
+
+Pricing is resolved in this order (first match wins):
+
+1. **Provider-level** - Override all models for a provider
+2. **User model config** - Custom model pricing in config file
+3. **Built-in pricing** - Default pricing table
+4. **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:
+
+```json
+{
+  "providers": {
+    "github-copilot": { "input": 0, "output": 0 },
+    "cursor": { "input": 0, "output": 0 }
+  }
+}
+```
+
+#### Example: Custom model pricing
+
+Override or add pricing for specific models:
+
+```json
+{
+  "models": {
+    "claude-opus-4.5": { "input": 12, "output": 60, "cacheRead": 1.2 },
+    "my-local-model": { "input": 0, "output": 0 }
+  }
+}
+```
+
+### Toast Settings
 
-Future versions may support:
-- Custom pricing overrides
-- Toast display options
-- Export formats
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | boolean | `true` | Show toast notifications |
+| `duration` | number | `3000` | Toast display duration (ms) |
+| `showOnIdle` | boolean | `true` | Show session summary on idle |
 
 ## Development
 

package/dist/bin/opencode-tokens.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/opencode-tokens.js

@@ -0,0 +1,289 @@
+#!/usr/bin/env node
+import { readFileSync, existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+const LOG_FILE = join(homedir(), ".config", "opencode", "logs", "token-tracker", "tokens.jsonl");
+// ============================================================================
+// Helpers
+// ============================================================================
+function formatTokens(tokens) {
+    if (tokens >= 1_000_000)
+        return `${(tokens / 1_000_000).toFixed(2)}M`;
+    if (tokens >= 1_000)
+        return `${(tokens / 1_000).toFixed(1)}K`;
+    return tokens.toString();
+}
+function formatCost(cost) {
+    if (cost < 0.01)
+        return `$${cost.toFixed(4)}`;
+    if (cost < 1)
+        return `$${cost.toFixed(3)}`;
+    return `$${cost.toFixed(2)}`;
+}
+function padRight(str, len) {
+    return str.length >= len ? str : str + " ".repeat(len - str.length);
+}
+function padLeft(str, len) {
+    return str.length >= len ? str : " ".repeat(len - str.length) + str;
+}
+function getStartOfDay(date) {
+    const d = new Date(date);
+    d.setHours(0, 0, 0, 0);
+    return d.getTime();
+}
+function getStartOfWeek(date) {
+    const d = new Date(date);
+    const day = d.getDay();
+    const diff = d.getDate() - day + (day === 0 ? -6 : 1); // Monday as start
+    d.setDate(diff);
+    d.setHours(0, 0, 0, 0);
+    return d.getTime();
+}
+function getStartOfMonth(date) {
+    const d = new Date(date);
+    d.setDate(1);
+    d.setHours(0, 0, 0, 0);
+    return d.getTime();
+}
+// ============================================================================
+// Data Loading
+// ============================================================================
+function loadEntries(since) {
+    if (!existsSync(LOG_FILE)) {
+        return [];
+    }
+    const content = readFileSync(LOG_FILE, "utf-8");
+    const lines = content.trim().split("\n").filter(Boolean);
+    const entries = [];
+    for (const line of lines) {
+        try {
+            const entry = JSON.parse(line);
+            if (entry.type !== "tokens")
+                continue;
+            if (since && entry._ts < since)
+                continue;
+            if (!entry.input && !entry.output)
+                continue; // Skip empty entries
+            entries.push(entry);
+        }
+        catch {
+            // Skip malformed lines
+        }
+    }
+    return entries;
+}
+// ============================================================================
+// Stats Aggregation
+// ============================================================================
+function createEmptyStats() {
+    return { input: 0, output: 0, reasoning: 0, cacheRead: 0, cacheWrite: 0, cost: 0, count: 0 };
+}
+function aggregateStats(entries) {
+    const stats = createEmptyStats();
+    for (const e of entries) {
+        stats.input += e.input ?? 0;
+        stats.output += e.output ?? 0;
+        stats.reasoning += e.reasoning ?? 0;
+        stats.cacheRead += e.cacheRead ?? 0;
+        stats.cacheWrite += e.cacheWrite ?? 0;
+        stats.cost += e.cost ?? 0;
+        stats.count += 1;
+    }
+    return stats;
+}
+function groupBy(entries, keyFn) {
+    const groups = new Map();
+    for (const e of entries) {
+        const key = keyFn(e);
+        if (!groups.has(key)) {
+            groups.set(key, createEmptyStats());
+        }
+        const stats = groups.get(key);
+        stats.input += e.input ?? 0;
+        stats.output += e.output ?? 0;
+        stats.reasoning += e.reasoning ?? 0;
+        stats.cacheRead += e.cacheRead ?? 0;
+        stats.cacheWrite += e.cacheWrite ?? 0;
+        stats.cost += e.cost ?? 0;
+        stats.count += 1;
+    }
+    return groups;
+}
+// ============================================================================
+// Display
+// ============================================================================
+function printSummary(title, stats) {
+    const totalTokens = stats.input + stats.output;
+    console.log();
+    console.log(`  ${title}`);
+    console.log(`  ${"─".repeat(50)}`);
+    console.log(`  Total Tokens:    ${padLeft(formatTokens(totalTokens), 12)}`);
+    console.log(`    Input:         ${padLeft(formatTokens(stats.input), 12)}`);
+    console.log(`    Output:        ${padLeft(formatTokens(stats.output), 12)}`);
+    if (stats.reasoning > 0) {
+        console.log(`    Reasoning:     ${padLeft(formatTokens(stats.reasoning), 12)}`);
+    }
+    console.log(`  Cache Read:      ${padLeft(formatTokens(stats.cacheRead), 12)}`);
+    console.log(`  Total Cost:      ${padLeft(formatCost(stats.cost), 12)}`);
+    console.log(`  Messages:        ${padLeft(stats.count.toString(), 12)}`);
+    console.log();
+}
+function printTable(title, groups, labelHeader) {
+    // Sort by cost descending
+    const sorted = Array.from(groups.entries()).sort((a, b) => b[1].cost - a[1].cost);
+    if (sorted.length === 0) {
+        console.log(`\n  No data for ${title}\n`);
+        return;
+    }
+    // Calculate column widths
+    const labelWidth = Math.max(labelHeader.length, ...sorted.map(([k]) => k.length));
+    const tokensWidth = 10;
+    const costWidth = 10;
+    const countWidth = 6;
+    console.log();
+    console.log(`  ${title}`);
+    console.log(`  ${"─".repeat(labelWidth + tokensWidth + costWidth + countWidth + 12)}`);
+    // Header
+    console.log(`  ${padRight(labelHeader, labelWidth)}  ${padLeft("Tokens", tokensWidth)}  ${padLeft("Cost", costWidth)}  ${padLeft("Msgs", countWidth)}`);
+    console.log(`  ${"-".repeat(labelWidth)}  ${"-".repeat(tokensWidth)}  ${"-".repeat(costWidth)}  ${"-".repeat(countWidth)}`);
+    // Rows
+    for (const [label, stats] of sorted) {
+        const totalTokens = stats.input + stats.output;
+        console.log(`  ${padRight(label, labelWidth)}  ${padLeft(formatTokens(totalTokens), tokensWidth)}  ${padLeft(formatCost(stats.cost), costWidth)}  ${padLeft(stats.count.toString(), countWidth)}`);
+    }
+    console.log();
+}
+function printDailyBreakdown(entries) {
+    const byDay = groupBy(entries, (e) => {
+        const date = new Date(e._ts);
+        return date.toISOString().slice(0, 10); // YYYY-MM-DD
+    });
+    // Sort by date descending
+    const sorted = Array.from(byDay.entries()).sort((a, b) => b[0].localeCompare(a[0]));
+    if (sorted.length === 0) {
+        console.log("\n  No data\n");
+        return;
+    }
+    const dateWidth = 12;
+    const tokensWidth = 10;
+    const costWidth = 10;
+    const countWidth = 6;
+    console.log();
+    console.log(`  Daily Breakdown`);
+    console.log(`  ${"─".repeat(dateWidth + tokensWidth + costWidth + countWidth + 12)}`);
+    console.log(`  ${padRight("Date", dateWidth)}  ${padLeft("Tokens", tokensWidth)}  ${padLeft("Cost", costWidth)}  ${padLeft("Msgs", countWidth)}`);
+    console.log(`  ${"-".repeat(dateWidth)}  ${"-".repeat(tokensWidth)}  ${"-".repeat(costWidth)}  ${"-".repeat(countWidth)}`);
+    for (const [date, stats] of sorted) {
+        const totalTokens = stats.input + stats.output;
+        console.log(`  ${padRight(date, dateWidth)}  ${padLeft(formatTokens(totalTokens), tokensWidth)}  ${padLeft(formatCost(stats.cost), costWidth)}  ${padLeft(stats.count.toString(), countWidth)}`);
+    }
+    console.log();
+}
+// ============================================================================
+// Commands
+// ============================================================================
+function cmdStats(period, breakdown) {
+    const now = new Date();
+    let since;
+    let title;
+    switch (period) {
+        case "today":
+            since = getStartOfDay(now);
+            title = "Today's Usage";
+            break;
+        case "week":
+            since = getStartOfWeek(now);
+            title = "This Week's Usage";
+            break;
+        case "month":
+            since = getStartOfMonth(now);
+            title = "This Month's Usage";
+            break;
+        case "all":
+        default:
+            since = undefined;
+            title = "All-Time Usage";
+            break;
+    }
+    const entries = loadEntries(since);
+    if (entries.length === 0) {
+        console.log(`\n  No data for ${title.toLowerCase()}\n`);
+        return;
+    }
+    // Overall summary
+    const total = aggregateStats(entries);
+    printSummary(title, total);
+    // Breakdown
+    switch (breakdown) {
+        case "model":
+            printTable("By Model", groupBy(entries, (e) => e.model ?? "unknown"), "Model");
+            break;
+        case "agent":
+            printTable("By Agent", groupBy(entries, (e) => e.agent ?? "unknown"), "Agent");
+            break;
+        case "provider":
+            printTable("By Provider", groupBy(entries, (e) => e.provider ?? "unknown"), "Provider");
+            break;
+        case "day":
+        case "daily":
+            printDailyBreakdown(entries);
+            break;
+        case "all":
+            printTable("By Model", groupBy(entries, (e) => e.model ?? "unknown"), "Model");
+            printTable("By Agent", groupBy(entries, (e) => e.agent ?? "unknown"), "Agent");
+            printTable("By Provider", groupBy(entries, (e) => e.provider ?? "unknown"), "Provider");
+            break;
+    }
+}
+function cmdHelp() {
+    console.log(`
+  opencode-tokens - Token usage statistics CLI
+
+  Usage:
+    opencode-tokens [period] [--by <breakdown>]
+
+  Period:
+    today       Show today's usage
+    week        Show this week's usage  
+    month       Show this month's usage
+    all         Show all-time usage (default)
+
+  Breakdown (--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
+
+  Examples:
+    opencode-tokens                  # All-time summary
+    opencode-tokens today            # Today's summary
+    opencode-tokens week --by model  # This week, grouped by model
+    opencode-tokens month --by all   # This month, all breakdowns
+    opencode-tokens --by daily       # All-time, day by day
+`);
+}
+// ============================================================================
+// Main
+// ============================================================================
+function main() {
+    const args = process.argv.slice(2);
+    if (args.includes("--help") || args.includes("-h")) {
+        cmdHelp();
+        return;
+    }
+    // Parse arguments
+    let period = "all";
+    let breakdown;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--by" || arg === "-b") {
+            breakdown = args[++i];
+        }
+        else if (["today", "week", "month", "all"].includes(arg)) {
+            period = arg;
+        }
+    }
+    cmdStats(period, breakdown);
+}
+main();

package/dist/index.js

@@ -1,10 +1,21 @@
-import { appendFileSync, existsSync, mkdirSync } from "fs";
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "fs";
 import { join } from "path";
 import { homedir } from "os";
-const LOG_DIR = join(homedir(), ".config", "opencode", "logs", "token-tracker");
+const CONFIG_DIR = join(homedir(), ".config", "opencode");
+const CONFIG_FILE = join(CONFIG_DIR, "token-tracker.json");
+const LOG_DIR = join(CONFIG_DIR, "logs", "token-tracker");
 const LOG_FILE = join(LOG_DIR, "tokens.jsonl");
-// Prices as of 2026-02 (update as needed)
-const PRICING = {
+const DEFAULT_CONFIG = {
+    providers: {},
+    models: {},
+    toast: {
+        enabled: true,
+        duration: 3000,
+        showOnIdle: true,
+    },
+};
+// Built-in pricing table (USD per 1M tokens) - as of 2026-02
+const BUILTIN_PRICING = {
     // Anthropic Claude
     "claude-opus-4.5": { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75 },
     "claude-sonnet-4.5": { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
@@ -38,21 +49,58 @@ const PRICING = {
     // Fallback for unknown models
     "_default": { input: 1, output: 4 },
 };
-function getModelPricing(model) {
-    // Try exact match first
-    if (PRICING[model])
-        return PRICING[model];
-    // Try partial match (e.g., "claude-opus-4.5" matches "claude-opus-4.5-xxx")
+let config = DEFAULT_CONFIG;
+function loadConfig() {
+    try {
+        if (existsSync(CONFIG_FILE)) {
+            const content = readFileSync(CONFIG_FILE, "utf-8");
+            const userConfig = JSON.parse(content);
+            return {
+                providers: { ...DEFAULT_CONFIG.providers, ...userConfig.providers },
+                models: { ...DEFAULT_CONFIG.models, ...userConfig.models },
+                toast: { ...DEFAULT_CONFIG.toast, ...userConfig.toast },
+            };
+        }
+    }
+    catch (e) {
+        // Config parse error - use defaults
+    }
+    return DEFAULT_CONFIG;
+}
+// ============================================================================
+// Pricing
+// ============================================================================
+function getModelPricing(model, provider) {
+    // 1. Check provider-level override first (highest priority)
+    if (config.providers[provider]) {
+        return config.providers[provider];
+    }
+    // 2. Check user-defined model pricing
+    if (config.models[model]) {
+        return config.models[model];
+    }
+    // 3. Check built-in exact match
+    if (BUILTIN_PRICING[model]) {
+        return BUILTIN_PRICING[model];
+    }
+    // 4. Try partial match in user config
     const modelLower = model.toLowerCase();
-    for (const [key, pricing] of Object.entries(PRICING)) {
+    for (const [key, pricing] of Object.entries(config.models)) {
+        if (modelLower.includes(key.toLowerCase())) {
+            return pricing;
+        }
+    }
+    // 5. Try partial match in built-in pricing
+    for (const [key, pricing] of Object.entries(BUILTIN_PRICING)) {
         if (key !== "_default" && modelLower.includes(key.toLowerCase())) {
             return pricing;
         }
     }
-    return PRICING["_default"];
+    // 6. Fallback to default
+    return BUILTIN_PRICING["_default"];
 }
-function calculateCost(model, input, output, cacheRead = 0, cacheWrite = 0) {
-    const pricing = getModelPricing(model);
+function calculateCost(model, provider, input, output, cacheRead = 0, cacheWrite = 0) {
+    const pricing = getModelPricing(model, provider);
     // Billable input = total input - cache read (cached tokens are charged at cache rate)
     const billableInput = Math.max(0, input - cacheRead);
     const inputCost = (billableInput / 1_000_000) * pricing.input;
@@ -120,7 +168,9 @@ function logJson(data) {
     appendFileSync(LOG_FILE, entry);
 }
 export const TokenTrackerPlugin = async ({ directory, client }) => {
-    logJson({ type: "init", directory });
+    // Load config on plugin init
+    config = loadConfig();
+    logJson({ type: "init", directory, configLoaded: existsSync(CONFIG_FILE) });
     return {
         event: async ({ event }) => {
             try {
@@ -147,7 +197,7 @@ export const TokenTrackerPlugin = async ({ directory, client }) => {
                         return;
                     const model = info.model?.modelID ?? info.modelID ?? "unknown";
                     const provider = info.model?.providerID ?? info.providerID ?? "unknown";
-                    const cost = calculateCost(model, input, output, cacheRead, cacheWrite);
+                    const cost = calculateCost(model, provider, input, output, cacheRead, cacheWrite);
                     // Update session stats
                     const stats = getOrCreateSessionStats(sessionId);
                     stats.totalInput += input;
@@ -174,21 +224,25 @@ export const TokenTrackerPlugin = async ({ directory, client }) => {
                         cost,
                     });
                     // Show toast for this message
-                    const totalTokens = input + output;
-                    try {
-                        await client.tui.showToast({
-                            body: {
-                                title: `${formatTokens(totalTokens)} tokens`,
-                                message: `${formatCost(cost)} | Session: ${formatCost(stats.totalCost)}`,
-                                variant: "info",
-                                duration: 3000,
-                            },
-                        });
+                    if (config.toast.enabled) {
+                        const totalTokens = input + output;
+                        try {
+                            await client.tui.showToast({
+                                body: {
+                                    title: `${formatTokens(totalTokens)} tokens`,
+                                    message: `${formatCost(cost)} | Session: ${formatCost(stats.totalCost)}`,
+                                    variant: "info",
+                                    duration: config.toast.duration,
+                                },
+                            });
+                        }
+                        catch { }
                     }
-                    catch { }
                 }
                 // Handle session idle (show summary)
                 if (event.type === "session.idle") {
+                    if (!config.toast.enabled || !config.toast.showOnIdle)
+                        return;
                     const props = event.properties;
                     const sessionId = props?.sessionID;
                     if (!sessionId)

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "opencode-token-tracker",
-  "version": "1.0.0",
-  "description": "Real-time token usage and cost tracking plugin for OpenCode with Toast notifications",
+  "version": "1.2.0",
+  "description": "Real-time token usage and cost tracking plugin for OpenCode with Toast notifications and CLI stats",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
+  "bin": {
+    "opencode-tokens": "dist/bin/opencode-tokens.js"
+  },
   "scripts": {
     "build": "tsc",
     "prepublishOnly": "npm run build"