Controlling headroom.js with JavaScript API: A Complete SDK Guide

You can control headroom.js programmatically using the headroom-ai SDK, which exposes the HeadroomClient class and compress() function to manage message compression, format conversion, and LLM provider integration through a local HTTP proxy.

The headroom.js JavaScript API provides a robust TypeScript SDK (headroom-ai) that enables developers to programmatically compress chat messages and manage LLM interactions. Located in the chopratejas/headroom repository, this client-side library abstracts proxy communication details while offering fine-grained control through hooks and adapters. By importing compress or instantiating HeadroomClient, you can integrate headroom.js into Node.js or browser environments with support for OpenAI, Anthropic, Gemini, and Vercel AI formats.

Core SDK Components

HeadroomClient Class

The HeadroomClient class, defined in sdk/typescript/src/client.ts (line 31), serves as the primary HTTP client for interacting with the Headroom proxy. It handles authentication, timeout management, and error mapping while exposing methods like compress(), chat.completions.create(), and messages.create(). The client also provides telemetry and CCR (Cached Content Retrieval) namespaces for monitoring compression statistics and retrieving cached content.

The compress() Function

Located in sdk/typescript/src/compress.ts (line 19), the compress() function acts as the high-level entry point for message compression. This async function auto-detects input formats, runs pre-compression hooks, forwards requests to the proxy at /v1/compress, and restores the original message shape. It accepts a messages array, model identifier, and optional configuration including tokenBudget and custom hooks.

Message Format Handling

The SDK automatically handles format conversion through utilities in sdk/typescript/src/utils/format.ts. The detectFormat() function infers whether input follows OpenAI, Anthropic, Vercel AI, or Gemini conventions. The pipeline then normalizes payloads to OpenAI's structure via toOpenAI(), sends the request to the proxy, and remaps the compressed output back to the original format using fromOpenAI() (lines 46-64 in src/compress.ts). This format-agnostic approach allows you to use your native SDK patterns without manual conversion.

Customizing Behavior with Hooks

Hooks provide interception points for custom logic during the compression lifecycle. Defined in sdk/typescript/src/hooks.ts (line 38), the CompressionHooks base class exposes three key methods:

• preCompress – Modifies the message array before proxy submission
• computeBiases – Returns per-message bias factors to influence preservation priorities
• postCompress – Receives CompressEvent data including token savings and CCR hashes for telemetry

When supplied to compress(), the SDK builds a CompressContext containing model details, turn count, and tool calls, then executes the hook pipeline sequentially.

Provider Adapters

The SDK includes provider-specific adapters in sdk/typescript/src/adapters/ to wrap native SDK calls with Headroom compression:

• OpenAI: src/adapters/openai.ts
• Anthropic: src/adapters/anthropic.ts
• Gemini: src/adapters/gemini.ts
• Vercel AI: src/adapters/vercel-ai.ts

These adapters translate provider-specific payloads to the OpenAI format expected by the proxy, enabling seamless integration into existing codebases without structural changes.

Implementation Examples

Basic Compression of OpenAI-Style Messages

import { compress } from "headroom-ai";

const messages = [
  { role: "system", content: "You are a helpful assistant." },
  { role: "user", content: "Explain quantum tunneling in simple terms." },
];

(async () => {
  const result = await compress(messages, {
    model: "gpt-4o",
    tokenBudget: 500,
  });

  console.log("Compressed tokens:", result.tokensBefore, "→", result.tokensAfter);
  console.log("Compressed messages:", result.messages);
})();

Configuring a Custom Proxy Endpoint

import { HeadroomClient, compress } from "headroom-ai";

const client = new HeadroomClient({
  baseUrl: "http://localhost:8788",
  apiKey: "my-proxy-key",
});

const msgs = [
  { role: "user", content: "Summarize the last 5 pages of a PDF." },
];

(async () => {
  const result = await compress(msgs, {
    client,
    model: "gpt-4o",
    tokenBudget: 300,
  });
  console.log(result);
})();

Implementing Pre-Compress Hooks

import { compress, CompressionHooks } from "headroom-ai";

class ImageStripper extends CompressionHooks {
  preCompress(messages, _ctx) {
    return messages.map((msg) => ({
      ...msg,
      content: Array.isArray(msg.content)
        ? msg.content.filter((p) => p.type !== "image")
        : msg.content,
    }));
  }
}

const msgs = [/* mixed text/image payload */];

(async () => {
  const result = await compress(msgs, {
    hooks: new ImageStripper(),
    model: "gpt-4o",
  });
  console.log(result.messages);
})();

Vercel AI Middleware Integration

import { headroomMiddleware } from "headroom-ai/vercel-ai";

export const config = {
  runtime: "edge",
  middleware: headroomMiddleware(),
};

export default async function handler(req) {
  // generateText calls automatically use Headroom compression
}

Retrieving CCR-Stored Content

import { HeadroomClient } from "headroom-ai";

const client = new HeadroomClient();

(async () => {
  const result = await client.retrieve("sha256:abcd1234...", {
    query: "What was the original user question?",
  });
  console.log("Original snippet:", result);
})();

Summary

• The headroom-ai SDK provides the HeadroomClient class in src/client.ts for low-level HTTP communication with the local proxy
• Use the compress() function from src/compress.ts to handle format detection, hook execution, and message compression in a single call
• The SDK automatically converts between OpenAI, Anthropic, Gemini, and Vercel AI formats using utilities in src/utils/format.ts
• Implement CompressionHooks from src/hooks.ts to customize pre-compression filtering, bias calculation, and post-compression telemetry
• Provider adapters in src/adapters/ enable drop-in integration with existing LLM SDKs without code restructuring

Frequently Asked Questions

How do I install the headroom.js JavaScript SDK?

You can install the SDK via npm or your preferred package manager using the package name headroom-ai. After installation, import the compress function or HeadroomClient class to begin interacting with your local Headroom proxy.

What is the difference between using compress() and HeadroomClient directly?

The compress() function in src/compress.ts provides a convenience wrapper that handles format detection, hook execution, and result conversion automatically. Using HeadroomClient directly from src/client.ts gives you lower-level control over HTTP configuration, authentication headers, and access to ancillary methods like retrieve() for CCR content and telemetry endpoints.

Can I use headroom.js with multiple LLM providers simultaneously?

Yes, the SDK supports multiple providers through adapter files in src/adapters/. The compress() function automatically detects whether your messages follow OpenAI, Anthropic, Gemini, or Vercel AI conventions using detectFormat() in src/utils/format.ts, allowing you to process different provider formats without manual conversion.

How do hooks affect the compression process?

Hooks allow you to inject custom logic at three stages: preCompress modifies messages before they reach the proxy, computeBiases influences which message parts get preserved during compression, and postCompress receives telemetry data about token savings and applied transforms. These are defined in src/hooks.ts and passed to the compress() function via the hooks option.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}