TokenPak — Cut your LLM token spend — guided setup

PyPI version Python 3.10+ License: Apache-2.0

The open logistics layer for AI context.

TokenPak starts as a local proxy that packs AI requests before they ship — reducing wasted context and giving teams receipts for what changed. Fewer tokens, lower cost. No code changes, no cloud, no credentials stored.

First measured request receipt in three commands

Prerequisites: Python 3.10+ and an already authenticated supported client. The reference path below uses Codex and reuses its existing OAuth login and normal default model. An API key or explicit model override is optional, not required. Run it from a real project; provider usage may count against your subscription or incur provider charges.

python -m pip install tokenpak
tokenpak serve --profile aggressive --stats-footer  # terminal 1; leave running
tokenpak codex  # terminal 2; use your existing login and selected/default model

In Codex, make a normal context-bearing request. The proxy prints a measured receipt in terminal 1. In this unmodified reference setup, the built-in Pak builder leaves every system, user, and assistant conversation turn intact, so the receipt truthfully reports 0 tokens saved. This verifies routing and accounting without claiming savings that did not occur. The session-only footer is off by default and does not alter the provider response.

See the first receipt guide for prerequisites, the expected zero-savings output, the five-minute reference target, and the separate explicit compression surfaces.

Offline fixture demo

To inspect compression without credentials or provider spend:

tokenpak demo

┌──────────────────────────────────────────────────────┐
│  TokenPak — Offline Fixture Demo                     │
├──────────────────────────────────────────────────────┤
│  Scenario              DevOps agent (config + logs)  │
│  Data source                built-in sample fixture  │
│  Savings drivers                      dedup + alias  │
├──────────────────────────────────────────────────────┤
│  Original                                747 tokens  │
│  Compressed                              502 tokens  │
│  Fixture delta                  245 tokens  (32.8%)  │
│  Fixture cost delta            $0.00073 per fixture  │
│  Receipt status               not a savings receipt  │
├──────────────────────────────────────────────────────┤
│  Stages: dedup, alias, segmentize, directives        │
└──────────────────────────────────────────────────────┘

This is an illustrative fixture, not a measured first-request receipt. Token counts vary by route and workload. Measure your own with tokenpak savings; inspect provider-cache vs. TokenPak attribution with tokenpak status --tip-cache.

Works with

Claude Code · Cursor · Cline · Continue.dev · Aider · OpenAI SDK · Anthropic SDK · LiteLLM · Codex

Run tokenpak integrate to see the full client list with setup guides for each.

Install

uv tool install tokenpak      # or: pipx install tokenpak

Either one installs the tokenpak command into its own isolated environment. To use TokenPak as a library inside a project, pip install tokenpak into an activated virtual environment instead.

See docs/install-guide.md for per-installer detail, optional extras, and the externally-managed-environment (PEP 668) error. See docs/quickstart.md for per-client configuration.

Requirements: Python 3.10+.

Exposing the proxy beyond 127.0.0.1? Set TOKENPAK_PROXY_AUTH_TOKEN to a shared secret to require Authorization: Bearer <token> on remote requests (see docs/configuration/proxy-auth.md).

Runnable examples

The PyPI wheel keeps the install slim and does not bundle the repository's top-level examples. To run them after a normal package install, clone or download the source tree for the example files:

git clone https://github.com/tokenpak/tokenpak.git
cd tokenpak
python -m venv .venv
source .venv/bin/activate
python -m pip install -U tokenpak
python examples/basic_compression.py

examples/basic_compression.py is local-first and does not require provider credentials. See examples/README.md for the full examples index and developer editable-install path.

What's included (Free)

Dispatch (v0.1-alpha preview): turn a request into a scoped, resumable, reviewable workflow from the CLI. It is a source/main-branch preview and is not yet part of a released pip install tokenpak; see the Dispatch guide.

  • Context compression — deterministic token reduction on real agent workloads, <50ms latency. Savings are route-specific: direct API, CLI, and uncached repeated-agent loops are the best fit, while Claude Code/TUI routes may show lower incremental savings when the provider cache already handled repeated context. Measure your own savings with tokenpak savings; inspect attribution with tokenpak status --tip-cache (reproduce the headline benchmark with make benchmark-headline).
  • Client integration — one command wires Claude Code, Cursor, Aider, and 6 other clients
  • Model routing — send requests to the right model automatically, with fallback rules
  • Cost tracking — per model, per session, per agent; local SQLite, zero cloud
  • TIP Spend Guard — pre-send circuit breaker; blocks runaway requests before provider call. Yes/No release or [TIP: allow=once max=$X] directive. Catches both single-request spikes and the death-by-1000-cuts pattern via session-cumulative tracking. See docs/spend-guard.md.
  • Vault indexing + semantic search — index your codebase; search without an LLM call
  • MultiPak Pro Phase 1 OSS surface — read-only Vault Pak adapter, companion journal promotion-candidate marking, tokenpak pak CLI, /pak/v1/* proxy stubs. Full MultiPak (capture pipeline, recall ranking, Handoff Paks, anchor hydration) requires tokenpak-paid (Pro). See docs/multipak.md.
  • CLI + proxy server — tokenpak serve, tokenpak cost, tokenpak savings
  • Value proof — tokenpak prove run benchmarks direct API vs. TokenPak on your own prompt workload and prints a side-by-side cost/token report. See the value proof guide.
  • A/B testing and replay/debug — compare compression configs, replay past requests
  • 50 built-in compression recipes — YAML, customizable

Repeated context is reused from cache instead of re-sent on every call. See docs/quickstart.md and docs/api-tpk-v1.md to get started.

Open source & editions

TokenPak's core is Apache-2.0 open source; TokenPak Pro and hosted services are proprietary. Commercial packaging is not published yet.

Support

License

The TokenPak open-source core is licensed under the Apache License 2.0 — see LICENSE. TokenPak Pro and hosted services are proprietary.

Trademark

"TokenPak", the TokenPak name, logo, and brand assets are trademarks of TokenPak and are not licensed under Apache-2.0 (Apache-2.0 §6 grants no trademark rights). Nominative and reference use — for example "works with TokenPak" or "a plugin for TokenPak" — is fine. Using the name or logo in a way that implies endorsement, sponsorship, or affiliation, or naming a fork, product, or service "TokenPak" (or something confusingly similar), is not.

Project links

Data verified by PyPI on Sep 9, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (1.28.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for TokenPak from gravatar.com TokenPak

Credits

PyPI data
Data sourced directly from PyPI's database.

Author/Maintainer: TokenPak

GitHub Statistics

Data verified by PyPI on Sep 9, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

Apache Software License (Apache License)

Requires

Python >=3.10

Provides Extra

retrieval code-compression intelligence data compression integrations-litellm dispatch full dev tokens docs otel autogen llamaindex serve telemetry

Tags

llm ai proxy token-optimization openai anthropic compression context context-window tokens cost-tracking routing

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

tokenpak-1.27.0.tar.gz (2.6 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

tokenpak-1.27.0-py3-none-any.whl (3.1 MB view details)

Uploaded Python 3

File details

Details for the file tokenpak-1.27.0.tar.gz.

File metadata

  • Download URL: tokenpak-1.27.0.tar.gz
  • Upload date:
  • Size: 2.6 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for tokenpak-1.27.0.tar.gz
Algorithm Hash digest
SHA256 fa19e72bb746d45ea62116f071c2b8997ed28b597b96cacf172e373276cdb39b
MD5 aff346a30a570fa77279d9c991e2a6cb
BLAKE2b-256 92e36697b89cd490be2936ea3fa8c4914e936a5d8becbc33e47099258bd53978

See more details on using hashes here.

Provenance

The following attestation bundles were made for tokenpak-1.27.0.tar.gz:

Publisher: release.yml on tokenpak/tokenpak

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tokenpak-1.27.0-py3-none-any.whl.

File metadata

  • Download URL: tokenpak-1.27.0-py3-none-any.whl
  • Upload date:
  • Size: 3.1 MB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for tokenpak-1.27.0-py3-none-any.whl
Algorithm Hash digest
SHA256 640cda27098b6b4d8729e2dbe669145a3d77b88fee4b3f0b190d8e9695b93f77
MD5 39727e705adf48d64f0525acbcfc17c7
BLAKE2b-256 b48a9a3d77db95db2b9094997623a085b55d2d89efdb69b91b417d9d29466aaa

See more details on using hashes here.

Provenance

The following attestation bundles were made for tokenpak-1.27.0-py3-none-any.whl:

Publisher: release.yml on tokenpak/tokenpak

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

1.28.0

2 files

This release

1.27.0 This release

2 files

1.26.0

2 files

1.25.3

2 files

1.25.2

2 files

1.25.1

2 files

1.24.0

2 files

1.23.0

2 files

1.22.0

2 files

1.21.0

2 files

1.20.0

2 files

1.19.3

2 files

1.19.1

2 files

1.19.0

2 files

1.18.5

2 files

1.18.4

2 files

1.18.3

2 files

1.18.2

2 files

1.18.1

2 files

1.18.0

2 files

1.17.1

2 files

1.17.0

2 files

1.16.0

2 files

1.15.0

2 files

1.14.0

2 files

1.13.0

2 files

1.12.0

2 files

1.11.3

2 files

1.11.1

2 files

1.11.0

2 files

1.10.4

2 files

1.10.2

2 files

1.10.0

2 files

1.9.3

2 files

1.9.2

2 files

1.9.1

2 files

1.9.0

2 files

1.8.0

2 files

1.7.1

2 files

1.7.0

2 files

1.6.1

2 files

1.5.6

2 files

1.5.5

2 files

1.5.4

2 files

1.5.2

2 files

1.5.1

2 files

1.5.0

2 files

1.4.0

2 files

1.3.22

2 files

1.3.20

2 files

1.3.18

2 files

1.3.17

2 files

1.3.16

2 files

1.3.15

2 files

1.3.14

2 files

1.3.13

2 files

1.3.12

2 files

1.3.11

2 files

1.3.10

2 files

1.3.9

2 files

1.3.8

2 files

1.3.7

2 files

1.3.6

2 files

1.3.2

2 files

1.3.1

2 files

1.3.0

2 files

1.2.93

2 files

1.2.92

2 files

1.2.91

2 files

1.2.9

2 files

1.2.8

2 files

1.2.7

2 files

1.2.6

2 files

1.2.5

2 files

1.2.4

2 files

1.2.3

2 files

1.2.2

2 files

1.2.1

2 files

Yanked

1.2.0

2 files

Yanked reason: Release-blocking bugs; superseded by 1.2.1 (same day)

1.1.0

1 file

Yanked

1.0.2

2 files

Yanked reason: will be republished soon

Yanked

1.0.1

2 files

Yanked reason: will be republished soon

Yanked

1.0.0

2 files

Yanked reason: will be republished soon

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