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

> Master headroom.js control with the headroom-ai SDK. Leverage the JavaScript API's HeadroomClient and compress function for seamless message compression and LLM integration via a local HTTP proxy.

- Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom)
- Tags: sdk-guide
- Published: 2026-06-19

---

**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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/src/adapters/openai.ts)
- **Anthropic**: [`src/adapters/anthropic.ts`](https://github.com/chopratejas/headroom/blob/main/src/adapters/anthropic.ts)
- **Gemini**: [`src/adapters/gemini.ts`](https://github.com/chopratejas/headroom/blob/main/src/adapters/gemini.ts)
- **Vercel AI**: [`src/adapters/vercel-ai.ts`](https://github.com/chopratejas/headroom/blob/main/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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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`](https://github.com/chopratejas/headroom/blob/main/src/client.ts) for low-level HTTP communication with the local proxy
- Use the `compress()` function from [`src/compress.ts`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/src/utils/format.ts)
- Implement `CompressionHooks` from [`src/hooks.ts`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/src/compress.ts) provides a convenience wrapper that handles format detection, hook execution, and result conversion automatically. Using `HeadroomClient` directly from [`src/client.ts`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/src/hooks.ts) and passed to the `compress()` function via the `hooks` option.