tokenmeter - AI Usage & Cost Tracking for OpenClaw

---

name: tokenmeter

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

user-invocable: true

metadata: {"openclaw":{"emoji":"📊"}}

---

# tokenmeter - AI Usage & Cost Tracking for OpenClaw

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

Slash Command Examples

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:

# 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**

**Step 2: Bot checks if tokenmeter exists**

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**

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**

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:**

cd ~/clawd/tokenmeter && source .venv/bin/activate && tokenmeter [command]

**Common commands the bot will use:**

# 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

# 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**

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

This shows all discovered session directories:

**Step 2: Import all at once**

tokenmeter import --auto

This will:

**Options:**

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:

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

Options:

---

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:**

**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:**

This is why the cost stays low despite huge cache numbers.

Comparing to Claude Max Plan

**Your Max plan:** $100/month flat rate

**If tokenmeter shows $800 this month:**

**If tokenmeter shows $90 this month:**

---

Workflows

Daily Check-In

cd ~/clawd/tokenmeter
source .venv/bin/activate

# Import latest usage
tokenmeter import --auto

# Quick overview
tokenmeter dashboard

Weekly Review

tokenmeter summary --period week
tokenmeter costs --period week

Look for:

Monthly Billing Comparison

At month end:

tokenmeter costs --period month

Compare to your Anthropic invoice:

---

Cron Automation (Optional)

Add to your HEARTBEAT.md or run via cron:

# Run daily at 11 PM
0 23 * * * cd ~/clawd/tokenmeter && source .venv/bin/activate && tokenmeter import --auto

This keeps tokenmeter in sync without manual effort.

---

Multi-Bot Tracking

If you run multiple OpenClaw instances (e.g., Cheenu + Chhotu):

1. Both bots import to tokenmeter on their respective machines

2. Each uses `--app` flag to distinguish:

```bash

tokenmeter log -p anthropic -m claude-sonnet-4 -i 1000 -o 500 --app cheenu

tokenmeter log -p anthropic -m claude-sonnet-4 -i 800 -o 400 --app chhotu

```

3. Nagaconda can aggregate reports from both to see total team usage

---

Troubleshooting

"tokenmeter: command not found"

Activate the virtual environment:

cd ~/clawd/skills/tokenmeter
source .venv/bin/activate

Empty dashboard after import

Check:

1. OpenClaw session files exist: `ls ~/.clawdbot/agents/*/sessions/*.jsonl`

2. Import command ran successfully (no errors)

3. Database has entries: `sqlite3 ~/.tokenmeter/usage.db "SELECT COUNT(*) FROM usage;"`

Prices seem wrong

Pricing is based on API rates as of Feb 2026. If Anthropic changes pricing, update `tokenmeter/pricing.py` or open an issue on GitHub.

---

Examples

Example 1: Check today's usage

$ tokenmeter dashboard
╭─────────────────── tokenmeter ───────────────────╮
│  TODAY  $4.23  (141,000 tokens)                  │
│  WEEK   $28.90  (963,000 tokens)                 │
╰──────────────────────────────────────────────────╯

**Analysis:** $4.23 today, trending toward ~$30/week. Well within Max plan ($100/mo).

Example 2: Weekly cost breakdown

$ tokenmeter costs --period week

Provider   Model              Input      Output     Cost      %
─────────────────────────────────────────────────────────────
Anthropic  claude-sonnet-4    450K       180K       $4.05    45%
Anthropic  claude-opus-4       90K        30K       $3.60    40%
Anthropic  claude-3.5-haiku   800K       200K       $1.44    15%
─────────────────────────────────────────────────────────────
Total                        1,340K      410K       $9.09   100%

**Analysis:** Using Opus for 40% of costs but only ~7% of token volume. Consider using Sonnet more.

Example 3: Month-end comparison (Real Data - Feb 2026)

$ tokenmeter import --auto
Imported 13,713 records
Total cost: $1,246.55

$ tokenmeter costs --period month

Model                    Input   Output    Cost      % of Total
─────────────────────────────────────────────────────────────────
anthropic/claude-opus-4  47.3K   1.6M      $743.35   59.6%
anthropic/claude-sonnet-4 70.8K  2.2M      $501.75   40.3%
─────────────────────────────────────────────────────────────────
Total                    118.8K  3.8M      $1,246.55 100%

$ tokenmeter summary --period month

Provider   Input    Output   Total    Cost        Requests
─────────────────────────────────────────────────────────
Anthropic  118.8K   3.8M     3.9M     $1,246.55   12,552

**Analysis:**

Opus usage (59.6% of cost) shows heavy extended-thinking use. Max plan absolutely paid for itself this month!

---

FAQ

**Q: Does tokenmeter send data anywhere?**

A: No. Everything is stored locally in `~/.tokenmeter/usage.db`. Zero telemetry.

**Q: What if I delete the database?**

A: You lose history, but can rebuild by re-importing OpenClaw sessions (idempotent).

**Q: Can I use this with non-OpenClaw tools?**

A: Yes! It supports Claude Code, Cursor, and manual logging for any LLM tool.

**Q: Will this slow down OpenClaw?**

A: No. Import runs separately and reads logs after-the-fact.

**Q: What about cache tokens?**

A: tokenmeter includes cache read/write tokens in its calculations (OpenClaw tracks them).

---

References

---

Changelog

2026-02-06 (v2)

2026-02-06 (v1)

---

*Built to answer the question: "How much is my Max plan really saving me?" 💰*