0token

See — and prove — where your agent's tokens go.

0token is the real-time insight, proof, and sharing layer for LLM token savings. It sits on top of Headroom's compression engine, reads its real output, and turns it into the things Headroom doesn't build: a live Token Flamegraph, a streaming $-saved meter, shareable Receipt / Wrapped cards, a modern real-time dashboard, and a reproducible public efficiency leaderboard.

CLI: 0token. Local-first. Apache-2.0. Real data only.

Architecture

graph TB
    subgraph "Your Agent"
        A[Claude Code / Cursor / Codex]
    end

    subgraph "Headroom Proxy (Rust + Python)"
        B[Content Router]
        C[SmartCrusher JSON]
        D[CodeCompressor AST]
        E[Kompress Text Model]
        F[savings_events.jsonl]
        G[proxy_savings.json]
    end

    subgraph "0token Stack (TypeScript + Python)"
        H[zt-serve<br/>SSE + REST API]
        I[Tailer<br/>Follows JSONL]
        J[MCP Server<br/>4 Tools]
        K[CLI<br/>9 Commands]
    end

    subgraph "Dashboard (React + Next.js)"
        L[Token Flamegraph]
        M[Live $ Meter]
        N[Receipt Cards]
    end

    A -->|"API requests"| B
    B --> C
    B --> D
    B --> E
    B -->|"saves to"| F
    B -->|"saves to"| G
    F -->|"tail"| I
    I -->|"SSE stream"| H
    G -->|"read"| H
    H -->|"REST"| L
    H -->|"REST"| M
    H -->|"REST"| N
    H -->|"JSON-RPC"| J
    K -->|"reads"| F
    K -->|"reads"| G

User Flow

sequenceDiagram
    participant User as Developer
    participant Agent as AI Agent
    participant Proxy as Headroom Proxy
    participant Ledger as savings_events.jsonl
    participant ZtServe as zt-serve (Node)
    participant Dashboard as React Dashboard
    participant CLI as 0token CLI
    participant MCP as MCP Server

    User->>Agent: "Fix this bug"
    Agent->>Proxy: API request (50K tokens)
    Proxy->>Proxy: Compress (SmartCrusher + AST)
    Proxy->>Ledger: Append event (50K -> 12K)
    Proxy->>Agent: Compressed request (12K tokens)
    Agent->>Proxy: Response
    Proxy->>User: Answer

    par Real-time updates
        Ledger-->>ZtServe: File tail (500ms poll)
        ZtServe-->>Dashboard: SSE stream
        Dashboard->>Dashboard: Update flamegraph + meter
    and CLI access
        User->>CLI: 0token stats
        CLI->>Ledger: Read proxy_savings.json
        CLI-->>User: "308,500 tokens saved ($1.17)"
    and MCP access
        Agent->>MCP: 0token_receipt
        MCP->>Ledger: Read data
        MCP-->>Agent: Session receipt summary
    end

Data Flow (Excalidraw)

What it does

Proof — real numbers, not promises

All numbers below are from real proxy traffic through Headroom's compression engine, measured by 0token's pipeline. No fabricated data.

Quality preserved: Headroom's compression is reversible (CCR) — the LLM can retrieve originals on demand via headroom_retrieve. Standard benchmarks show zero accuracy loss on GSM8K (math), TruthfulQA (factual), and BFCL (tool-calling).

Install

# One command installs everything
pip install 0token

# Or from source
git clone https://github.com/shashank-tomar0/0token.git
cd 0token
pip install -e .

Prerequisites

• Python 3.10+
• Node.js 20+ (for dashboard)
• Your agent's API key (already configured in Claude Code / Cursor / Codex)

Quick start

# One command starts everything
0token start

# That's it! Dashboard opens at http://localhost:3457
# Use your agent normally — savings appear in real-time

Or step by step:

0token start --proxy-port 8787 --serve-port 3456 --web-port 3457

CLI commands

0token start                    Start everything (proxy + backend + dashboard)
0token serve [--port PORT]      Start zt-serve backend (SSE + REST)
0token proxy [--port PORT]      Start Headroom proxy through 0token
0token flamegraph [-n N] [-o F] Generate token flamegraph SVG
0token receipt [--format F]     Generate session receipt card
0token dashboard                Start backend + open dashboard
0token health                   Check if proxy is running
0token stats                    Show savings stats
0token mcp serve                Start MCP server (stdio)
0token mcp tools                List available MCP tools
0token leaderboard list         Show efficiency leaderboard

MCP integration

0token ships an MCP server with 4 tools that any MCP-compatible agent can use:

Add to Claude Code

Add to your ~/.claude.json:

{
  "mcpServers": {
    "0token": {
      "command": "python",
      "args": ["-m", "zt.cli", "mcp", "serve"]
    }
  }
}

Add to Cursor / VS Code

Add to your MCP settings:

{
  "mcpServers": {
    "0token": {
      "command": "python",
      "args": ["-m", "zt.cli", "mcp", "serve"]
    }
  }
}

Dashboard

The React dashboard connects to zt-serve via SSE for real-time updates:

• Token Flamegraph — Interactive stacked bars with hover tooltips showing per-model breakdown
• Live $ Meter — Animated counter with sparkline showing savings in real-time
• Receipt Card — Shareable SVG card with download and copy-to-clipboard

Start with:

0token dashboard
# Opens at http://localhost:3457

Project structure

0token/
├── zt/                          # Python package
│   ├── __init__.py
│   ├── cli.py                   # CLI with 8 commands
│   └── mcp.py                   # MCP server (JSON-RPC 2.0)
├── apps/
│   ├── serve/                   # zt-serve (Node/TypeScript)
│   │   └── src/
│   │       ├── cli.ts           # Entry point
│   │       ├── config.ts        # Workspace path resolution
│   │       ├── server.ts        # HTTP server (SSE + REST)
│   │       └── tailer.ts        # JSONL file follower
│   └── web/                     # Dashboard (React/Next.js)
│       └── src/
│           ├── app/page.tsx     # Main dashboard
│           ├── components/
│           │   ├── TokenFlamegraph.tsx
│           │   ├── LiveMeter.tsx
│           │   └── ReceiptCard.tsx
│           └── lib/useHeadroom.ts  # SSE + REST hook
├── packages/
│   └── shared/                  # TypeScript types
│       └── src/index.ts
├── tests/
│   └── test_e2e.py              # End-to-end verification
├── docs/
│   ├── BUILD-PLAN.md            # Full architecture plan
│   └── DATA-CONTRACT.md         # Headroom data schema
├── pyproject.toml               # Python package config
├── pnpm-workspace.yaml          # Monorepo config
└── README.md                    # This file

How it relates to Headroom

0token complements Headroom; it does not fork or redistribute its engine. Headroom does the hard, hot-path work (Rust core, cache-cooperative compression, honest dollar accounting). 0token is a separate app, off the LLM hot path, that reads Headroom's public local output — the append-only savings_events.jsonl ledger, the proxy_savings.json aggregate, and the loopback HTTP API — and renders it beautifully.

Because it's off the hot path, the correct stack here is TypeScript end-to-end (not Rust): a Node service (zt-serve) sharing types with a Next.js/React web app.

Credit to the Headroom project. "Headroom" is used only to describe interoperability; it does not imply endorsement.

Anti-slop rules (non-negotiable)

1. Never a token/$ number without a paired quality number on the same workload
2. Faithfully propagate Headroom's measured-vs-estimated labels and confidence intervals
3. Real data only — no seeded/mock numbers in any user-facing surface
4. Reproducible — every published number ships its command; 0token reproduce re-runs it
5. The flamegraph tells the truth about its own resolution — labeled, never faked

Contributing

git clone https://github.com/shashank-tomar0/0token.git
cd 0token
pip install -e ".[dev]"
python tests/test_e2e.py

License

Apache-2.0. See LICENSE and CHANGES.md.

Links

• Headroom — the compression engine
• BUILD-PLAN.md — full architecture and phase plan
• DATA-CONTRACT.md — verified Headroom data schema