tokenmeter

# 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 tokenme...

<p align="center">
  <img src="assets/logo.png" alt="tokenmeter logo" width="200" />
</p>

# 🪙 tokenmeter

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

![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)
![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)

## Why This Exists

You're using Claude Code, Cursor, ChatGPT, Azure OpenAI, and a dozen other AI tools. Your monthly bill is a mystery until it arrives. Sound familiar?

**tokenmeter** solves this by:
- 📊 Tracking token usage across OpenAI, Anthropic, Azure OpenAI, and Google
- 💰 Calculating real-time cost estimates based on current pricing
- 🔒 Running 100% locally — your data never leaves your machine
- 📈 Showing trends and breakdowns by model, day, and application

## Installation

```bash
pip install tokenmeter
# or
pipx install tokenmeter
```

## Quick Start

```bash
# Log a usage event manually
tokenmeter log --provider anthropic --model claude-sonnet-4 --input 1500 --output 500

# Import from Claude Code's usage file
tokenmeter import claude-code

# Show today's summary
tokenmeter summary

# Show cost breakdown
tokenmeter costs --period week

# Interactive dashboard
tokenmeter dashboard
```

## Features

### 🎯 Multi-Provider Support
- **Anthropic** (Claude 3.5, 4, Opus, Sonnet, Haiku)
- **OpenAI** (GPT-4, GPT-4o, o1, o3)
- **Azure OpenAI** (all deployed models)
- **Google** (Gemini Pro, Ultra, Flash)

### 📊 Rich CLI Dashboard with Cache Tracking
```
╭─────────────────── 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
```

**Cache R** and **Cache W** show prompt caching usage:
- **Cache Write**: Tokens stored in ca...