Tokenria

See where your LLM tokens actually go, and how much of what you generate is actually worth using.

What it is • Features • Screenshots • Getting Started • Design Principles • Roadmap • Contributing

_{Python + FastAPI · SQLite · Vanilla JS · Chart.js — one process, one database, no build step, no cloud.}

---

The Problem

If you use LLMs regularly for work, you're paying for tokens without any real visibility into two things:

1. Structural waste. How much of your spend is repeated system prompts, tool schemas, and conversation history versus genuinely new work.
2. Value waste. How much of what the model generates you actually use, versus how much gets discarded, ignored, or rewritten.

Usage dashboards from LLM providers show you totals. They don't show you whether that spend was productive. Tokenria closes that gap — locally, on your own machine, from your own data.

What Tokenria Is

Tokenria does not reveal the internal mechanics of how a closed model (Claude, GPT, Gemini, etc.) decides which tokens to generate — that requires access to model internals, which API-based tools do not have and cannot fake. Tokenria focuses on what's actually measurable: real token counts from real usage data, and the value you assign to what was produced.

Features

• 📊 Token Accounting — parses Claude Code session transcripts (exact, per-turn token counts, no export step required), breaking usage down into new input / cache write / cache read / output, rolled up by day, week, or month with cost attached. Answers "where is my money structurally going." Ingesting raw Anthropic/OpenAI API response objects is the same category of source and is next on the roadmap.
• ✍️ Manual Value Tagging — click through any response's chunks and mark each one used or discarded. Produces an adoption ratio (tokens kept / tokens generated) per response, tracked over time — the honest signal of value, based entirely on your own judgment, never an automated guess.
• 🤖 Optional Auto-Annotation (planned) — a cheap secondary LLM pass that pre-highlights likely-useful vs. likely-filler chunks before your manual review. Always editable, always labeled as a suggestion, never a substitute for your own call.

Every ingested record is tagged as either exact (real provider usage data) or estimated (locally tokenized pasted text), so accounting reports never blur the two.

Screenshots

Accounting — structural token/cost breakdown by week, with a running total and a per-period detail table:

Tagging — pick a record, review its response chunk by chunk, and get a live adoption ratio as you go:

Getting Started

python3 -m venv .venv && source .venv/bin/activate
pip install fastapi uvicorn tiktoken python-dotenv pytest ruff httpx2

Ingest your real Claude Code usage data (parses every session under ~/.claude/projects/**/*.jsonl, safe to re-run any time):

python -m ingest.claude_code_adapter

Start the server:

python main.py

Then open http://127.0.0.1:8000 for the accounting view, and http://127.0.0.1:8000/static/tagging.html for tagging. Bound to localhost only, deliberately — this is a local, single-user tool with no auth.

See DEV.md for the full walkthrough, including tests and linting.

Design Principles

• No black boxes. Every number in a report traces back to either a token count or a decision you made. Nothing is presented as fact unless it's mechanically derived from usage data.
• Local first. Your conversation data and tagging decisions stay on your machine by default (SQLite storage). No requirement to send data to a third party to use the tool.
• Model agnostic. Works with any provider that exposes token usage metadata (input, output, cached tokens) in its API responses or exports.
• Simple over clever. The core value is a clear number you can point to and say "this is what I actually got for this spend." Anything that adds complexity without adding clarity gets left out.

Roadmap

• Claude Code JSONL ingestion (exact token counts, no export step)
• Shared SQLite schema for usage records
• Accounting view — structural cost/token breakdown, charted
• Tagging view — manual chunk tagging, adoption ratio
• Generic API-response adapter (raw Anthropic/OpenAI response objects)
• Text-paste input path (estimated token counts via tiktoken)
• Auto-annotation overlay (LLM-assisted tag suggestions)

Contributing

This project is being built in the open, in stages, each one built and verified before the next starts. If you want to contribute, watch the repo for updates, open an issue, or send a PR — see CONTRIBUTING.md to get started, and DEV.md for the local environment walkthrough. Participation is covered by the Code of Conduct.

License

Released under the MIT License.