Anthropic SDK

Auto-compress messages in the Anthropic TypeScript SDK with a single withHeadroom() wrapper.

Headroom wraps the Anthropic TypeScript SDK to automatically compress messages before every messages.create() call. All other methods pass through unchanged.

Installation

npm install headroom-ai @anthropic-ai/sdk

Proxy required

The TypeScript SDK sends messages to a local Headroom proxy for compression. Start the proxy before using the SDK:

pip install "headroom-ai[proxy]"
headroom proxy

Quick start

import {  } from 'headroom-ai/anthropic';
import  from '@anthropic-ai/sdk';

const  = (new ());

const  = await .messages.create({
  : 'claude-sonnet-4-5-20250929',
  : longConversation,
  : 1024,
});

Every call to client.messages.create() compresses messages first. The response format is identical to the unwrapped client.

How it works

withHeadroom() returns a proxy around your Anthropic client that intercepts messages.create():

Converts Anthropic-format messages to OpenAI format (the compression engine's native format)
Sends them to the Headroom proxy's /v1/compress endpoint
Converts the compressed messages back to Anthropic format
Forwards the request to Anthropic as normal

Message format conversion

The adapter handles the full Anthropic message format including content blocks:

Anthropic format	OpenAI format
`{ type: "text", text: "..." }`	`{ role: "user", content: "..." }`
`{ type: "tool_use", id, name, input }`	`{ tool_calls: [{ id, function: { name, arguments } }] }`
`{ type: "tool_result", tool_use_id, content }`	`{ role: "tool", tool_call_id, content }`

This conversion is lossless. Your request and response behave identically to an unwrapped client.

Options

Pass compression options as the second argument:

import {  } from 'headroom-ai/anthropic';
import  from '@anthropic-ai/sdk';

const  = (new (), {
  : 'claude-sonnet-4-5-20250929',
  : 'http://localhost:8787',
});

Streaming

Streaming works normally. Compression happens before the request:

import {  } from 'headroom-ai/anthropic';
import  from '@anthropic-ai/sdk';

const  = (new ());

const  = await .messages.create({
  : 'claude-sonnet-4-5-20250929',
  : longConversation,
  : 1024,
  : true,
});

Tool use

Tool results are where compression has the biggest impact. Large JSON payloads from tool calls are compressed automatically:

import {  } from 'headroom-ai/anthropic';
import  from '@anthropic-ai/sdk';

const  = (new ());

const  = await .messages.create({
  : 'claude-sonnet-4-5-20250929',
  : 1024,
  : [
    { : 'user', : 'What went wrong?' },
    {
      : 'assistant',
      : [
        { : 'tool_use', : 'toolu_1', : 'get_logs', : { : 'api' } },
      ],
    },
    {
      : 'user',
      : [
        {
          : 'tool_result',
          : 'toolu_1',
          : hugeLogOutput, // Compressed automatically
        },
      ],
    },
  ],
  : [{ : 'get_logs', : 'Get logs', : { : 'object', : {} } }],
});