BurnLens Documentation

Install

BurnLens is a Python package. The published wheel needs Python 3.10 or newer, and everything it records lives in a local SQLite database at ~/.burnlens/burnlens.db. Nothing on this page needs an account.

pip install burnlens

Two entry points — you do not need both

BurnLens answers two different questions, and the way in is different for each. Most people start with scanning, because it produces a real number in about fifteen seconds without touching any application code.

1. Scan — what have my coding agents already spent?

Claude Code, Cursor, Codex and Gemini CLI all write session logs to disk. burnlens scan reads them, prices every call, and stores the result. It is retroactive: it works on history that already exists, with no proxy and no code change.

burnlens scan
burnlens top

Full scanning documentation →

2. Proxy — stop the next expensive call before it is billed

For production API traffic, BurnLens runs a local proxy on 127.0.0.1:8420. Point your SDK at it and calls route through unchanged, including streaming. Because the proxy sees the request before it is forwarded, it can refuse one that would breach a budget — the call is never billed, rather than being reported after the fact.

burnlens start
export OPENAI_BASE_URL=http://127.0.0.1:8420/proxy/openai

Full proxy and tagging documentation →

What leaves your machine

Nothing, until you ask for it. Scanning and the proxy are entirely local: the proxy forwards your request to the provider you were already calling, and the scanner never makes a network call at all.

If you enable cloud sync, cost metadata is uploaded — model, token counts, timestamps, tag values, repo. Prompt and response bodies are not, and there is no setting that turns that on. How data is handled.

Cloud sync (optional)

Everything above works offline and free, forever. Cloud sync exists so a team can share one dashboard instead of each developer reading their own SQLite file.

burnlens login          # authenticate and enable cloud sync
burnlens sync --status  # what has been pushed, and what has not
burnlens sync --now     # push everything un-synced immediately

The free plan keeps 7 days of history, 10,000 records per month, one API key and one seat. Paid plans extend retention and seats — see pricing.

Reference beyond these pages

• ARCHITECTURE.md — how the proxy, pricing engine, WAL and dashboard fit together.
• BUDGET_ENFORCEMENT.md — enforcement semantics under concurrency, streaming and retries, with the implementing function cited per claim.
• PROVIDERS.md — per-provider routing, auth and pricing detail.
• Troubleshooting — common errors and fixes.
• FAQ — what BurnLens does and does not do.