Metadata-Version: 2.5
Name: 0token
Version: 0.4.0
Summary: See and prove where your agent's tokens go
Project-URL: Homepage, https://github.com/shashank-tomar0/0token
Project-URL: Repository, https://github.com/shashank-tomar0/0token
Author: 0token contributors
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: ai,compression,flamegraph,llm,proxy,savings,token
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: headroom-ai[proxy]
Description-Content-Type: text/markdown

# 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](https://github.com/headroomlabs-ai/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

```mermaid
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

```mermaid
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)

<p align="center">
  <img src="docs/excalidraw-flow.svg" alt="0token Data Flow" width="900">
</p>

---

## What it does

| Surface | What you get | How |
|---------|-------------|-----|
| **Token Flamegraph** | Per-request breakdown of where tokens go | `0token flamegraph` → SVG |
| **Live $ Meter** | Real-time animated savings counter | Dashboard SSE stream |
| **Receipt Cards** | Shareable PNG/SVG after sessions | `0token receipt` → image |
| **MCP Server** | 4 tools for any MCP-compatible agent | `0token mcp serve` (stdio) |
| **CLI** | 8 commands for every workflow | `0token {command}` |
| **Dashboard** | React real-time UI | `0token dashboard` |

---

## 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.

| Workload | Before | After | Savings | Cost Saved |
|----------|-------:|------:|--------:|-----------:|
| 20 mixed agent requests | 430,000 | 121,500 | **71.7%** | $1.175 |
| gpt-4o (10 requests) | 229,900 | 61,800 | **73.1%** | $0.575 |
| claude-sonnet-4 (10 requests) | 200,100 | 59,700 | **70.2%** | $0.600 |

**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

```bash
# 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

```bash
# 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:

| Tool | Description |
|------|-------------|
| `0token_stats` | Lifetime and session token savings, per-model breakdown |
| `0token_recent` | Last N compression events with before/after/cost |
| `0token_flamegraph` | Text-based flamegraph of token usage by model |
| `0token_receipt` | Session receipt summary (tokens, %, cost, model) |

### Add to Claude Code

Add to your `~/.claude.json`:

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

### Add to Cursor / VS Code

Add to your MCP settings:

```json
{
  "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:

```bash
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

```bash
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`](LICENSE) and [`CHANGES.md`](CHANGES.md).

---

## Links

- [Headroom](https://github.com/headroomlabs-ai/headroom) — the compression engine
- [BUILD-PLAN.md](docs/BUILD-PLAN.md) — full architecture and phase plan
- [DATA-CONTRACT.md](docs/DATA-CONTRACT.md) — verified Headroom data schema
