tokenmeter

Track AI token usage and costs across providers. Import sessions, view dashboard, costs breakdown, and compare Max plan savings.

# tokenmeter - AI Usage & Cost Tracking for OpenClaw

Track your AI token usage and costs across all providers — locally, privately.

## Slash Command Examples

- `/tokenmeter` — show today's dashboard
- `/tokenmeter how much did we spend this week?` — weekly cost report
- `/tokenmeter costs breakdown by model` — model split analysis
- `/tokenmeter import latest sessions` — pull in new usage data
- `/tokenmeter compare max plan savings` — show API vs subscription savings

## Overview

**tokenmeter** is a CLI tool that tracks LLM API usage and calculates real-time cost estimates. For OpenClaw users on the Claude Max plan, it helps:

1. **Prove Max plan value** - Show what you *would* have paid on API billing
2. **Monitor usage patterns** - Understand which models you use most
3. **Catch overages early** - Know if you're using expensive models too much
4. **Unified tracking** - Track usage across multiple OpenClaw instances

All data stays local (SQLite at `~/.tokenmeter/usage.db`). No telemetry, no cloud sync.

---

## Installation

**The bot handles everything automatically.**

When first needed, the bot will:

```bash
# 1. Clone repo if it doesn't exist
if [ ! -d ~/clawd/tokenmeter ]; then
  cd ~/clawd
  git clone https://github.com/jugaad-lab/tokenmeter.git
fi

# 2. Setup Python venv if it doesn't exist
cd ~/clawd/tokenmeter
if [ ! -d ".venv" ]; then
  python3 -m venv .venv
  source .venv/bin/activate
  pip install -e .
fi

# 3. Activate and use
source .venv/bin/activate
tokenmeter import --auto
```

**After first setup:** Bot just activates venv and runs commands.

**No admin action needed** - the bot clones, installs, and configures automatically when you first ask it to check usage or costs.

---

## How the Bot Uses This Tool

### When You Ask: "How much did I spend this week?"

**Step 1: Bot reads this SKILL.md**
- Skill matching triggers on keywords: "spend", "cost", "usage", "tokens"
- Bot loads this entire file into context

**Step 2: Bot checks if tokenmeter exists**
```bash
if [ ! -d ~/clawd/tokenmeter ]; then
  cd ~/clawd
  git clone https://github.com/jugaad-lab/tokenmeter.git
  cd tokenmeter
  python3 -m venv .venv
  source .venv/bin/activate
  pip install -e .
fi
```

**Step 3: Bot imports latest usage**
```bash
cd ~/clawd/tokenmeter
source .venv/bin/activate
tokenmeter import --auto
```

This reads all OpenClaw session files and logs them to the database.

**Step 4: Bot runs the appropriate command**
```bash
tokenmeter costs --period week
```

**Step 5: Bot parses the output**
```
Model                    Cost      % of Total
────────────────────────────────────────────
anthropic/claude-opus-4  $741.95   65.0%
anthropic/claude-sonnet-4 $400.26  35.0%
────────────────────────────────────────────
Total                    $1,142.22
```

**Step 6: Bot responds to you in plain English**
> "You spent $1,142 this week (API-equivalent). Opus cost $742 (65%), Sonnet cost $400 (35%). Your Max plan ($100/month = ~$25/week) saved you $1,117 this week."

---

## Bot Command Reference

**Standard pattern:**
```bash
cd ~/clawd/tokenmeter && source .venv/bin/activate && tokenmeter [command]
```

**Common commands the bot will use:**
```bash
# Import latest usage
tokenmeter import --auto

# Quick overview
tokenmeter dashboard

# Weekly breakdown
tokenmeter costs --period week

# Monthly summary
tokenmeter summary --period month
```

---

## Usage

### Quick Commands

```bash
# Discover session sources (OpenClaw, Claude Code, etc.)
tokenmeter scan

# Import all discovered sessions
tokenmeter import --auto

# Preview import without writing
tokenmeter import --auto --dry-run

# Show today's usage
tokenmeter dashboard

# Weekly summary
tokenmeter summary --period week

# Cost breakdown by model
tokenmeter costs --period month

# List all supported models + pricing
tokenmeter models

# View recent history
tokenmeter history --limit 20
```

---

## Integration with OpenClaw

### Automatic Import (Recommended)

OpenClaw writes token usage to session JSONL files at:
```
~/.clawdbot/agents/*/sessions/*.jsonl
```

**Step 1: Discover session sources**

```bash
cd ~/clawd/tokenmeter
source .venv/bin/activate
tokenmeter scan
```

This shows all discovered session directories:
- `.clawdbot/agents/main/sessions/` (OpenClaw)
- `.claude/projects/*/sessions/` (Claude Code)
- Any other compatible session formats

**Step 2: Import all at once**

```bash
tokenmeter import --auto
```

This will:
- Parse all discovered session files
- Extract token usage from each LLM call
- Log to tokenmeter with API-equivalent costs
- Skip already-imported entries (idempotent)
- Show total records and cost

**Options:**
```bash
tokenmeter import --auto --dry-run  # Preview without writing
tokenmeter import --path ~/.clawdbot/agents/main/sessions/  # Import specific directory
```

**Recommended:** Run `tokenmeter import --auto` daily via cron or manually after heavy usage.

### Manual Logging (Fallback)

If you need to log usage manually:

```bash
tokenmeter log \
  --provider anthropic \
  --model claude-sonnet-4 \
  --input 1500 \
  --output 500 \
  --app openclaw
```

Options:
- `--provider` / `-p`: anthropic, openai, google, azure
- `--model` / `-m`: Model name (see `tokenmeter models`)
- `--input` / `-i`: Input tokens
- `--output` / `-o`: Output tokens
- `--app` / `-a`: Application name (e.g., "openclaw")

---

## Understanding the Data

### Model Pricing (as of Feb 2026)

| Token Type | claude-sonnet-4 | claude-opus-4 | claude-3.5-haiku |
|------------|----------------|---------------|------------------|
| **Input** | $3.00/1M | $15.00/1M | $0.80/1M |
| **Output** | $15.00/1M | $75.00/1M | $4.00/1M |
| **Cache Write** | $3.75/1M | $18.75/1M | $1.00/1M |
| **Cache Read** | $0.30/1M | $1.50/1M | $0.08/1M |

### Understanding Cache Tokens

**What are cache tokens?**

OpenClaw (and Claude) use **prompt caching** to store parts of your conversation in memory. This means you don't send the same context repeatedly.

**Two types of cache tokens:**

1. **Cache WRITE tokens** - Tokens sent ONCE and stored in cache
   - Example: Your entire codebase, documentation, system prompts
   - Slightly more expensive than regular input (~25% markup)
   - Only paid once, then reused for free (almost)

2. **Cache READ tokens** - Tokens reused from cache
   - You're NOT sending these again - Claude reads them from memory
   - **90% cheaper** than regular input tokens
   - This is where massive savings come from

**Real example from our usage:**
```
This Month:
Regular Input:    119.5K tokens  ($0.36)
Regular Output:     3.8M tokens  ($57.00)
Cache Write:      157.2M tokens  ($589.50 - paid once)
Cache Read:     1,024.3M tokens  ($307.29 - 90% discount!)
Total: $954.15
```

Without caching, we'd send ~1.2 BILLION tokens as regular input ($3,600+).
With caching: We only pay $307 for those cache reads.

**Savings: $3,293** from caching alone this month! 🎉

### Reading the Dashboard

```
╭─────────────────── tokenmeter ───────────────────╮
│  TODAY  $122.42  (396.9K tokens)                 │
│  WEEK  $1142.22  (3.4M tokens)                   │
╰──────────────────────────────────────────────────╯

Provider   Input   Output  Cache R  Cache W  Total    Cost
───────────────────────────────────────────────────────────
Anthropic  12.2K   384.7K  116.4M   13.1M    396.9K   $122.42
```

**Reading the columns:**
- **Input**: Fresh tokens sent to Claude
- **Output**: Tokens Claude generated
- **Cache R**: Tokens reused from cache (READ)
- **Cache W**: Tokens written to cache (WRITE)
- **Total**: Input + Output (regular tokens only)
- **Cost**: API-equivalent cost

**Why Cache R is so large:** Every time you continue a conversation, Claude reads your entire context from cache instead of you sending it fresh. Over many turns, this adds up to billions of tokens reused.

**Cost breakdown:**
- Regular tokens: Expensive ($3-15 per 1M)
- Cache Write: Slightly more expensive (~25% markup)
- Cache Read: **90% cheaper** ($0.3