# Paritok

> A non-destructive compression gateway for AI coding agents that cuts input-token bills by compressing tool schemas, file reads, and history on the fly.

Paritok is an open-source compression gateway that sits between your coding agent and the LLM API, rewriting requests to strip token bloat before forwarding them upstream. Built by two engineers — Jiayu Shi (training, modeling, data pipeline) and Luzhuo Chen (evaluation, deployment, product) — it ships under Apache 2.0 and is available both as a self-hosted stack and as a managed hosted endpoint.

## What It Is

Paritok acts as a drop-in proxy: you point your agent's `BASE_URL` at Paritok instead of Anthropic or OpenAI, and everything else stays the same. On every request it applies three independent compression levers — tool-schema filtering, content compression, and history summarization — then forwards the rewritten request upstream. The LLM's response comes back untouched. Nothing is permanently discarded: any compressed or filtered content is recoverable on demand via `read_original` or `gateway_search_tools` calls.

The compression engine is **Paritok-4B-v1**, described by the project as the first open-source 4B model trained specifically on real coding-agent trajectories (45K samples, Qwen3-4B backbone, LoRA adapter, Apache 2.0 weights). On SWE-bench Lite end-to-end evaluation, the project reports 86.5% quality retained at a 25.7% compression rate — meaning it compresses content to roughly one-quarter of its original size while retaining most agent solve quality.

## The Three Compression Levers

Paritok attacks the token bill through three stacking mechanisms:

- **Tool-schema filter:** Coding agents often send 70+ tool schemas in full JSON on every request. Paritok uses an embedding model (BAAI/bge-small-en-v1.5, CPU-only) to keep only the schemas relevant to the current task and stub the rest. The project reports this drops a typical ~29K-token tool block to ~8K per turn — the largest single-turn saving.
- **Content compression:** File reads, tool output, and stale history turns are compressed by the 4B model to approximately 26% of their original size, tagged with recoverable references. Identifiers, paths, and error strings are preserved by design.
- **History summarization:** Turns beyond a configurable recent window are summarized once the context budget fills, keeping long sessions inside the model's context window without forcing aggressive client-side compaction.

## Compounding Savings Over Sessions

The project's own measurements show savings grow non-linearly with session length. According to the README, content compression savings are roughly quadratic (each turn's compressed reads keep paying off on every later turn), while the tool filter adds a fixed linear cut on top. The project reports approximately 25% end-to-end savings on turn 1, growing to ~39% by turn 5 and past 60% by turn 20 in a default ~40-tool configuration. A secondary benefit: because each turn's prefix is smaller, the agent fits roughly 3× more turns in the same context window before hitting compaction limits.

## Deployment Model

Paritok supports two deployment paths:

- **Self-host (free, Apache 2.0):** The full gateway and 4B model ship open. The model runs via Ollama (~2.5GB at Q4, any 8GB GPU) or vLLM (24GB GPU, full precision). The tool filter runs entirely on CPU. Setup is a `pip install "paritok[proxy]"` and a single environment variable.
- **Hosted GPU endpoint:** A managed, always-on endpoint served by Paritok's own GPUs, accessible via API key from paritok.com. No local GPU required.

Compatible agents include Claude Code, Cursor, Codex, OpenHands, and any agent that honors `BASE_URL` or uses the OpenAI Chat Completions API. Any OpenAI-compatible upstream (Groq, OpenRouter, Gemini, etc.) is also supported via `--openai-url`.

## Update: v1.3.0

The project's changelog shows active development since its July 2026 launch:

- **v1.3.0 (2026-07-31):** Stability release; edit-recovery improvements; `read_original` API rename (previously `expand_context`).
- **v1.2.0 (2026-07-19):** Shipped the embedding-based tool filter, described as the biggest single-turn lever, with prompt-cache-friendly tool selection and `gateway_search_tools` recall.
- **v1.0.0 (2026-07-15):** Gateway open-sourced as a drop-in proxy for Claude Code, Cursor, and Codex.
- **Paritok-4B-v1 (2026-07-14):** Model released on Hugging Face Hub with full SWE-bench Lite evaluation.

The roadmap lists a Paritok-4B-v2 targeting sub-20% compression rate, larger backbone models (10B+) for multi-day sessions, multi-language expansion beyond Python, and native MCP plugin integrations.

## Features
- Drop-in proxy via single BASE_URL environment variable
- Tool-schema semantic filter (embedding-based, CPU-only)
- 4B model content compression to ~26% of original size
- Non-destructive: all compressed content recoverable via read_original
- History summarization for long multi-turn sessions
- Prompt-cache-friendly frozen tool-schema block
- Self-host on Ollama or vLLM (Apache 2.0)
- Managed hosted GPU endpoint
- Compatible with Claude Code, Cursor, Codex, OpenHands
- Any OpenAI-compatible upstream supported
- Live /stats endpoint with compression totals and cost savings
- SDK mode via ParitokClient wrapper
- Python 3.11+ support
- PyPI package with proxy and toolselect extras

## Integrations
Claude Code, Cursor, Codex, OpenHands, Anthropic API, OpenAI API, Groq, OpenRouter, Gemini, Ollama, vLLM, Hugging Face Hub, PyPI

## Platforms
WINDOWS, MACOS, LINUX, WEB, API, CLI

## Pricing
Open Source, Free tier available

## Version
1.3.0

## Links
- Website: https://www.paritok.com
- Documentation: https://github.com/Paritok-official/paritok-4b-v1
- Repository: https://github.com/Paritok-official/paritok-4b-v1
- EveryDev.ai: https://www.everydev.ai/tools/paritok