TokenWatch

TokenWatch

Track, analyze, and optimize token usage and costs across AI providers. Set budgets, get alerts, compare models, and reduce your spend.

Free and open-source (MIT License) • Zero dependencies • Works locally • No API keys required

Why This Skill?

After OpenAI's acquisition of OpenClaw, token costs are the #1 concern for power users. This skill gives you full visibility into what you're spending, where it's going, and exactly how to reduce it.

Problems it solves:

• You don't know how much you're spending until the bill arrives
• No way to compare costs across providers before choosing a model
• No alerts when you're approaching your budget
• No actionable suggestions for reducing spend

Features

1. Record Usage & Auto-Calculate Costs

from tokenwatch import TokenWatch

monitor = TokenWatch()

monitor.record_usage(
    model="claude-haiku-4-5-20251001",
    input_tokens=1200,
    output_tokens=400,
    task_label="summarize article"
)
# ✅ Recorded: $0.00192

2. Auto-Record from API Responses

from tokenwatch import record_from_anthropic_response, record_from_openai_response

# Anthropic
response = client.messages.create(model="claude-haiku-4-5-20251001", ...)
record_from_anthropic_response(monitor, response, task_label="my task")

# OpenAI
response = client.chat.completions.create(model="gpt-4o-mini", ...)
record_from_openai_response(monitor, response, task_label="my task")

3. Set Budgets with Alerts

monitor.set_budget(
    daily_usd=1.00,
    weekly_usd=5.00,
    monthly_usd=15.00,
    per_call_usd=0.10,
    alert_at_percent=80.0   # Alert at 80% of budget
)
# ✅ Budget set: daily=$1.0, weekly=$5.0, monthly=$15.0
# 🚨 BUDGET ALERT fires automatically when threshold is crossed

4. Dashboard

print(monitor.format_dashboard())

💰 SPENDING SUMMARY
  Today:   $0.0042  (4 calls, 13,600 tokens)
  Week:    $0.0231  (18 calls, 67,200 tokens)
  Month:   $0.1847  (92 calls, 438,000 tokens)

📋 BUDGET STATUS
  Daily:   [████░░░░░░░░░░░░░░░░] 42% $0.0042 / $1.00 ✅
  Monthly: [███████░░░░░░░░░░░░░] 37% $0.1847 / $0.50 ⚠️

💡 OPTIMIZATION TIPS
  🔴 Swap Opus → Sonnet for non-reasoning tasks (save ~$8.20/mo)
  🟡 High avg cost/call on gpt-4o — reduce prompt length

5. Compare Models Before Calling

# For 2000 input + 500 output tokens:
for m in monitor.compare_models(2000, 500)[:6]:
    print(f"{m['model']:<42} ${m['cost_usd']:.6f}")

gemini-2.5-flash                           $0.000300
gpt-4o-mini                                $0.000600
mistral-small-2501                         $0.000350
claude-haiku-4-5-20251001                  $0.003600
mistral-large-2501                         $0.007000
gemini-2.5-pro                             $0.007500

6. Estimate Before You Call

estimate = monitor.estimate_cost("claude-sonnet-4-5-20250929", input_tokens=5000, output_tokens=1000)
print(f"Estimated cost: ${estimate['estimated_cost_usd']:.6f}")

7. Optimization Suggestions

suggestions = monitor.get_optimization_suggestions()
for s in suggestions:
    savings = s.get("estimated_monthly_savings_usd", 0)
    print(f"[{s['priority'].upper()}] {s['message']}")
    if savings:
        print(f"  → Save ~${savings:.2f}/month")

8. Export Reports

monitor.export_report("monthly_report.json", period="month")

Supported Models (Feb 2026)

41 models across 10 providers — updated Feb 16, 2026.

To add a custom model: add it to PROVIDER_PRICING dict at the top of tokenwatch.py.

API Reference

TokenWatch(storage_path)

Initialize monitor. Data stored in .tokenwatch/ by default.

record_usage(model, input_tokens, output_tokens, task_label, session_id)

Record a single API call. Returns TokenUsageRecord with calculated cost.

set_budget(daily_usd, weekly_usd, monthly_usd, per_call_usd, alert_at_percent)

Configure spending limits. Alerts fire automatically when thresholds are crossed.

get_spend(period)

Get aggregated spend. Period: "today", "week", "month", "all", or "YYYY-MM-DD".

get_spend_by_model(period)

Spending breakdown by model, sorted by cost descending.

get_spend_by_provider(period)

Spending breakdown by provider.

compare_models(input_tokens, output_tokens)

Compare costs across all known models. Returns list sorted cheapest first.

estimate_cost(model, input_tokens, output_tokens)

Estimate cost before making a call.

get_optimization_suggestions()

Analyze usage and return ranked suggestions with estimated monthly savings.

format_dashboard()

Human-readable spending dashboard with budget bars and tips.

export_report(output_file, period)

Export full report to JSON.

record_from_anthropic_response(monitor, response, task_label)

Helper to auto-record from Anthropic SDK response object.

record_from_openai_response(monitor, response, task_label)

Helper to auto-record from OpenAI SDK response object.

Privacy & Security

• ✅ Zero telemetry — No data sent anywhere
• ✅ Local-only storage — Everything in .tokenwatch/ on your machine
• ✅ No API keys required — The monitor itself needs no credentials
• ✅ No authentication — No accounts or logins needed
• ✅ Full transparency — MIT licensed, source code included

Changelog

[1.2.3] - 2026-02-16

• 📋 Updated SKILL.md model table to match code: 41 models across 10 providers

[1.2.0] - 2026-02-16

• ✨ Added DeepSeek, Meta Llama, MiniMax providers
• ✨ Expanded to 41 models across 10 providers
• ✨ Updated all Anthropic/OpenAI/Google/Mistral pricing to Feb 2026 rates

[1.1.0] - 2026-02-16

• ✨ Added xAI Grok, Kimi (Moonshot), Qwen (Alibaba)
• ✨ Expanded to 32 models across 7 providers

[1.0.0] - 2026-02-16

• ✨ Initial release — TokenWatch
• ✨ Pricing table for 11 models across 5 providers
• ✨ Budget alerts: daily, weekly, monthly, per-call thresholds
• ✨ Model cost comparison, cost estimation, optimization suggestions
• ✨ Auto-hooks for Anthropic and OpenAI response objects
• ✨ Dashboard, JSON export, local-only storage, MIT licensed

Last Updated: February 16, 2026 Current Version: 1.2.3 Status: Active & Community-Maintained

© 2026 UnisAI Community