🤖 I have created a release *beep* *boop* --- <details><summary>0.29.0</summary> ## [0.29.0](https://github.com/headroomlabs-ai/headroom/compare/v0.28.0...v0.29.0) (2026-07-03) ### Features * **proxy:** add --lossless no-CCR mode with format-native compaction ([#1721](https://github.com/headroomlabs-ai/headroom/issues/1721)) ([c75ebde](https://github.com/headroomlabs-ai/headroom/commit/c75ebdee6df9b1689a44ef321e36e8b360406ed7)) * **stats:** surface Codex WS compression counters in /stats summary ([#1680](https://github.com/headroomlabs-ai/headroom/issues/1680)) ([2fe19c3](https://github.com/headroomlabs-ai/headroom/commit/2fe19c39e40fc350af39f72e1a3bac28f9ce9874)) * **transforms:** adaptive Otsu KEEP/DROP threshold (+ land relevance split on main) ([#1726](https://github.com/headroomlabs-ai/headroom/issues/1726)) ([eea667a](https://github.com/headroomlabs-ai/headroom/commit/eea667a72019cc98401db9211907f67ddf45e7eb)) ### Bug Fixes * **bedrock:** fail fast when session-token auth lacks botocore ([#1553](https://github.com/headroomlabs-ai/headroom/issues/1553)) ([54cfa36](https://github.com/headroomlabs-ai/headroom/commit/54cfa361d308dec567615c346af7c77d52ebb676)) * **bedrock:** route ARNs via converse, named AWS profiles, and au. re… ([#1456](https://github.com/headroomlabs-ai/headroom/issues/1456)) ([7d87aa2](https://github.com/headroomlabs-ai/headroom/commit/7d87aa2f1cbd93c970a77c6dfec8df03603251b9)) * **ccr:** honor workspace dir for sqlite store ([#1564](https://github.com/headroomlabs-ai/headroom/issues/1564)) ([96e1dfe](https://github.com/headroomlabs-ai/headroom/commit/96e1dfe395a440f9e2dddf4589c4f6988f4ee4cd)) * **claude:** surface Remote Control proxy incompatibility ([#1610](https://github.com/headroomlabs-ai/headroom/issues/1610)) ([4bf7f92](https://github.com/headroomlabs-ai/headroom/commit/4bf7f92417a8799ab3ae5f61b7ea9e96c5605a4f)) * **cli:** stop advertising unwired compression tuning env vars in banner ([#1634](https://github.com/headroomlabs-ai/headroom/issues/1634)) ([d5bf98d](https://github.com/headroomlabs-ai/headroom/commit/d5bf98df31528dfd6c23ec45dbd3440efcb1cb75)) * **codex:** avoid duplicate headroom provider config ([#1431](https://github.com/headroomlabs-ai/headroom/issues/1431)) ([ddd4adf](https://github.com/headroomlabs-ai/headroom/commit/ddd4adf911ee2d7a5323657a771ea0162b5590c4)) * **compression:** reject lossy unmarked tool output in unit router path ([#1479](https://github.com/headroomlabs-ai/headroom/issues/1479)) ([de24cd5](https://github.com/headroomlabs-ai/headroom/commit/de24cd5fc0b894037c0481b5394e6851e87b3993)) * **cortex-code:** migrate to current Cortex REST API endpoints + add e2e benchmarks ([#1474](https://github.com/headroomlabs-ai/headroom/issues/1474)) ([f00ace6](https://github.com/headroomlabs-ai/headroom/commit/f00ace6da57aec2f68b833f42603ba3fda0f9110)) * **dashboard:** align token savings headline denominator ([#1653](https://github.com/headroomlabs-ai/headroom/issues/1653)) ([646e705](https://github.com/headroomlabs-ai/headroom/commit/646e7055143638ac4a2bc9980649fd046cea7840)) * **dashboard:** derive per-project setup URL from live origin ([#1511](https://github.com/headroomlabs-ai/headroom/issues/1511)) ([e035aef](https://github.com/headroomlabs-ai/headroom/commit/e035aefce23fd2e20afccf2659c1db613b05d8ca)) * **detection:** contain unidiff panic on orphaned +++ target line ([#1548](https://github.com/headroomlabs-ai/headroom/issues/1548)) ([e386c09](https://github.com/headroomlabs-ai/headroom/commit/e386c097d6d507aa311ca3a22725b226e9d7b223)) * **evals:** CJK-aware F1 tokenization + token estimation ([#1527](https://github.com/headroomlabs-ai/headroom/issues/1527)) ([99a8540](https://github.com/headroomlabs-ai/headroom/commit/99a8540e657445df3204f1d15e213262f4289a42)) * **install:** close parent log fd in start_detached_agent ([#1576](https://github.com/headroomlabs-ai/headroom/issues/1576)) ([816cb85](https://github.com/headroomlabs-ai/headroom/commit/816cb85fa8ee8d349fe673e7affd9a54acb1207d)) * **install:** use Windows-safe PID liveness probe in runtime_status ([#1544](https://github.com/headroomlabs-ai/headroom/issues/1544)) ([#1560](https://github.com/headroomlabs-ai/headroom/issues/1560)) ([6b227b9](https://github.com/headroomlabs-ai/headroom/commit/6b227b9c906d708923f39c0d877989a49942adae)) * **learn:** aggregate verbosity baselines across projects instead of overwriting ([#1288](https://github.com/headroomlabs-ai/headroom/issues/1288)) ([27a5468](https://github.com/headroomlabs-ai/headroom/commit/27a546834960b349e710a0b2e86ca3471523f34d)) * **mcp:** show lifetime totals and label rolling session scope in headroom_stats ([#1428](https://github.com/headroomlabs-ai/headroom/issues/1428)) ([1c0e152](https://github.com/headroomlabs-ai/headroom/commit/1c0e15243eda8f2dc868fe9ed4a08d944893686b)) * **memory:** cap local embedder CPU thread oversubscription ([#198](https://github.com/headroomlabs-ai/headroom/issues/198)) ([#1559](https://github.com/headroomlabs-ai/headroom/issues/1559)) ([b84afbf](https://github.com/headroomlabs-ai/headroom/commit/b84afbfb833999ddf164d324971bf6c11014a9d3)) * **memory:** singleflight LocalBackend init to stop cold-start races ([#1691](https://github.com/headroomlabs-ai/headroom/issues/1691)) ([bec47a1](https://github.com/headroomlabs-ai/headroom/commit/bec47a1898883919ad8c5ea41e3a7443a6890e7f)) * **openclaw:** detect uv-installed headroom binary in ~/.local/bin ([#1459](https://github.com/headroomlabs-ai/headroom/issues/1459)) ([adaeb88](https://github.com/headroomlabs-ai/headroom/commit/adaeb88a4d5512da5bd0bf58c1e3a276a5269d44)) * **opencode:** preserve custom OpenAI gateway paths ([#1596](https://github.com/headroomlabs-ai/headroom/issues/1596)) ([c19347c](https://github.com/headroomlabs-ai/headroom/commit/c19347c31046bf25baf9b1a816c9bede5d3ee807)) * **opencode:** route native providers + load transport plugin, fix Serena context ([#1573](https://github.com/headroomlabs-ai/headroom/issues/1573)) ([ad0034f](https://github.com/headroomlabs-ai/headroom/commit/ad0034f98191501c1a60d26383bc3ed9f6d532be)) * preserve anthropic passthrough tool order ([#1427](https://github.com/headroomlabs-ai/headroom/issues/1427)) ([a932247](https://github.com/headroomlabs-ai/headroom/commit/a9322477e33ec2c5ccd6442d3f72c17b7388c9e0)) * **proxy/auth:** match real Anthropic OAuth token prefix (sk-ant-oat) ([#1672](https://github.com/headroomlabs-ai/headroom/issues/1672)) ([8cddf9b](https://github.com/headroomlabs-ai/headroom/commit/8cddf9b58ea9ed11a0cd3532be6e779dffe57b55)) * **proxy:** expose persistent savings metrics ([#1647](https://github.com/headroomlabs-ai/headroom/issues/1647)) ([5fe4e7b](https://github.com/headroomlabs-ai/headroom/commit/5fe4e7b19530da0c2d07d17f20b18d79b6fab367)) * **proxy:** fail open when kompress saturation would exhaust pre-upstream budget ([#1430](https://github.com/headroomlabs-ai/headroom/issues/1430)) ([15ac650](https://github.com/headroomlabs-ai/headroom/commit/15ac650d409ea7def9e54d9962af1cfdc1f11f5d)) * **proxy:** handle streaming CCR retrieval ([#1451](https://github.com/headroomlabs-ai/headroom/issues/1451)) ([d337e3b](https://github.com/headroomlabs-ai/headroom/commit/d337e3b828ffc1f22cd5ca1884500b8905e9bd82)) * **proxy:** include system/tools/sampling in cache key ([#1473](https://github.com/headroomlabs-ai/headroom/issues/1473)) ([312129a](https://github.com/headroomlabs-ai/headroom/commit/312129a8e7465c97402ae45b9e9d51b7f4b5b0c7)) * **proxy:** preserve Responses passthrough bytes ([#1598](https://github.com/headroomlabs-ai/headroom/issues/1598)) ([2a34a82](https://github.com/headroomlabs-ai/headroom/commit/2a34a822f2a39da57fbd07575752888f5515f51a)) * **proxy:** strip Codex lite header on the HTTP /responses path ([#1663](https://github.com/headroomlabs-ai/headroom/issues/1663)) ([9fbd47b](https://github.com/headroomlabs-ai/headroom/commit/9fbd47ba6bdf38b618795541ee517b7e2fa2c6df)) * **proxy:** wire --compression-max-workers / HEADROOM_COMPRESSION_MAX_WORKERS ([#1632](https://github.com/headroomlabs-ai/headroom/issues/1632)) ([814ffa3](https://github.com/headroomlabs-ai/headroom/commit/814ffa36a4d1bb40165a630f96a855452037735e)) * **savings:** count cache-read tokens in input cost estimate ([#1429](https://github.com/headroomlabs-ai/headroom/issues/1429)) ([72ade37](https://github.com/headroomlabs-ai/headroom/commit/72ade3711211183b9134a46d9c5d45db6a87edc2)) * skip Magika backend on x86 CPUs without AVX2 ([#1162](https://github.com/headroomlabs-ai/headroom/issues/1162)) ([64783d8](https://github.com/headroomlabs-ai/headroom/commit/64783d8824e3c3afc43d9980573d9440693d0963)) * **transforms/content-router:** route grep/log output away from HTML extractor ([#1719](https://github.com/headroomlabs-ai/headroom/issues/1719)) ([0d18ef2](https://github.com/headroomlabs-ai/headroom/commit/0d18ef26f4d126f8eec9df1d34330a7129c4c63f)) * **transforms:** bound native content detection with a Windows watchdog ([#575](https://github.com/headroomlabs-ai/headroom/issues/575)) ([#1563](https://github.com/headroomlabs-ai/headroom/issues/1563)) ([95abca3](https://github.com/headroomlabs-ai/headroom/commit/95abca3abd69add5f075d241284b565e0014d5a4)) * Vertex AI support for Claude Code with ANTHROPIC_VERTEX_BASE_URL ([#1393](https://github.com/headroomlabs-ai/headroom/issues/1393)) ([cff7247](https://github.com/headroomlabs-ai/headroom/commit/cff7247efd6fbecc1c2e66280a4a9b6381d7b7a4)) * **wrap:** detach the shared proxy on Windows so it survives an ungraceful agent close ([#1464](https://github.com/headroomlabs-ai/headroom/issues/1464)) ([6cba441](https://github.com/headroomlabs-ai/headroom/commit/6cba4419d04bea79c1b44632a9288cde5b48bbce)) * **wrap:** preserve custom Vertex base URL ([#1477](https://github.com/headroomlabs-ai/headroom/issues/1477)) ([75427bb](https://github.com/headroomlabs-ai/headroom/commit/75427bbd4ad14fcb1b205f3253ec4e24ae1d2118)) * **wrap:** remove rtk instructions from Codex AGENTS.md on unwrap ([#1604](https://github.com/headroomlabs-ai/headroom/issues/1604)) ([c9d717c](https://github.com/headroomlabs-ai/headroom/commit/c9d717c13c7ae006178e49b6570f63b3f82de9a2)) </details> --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
headroom-ai
Compress LLM context. Save tokens. Fit more into every request.
Install
npm install headroom-ai
Quick Start
import { compress } from 'headroom-ai';
const result = await compress(messages, { model: 'gpt-4o' });
console.log(`Saved ${result.tokensSaved} tokens (${((1 - result.compressionRatio) * 100).toFixed(0)}%)`);
// Use compressed messages with any LLM client
const response = await openai.chat.completions.create({
model: 'gpt-4o',
messages: result.messages,
});
Requires a running Headroom proxy (headroom proxy).
Framework Adapters
Vercel AI SDK
import { withHeadroom } from 'headroom-ai/vercel-ai';
import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';
const model = withHeadroom(openai('gpt-4o'));
const { text } = await generateText({ model, messages });
Advanced: using middleware directly
import { headroomMiddleware } from 'headroom-ai/vercel-ai';
import { wrapLanguageModel } from 'ai';
const model = wrapLanguageModel({
model: openai('gpt-4o'),
middleware: headroomMiddleware({ baseUrl: 'http://localhost:8787' }),
});
OpenAI SDK
import { withHeadroom } from 'headroom-ai/openai';
import OpenAI from 'openai';
const client = withHeadroom(new OpenAI());
const response = await client.chat.completions.create({
model: 'gpt-4o',
messages: longConversation,
});
Anthropic SDK
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,
});
Google Gemini
import { withHeadroom } from 'headroom-ai/gemini';
import { GoogleGenerativeAI } from '@google/generative-ai';
const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY!);
const model = withHeadroom(genAI.getGenerativeModel({ model: 'gemini-2.0-flash' }));
const result = await model.generateContent({
contents: longConversation,
});
HeadroomClient
The full client provides direct access to the proxy's OpenAI and Anthropic passthrough endpoints, plus metrics, CCR, and observability.
import { HeadroomClient } from 'headroom-ai';
const client = new HeadroomClient({
baseUrl: 'http://localhost:8787',
providerApiKey: process.env.OPENAI_API_KEY,
config: {
smartCrusher: { enabled: true, maxItemsAfterCrush: 10 },
ccr: { enabled: true },
},
});
Chat Completions (OpenAI-style)
const response = await client.chat.completions.create({
model: 'gpt-4o',
messages: longConversation,
headroomMode: 'optimize',
});
Messages (Anthropic-style)
const response = await client.messages.create({
model: 'claude-sonnet-4-5-20250929',
messages: longConversation,
max_tokens: 1024,
headroomMode: 'optimize',
});
Direct Compression
const result = await client.compress(messages, { model: 'gpt-4o', tokenBudget: 4000 });
Simulation (Dry Run)
See what compression would do without calling the LLM.
import { simulate } from 'headroom-ai';
const sim = await simulate(messages, { model: 'gpt-4o' });
console.log(`Would save ${sim.tokensSaved} tokens (${sim.estimatedSavings})`);
console.log('Transforms:', sim.transforms);
console.log('Waste signals:', sim.wasteSignals);
console.log('Cache alignment:', sim.cacheAlignmentScore);
Also available on the client:
const sim = await client.chat.completions.simulate({
model: 'gpt-4o',
messages,
});
Compression Hooks
Customize compression with pre/post hooks — matching the Python CompressionHooks API.
import { compress, CompressionHooks } from 'headroom-ai';
import type { CompressContext, CompressEvent } from 'headroom-ai';
class MyHooks extends CompressionHooks {
// Modify messages before compression
preCompress(messages: any[], ctx: CompressContext) {
return [{ role: 'system', content: 'Always preserve error details.' }, ...messages];
}
// Set per-message importance biases
computeBiases(messages: any[], ctx: CompressContext) {
return { 0: 2.0 }; // preserve first message
}
// Observe compression results
postCompress(event: CompressEvent) {
console.log(`Saved ${event.tokensSaved} tokens via ${event.transformsApplied.join(', ')}`);
}
}
const result = await compress(messages, { model: 'gpt-4o', hooks: new MyHooks() });
SharedContext (Multi-Agent)
Compressed inter-agent context sharing — matching the Python SharedContext API.
import { SharedContext } from 'headroom-ai';
const ctx = new SharedContext({ model: 'gpt-4o', ttl: 3600, maxEntries: 100 });
// Agent A stores data (automatically compressed)
const entry = await ctx.put('research', bigAgentOutput, { agent: 'researcher' });
console.log(`Compressed: ${entry.savingsPercent.toFixed(0)}% savings`);
// Agent B reads it (~80% smaller)
const summary = ctx.get('research');
// Agent B gets original if needed
const full = ctx.get('research', { full: true });
// Stats
const stats = ctx.stats();
console.log(`${stats.entries} entries, ${stats.totalTokensSaved} tokens saved`);
CCR Retrieve (Compress-Cache-Retrieve)
Retrieve original content when the LLM needs full details.
const result = await client.compress(messages, { model: 'gpt-4o' });
// Later, when the LLM calls headroom_retrieve:
for (const hash of result.ccrHashes) {
const original = await client.retrieve(hash);
console.log(`${original.originalTokens} original tokens for ${original.toolName}`);
}
// Search within compressed content
const search = await client.retrieve('abc123', { query: 'error logs' });
// Handle LLM tool calls in an agent loop
const toolResult = await client.handleToolCall({
toolCall: assistantMessage.tool_calls[0],
provider: 'openai',
});
Metrics & Observability
// Proxy health
const health = await client.health();
// → { status: 'healthy', version: '0.5.18', config: { optimize: true, ... } }
// Proxy stats
const stats = await client.proxyStats();
// → { requests: { total, cached, failed }, tokens: { saved, savingsPercent }, ... }
// Request metrics
const metrics = await client.getMetrics({ model: 'gpt-4o', limit: 10 });
// Summary
const summary = await client.getSummary();
// Validate setup
const validation = await client.validateSetup();
// Clear cache
await client.clearCache();
// Prometheus metrics
const prom = await client.prometheusMetrics();
Telemetry, Feedback & TOIN
Access the proxy's learning systems.
// Telemetry
const telemetry = await client.telemetry.getStats();
const tools = await client.telemetry.getTools();
// Feedback — per-tool compression hints
const hints = await client.feedback.getHints('list_servers');
// → { hints: { maxItems: 8, skipCompression: false, preserveFields: ['id', 'status'] } }
// TOIN (Tool Output Intelligence Network)
const toinStats = await client.toin.getStats();
const patterns = await client.toin.getPatterns(20);
Configuration Types
Full TypeScript interfaces for every Python config dataclass.
import type { HeadroomConfig, SmartCrusherConfig, CCRConfig } from 'headroom-ai';
const config: HeadroomConfig = {
defaultMode: 'optimize',
smartCrusher: {
enabled: true,
minItemsToAnalyze: 5,
maxItemsAfterCrush: 10,
varianceThreshold: 2.0,
relevance: { tier: 'hybrid', relevanceThreshold: 0.25 },
anchor: { anchorBudgetPct: 0.25 },
},
ccr: { enabled: true, injectTool: true },
cacheOptimizer: { enabled: true, autoDetectProvider: true },
intelligentContext: { enabled: true, useImportanceScoring: true },
};
const client = new HeadroomClient({ config });
Error Handling
Full error hierarchy matching the Python SDK.
import {
HeadroomError,
HeadroomConnectionError,
HeadroomAuthError,
HeadroomCompressError,
ConfigurationError,
ProviderError,
StorageError,
TokenizationError,
CacheError,
ValidationError,
TransformError,
} from 'headroom-ai';
try {
await client.compress(messages);
} catch (err) {
if (err instanceof HeadroomAuthError) {
console.error('Auth failed — check HEADROOM_API_KEY');
} else if (err instanceof HeadroomCompressError) {
console.error(`Compression error ${err.statusCode}: ${err.errorType}`);
} else if (err instanceof ConfigurationError) {
console.error('Bad config:', err.details);
}
}
Format Detection & Conversion
Auto-detects and converts between OpenAI, Anthropic, Vercel AI SDK, and Gemini formats.
import { detectFormat, toOpenAI, fromOpenAI } from 'headroom-ai';
const format = detectFormat(messages); // 'openai' | 'anthropic' | 'vercel' | 'gemini'
const openaiMessages = toOpenAI(messages);
const back = fromOpenAI(openaiMessages, format);
The compress() function handles this automatically — pass any format and get the same format back.
Configuration
import { compress } from 'headroom-ai';
const result = await compress(messages, {
model: 'gpt-4o',
baseUrl: 'http://localhost:8787', // proxy URL
apiKey: 'your-api-key', // optional, for authenticated endpoints
timeout: 30000, // ms
fallback: true, // return uncompressed if proxy is down (default)
retries: 1, // retry on transient failures (default)
tokenBudget: 4000, // compress to fit this limit
hooks: new MyHooks(), // pre/post compression hooks
});
Or use environment variables:
HEADROOM_BASE_URL— proxy URLHEADROOM_API_KEY— optional API key for authenticated endpoints
Utilities
// Case conversion for proxy communication
import { deepCamelCase, deepSnakeCase } from 'headroom-ai';
const tsObj = deepCamelCase({ tokens_before: 100 }); // { tokensBefore: 100 }
const pyObj = deepSnakeCase({ tokensBefore: 100 }); // { tokens_before: 100 }
// SSE stream parsing
import { parseSSE, collectStream } from 'headroom-ai';
// Hook helpers
import { extractUserQuery, countTurns, extractToolCalls } from 'headroom-ai';
License
Apache-2.0