opencode-token-tracker 1.3.2 → 1.4.0

package/README.md

@@ -7,6 +7,7 @@ Real-time token usage and cost tracking plugin for [OpenCode](https://opencode.a
 ## 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
@@ -37,6 +38,13 @@ Once installed, you'll see Toast notifications after each AI response:
 $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:
 
 ```
@@ -44,6 +52,49 @@ Session: 45.2K tokens
 $0.156 | 8 msgs | 5min
 ```
 
+### Budget Control
+
+Set spending limits to avoid unexpected costs:
+
+```bash
+# 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`:
+
+```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:
@@ -97,6 +148,9 @@ Breakdown options (`--by`):
 ### Pricing & Config Commands
 
 ```bash
+# Check budget status
+opencode-tokens budget
+
 # Show built-in pricing table
 opencode-tokens pricing
 
@@ -179,10 +233,30 @@ Create a config file at `~/.config/opencode/token-tracker.json`:
     "enabled": true,
     "duration": 3000,
     "showOnIdle": true
+  },
+  "budget": {
+    "daily": 10,
+    "weekly": 50,
+    "monthly": 200,
+    "warnAt": 0.8
   }
 }
 ```
 
+### Budget Settings
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `daily` | number | - | Maximum daily spend in USD |
+| `weekly` | number | - | Maximum weekly spend in USD |
+| `monthly` | number | - | Maximum monthly spend in USD |
+| `warnAt` | number | `0.8` | Warning threshold (0-1), e.g., 0.8 = warn at 80% |
+
+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**:

package/dist/bin/opencode-tokens.js

@@ -404,6 +404,12 @@ function cmdConfig(action) {
                 duration: 3000,
                 showOnIdle: true,
             },
+            budget: {
+                daily: 5,
+                weekly: 25,
+                monthly: 100,
+                warnAt: 0.8,
+            },
         };
         // Add providers as comments/examples
         for (const provider of providers) {
@@ -418,11 +424,11 @@ function cmdConfig(action) {
         }
         // Print explanation first
         console.log(`
-  Pricing Configuration Guide
+  Configuration Guide
   ══════════════════════════════════════════════════════════════════
 
-  All prices are in USD per 1 MILLION tokens.
-
+  PRICING (prices in USD per 1 MILLION tokens)
+  ────────────────────────────────────────────────────────────────
   Fields:
     input      Cost for input/prompt tokens sent to the model
     output     Cost for output/completion tokens from the model
@@ -434,7 +440,7 @@ function cmdConfig(action) {
     { "input": 0, "output": 0 }       = Free (subscription or local model)
 
   Common scenarios:
-    - GitHub Copilot, Cursor, etc.   → Set to 0 (subscription-based)
+    - GitHub Copilot, Cursor, etc.   → Set provider to { input: 0, output: 0 }
     - Local/self-hosted models       → Set to 0
     - Direct API usage               → Look up provider's pricing page
 
@@ -445,6 +451,17 @@ function cmdConfig(action) {
     - Google:    https://ai.google.dev/pricing
     - Or run:    opencode-tokens pricing
 
+  BUDGET CONTROL
+  ────────────────────────────────────────────────────────────────
+  Set spending limits to avoid unexpected costs:
+    daily      Maximum spend per day (USD)
+    weekly     Maximum spend per week (USD)
+    monthly    Maximum spend per month (USD)
+    warnAt     Warning threshold (0-1), default 0.8 = 80%
+
+  When budget is exceeded, you'll see a warning toast.
+  Check status anytime with: opencode-tokens budget
+
   ────────────────────────────────────────────────────────────────
   Example config based on your usage:
 `);
@@ -485,6 +502,92 @@ function cmdConfig(action) {
     console.log(`    opencode-tokens config generate  Create config file`);
     console.log();
 }
+function cmdBudget() {
+    const config = loadConfig();
+    const budget = config.budget;
+    if (!budget?.daily && !budget?.weekly && !budget?.monthly) {
+        console.log(`
+  Budget Status
+  ══════════════════════════════════════════════════════════════════
+
+  No budget configured.
+
+  To set a budget, add to your config file (${CONFIG_FILE}):
+
+  {
+    "budget": {
+      "daily": 5,       // $5 per day
+      "weekly": 25,     // $25 per week (optional)
+      "monthly": 100,   // $100 per month (optional)
+      "warnAt": 0.8     // Warn at 80% usage
+    }
+  }
+
+  Run: opencode-tokens config init  for more details.
+`);
+        return;
+    }
+    const now = new Date();
+    const warnAt = budget.warnAt ?? 0.8;
+    console.log(`
+  Budget Status
+  ══════════════════════════════════════════════════════════════════
+`);
+    // Helper to create progress bar
+    const progressBar = (pct, width = 20) => {
+        const filled = Math.min(Math.round(pct * width), width);
+        const empty = width - filled;
+        const bar = "█".repeat(filled) + "░".repeat(empty);
+        return bar;
+    };
+    // Helper to get color indicator
+    const statusIndicator = (pct) => {
+        if (pct >= 1)
+            return "🔴";
+        if (pct >= warnAt)
+            return "🟡";
+        return "🟢";
+    };
+    const entries = loadEntries();
+    // Daily budget
+    if (budget.daily) {
+        const dayStart = getStartOfDay(now);
+        const dayEntries = entries.filter(e => e._ts >= dayStart);
+        const spent = dayEntries.reduce((sum, e) => sum + (e.cost ?? 0), 0);
+        const pct = spent / budget.daily;
+        const pctDisplay = Math.round(pct * 100);
+        console.log(`  ${statusIndicator(pct)} Daily`);
+        console.log(`    ${formatCost(spent)} / ${formatCost(budget.daily)}  [${progressBar(pct)}] ${pctDisplay}%`);
+        console.log(`    Remaining: ${formatCost(Math.max(0, budget.daily - spent))}`);
+        console.log();
+    }
+    // Weekly budget
+    if (budget.weekly) {
+        const weekStart = getStartOfWeek(now);
+        const weekEntries = entries.filter(e => e._ts >= weekStart);
+        const spent = weekEntries.reduce((sum, e) => sum + (e.cost ?? 0), 0);
+        const pct = spent / budget.weekly;
+        const pctDisplay = Math.round(pct * 100);
+        console.log(`  ${statusIndicator(pct)} Weekly`);
+        console.log(`    ${formatCost(spent)} / ${formatCost(budget.weekly)}  [${progressBar(pct)}] ${pctDisplay}%`);
+        console.log(`    Remaining: ${formatCost(Math.max(0, budget.weekly - spent))}`);
+        console.log();
+    }
+    // Monthly budget
+    if (budget.monthly) {
+        const monthStart = getStartOfMonth(now);
+        const monthEntries = entries.filter(e => e._ts >= monthStart);
+        const spent = monthEntries.reduce((sum, e) => sum + (e.cost ?? 0), 0);
+        const pct = spent / budget.monthly;
+        const pctDisplay = Math.round(pct * 100);
+        console.log(`  ${statusIndicator(pct)} Monthly`);
+        console.log(`    ${formatCost(spent)} / ${formatCost(budget.monthly)}  [${progressBar(pct)}] ${pctDisplay}%`);
+        console.log(`    Remaining: ${formatCost(Math.max(0, budget.monthly - spent))}`);
+        console.log();
+    }
+    console.log(`  Legend: 🟢 OK  🟡 Warning (>${Math.round(warnAt * 100)}%)  🔴 Exceeded`);
+    console.log();
+}
 function cmdHelp() {
     console.log(`
   opencode-tokens - Token usage statistics CLI
@@ -494,6 +597,7 @@ function cmdHelp() {
 
   Commands:
     (default)     Show usage statistics
+    budget        Show budget status (daily/weekly/monthly)
     pricing       Show built-in pricing table
     models        Show your used models and their pricing status  
     config        Show/generate configuration
@@ -508,6 +612,7 @@ function cmdHelp() {
 
   Examples:
     opencode-tokens                  # All-time summary
+    opencode-tokens budget           # Check budget status
     opencode-tokens today            # Today's summary
     opencode-tokens week --by model  # This week, by model
     opencode-tokens pricing          # Show pricing table
@@ -526,6 +631,10 @@ function main() {
         return;
     }
     // Handle subcommands
+    if (command === "budget") {
+        cmdBudget();
+        return;
+    }
     if (command === "pricing") {
         cmdPricing();
         return;

package/dist/index.js

@@ -13,6 +13,9 @@ const DEFAULT_CONFIG = {
         duration: 3000,
         showOnIdle: true,
     },
+    budget: {
+        warnAt: 0.8,
+    },
 };
 // Built-in pricing table (USD per 1M tokens) - Updated 2026-02-05
 // Sources:
@@ -87,6 +90,7 @@ function loadConfig() {
                 providers: { ...DEFAULT_CONFIG.providers, ...userConfig.providers },
                 models: { ...DEFAULT_CONFIG.models, ...userConfig.models },
                 toast: { ...DEFAULT_CONFIG.toast, ...userConfig.toast },
+                budget: { ...DEFAULT_CONFIG.budget, ...userConfig.budget },
             };
         }
     }
@@ -195,6 +199,102 @@ function logJson(data) {
     const entry = JSON.stringify({ ...data, _ts: Date.now() }) + "\n";
     appendFileSync(LOG_FILE, entry);
 }
+function getStartOfDay(date = new Date()) {
+    const d = new Date(date);
+    d.setHours(0, 0, 0, 0);
+    return d.getTime();
+}
+function getStartOfWeek(date = new Date()) {
+    const d = new Date(date);
+    const day = d.getDay();
+    const diff = d.getDate() - day + (day === 0 ? -6 : 1); // Monday as first day
+    d.setDate(diff);
+    d.setHours(0, 0, 0, 0);
+    return d.getTime();
+}
+function getStartOfMonth(date = new Date()) {
+    const d = new Date(date);
+    d.setDate(1);
+    d.setHours(0, 0, 0, 0);
+    return d.getTime();
+}
+function loadEntriesSince(since) {
+    if (!existsSync(LOG_FILE))
+        return [];
+    try {
+        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" && entry._ts >= since && entry.cost) {
+                    entries.push(entry);
+                }
+            }
+            catch { }
+        }
+        return entries;
+    }
+    catch {
+        return [];
+    }
+}
+function calculateSpentSince(since) {
+    const entries = loadEntriesSince(since);
+    return entries.reduce((sum, e) => sum + (e.cost ?? 0), 0);
+}
+function checkBudgetStatus() {
+    const budget = config.budget;
+    if (!budget.daily && !budget.weekly && !budget.monthly) {
+        return null;
+    }
+    const warnAt = budget.warnAt ?? 0.8;
+    const now = new Date();
+    // Check in order: daily -> weekly -> monthly (most restrictive first)
+    if (budget.daily) {
+        const spent = calculateSpentSince(getStartOfDay(now));
+        const percentage = spent / budget.daily;
+        return {
+            period: "daily",
+            spent,
+            limit: budget.daily,
+            percentage,
+            exceeded: percentage >= 1,
+            warning: percentage >= warnAt && percentage < 1,
+        };
+    }
+    if (budget.weekly) {
+        const spent = calculateSpentSince(getStartOfWeek(now));
+        const percentage = spent / budget.weekly;
+        return {
+            period: "weekly",
+            spent,
+            limit: budget.weekly,
+            percentage,
+            exceeded: percentage >= 1,
+            warning: percentage >= warnAt && percentage < 1,
+        };
+    }
+    if (budget.monthly) {
+        const spent = calculateSpentSince(getStartOfMonth(now));
+        const percentage = spent / budget.monthly;
+        return {
+            period: "monthly",
+            spent,
+            limit: budget.monthly,
+            percentage,
+            exceeded: percentage >= 1,
+            warning: percentage >= warnAt && percentage < 1,
+        };
+    }
+    return null;
+}
+function formatBudgetMessage(status) {
+    const pct = Math.round(status.percentage * 100);
+    const periodLabel = status.period.charAt(0).toUpperCase() + status.period.slice(1);
+    return `${periodLabel}: ${formatCost(status.spent)}/${formatCost(status.limit)} (${pct}%)`;
+}
 export const TokenTrackerPlugin = async ({ directory, client }) => {
     // Load config on plugin init
     config = loadConfig();
@@ -254,13 +354,30 @@ export const TokenTrackerPlugin = async ({ directory, client }) => {
                     // Show toast for this message
                     if (config.toast.enabled) {
                         const totalTokens = input + output;
+                        // Check budget status
+                        const budgetStatus = checkBudgetStatus();
+                        let title = `${formatTokens(totalTokens)} tokens`;
+                        let message = `${formatCost(cost)} | Session: ${formatCost(stats.totalCost)}`;
+                        let variant = "info";
+                        // Add budget warning/alert if applicable
+                        if (budgetStatus) {
+                            if (budgetStatus.exceeded) {
+                                title = `⚠️ Budget exceeded!`;
+                                message = formatBudgetMessage(budgetStatus);
+                                variant = "error";
+                            }
+                            else if (budgetStatus.warning) {
+                                message = `${formatCost(cost)} | ${formatBudgetMessage(budgetStatus)}`;
+                                variant = "warning";
+                            }
+                        }
                         try {
                             await client.tui.showToast({
                                 body: {
-                                    title: `${formatTokens(totalTokens)} tokens`,
-                                    message: `${formatCost(cost)} | Session: ${formatCost(stats.totalCost)}`,
-                                    variant: "info",
-                                    duration: config.toast.duration,
+                                    title,
+                                    message,
+                                    variant,
+                                    duration: budgetStatus?.exceeded ? 5000 : config.toast.duration,
                                 },
                             });
                         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-token-tracker",
-  "version": "1.3.2",
+  "version": "1.4.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",