Paritok-4B-v1: a compression gateway that rewrites coding-agent requests before they hit the API

The bill Paritok targets is the prefix you resend every turn

A coding agent resends a large fixed prefix on every request: dozens of tool schemas in full JSON, the accumulating message history, and the big blocks produced by file reads and tool output. Paritok's README states that tool schemas alone can reach 70+ entries once MCP servers are added, and that on a typical Claude Code turn the tool block is roughly 29K tokens. That number is the one the project is built around, because it is paid again on every turn regardless of what the user asked. Paritok is aimed at teams running Claude Code, Cursor, Codex, or OpenHands against a metered API, where input tokens dominate the invoice and session length is measured in dozens of turns rather than one. It is not a code-completion tool and it does not change what the agent does. It rewrites the request on the wire.

Three levers, only one of which is a single-turn win

The gateway applies three independent mechanisms. The first is a semantic tool-schema filter: it keeps the schemas relevant to the user's intent in full and stubs the rest. The README calls this the largest single-turn lever, citing a drop from about 29K to about 8K tokens on a typical Claude Code turn, and notes that an agent's core execution tool (shell, exec, apply_patch) is never stubbed so agents like Codex always keep the tool they cannot work without. The second is content compression: each tool_result, file read, and expired history turn is compressed by the 4B model to roughly 26% of its original size and tagged with a reference id. The README is candid that this is the smaller lever within a single turn, since most of a turn's cost is the fixed prefix, and that its effect accumulates across a session. The third is history summarization, applied once the context window fills, so a long session stays inside the window instead of overflowing or forcing client-side compaction. The three stack, and they touch different parts of the request.

Non-destructive means the wire format is lossy, not the session

The design choice worth understanding is recoverability. Compressed segments are replaced by a reference tag, and filtered tool schemas are removed from the request, but neither is discarded. The README states that the agent can call `gateway_search_tools` to get a full schema back and `read_original` (renamed from `expand_context` in v1.3.0) to pull back the exact untouched bytes of a compressed segment. That is what makes the proxy viable as a drop-in: the model is not permanently working from a lossy summary, it is working from a summary plus an escape hatch. The trade-off is that recovery depends on the model recognizing when it needs the original. A model that never calls `read_original` will operate on compressed text indefinitely, and the README does not describe any mechanism that forces re-expansion when the compressed form turns out to be insufficient.

Prompt-cache stability is the constraint that shapes the tool filter

Filtering tools per request would be the obvious implementation, and it would also be the wrong one. The README states that the tool selection is frozen per conversation so the tools block stays byte-stable turn to turn and does not invalidate the provider's KV cache. That single constraint explains why the filter is described as embedding-based and conversation-scoped rather than recalculated from each new user message. It also explains the v1.2.0 release note, which frames the embedding tool filter as unlocking prompt-cache-friendly tool selection. The cost of this choice is that a conversation whose task drifts mid-session keeps the tool set chosen at the start until the selection is recomputed. The README does not specify what triggers recomputation, so that is a behaviour to observe rather than assume.

Running it: a BASE_URL swap and a local embedding model

The integration model is a proxy. The README's diagram shows the agent pointing at Paritok instead of Anthropic or OpenAI, with the gateway rewriting the request before it is forwarded upstream and the response flowing back unchanged. The claim is that no agent code changes, which is what makes it usable with Claude Code, Cursor, Codex, OpenHands, and anything else that honours BASE_URL. The tool filter runs locally: the README names BAAI/bge-small-en-v1.5, an MIT-licensed model of roughly 130MB, executed on CPU with no API call and no per-token fee. The configuration key given for the filter is `tool_discovery.strategy: embedding`. The README also references a `/stats` dashboard introduced in v1.3.8 that shows live token savings and per-request original-to-compressed figures, which is the surface you would use to check that the gateway is doing what you expect on your own traffic. The Python requirement is 3.11+.

The savings claim is a session claim, and the README says so

The headline figures are 25% on turn one and past 85% in long or context-saturated sessions, with roughly 3x more turns fitting in the same window. The README is unusually direct about why the first number is small: most of a single turn's cost is the fixed prefix, so content compression contributes only a few percent on its own. The large number is a session-level effect produced by compounding, and the README's supporting evidence is an A/B on a read-only find-the-bug task run for five consecutive turns in one Claude Code session on Sonnet. That is a narrow task shape. Read-only investigation is exactly the workload where file reads and tool output dominate and where nothing gets mutated, so the compression ratio is likely at its most favourable. A session that writes files, runs test suites, and re-reads its own diffs has a different token profile, and the supplied material contains no measurement for it. The turn-one figure is the one I would trust most, because it depends mainly on the tool block rather than on the model's compression quality.

Where a compression gateway is the wrong layer

The clearest alternative is client-side context management: the compaction that agents like Claude Code already perform when the window fills, which drops or summarizes old turns before the request is built. Paritok's third lever overlaps with that directly, and the README positions summarization as the thing that avoids an aggressive client-side compaction that drops detail. The difference in approach is where the decision is made and whether it is reversible. Client-side compaction happens inside the agent, is not recoverable, and cannot see the tool-schema block as a separate budget line. Paritok makes the same decision at the proxy, keeps a reference to the original, and treats tools as a distinct lever. A second alternative is simply paying for a larger context window or a cheaper input tier. If your sessions are short, or if your provider already caches your prefix aggressively, the fixed prefix is cheap and a proxy that rewrites every request adds a hop and a local model without much to remove. Paritok is the wrong tool when the dominant cost is output tokens, because none of the three levers touch the response.

Maintenance surface: a proxy, a model, and a fast-moving changelog

The gateway repository is Apache-2.0, which permits commercial use and modification, and the licence text in the repository is the authoritative version rather than any summary here. Two operational costs are visible in the material. First, the gateway sits in the request path for every call, so its availability and latency are now part of your agent's availability and latency; the README does not describe a fallback path for when the gateway is down. Second, the project is moving quickly. The changelog in the README spans v1.0.0 in mid-July 2026 through v1.3.8 in mid-August 2026, and it includes an API rename (`expand_context` to `read_original`) in v1.3.0. Renames in a component that agents call by name are upgrade work, not cosmetic. The 4B model itself is a separate artifact hosted on Hugging Face, and its licence terms are not stated in the supplied material, so anyone planning to redistribute or fine-tune the weights should read that page rather than assume Apache-2.0 covers both.

Editorial conclusion

Adopt Paritok if you run a long-session coding agent against a metered input-token API and you are willing to route traffic through a local proxy plus a 4B model. Do not adopt it if your workload is dominated by short single-turn calls, if you cannot run the model alongside the agent, or if you need a published per-turn cost model before committing. Verify first: reproduce the README's five-turn A/B on your own repository, confirm that `tool_discovery.strategy: embedding` keeps your agent's core execution tool unstubbed, and check that `read_original` returns byte-identical content for the file types you care about. The Apache-2.0 licence covers the gateway repository; the model weights on Hugging Face are a separate artifact and their terms should be read on their own page.

Official sources

1. Issues
2. License: Apache-2.0
3. Paritok-official/paritok-4b-v1 on GitHub
4. Project website
5. README