0token

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+
• Your agent already configured with API key (Claude Code, Cursor, Codex)
• (Optional) Node.js 20+ if you want the React dashboard instead of the built-in one

---

Quick start

# 1. Install
pip install 0token

# 2. Run setup (auto-detects your API key)
zt setup

# 3. Start everything
zt start

# 4. Route your agent through the proxy
set ANTHROPIC_BASE_URL=http://127.0.0.1:8787
claude

# 5. Use your agent normally — savings appear on the dashboard

That's it! No API key configuration needed — 0token auto-detects it from your Claude Code config.

Note: On Windows, if zt is not recognized, add Python Scripts to PATH: C:\Users\YOU\AppData\Roaming\Python\Python313\Scripts Or use: python -m zt.cli start

---

CLI commands

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

All commands also work via python -m zt.cli <command>

---

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:3456

---

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