Skip to main content

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:

  1. 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.
  2. 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.
  3. Output governor — calculate_esg_impact + a policy injector that nudges the LLM toward terser responses on simple questions.
  4. Transparent proxy — tokenleaf proxy runs an Anthropic-API-compatible server on localhost that compresses every outgoing role=user message before forwarding to api.anthropic.com. Works with Cursor and any SDK that respects ANTHROPIC_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:

  1. Saving your activation key (purchased at https://tokenleaf.app)
  2. Validating it against the TokenLeaf backend
  3. Detecting installed MCP hosts (Claude Desktop, Cursor)
  4. 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_KEY is set) carries only your license_id, machine fingerprint, timestamp, and lifetime aggregate totals. No per-event detail, no domain breakdown, no prompt content. The exact request body is built by src/tokenleaf/telemetry/heartbeat.py and a privacy-canary test in tests/test_telemetry.py fails 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)

Source distribution for tokenleaf 0.6.3
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)

Table of built distributions (wheels) for tokenleaf 0.6.3
File Interpreter ABI Platform Actions
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 log

Release 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 log

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

Select from 2 files

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 log

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

Release history Release notifications | RSS feed

This release

0.6.3 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page