@tokz/anthropic

Drop-in tokz compression for the official @anthropic-ai/sdk. tool_result content is compressed with deterministic intent derived from the latest user request and matching tool_use name/input.

Install

npm install @tokz/anthropic @tokz/sdk @anthropic-ai/sdk

Usage

import Anthropic from "@anthropic-ai/sdk";
import { withTokz } from "@tokz/anthropic";

const anthropic = withTokz(new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY! }), {
  apiKey: process.env.TOKZ_API_KEY!, // required
});

const bigKubectlJson = JSON.stringify({
  items: Array.from({ length: 200 }, (_, i) => ({
    metadata: { name: `web-${i}` },
    status: { phase: i % 37 === 0 ? "CrashLoopBackOff" : "Running" },
  })),
});

const msg = await anthropic.messages.create({
  model: "claude-sonnet-4-5",
  max_tokens: 1024,
  messages: [
    { role: "user", content: "How many pods are running?" },
    { role: "assistant", content: [{ type: "tool_use", id: "t1", name: "getPods", input: {} }] },
    { role: "user", content: [{ type: "tool_result", tool_use_id: "t1", content: bigKubectlJson }] }, // ← compressed
  ],
});

Before / after

A 4,000-token kubectl get pods -o json tool result, at the default targetRatio: 0.45:

| | tokens | |---|---| | before | ~4,000 | | after | ~1,800 |

Handles both content: string and content: ContentBlock[] forms. tool_use, image, and thinking blocks pass through untouched. Every emitted span is a byte-exact substring of your original text — the server only ever returns offsets.

Options

import Anthropic from "@anthropic-ai/sdk";
import { withTokz } from "@tokz/anthropic";

const anthropic = withTokz(new Anthropic(), {
  apiKey: process.env.TOKZ_API_KEY!,        // required
  baseUrl: "https://api.tokz.dev",          // default
  targetRatio: 0.45,                        // fraction of bytes kept
  autoCompress: ["tool_result"],            // default; add "system" or "user" too
  firewall: true,                           // protect system/control selection
  onSavings: (originalTokens, compressedTokens, originalCost, compressedCost) => {
    console.log(`${originalTokens} -> ${compressedTokens} tokens`);
  },
});

Firewall mode sends one segmented request: system text is protected, conversation text is control, and tool_result text is data. Only data is compressible. The wrapper fails open to the original Anthropic payload on a Tokz error.

Add "system" to also compress the system prompt (string or SystemBlock[]), "user" to compress user text blocks. Token counts in onSavings are estimates (~4 bytes/token). Compression results are also cached per client by default — see cache/cacheBytes — so a resent transcript doesn't pay to re-compress tool results it already compressed.

Docs

Full documentation: https://tokz.dev/docs