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
• INLINECODE1 — weekly cost report
• INLINECODE2 — model split analysis
• INLINECODE3 — pull in new usage data
• INLINECODE4 — 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. 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:

CODEBLOCK0

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
CODEBLOCK1

Step 3: Bot imports latest usage
CODEBLOCK2

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

Step 4: Bot runs the appropriate command
CODEBLOCK3

Step 5: Bot parses the output
CODEBLOCK4

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

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

CODEBLOCK7

Integration with OpenClaw

Automatic Import (Recommended)

OpenClaw writes token usage to session JSONL files at:
CODEBLOCK8

Step 1: Discover session sources

CODEBLOCK9

This shows all discovered session directories:

• - .clawdbot/agents/main/sessions/ (OpenClaw)
• INLINECODE7 (Claude Code)
• Any other compatible session formats

Step 2: Import all at once

CODEBLOCK10

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

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

Manual Logging (Fallback)

If you need to log usage manually:

CODEBLOCK12

Options:

• - --provider / -p: anthropic, openai, google, azure
• INLINECODE11 / -m: Model name (see tokenmeter models)
• INLINECODE14 / -i: Input tokens
• INLINECODE16 / -o: Output tokens
• INLINECODE18 / -a: Application name (e.g., "openclaw")

Understanding the Data

Model Pricing (as of Feb 2026)

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. 1. Cache WRITE tokens - Tokens sent ONCE and stored in cache

1. 2. Cache READ tokens - Tokens reused from cache

Real example from our usage:
CODEBLOCK13

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

CODEBLOCK14

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.30-1.50 per 1M)

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:

• - API-equivalent cost: $800
• Max plan cost: $100
• Savings: $700 ✅

If tokenmeter shows $90 this month:

• - API-equivalent cost: $90
• Max plan cost: $100
• Overpaying by $10 (but you get peace of mind!)

Workflows

Daily Check-In

CODEBLOCK15

Weekly Review

CODEBLOCK16

Look for:

• - Heavy Opus usage (expensive!)
• Unusual spikes
• High output token counts (code generation, long responses)

Monthly Billing Comparison

At month end:

CODEBLOCK17

Compare to your Anthropic invoice:

• - Max plan: $100 flat
• API-equivalent (tokenmeter): $XXX
• Delta = savings (or loss)

Cron Automation (Optional)

Add to your HEARTBEAT.md or run via cron:

CODEBLOCK18

This keeps tokenmeter in sync without manual effort.

Multi-Bot Tracking

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

1. 1. Both bots import to tokenmeter on their respective machines
2. Each uses --app flag to distinguish:

   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
   

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

Troubleshooting

"tokenmeter: command not found"

Activate the virtual environment:
CODEBLOCK20

Empty dashboard after import

Check:

1. 1. OpenClaw session files exist: INLINECODE21
2. Import command ran successfully (no errors)
3. Database has entries: INLINECODE22

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

CODEBLOCK21

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

Example 2: Weekly cost breakdown

CODEBLOCK22

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)

CODEBLOCK23

Analysis:

• - API-equivalent cost: $1,246.55
• Max plan cost: $100.00
• Savings: $1,146.55 ✅

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

• - GitHub: https://github.com/jugaad-lab/tokenmeter
• OpenClaw Docs: https://docs.openclaw.ai
• Anthropic Pricing: https://anthropic.com/pricing

Changelog

2026-02-06 (v2)

• - ✅ tokenmeter scan - Auto-discover session sources
• ✅ tokenmeter import --auto - Import all discovered sessions
• ✅ Real data example showing $1,146 monthly savings on Max plan
• ✅ Updated workflows with new commands
• ✅ Tested on actual OpenClaw + Claude Code sessions

2026-02-06 (v1)

• - Initial skill creation
• Documented installation and usage
• Added workflow examples