TokenSave

Overview

$ tokensave analyze

Session 20260711_a1b2c3: 12,000 tokens, ~$0.05, 44% avoidable.

Top wastes:
  1. duplicate_tool_calls (5x): ~3,000 tokens — read_file called 5x with same path
  2. context_bloat (1x): ~1,800 tokens — 40% of input is stale context
  3. model_mismatch (3x): ~500 tokens — simple queries routed through pro

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

One session. 12K tokens. 44% could have been avoided — that's 5,300 tokens saved with a single paste. Run after every session, bills drop immediately.

All numbers above are from tests/test_analyzer.py real test fixtures. 12,000 input + output tokens, captured waste across all 4 detectors. No made-up data.

When to Use

• User explicitly asks to "run tokensave", "analyze my session", or similar
• User provides a specific session ID or file path to analyze
• User asks "how much did this session cost" with clear intent to run analysis
• User mentions specific waste patterns like "duplicate tool calls" or "context bloat"

When NOT to Use — Read This First

• Do NOT auto-analyze on general cost complaints ("this is expensive", "save money", "too expensive")
• Do NOT read session data (~/.hermes/state.db) without explicit user confirmation
• For general billing questions, explain that TokenSave can analyze a specific session but wait for an explicit command like tokensave analyze <session_id>
• Always prefer tokensave analyze <session_id> over auto-detecting the latest session when the user has not explicitly asked for it

How It Works

When the user has explicitly asked to run an analysis, use:

tokensave analyze

If the user has provided a specific session ID or path, use that instead:

tokensave analyze <session_id>          # specific session from state.db
tokensave analyze <file.json>           # error request dump
tokensave analyze <directory/>          # latest JSON in directory
tokensave analyze --detectors dup,bloat # specific detectors only

Always confirm with the user before analyzing if they haven't provided a specific session target. Auto-detect only when the user has explicitly asked for their "latest session" or "current session."

Copy the output and paste it into your response. The user sees:

Session abc123: 12,400 tokens, ~$0.19, 41% avoidable.

Top wastes:
  #1 duplicate_tool_calls (8x): ~4,800 tokens
  #2 model_mismatch (5x): ~860 tokens
  #3 context_bloat: ~3,700 tokens

Send to your agent: "Before reading a file, check if you already..."

What It Detects

Four waste detectors run against your session:

Data Sources

TokenSave reads from two sources (no config needed):

Auto-detect tries SQLite first, falls back to JSON, then gives a clear error message.

What You Need

• Python 3.10+
• pip install tokensave
• Analyze mode: nothing else — no API keys, no network, no config
• Pipeline mode (separate): requires OPENAI_API_KEY and makes API calls

Pipeline Mode (Bonus — Requires Network)

tokensave also works as a transparent OpenAI wrapper that cuts token usage automatically. This mode requires an API key and makes network calls to your configured API endpoint. If the user has installed it with from tokensave import OpenAI, their API calls go through normalize → cache → compress. But that's automatic — you don't need to do anything.

This mode is separate from tokensave analyze. The analyze command never makes network calls; it only reads local session data.

Tier Reference

Common Pitfalls

1. No session data found. If tokensave analyze returns no results, the session may not have been written to state.db yet. Hermes writes state.db on session end — try again after /new.
2. JSON fallback gives incomplete analysis. JSON error dumps lack full metadata. Always prefer SQLite mode (default). If you're seeing JSON fallback, the state.db may be locked by another Hermes process.
3. Duplicate detection is generous. Near-duplicate detection uses fuzzy matching and may flag legitimate re-reads. Use the report as a starting point, not a verdict.
4. Pipeline mode doesn't work with all providers. The transparent wrapper only supports OpenAI-compatible APIs. Non-OpenAI providers will fall through to direct calls.