TokenLeaf
FinOps + GreenOps for LLM users. Compress your prompts losslessly before they hit the LLM, save money and reduce CO₂ emissions — without changing the meaning of what you ask.
Typical savings on debugging prompts with duplicated code, JSON dumps, or repetitive logs: 25–45 %. Savings on short conversational messages: ~0 %. What you save depends entirely on what you paste.
The four pillars
TokenLeaf is more than a single MCP tool. It's four cooperating pieces:
analyze_and_compress_prompt— seven lossless strategies (stack-trace collapse, code-block dedup, JSON minify, HTML/XML, Markdown tables, log collapse, whitespace) applied in a safe order.preprocess_document/preprocess_directory— turn PDFs, DOCX, PPTX, XLSX, EPUB, HTML, RTF into compressed markdown before they're uploaded into a prompt. PDF savings are routinely 70–90 % vs. multimodal page-tokenization.- Output governor —
calculate_esg_impact+ a policy injector that nudges the LLM toward terser responses on simple questions. - Transparent proxy —
tokenleaf proxyruns an Anthropic-API-compatible server on localhost that compresses every outgoingrole=usermessage before forwarding toapi.anthropic.com. Works with Cursor and any SDK that respectsANTHROPIC_BASE_URL.
Code blocks (``` and inline backticks) are never modified beyond
whitespace cleanup. The compressed prompt is always semantically equivalent
to the original for the LLM.
Install
pip install tokenleaf
tokenleaf init
tokenleaf init walks you through:
- Saving your activation key (purchased at https://tokenleaf.app)
- Validating it against the TokenLeaf backend
- Detecting installed MCP hosts (Claude Desktop, Cursor)
- Wiring TokenLeaf into each host's config (with backup + diff confirmation)
Restart your MCP host and you're done.
How it integrates with each host
TokenLeaf intercepts in two complementary ways. Different hosts get different paths:
| Host / Tool | How TokenLeaf intercepts | Reliability |
|---|---|---|
| Claude Desktop | MCP tool invocation via LEAF_INSTRUCTIONS.md in your Claude profile |
~95 % on long prompts |
| Cursor | MCP tools and transparent proxy via ANTHROPIC_BASE_URL |
100 % via proxy |
| Anthropic SDK / scripts | Transparent proxy via ANTHROPIC_BASE_URL |
100 % |
| Claude Code | MCP tools (proxy planned for v0.7) | ~95 % |
Soft transparency on Claude Desktop
Paste the contents of LEAF_INSTRUCTIONS.md into
your Claude Personal preferences or a project's Custom instructions.
Claude will then invoke analyze_and_compress_prompt and preprocess_document
on its own whenever the routine matches. No manual "compress this first"
needed.
True transparency on Cursor / SDK
tokenleaf proxy --port 8788
# Then in another terminal:
export ANTHROPIC_BASE_URL=http://localhost:8788
cursor .
Every outgoing user message is compressed before it reaches Anthropic. System prompts and assistant turns are passed through unchanged.
Usage
In Claude Desktop or Cursor, just paste a long debugging prompt or upload a
document. With LEAF_INSTRUCTIONS.md installed, you'll see a one-line note
at the bottom of Claude's reply:
LEAF saved 8,432 → 4,891 tokens (42.0 % · $0.0106 · 1.42 g CO₂). Deduplicé 2 bloques de código idénticos; minimicé 1 bloque HTML/XML.
Inspect your cumulative savings any time:
tokenleaf summary
tokenleaf dashboard # opens leaf-dashboard.html in your browser
CLI
tokenleaf init # interactive first-time setup
tokenleaf doctor # diagnose license, hosts, ledger
tokenleaf serve # run the MCP server (stdio)
tokenleaf install # add TokenLeaf to all detected hosts
tokenleaf uninstall # remove TokenLeaf from a host's config
tokenleaf summary # cumulative savings ledger as JSON
tokenleaf dashboard # open the local savings dashboard
tokenleaf proxy # run the transparent Anthropic-API proxy
tokenleaf convert # convert a document/folder to compressed markdown
tokenleaf handshake # force a fresh license handshake
tokenleaf config # print resolved settings (secrets masked)
Privacy
- Prompt content never leaves your machine. All compression and document conversion happen locally.
- The local ledger stores only sizes, costs, and SHA-256 hashes — never prompt text.
- The license-validation handshake sends only your activation key and a stable machine fingerprint. No prompt data is transmitted.
- The optional heartbeat (fired once per UTC day per machine, only when
TOKENLEAF_LICENSE_KEYis set) carries only yourlicense_id, machine fingerprint, timestamp, and lifetime aggregate totals. No per-event detail, no domain breakdown, no prompt content. The exact request body is built bysrc/tokenleaf/telemetry/heartbeat.pyand a privacy-canary test intests/test_telemetry.pyfails CI if any prompt-content-shaped field name appears. - Personal-use mode (no license key +
TOKENLEAF_ALLOW_OFFLINE=true, the default) makes zero network calls. You can use the full feature set offline; only paid tier requires a key.
Requirements
- Python ≥ 3.11
- An MCP-compatible host (Claude Desktop, Cursor, Claude Code, or any client supporting MCP)
- A TokenLeaf subscription — start at https://tokenleaf.app
License
Proprietary. See the LICENSE file. Use requires an active subscription.
Metadata
Release files for tokenleaf 0.6.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| tokenleaf-0.6.3.tar.gz | 105.6 kB | With provenance | Details for tokenleaf-0.6.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| tokenleaf-0.6.3-py3-none-any.whl | Python 3 | none | any | Details for tokenleaf-0.6.3-py3-none-any.whl |
Total release size: 227.5 kB
Release files / tokenleaf-0.6.3.tar.gz
| Download URL | tokenleaf-0.6.3.tar.gz |
|---|---|
| Size | 105.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f8029d665c3d76dede4903bd94bfde6efe4f9c8c849df136266672504fb5fcca
|
|
BLAKE2b-256 checksum How to use checksums |
e0985996080f5c5f3a8a19d25c017c43f7f6e23a7efe64b8a45d26cdf85dc53b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 9, 2026.
Transparency logRelease files / tokenleaf-0.6.3-py3-none-any.whl
| Download URL | tokenleaf-0.6.3-py3-none-any.whl |
|---|---|
| Size | 121.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7dedb453d5569ad3e11285f4003719aeedafc8c0448c2cd1e72a4d263ddfcb0b
|
|
BLAKE2b-256 checksum How to use checksums |
51c93757cb600988bc98cd0fd78c41e5f46446608cd8f72c4eb831a8455a92ae
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 9, 2026.
Transparency logSecurity for tokenleaf 0.6.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for tokenleaf-0.6.3.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 9, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.