tokensave 0.4.3

Token waste analyzer for AI agents — find where your money goes and get one-click fix prompts. pip install, bills go down.

TokenSave v0.4.2

Token waste analyzer for AI agents — find where your money goes and get one-click fix prompts. pip install tokensave — bills go down.

---

$ tokensave analyze

Session test_123: 12,000 tokens, ~$0.05, 25% avoidable

  #1 duplicate_tool_calls (5x): 3,000 tokens
      read_file called 5x with same path

Send to your agent: "Before calling any tool, check if you already have
the result in a previous message..."

tokensave scans your session → finds the waste → gives you the exact prompt to stop it. One command. Paste the output. Bills go down.

All demo numbers above are from real test fixtures in tests/test_analyzer.py — 12,000 tokens, 3,000 wasted on duplicate reads, 25% avoidable. No made-up data.

---

What It Does (Two Modes)

Mode 1: Analyze (tokensave analyze)

Reads Hermes session data from ~/.hermes/state.db (SQLite, primary) or ~/.hermes/sessions/*.json (API error dumps, fallback) and detects four categories of waste:

Detector	What it finds
Duplicate tool calls	Same tool + same args called 2+ times (exact + near-duplicate)
Context bloat	Stale overlapping content, oversized tool outputs, unused tools, session overhead
Model mismatch	Simple queries running on expensive models
Heartbeat waste	Cron/scheduled/idle-check messages on pro-tier

Output: ≤5 lines, actionable. Zero config. 100% local.

Mode 2: Pipeline (v0.3.0, unchanged)

Transparent OpenAI wrapper — from tokensave import OpenAI — automatic normalization, exact-match cache, and context compression. Cuts token usage without changing your code.

Why TokenSave + Smart Router

	TokenSave	Smart Router
When	After the session (diagnosis)	Before each message (prevention)
Job	"Here's where you're wasting money"	"Use this model instead"
User	Run manually, get insights	Runs automatically, suggests switches

Use both for maximum savings: Smart Router prevents waste, TokenSave reveals what slipped through.

Install

pip install tokensave

Or as a Hermes skill:

hermes skills install raydatalab/tokensave     # from ClawHub
hermes skills install raydatalab/tokensave     # from GitHub

Usage

# Analyze your latest session (auto-detect from state.db)
tokensave analyze

# Analyze a specific session by ID
tokensave analyze 20260710_214623_e95335

# Analyze an error request dump
tokensave analyze ~/.hermes/sessions/request_dump_*.json

# Run only specific detectors
tokensave analyze --detectors duplicate_tool_calls,model_mismatch

# Pipeline mode (automatic)
export OPENAI_API_KEY=sk-...
python3 -c "
from tokensave import OpenAI
client = OpenAI()
# All calls go through normalize → cache → compress
"

Benchmarks (Pipeline Mode)

Scenario	Before	After	Savings
10MB production logs	~2,500,000 tok	~5,000 tok	~99.8%
2MB code/dataset	~500,000 tok	~295,000 tok	41%

Full benchmarks → BENCHMARK.md

Tech Stack

Component	Role
Python stdlib	Waste detection, session parsing
SQLite (stdlib)	Exact-match cache
headroom-ai	SmartCrusher + CodeCompressor (pipeline mode)

License

Apache 2.0 — see LICENSE.