Metadata-Version: 2.4
Name: tokenburn
Version: 0.2.0
Summary: Local-first proxy for LLM spend visibility and control.
License: MIT
Keywords: llm,proxy,tokens,cost,observability
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: click>=8.0
Requires-Dist: rich>=12.0
Provides-Extra: share
Requires-Dist: jinja2>=3.0; extra == "share"
Provides-Extra: proxy
Requires-Dist: starlette>=0.37; extra == "proxy"
Requires-Dist: uvicorn>=0.29; extra == "proxy"
Requires-Dist: httpx>=0.25; extra == "proxy"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: jinja2>=3.0; extra == "dev"
Requires-Dist: starlette>=0.37; extra == "dev"
Requires-Dist: uvicorn>=0.29; extra == "dev"
Requires-Dist: httpx>=0.25; extra == "dev"
Provides-Extra: all
Requires-Dist: jinja2>=3.0; extra == "all"
Requires-Dist: starlette>=0.37; extra == "all"
Requires-Dist: uvicorn>=0.29; extra == "all"
Requires-Dist: httpx>=0.25; extra == "all"

# TokenBurn

> `htop` for your LLM spend — proxy-only.

TokenBurn is a local-first HTTP proxy for LLM spend visibility and control.

Route OpenAI-, Anthropic-, and Gemini-compatible traffic through a local proxy. TokenBurn logs usage locally, attributes cost by model/provider/program/tag, and turns raw traffic into actionable waste reports.

**No hosted backend. No account. No prompt egress by default.**

---

## Install

```bash
pip install "tokenburn[proxy]"
tokenburn proxy setup
tokenburn proxy start --background
```

After setup, clients that support base URL overrides can route through TokenBurn with no app-specific SDK integration.

---

## What it does

- **Proxy-based capture** — intercepts LLM traffic at the HTTP layer
- **Cross-language** — works with Python, TypeScript, Go, curl, and anything else that can point at a base URL
- **Cross-provider** — OpenAI, Anthropic, Gemini
- **Local logs** — normalized JSONL logs under `~/.tokenburn/logs/`
- **Spend reports** — model, provider, endpoint, program, and tag breakdowns
- **Waste detection** — highlights expensive patterns worth fixing first
- **Shareable output** — terminal and exported reports

---

## Core commands

```bash
tokenburn proxy setup
tokenburn proxy start --background
tokenburn proxy status
tokenburn proxy stop

tokenburn report
tokenburn gain
tokenburn share --open
tokenburn doctor
```

---

## Product direction

TokenBurn is proxy-only.

That means the product lives at the proxy boundary rather than inside application runtimes.

The product lives at the network boundary, not inside app SDKs.

---

## Repo docs

- `PROXY_TFF.md` — proxy technical design
- `SPEC.md` — product and positioning
- `keche.md` — project operating brief
- `CLAUDE.md` — maintainer workflow notes

---

## License

MIT
