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.

| Provider | Model | Input/1M | Output/1M | |----------|-------|----------|-----------| | Anthropic | claude-opus-4-6 | $5.00 | $25.00 | | Anthropic | claude-opus-4-5 | $5.00 | $25.00 | | Anthropic | claude-sonnet-4-5-20250929 | $3.00 | $15.00 | | Anthropic | claude-haiku-4-5-20251001 | $1.00 | $5.00 | | OpenAI | gpt-5.2-pro | $21.00 | $168.00 | | OpenAI | gpt-5.2 | $1.75 | $14.00 | | OpenAI | gpt-5 | $1.25 | $10.00 | | OpenAI | gpt-4.1 | $2.00 | $8.00 | | OpenAI | gpt-4.1-mini | $0.40 | $1.60 | | OpenAI | gpt-4.1-nano | $0.10 | $0.40 | | OpenAI | o3 | $10.00 | $40.00 | | OpenAI | o4-mini | $1.10 | $4.40 | | Google | gemini-3-pro | $2.00 | $12.00 | | Google | gemini-3-flash | $0.50 | $3.00 | | Google | gemini-2.5-pro | $1.25 | $10.00 | | Google | gemini-2.5-flash | $0.30 | $2.50 | | Google | gemini-2.5-flash-lite | $0.10 | $0.40 | | Google | gemini-2.0-flash | $0.10 | $0.40 | | Mistral | mistral-large-2411 | $2.00 | $6.00 | | Mistral | mistral-medium-3 | $0.40 | $2.00 | | Mistral | mistral-small | $0.10 | $0.30 | | Mistral | mistral-nemo | $0.02 | $0.10 | | Mistral | devstral-2 | $0.40 | $2.00 | | xAI | grok-4 | $3.00 | $15.00 | | xAI | grok-3 | $3.00 | $15.00 | | xAI | grok-4.1-fast | $0.20 | $0.50 | | Kimi | kimi-k2.5 | $0.60 | $3.00 | | Kimi | kimi-k2 | $0.60 | $2.50 | | Kimi | kimi-k2-turbo | $1.15 | $8.00 | | Qwen | qwen3.5-plus | $0.11 | $0.44 | | Qwen | qwen3-max | $0.40 | $1.60 | | Qwen | qwen3-vl-32b | $0.91 | $3.64 | | DeepSeek | deepseek-v3.2 | $0.14 | $0.28 | | DeepSeek | deepseek-r1 | $0.55 | $2.19 | | DeepSeek | deepseek-v3 | $0.27 | $1.10 | | Meta | llama-4-maverick | $0.27 | $0.85 | | Meta | llama-4-scout | $0.18 | $0.59 | | Meta | llama-3.3-70b | $0.23 | $0.40 | | MiniMax | minimax-m2.5 | $0.30 | $1.20 | | MiniMax | minimax-m1 | $0.43 | $1.93 | | MiniMax | minimax-text-01 | $0.20 | $1.10 |

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