Files
headroom/wiki/typescript-sdk.md
Tejas ChopraandClaude Opus 5 27bdc2a899 docs(wiki): correct the unpublished tree, and remove invented telemetry (#3390)
`wiki/` **is not published anywhere.** `.github/workflows/docs.yml` says
so in its own header, no mkdocs or sphinx config exists, and `wiki/**`
sits in `paths-ignore` for CI — changes there don't even run a build. It
survives as pending-migration reference material for contributors.

That's why this is separate from the published-site work in #3388:
nothing here reaches a user through `docs.headroomlabs.ai`. It still
matters, because a contributor migrating a page would carry its errors
across, and because the repo is public.

## The finding that justifies this PR on its own

`wiki/benchmarks.md` carried an entire **invented "Production Telemetry"
section**, presented as real-world fleet data:

> real-world production telemetry from 250+ active proxy instances …
**52ms median overhead** … **1.4 billion tokens saved** across 249
instances

Plus P90/P99 timings, ~$4,000 saved, an OS split, a version-share
breakdown, and a dated collection window of March 30 – April 2, 2026.

A repo-wide grep for those figures **matches only that one file.** No
script, test or fixture produces them. The published benchmarks page
never carried the section, so the site owner had already excised it.

Removed rather than re-estimated. The per-category ranges hanging off it
(4.8%, 40–80%, 83–94%, 85–94%, 60–76%) went with it and now point at the
concrete compression table on the same page.

The same page also described `HEADROOM_TELEMETRY` as the opt-in switch
governing fleet-wide numbers. Fleet data would come from
`HEADROOM_BEACON` — a **separate switch that defaults ON**. That note is
gone with the section it footnoted; the accurate description of both
switches shipped to the live site in #3388.

## Other corrections, each verified against source

- **`wiki/agno.md`** constructed `HeadroomAgnoModel(config=...)`; the
field is `headroom_config` (`integrations/agno/model.py:135`). The
sibling `HeadroomPreHook` genuinely does take `config`, which is how
they got conflated.
- **`wiki/ccr.md`** documented CLI flags that don't exist, and a dead
demo script.
- **`wiki/image-compression.md`** had two broken CLI examples.
- **`wiki/getting-started.md`** used `plan.transforms_applied`;
`SimulationResult` exposes `transforms`. (`CompressResult` really does
have `transforms_applied` — two different result types, easy to cross.)
- **`wiki/cli.md`** documents 15 of ~27 top-level commands; an audit
note now says so rather than implying completeness.

## Disposition, for whoever picks up the migration

`wiki/cli.md` is the highest-value page to port — no site page is a full
CLI reference, and `docs.yml` names it as the reason `wiki/` still
exists. `wiki/integration-guide.md` and `wiki/configuration.md` also
cover ground the site doesn't.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_01HRaEPjQcCSAwD2xbQMNENu

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-02 15:53:02 +05:30

7.6 KiB

TypeScript SDK

The Headroom TypeScript SDK lets any JavaScript or TypeScript application compress LLM messages before sending them to a model. It saves tokens, reduces costs, and fits more context into every request.

Install

npm install headroom-ai

Requires a running Headroom proxy.

Quick Start

import { compress } from 'headroom-ai';

const result = await compress(messages, { model: 'gpt-4o' });
console.log(`Saved ${result.tokensSaved} tokens`);

const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: result.messages,
});

How It Works

The TypeScript SDK is an HTTP client. When you call compress(), it sends your messages to the Headroom proxy's POST /v1/compress endpoint. The proxy runs the compression pipeline (ContentRouter and its compressors, including SmartCrusher) and returns compressed messages. No compression logic runs in Node.js — all the heavy lifting happens in the proxy.

The proxy must be reachable on loopback: /v1/compress rejects remote callers with 404 unless it was started with HEADROOM_COMPRESS_ALLOW_REMOTE=1.

Your TypeScript App
    │
    │  compress(messages)
    ▼
headroom-ai (npm)  ← HTTP client
    │
    │  POST /v1/compress
    ▼
Headroom Proxy (loopback)  ← compression pipeline (Python)
    │
    │  compressed messages
    ▼
Your TypeScript App
    │
    │  openai.chat.completions.create(compressed)
    ▼
LLM Provider

Core API: compress()

import { compress } from 'headroom-ai';

const result = await compress(messages, {
  model: 'gpt-4o',                      // model name (for token counting)
  baseUrl: 'http://localhost:8787',      // proxy URL (default)
  apiKey: 'your-api-key',                // optional, for authenticated endpoints
  timeout: 30000,                        // ms (default)
  fallback: true,                        // return uncompressed if proxy down (default)
  retries: 1,                            // retry on transient errors (default)
});

result.messages          // compressed messages (same format as input)
result.tokensBefore      // original token count
result.tokensAfter       // compressed token count
result.tokensSaved       // tokens removed
result.compressionRatio  // tokensAfter / tokensBefore
result.transformsApplied // e.g. ['router:smart_crusher:0.35']
result.compressed        // false if fallback kicked in

Messages use standard OpenAI chat format: { role, content, tool_calls?, tool_call_id? }.

Environment Variables

Instead of passing options, set environment variables:

  • HEADROOM_BASE_URL — proxy URL (default: http://localhost:8787)
  • HEADROOM_API_KEY — optional API key for authenticated endpoints

Reusable Client

For apps making many calls, create a client once and reuse it:

import { HeadroomClient } from 'headroom-ai';

const client = new HeadroomClient({
  baseUrl: 'http://localhost:8787',
  apiKey: 'your-api-key',
});

const r1 = await client.compress(messages1, { model: 'gpt-4o' });
const r2 = await client.compress(messages2, { model: 'gpt-4o' });

Framework Adapters

Vercel AI SDK

The Headroom middleware plugs directly into Vercel AI SDK's wrapLanguageModel():

import { headroomMiddleware } from 'headroom-ai/vercel-ai';
import { wrapLanguageModel, generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

const model = wrapLanguageModel({
  model: openai('gpt-4o'),
  middleware: headroomMiddleware(),
});

// All calls through this model are automatically compressed
const { text } = await generateText({ model, messages });

The middleware intercepts messages in the transformParams hook, converts Vercel's internal format to OpenAI format, compresses via the proxy, and converts back. Your app code doesn't change.

You can also compress Vercel messages directly:

import { compressVercelMessages } from 'headroom-ai/vercel-ai';

const result = await compressVercelMessages(modelMessages, { model: 'gpt-4o' });
// result.messages is in Vercel ModelMessage[] format

OpenAI SDK

Wrap your OpenAI client to auto-compress messages on every chat.completions.create() call:

import { withHeadroom } from 'headroom-ai/openai';
import OpenAI from 'openai';

const client = withHeadroom(new OpenAI());

// Messages are compressed before sending — transparent to your code
const response = await client.chat.completions.create({
  model: 'gpt-4o',
  messages: longConversation,
});

Only chat.completions.create() is intercepted. All other methods (embeddings, images, audio) pass through unchanged.

Anthropic SDK

Same pattern for the Anthropic client:

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

const client = withHeadroom(new Anthropic());

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

Only messages.create() is intercepted. The adapter converts between Anthropic's content block format and OpenAI format automatically.

Error Handling

import { compress, HeadroomConnectionError, HeadroomAuthError } from 'headroom-ai';

try {
  const result = await compress(messages, { model: 'gpt-4o', fallback: false });
} catch (error) {
  if (error instanceof HeadroomAuthError) {
    // Invalid API key (401)
  } else if (error instanceof HeadroomConnectionError) {
    // Proxy unreachable
  }
}

With fallback: true (the default), connection errors and 5xx responses return the original messages uncompressed instead of throwing. Auth errors (401) and client errors (400) always throw.

Fallback Behavior

By default, compress() never blocks your app. If the proxy is unreachable:

Scenario fallback: true (default) fallback: false
Proxy unreachable Returns uncompressed, compressed: false Throws HeadroomConnectionError
Proxy 503 error Returns uncompressed after retries Throws HeadroomCompressError
Invalid API key (401) Throws HeadroomAuthError Throws HeadroomAuthError
Bad request (400) Throws HeadroomCompressError Throws HeadroomCompressError

Zero Dependencies

The headroom-ai package has no runtime dependencies. Framework SDKs (Vercel AI, OpenAI, Anthropic) are optional peer dependencies — only install what you use.

OpenClaw Plugin

The TypeScript SDK powers the headroom-openclaw plugin for OpenClaw agents. The plugin uses HeadroomClient internally to compress context during the assemble() lifecycle hook. The preferred install flow is headroom wrap openclaw; the direct plugin command is openclaw plugins install --dangerously-force-unsafe-install headroom-ai/openclaw. See the plugin source for details.

Comparison with Python SDK

Feature Python SDK TypeScript SDK
compress() Native (runs locally) HTTP client (calls proxy)
Proxy Built-in server Connects to proxy
Vercel AI SDK N/A Middleware adapter
OpenAI SDK HeadroomClient wrapper withHeadroom() wrapper
Anthropic SDK HeadroomClient wrapper withHeadroom() wrapper
LangChain HeadroomChatModel Use compress() directly
Memory system Full (SQLite + HNSW) Not yet (use proxy)
MCP server Built-in Not yet
CLI tools headroom proxy, headroom wrap, etc. N/A (use Python CLI)