TokenVision

Per-project token usage tracker for Claude Code. Monitor consumption, detect token drains, and optimize your spending across all your projects.

Features

• Real-time tracking — Reads Claude Code session logs to calculate token usage and API-equivalent costs per project
• Weekly budget — Configure your plan (Pro, Max 5x/10x/20x) and track weekly consumption vs budget
• Live session monitor — See active sessions with segmented cost bar and per-project breakdown
• Token drain diagnostics — Automatic detection of context bloat, model overuse, cache waste, long sessions, and retry loops
• Smart recommendations — Actionable steps with estimated savings and difficulty level
• Health scores — Per-project health rating (0-100) based on usage patterns
• Multi-platform — Desktop app (Electron), CLI, and Chrome extension
• Multi-language — English, Spanish, Portuguese

Quick Start

# Clone and install
git clone https://github.com/Zarenk/tokenvision.git
cd tokenvision
npm install

# Start the API server
npm run serve

# Launch the desktop app (in another terminal)
npm run app

Usage

Desktop App (Electron)

Floating overlay with three tabs:

• Overview — Weekly budget progress, total stats, project list with cost breakdown
• Sessions — Live monitor with active session tracking and segmented cost bar
• Diagnostics — Health score, smart recommendations, alerts sorted by severity

The app starts as a compact bar showing your total cost and health score. Click to expand.

CLI

# Per-project summary table
tokenvision summary

# Detailed breakdown for a project
tokenvision detail my-project

# Projects ranked by cost
tokenvision ranking --sort cost

# Export as JSON
tokenvision json

# Start the API server
tokenvision serve

Options: --from YYYY-MM-DD --to YYYY-MM-DD --project <name> --sort tokens|cost --no-subagents

Chrome Extension

1. Load extension/ as unpacked extension in Chrome
2. Make sure the API server is running (npm run serve)
3. Click the extension icon for quick stats, or open the full dashboard

API Endpoints

Endpoint	Method	Description
/api/projects	GET	All projects with token/cost breakdown
/api/usage-summary	GET	Weekly budget, consumption, active sessions
/api/diagnostics	GET	Health scores, alerts, recommendations
/api/config	GET/POST	Read/write plan configuration
/api/health	GET	Server health check

Configuration

Open the settings panel (gear icon) in the desktop app, or POST to /api/config:

{
  "plan": "max5x",
  "weeklyBudgetUsd": 2500,
  "weekStartDay": "monday"
}

Available plans: pro ($20/mo), max5x ($100/mo), max10x ($200/mo), max20x ($400/mo), custom

The weekly budget represents API-equivalent cost, not your subscription price. It's an estimate of what your usage would cost at Anthropic's API prices — useful for understanding relative consumption.

How It Works

TokenVision reads the JSONL session files that Claude Code creates in ~/.claude/projects/. Each file contains timestamped messages with token usage data per API call.

Data flow:

~/.claude/projects/*.jsonl  →  Parser  →  Cache  →  Server API  →  UI

What gets tracked per message:

• Input tokens, output tokens
• Cache read tokens (90% discount), cache creation tokens (25% premium)
• Model used (Opus, Sonnet, Haiku) with model-specific pricing
• Speed mode, web search/fetch requests, subagent spawning

Cost calculation uses Anthropic's published API pricing:

Model	Input	Output	Cache Read	Cache Write
Opus 4.6	$15/M	$75/M	$1.50/M	$18.75/M
Sonnet 4.6	$3/M	$15/M	$0.30/M	$3.75/M
Haiku 4.5	$0.80/M	$4/M	$0.08/M	$1/M

Token Drain Diagnostics

The analyzer detects 6 types of issues:

Issue	What it detects	Typical savings
Model overuse	>50% messages on Opus	60-80% cost reduction
Context bloat	>30K input tokens/message	20-40% per project
Long sessions	>500 messages per session	30% per session
Cache waste	Cache created but not reused	Varies
Expensive sessions	Single session >$200	Review-dependent
Retry loops	Output <2% of input	Task-dependent

Architecture

tokenvision/
  src/
    parsers/claude.js   # JSONL parser — extracts usage from session files
    pricing.js          # Cost calculation with model-specific rates
    analyzer.js         # Token drain detection & recommendations
    server.js           # HTTP API server (localhost:7878)
    config.js           # Plan configuration & week range
    cache.js            # In-memory cache with smart invalidation
  app/                  # Electron desktop app
  extension/            # Chrome/Firefox extension
  bin/cli.js            # CLI interface
  tests/test.js         # Automated test suite

Development

# Run tests
npm test

# Start server in development
npm run serve

# Launch Electron app
npm run app

Privacy & Security

• 100% local — All data stays on your machine. No external API calls, no telemetry
• Localhost only — API server binds to 127.0.0.1:7878, not accessible from network
• Read-only — TokenVision only reads JSONL files, never writes to ~/.claude/
• CORS restricted — API only accepts requests from Chrome extension origins and localhost
• Input validation — Date format validation, path traversal protection, body size limits

License

MIT