Skip to content
CAI
Software that uses CAICheck a score

headroomlabs-ai/headroom

37.7

Weak · 14 November 2026

325k

lines of production code

Python

with Rust

5

measurements over time

CAI band scale
CAI trend line
CAI lens gauges

What this system is

Features

Add Hermes plugin to retrieve original content from compression markers

Users of the Hermes Agent can now install the \headroom\_retrieve\ plugin to resolve compressed output markers (e.g., \\<\<ccr:...\>\>\ or \hash=...\) into their full original content. This plugin registers a new tool that calls the headroom proxy's \/v1/retrieve\ endpoint, allowing the agent to fetch uncompressed data on demand instead of re-running commands or treating markers as file paths. The plugin requires the headroom proxy to be running on \127.0.0.1:8787\ and should be enabled in the Hermes config under \plugins.enabled\.

plugins/hermes · high confidence

Add Mistral Vibe provider support via local proxy

Users can now integrate the Mistral Vibe CLI with Headroom. This change introduces a new provider module that configures the Vibe environment to route Mistral API requests through the local Headroom proxy, enabling project-based savings attribution and centralized API key management.

_headroom/providers/mistral\vibe · high confidence

Add OpenTelemetry observability core for metrics and tracing

The \headroom/observability\ package introduces a new operational observability layer. It provides OpenTelemetry-backed metrics via \HeadroomOtelMetrics\, configurable via environment variables (e.g., \HEADROOM\_OTEL\_METRICS\_ENABLED\) to export to console or OTLP HTTP endpoints, and supports dynamic metric attributes through registered providers. It also adds a \HeadroomTracer\ facade for distributed tracing, with specific support for Langfuse integration via \LangfuseTracingConfig\ (configured via \LANGFUSE\_PUBLIC\_KEY\/\LANGFUSE\_SECRET\_KEY\), ensuring trace exports are guarded by the same air-gap egress checks as metrics.

headroom/observability · high confidence

Add ZCode desktop app provider support

A new provider module for the ZCode desktop app (zcode.z.ai) has been added to the system. This change introduces helper classes and functions, including ZCodeProxyTargets and ZCodeUpstream, which enable the application to detect upstream configurations, build proxy targets, and render necessary setup lines for users connecting via the ZCode desktop client.

headroom/providers/zcode · high confidence

Add benchmark comparing Claude Code native tool search vs Headroom server-side deferral

A new benchmark suite in \benchmarks/tool\_search\_vs\_native\ evaluates the cost and performance of Claude Code's native ToolSearch against Headroom's server-side tool deferral strategies (including a 'hot' mode that keeps frequently used tools loaded). The suite uses a fixture repository with a pricing bug and six fake enterprise MCP servers (GitHub, Jira, Slack, Datadog, PagerDuty, Confluence) to simulate a realistic workflow. Results indicate that keeping routinely used tools loaded reduces costs significantly (up to 25% on short tasks and 10% on long tasks) compared to native search or server-side deferral without pre-loading, while also avoiding issues with cache mode divergence when Claude Code re-serializes replies.

_benchmarks/tool\_search\_vs\native · high confidence

Add comprehensive benchmark suite for cache, compression, and retrieval performance

Introduces a new set of Python benchmark scripts in the \benchmarks/\ directory to measure and validate performance characteristics of the Headroom SDK. These include \cache\_validation\_bundle.py\ and \synthetic\_long\_cache\_suite\_report.py\ for validating cache behavior and TTL handling, \ccr\_retrieval\_history\_benchmark.py\ and \ccr\_sqlite\_expiry\_benchmark.py\ for measuring CCR retrieval and SQLite expiry costs, \memory\_fts\_reindex\_benchmark.py\ for FTS5 reindex throughput, \text\_crusher\_quality\_eval.py\ and \i18n\_compression\_eval.py\ for evaluating extractive compression quality and CJK retention, and \codemode\_ab.py\ with \codemode\_ab\_report.py\ for A/B testing code-mode steering directives. Additionally, \index\_proof\_table.py\ provides a reproducible method for generating the token savings statistics published in the documentation.

benchmarks · high confidence

Add cross-agent memory sync adapters for Claude Code and Codex

New sync adapters have been added to enable cross-agent memory interoperability. The \ClaudeCodeAdapter\ reads and writes memories to Claude Code's native \MEMORY.md\ index and individual \.md\ files, including logic to prevent data loss when multiple memories share the same first line by using content-hash suffixes. The \CodexAdapter\ manages a dedicated \\<!-- headroom:memory:start --\>\ section in \AGENTS.md\, ensuring that new memories are added additively without overwriting previously synced facts.

_headroom/memory/sync\adapters · high confidence

Add first-class Grok CLI and Antigravity IDE provider support

This change introduces new provider modules for Grok CLI and the Google Antigravity IDE, enabling native integration with these tools. For Grok, the implementation adds runtime helpers to detect official Grok client requests via specific user-agent prefixes and authentication headers, ensuring traffic is correctly routed through the local proxy to the xAI API while preserving business-seat authentication and model context metadata. It also includes install-time environment setup to configure the Grok CLI to use the proxy. Similarly, new helpers are added for the Antigravity IDE to build its install environment and proxy targets, allowing it to route requests through the same proxy infrastructure.

headroom/providers/grok · high confidence

Add headroom\_retrieve tool for hash-based content lookup

The OpenClaw plugin now includes a new 'headroom\_retrieve' tool that allows agents to retrieve original uncompressed content from the Headroom compression store. Users can pass a 24-character hex hash to fetch the full original content, with the tool validating the hash format and handling retrieval errors, including cases where content may have expired (default TTL: 30 minutes). Also in this area: 2 commits (2 fixes) fixing plugins/openclaw.

plugins/openclaw/src/tools · medium confidence · unverified

Add support for Cortex Code (Snowflake CoCo) as a provider

Users can now integrate with Snowflake Cortex Code (CoCo). This change introduces the provider implementation in the \headroom/providers/cortex\_code\ module, including runtime helpers to construct the correct Snowflake API URL (supporting custom hosts or accounts) and install-time logic to configure the local proxy environment variable (\OPENAI\_BASE\_URL\) for seamless routing.

_headroom/providers/cortex\code · high confidence

Added Headroom testing harness for local simulations and deployment planning

The \headroom.testing\ package has been introduced to provide a fluent API for defining and running scenario contracts. This harness allows users to configure \HeadroomConfig\ and \ProxyConfig\ instances locally without requiring upstream provider keys, enabling smoke tests, local simulations, and deployment planning. It exposes methods for auditing contracts, generating deployment plans, and creating manifest bundles compatible with \headroom-bench\ and agent evaluation workflows.

headroom/testing · high confidence

Added TypeScript SDK usage examples

The repository now includes runnable TypeScript examples demonstrating how to use the Headroom SDK for context compression. These examples cover basic compression, streaming chat, tool-calling agents, structured output extraction, and multi-provider support (OpenAI and Anthropic). They also showcase advanced features such as middleware composition with the Vercel AI SDK, custom compression hooks for observability and bias control, shared context for multi-agent handoffs, and lossless retrieval via the Compress-Cache-Retrieve (CCR) mechanism.

sdk/typescript/examples · high confidence

CI preflight check for Hugging Face model cache

A new CI script (\scripts/ci/verify\_hf\_model\_cache.py\) has been added to verify that the default embedding model is available in the Hugging Face cache before test shards run. This preflight ensures that offline tests (which set \TRANSFORMERS\_OFFLINE=1\) do not fail later due to network or cache issues, providing an early and specific error if the model is missing or has an unexpected dimension.

scripts/ci · high confidence

Centralized ML model configuration and shared instance registry

Introduces a centralized configuration module and a singleton registry for ML model instances (sentence transformers, SIGLIP, spaCy) to ensure consistent model selection across the application and prevent redundant loading of heavy models. The configuration allows switching model variants via environment variables (e.g., HEADROOM\_SENTENCE\_TRANSFORMER) or by editing the defaults, while the registry provides lazy-loaded, thread-safe access to these shared instances, improving memory efficiency and startup performance.

headroom/models · high confidence

Claude provider integration with VS Code and runtime configuration

This change introduces the initial Claude provider implementation, adding runtime helpers for version detection, 1M context window resolution, and Remote Control base-URL gating, alongside VS Code-specific logic to persistently configure Claude settings and proxy URLs, and install-time scripts to manage environment variables like tool search deferral.

headroom/providers/claude · high confidence

Introduce BYOK provider wrappers and transparent VS Code proxy for Copilot and Aider

Users can now route GitHub Copilot and Aider through the local Headroom proxy using Bring-Your-Own-Key (BYOK) configurations. For Copilot, the system transparently manages VS Code proxy settings (overrideProxyUrl and overrideCapiUrl) to ensure inline completions and chat requests are routed correctly, while also handling environment variables for provider type resolution (Anthropic/OpenAI) and stripping unsupported 'auto' model aliases. For Aider, the provider helpers build launch environments that point OpenAI and Anthropic API bases to the local proxy, enabling per-project savings attribution. This change adds the necessary install-time and runtime logic to integrate these IDE tools with the Headroom proxy infrastructure.

headroom/providers/copilot · high confidence

Introduce CCR module with inline marker resolution and streamable HTTP MCP transport

The new \headroom/ccr\ module implements the Compress-Cache-Retrieve architecture, adding a \marker\_resolution\ component that resolves \\<\<ccr:...\>\>\ placeholders inline within response text when the standard tool-call retrieval path is unavailable (e.g., in proxy/guardrail hops). It also introduces \mcp\_http\ to expose the CCR retrieval tool via a Streamable HTTP transport using Starlette and uvicorn, alongside core components for tool injection, response handling, context tracking, and batch processing.

headroom/ccr · high confidence

Introduce Grok Build provider with wrap/unwrap and MCP integration

A new Grok Build provider has been added to the system, enabling users to wrap their Grok configuration for proxy-based access and integrate with the Model Context Protocol (MCP). The implementation manages the Grok \config.toml\ file by injecting a \\[model.grok-build\]\ section that redirects traffic through a local proxy, while preserving a backup to allow safe unwrapping. It also provides helpers to build the necessary environment variables for persistent installation.

_headroom/providers/grok\build · high confidence

Introduce Headroom ContextEngine plugin for OpenClaw

The new \@headroom-ai/openclaw\ plugin integrates Headroom as a context-engine for OpenClaw, compressing tool outputs and structured data to reduce token usage while preserving provider metadata and thought signatures. It automatically selects the \headroom\ context engine on install and routes the built-in \openai-codex\ provider through the active Headroom proxy by default (configurable via \routeCodexViaProxy\ and \gatewayProviderIds\). The plugin supports both local auto-start (with launcher fallbacks and circuit-breaker resilience) and remote connect-only proxy modes, and includes a hook shim to ensure smooth local development installs.

plugins/openclaw · high confidence

Introduce Headroom Dashboard with light mode, accessibility, and settings management

The dashboard templates now provide a new user interface for monitoring proxy metrics and managing configuration. The dashboard view includes a header with session/lifetime/historical view switching, a live transformation feed, and status indicators, all styled with Tailwind CSS and Alpine.js. A key behavioral change is the addition of a light mode, which inverts the default dark theme based on user preference or system settings, ensuring readable text and correct card backgrounds. The interface is fully keyboard-operable with visible focus indicators to meet accessibility standards. Additionally, a dedicated settings page allows users to configure runtime knobs (booleans, enums, numbers, strings) with support for manifest-managed fields, environment variable overrides, and an 'Apply & Restart' workflow.

headroom/dashboard/templates · high confidence

Introduce Headroom Learn for offline coding-agent session analysis

Adds the \headroom/learn\ module, which analyzes local coding-agent conversation logs to extract actionable patterns and automatically update agent context files (such as \CLAUDE.md\) to prevent future token waste. The feature uses an LLM-based analyzer (supporting providers like Anthropic, OpenAI, and Google, or CLI-based backends like Claude Code, Codex, and Gemini) to detect inefficiencies like retry loops and errors. It includes a plugin architecture for multi-agent support, shared utilities for error classification and tool-name normalization, and platform-specific fixes for Windows path handling and UTF-8 encoding.

headroom/learn · high confidence

Introduce Headroom startup hooks for Claude Code and Copilot CLI

This change adds a new plugin that provides lightweight startup hooks for Claude Code and GitHub Copilot CLI. When a session starts or a Bash/PowerShell tool is used, the hooks automatically check for and start a durable Headroom runtime if needed, ensuring the local Headroom environment is available without blocking the host agent.

plugins/headroom-agent-hooks · high confidence

Introduce Hierarchical Memory system with SQLite/ONNX defaults and Markdown Bridge

Headroom now includes a new hierarchical memory system that persists user memories using SQLite with vector search (defaulting to sqlite-vec or HNSW) and text search (FTS5). The system uses ONNX Runtime for local embeddings by default, removing the PyTorch dependency and reducing memory overhead. A new Memory Bridge component enables bidirectional synchronization between Headroom's semantic memory and local markdown files (supporting formats for Claude Code, ChatGPT, and generic structures). The system exposes tools for LLM function calling and provides a simple API for saving and searching memories, with support for optional Qdrant/Neo4j backends via environment variables.

headroom/memory · high confidence

Introduce LiteLLM and any-llm backend providers for Headroom

The \headroom/backends\ module now includes two new backend implementations: \LiteLLMBackend\ and \AnyLLMBackend\. The LiteLLM backend enables routing requests to over 100 providers (including AWS Bedrock, Azure OpenAI, Google Vertex, and OpenRouter) by leveraging the LiteLLM library for authentication and format translation. The any-llm backend provides a similar multi-provider interface (supporting 38+ providers like OpenAI, Anthropic, and Ollama) via the any-llm SDK. Both backends handle the translation between the proxy's canonical Anthropic Messages API format and the specific requirements of the target provider APIs, allowing users to select their preferred provider via command-line flags (e.g., \--backend litellm-bedrock\ or \--backend anyllm\).

headroom/backends · high confidence

Introduce MCP server registration for multiple coding agents

Headroom now provides a unified interface to automatically register its MCP server (and Serena) into the configuration files of detected coding agents, including Claude Code, OpenAI Codex, Grok, OpenCode, and Google Antigravity IDE. This ensures that the headroom MCP server is available in supported environments without manual configuration, while safely preserving existing user settings and handling edge cases like unparseable config files.

_headroom/mcp\registry · high confidence

Introduce OpenClaw plugin with durable, restart-safe context compression

The OpenClaw plugin now provides context compression via a Headroom proxy, ensuring that conversation history is compacted algorithmically without LLM calls. To guarantee data integrity across process restarts and concurrent access, the plugin implements a durable advancement key store using OS-level file locking, preventing silent loss of committed turns. The engine normalizes message formats between OpenClaw and OpenAI, routes provider traffic through the proxy, and includes resilience features like circuit breakers and per-request timeouts for the proxy connection.

plugins/openclaw/src · high confidence

Introduce OpenCode integration plugin and transport helpers

This change adds the \plugins/opencode\ package, providing both a native OpenCode plugin and provider configuration helpers for Headroom. The native plugin intercepts OpenCode provider traffic via a Headroom proxy, exposes a \headroom\_retrieve\ tool, and supports both OpenCode 1.x and 2.x APIs (including automatic migration for 2.x). It allows users to exclude specific hosts from proxy routing via the \excludeHosts\ option or \HEADROOM\_OPENCODE\_EXCLUDE\_HOSTS\ environment variable. Additionally, the package includes a \hook-shim\ to ensure spawned Node child processes also route traffic through the proxy, and provides utilities for building OpenCode config content and compressing model requests.

plugins/opencode · high confidence

Introduce OpenCode plugin with transport proxying and retrieval tool

The OpenCode plugin now routes LLM traffic through the Headroom proxy, exposes a \headroom\_retrieve\ tool for fetching original content by hash, and supports both OpenCode 1.x and 2.x plugin APIs. It also includes a Node transport shim to ensure child processes route traffic correctly and fixes a crash in wheel installs by shipping the shim. Also in this area: 1 commit (1 fix) fixing plugins/opencode; 3 commits (3 fixes) fixing plugins/opencode.

plugins/opencode/src · medium confidence · unverified

Introduce TypeScript SDK for Headroom compression proxy

The TypeScript SDK is now available, providing an HTTP client to interact with the Headroom compression proxy. Users can compress messages via the universal \compress()\ function, which automatically detects and supports OpenAI, Anthropic, Vercel AI SDK, and Google Gemini formats, converting them to and from the proxy's internal OpenAI format. The SDK also includes a \HeadroomClient\ for direct proxy calls (including chat completions and message creation), a \simulate()\ function for dry-run compression analysis, and a \SharedContext\ class for managing compressed inter-agent context with TTL and eviction policies. Additionally, a \paths\ module is provided to mirror the Python SDK's filesystem contract for configuration and workspace directories. Also in this area: 1 commit (1 fix) fixing sdk/typescript; 3 commits (3 fixes) fixing sdk/typescript.

sdk/typescript/src · medium confidence · unverified

Introduce TypeScript SDK for headroom-ai

Adds the initial TypeScript SDK package (headroom-ai), providing a client for LLM context compression and framework adapters for Vercel AI SDK, OpenAI, Anthropic, and Google Gemini. The package is configured with tsup for ESM and CJS output, uses vitest for testing, and includes a .gitignore to exclude build artifacts.

sdk/typescript · high confidence

Introduce auth-mode classification and compression policy routing

The core library now classifies incoming requests into three auth modes—Payg, OAuth, and Subscription—based on headers like \Authorization\ and \User-Agent\. This classification drives downstream compression and caching policies: Payg allows aggressive compression, OAuth enforces lossless-only passthrough to protect cache keys, and Subscription preserves specific headers to maintain provider rate-limiting and stealth requirements. The implementation includes a pure, low-latency classifier, a \cache\_control\ walker to respect Anthropic's prompt caching boundaries, and a sharded in-memory CCR store for efficient context retrieval.

crates/headroom-core · high confidence

Introduce headroom performance analysis module

A new \headroom/perf\ module has been added to the codebase, providing the foundation for parsing proxy logs and surfacing actionable insights through the \headroom perf\ command.

headroom/perf · high confidence

Introduce headroom-simulators for deterministic local testing

A new standalone simulator service is available to act as a deterministic, provider-shaped upstream for local and CI validation of the Headroom proxy. It listens on port 8789 by default and serves pre-configured responses for major provider endpoints (OpenAI, Anthropic, Bedrock, Vertex) without contacting real LLM APIs. Users can define custom stub rules via a JSON configuration file to override default responses based on method, path, and body content, enabling reliable, offline testing of proxy routing and behavior.

crates/headroom-simulators · high confidence

Introduce hierarchical memory backend system with local and Mem0 options

The memory subsystem now supports a pluggable backend architecture, exposing LocalBackend (SQLite + HNSW/SQLite-vec + InMemoryGraph) as the default fully-local option, alongside optional Mem0-based backends (Mem0Backend, DirectMem0Adapter) for graph/vector storage via Neo4j and Qdrant. The new \_\init\\_.py module implements lazy imports for these optional dependencies to avoid startup failures when they are not installed, and deprecates the legacy Mem0SystemAdapter in favor of the optimized DirectMem0Adapter which bypasses redundant LLM extraction when pre-extracted facts are provided.

headroom/memory/backends · high confidence

Introduce hierarchical memory system with persistent storage and vector search adapters

The memory subsystem now uses a new hierarchical architecture with dedicated adapters for persistence and retrieval. SQLite is used for core memory storage (SQLiteMemoryStore) and knowledge graph data (SQLiteGraphStore), replacing previous in-memory or less structured approaches. Full-text search is handled via SQLite FTS5, while vector similarity search is supported by both HNSW (hnswlib) and SQLite-based (sqlite-vec) indexes, with optional dependencies loaded lazily to avoid crashes on incompatible hardware. Embedding generation is available through local (sentence-transformers/ONNX), OpenAI, and Ollama backends, with CPU thread usage capped to prevent event-loop starvation. A thread-safe LRU cache (LRUMemoryCache) speeds up access to hot memories, and all database files are created with owner-only permissions for improved security.

headroom/memory/adapters · high confidence

Introduce image token compression with ML-based technique routing

Users can now automatically compress images in LLM requests to save 40-90% of tokens while maintaining answer accuracy. The new \headroom.image\ module provides an \ImageCompressor\ and a \compress\_images\ convenience function that select the optimal compression technique (FULL\_LOW, PRESERVE, CROP, or TRANSCODE) using a trained ML router. This router combines a MiniLM classifier for query intent and SigLIP for image analysis, available in both a PyTorch-based \TrainedRouter\ and a dependency-light ONNX-based \OnnxTechniqueRouter\ that runs on CPU without GPU requirements. The system handles offline environments gracefully by degrading to a preserve strategy if models cannot be loaded, and includes optimizations such as capping ONNX thread pools and releasing model memory after compression.

headroom/image · high confidence

Introduce live code graph reindexing via file watcher

Added a new \headroom/graph\ module that provides live code graph reindexing. This includes a \CodeGraphWatcher\ that monitors project source files for changes and triggers incremental updates using the \codebase-memory-mcp\ backend, along with an installer helper to locate the required binary on the system path.

headroom/graph · high confidence

Introduce new provider implementations and unified provider registry

The providers module now includes dedicated implementations for Google Gemini and Cohere, each featuring accurate token counting via their respective official APIs (countTokens and tokenize) with estimation fallbacks, alongside updated context limits and pricing metadata. A new LiteLLM provider is added to support 100+ LLM providers through a unified interface, while the provider package exports are migrated to lazy loading to improve startup performance. Additionally, a new install registry centralizes environment building and scope mutation logic for various IDE integrations (such as Claude, Codex, Copilot, and Cursor), and the proxy routing layer is expanded to support Hermes scoped coding-agent passthrough compression and more granular upstream target resolution.

headroom/providers · high confidence

Introduce persistent deployment lifecycle management

The install module now provides a complete system for managing persistent Headroom deployments. It introduces a structured deployment manifest (persisted atomically with recovery snapshots) to track profile state, runtime kind, and supervisor configuration. The system automatically detects available tool targets (Claude, Codex, Copilot, Cursor, Aider, Grok, OpenClaw, OpenCode, Antigravity) and applies scoped environment variable mutations to shell profiles on Unix or system environment variables on Windows. Runtime execution is handled via platform-specific supervisors: macOS launchd, Linux systemd, Windows Task Scheduler, or Docker containers. The implementation also includes health probing, migration of deprecated Docker image repositories, and robust error handling for corrupt manifests.

headroom/install · high confidence

Introduce pluggable quota and rate-limit tracking for Anthropic, Codex, and Copilot

The subscription module now provides a pluggable architecture for tracking usage quotas and rate limits across multiple AI providers. It introduces a \QuotaTracker\ abstract base class and a \QuotaTrackerRegistry\ that allows the server to discover and manage trackers without hardcoding provider logic. Specific implementations are included for Anthropic Claude Code (polling the OAuth usage API and parsing local transcript files for token breakdowns), GitHub Copilot (monthly quota tracking via GitHub tokens), and OpenAI Codex (rate-limit window tracking). This enables the dashboard to display accurate, provider-specific usage metrics and headroom contributions.

headroom/subscription · high confidence

Introduce pluggable tokenizer system with multi-backend support and safety bounds

The \headroom/tokenizers\ package provides a registry-based system for counting tokens across multiple LLM backends (tiktoken, HuggingFace, Mistral, and estimation). It introduces specific mappings for new models (DeepSeek V4/V3.2/R1, GPT-4.1/4.5/5, and various Llama/Mistral families) and fixes counting accuracy for CJK/Kana/Hangul characters and non-string tool-call fields. To prevent request hangs and security risks, the system bounds HuggingFace tokenizer downloads with timeouts and an allowlist of known repositories, and limits tiktoken vocab loading to a configurable timeout, falling back to estimation if loads stall.

headroom/tokenizers · high confidence

Introduce plugin architecture for headroom learn

The \headroom learn\ command now uses a plugin system to support scanning session logs from multiple AI coding assistants. New built-in plugins have been added for Claude Code, OpenAI Codex CLI, Google Gemini CLI, Grok CLI, and OpenCode. These plugins automatically detect and parse session data from their respective local storage locations (such as \\~/.claude/projects/\, \\~/.codex/sessions/\, \\~/.gemini/tmp/\, \\~/.grok/sessions/\, and the OpenCode SQLite database) to extract tool calls and error patterns. The implementation includes robust path handling to support various operating systems and project structures, ensuring that learnings are correctly attributed to the relevant projects.

headroom/learn/plugins · high confidence

Introduce privacy-preserving telemetry with opt-in local stats and opt-out anonymous beacon

The telemetry module now separates local statistics collection from external reporting. Local stats (aggregating compression patterns, tool usage, and retrieval metrics) are disabled by default and require the explicit environment variable HEADROOM\_TELEMETRY=on to enable, ensuring no data leaves the machine unless the operator opts in. An anonymous usage beacon is enabled by default (opt-out) and sends content-free session summaries to Headroom Labs, respecting DO\_NOT\_TRACK and HEADROOM\_BEACON=off. The module also introduces identity fields (headroom\_stack, install\_mode) and strict cardinality caps for stack and model labels to prevent unbounded data explosion.

headroom/telemetry · high confidence

Introduce structured Headroom CLI with comprehensive subcommands and utilities

The \headroom/cli\ package is introduced, providing a structured Click-based command-line interface. This includes a main entry point (\main.py\) that handles versioning, air-gap enforcement, and subcommand registration, along with a suite of new commands: \agent-savings\ for rendering and verifying token-savings profiles, \audit-reads\ for analyzing transcript compression opportunities, \capture network-diff\ for comparing direct vs. proxied traffic, \copilot-auth\ for managing GitHub Copilot OAuth tokens, \evals\ for running memory and robustness benchmarks, \init\ for durable agent initialization, \inspect\ for viewing original vs. compressed content, \mcp\ for installing and managing the Model Context Protocol server, and \extensions\ for third-party plugin support. The package also adds utility modules for Rich-based formatting (\\_utils/formatting.py\) and duration parsing (\\_utils/parsers.py\), ensuring consistent output and input handling across the CLI.

headroom/cli · high confidence

Introduce tool-result interceptor framework with ast-grep optimization

The proxy now includes a new interceptor framework in \headroom/proxy/interceptors\ that rewrites tool results before they reach the model. This adds a built-in \astgrep\ interceptor that replaces verbose file-read outputs with compact function/class outlines for supported code languages, reducing token usage. The framework supports hot-reloading configuration via environment variables (e.g., \HEADROOM\_INTERCEPT\_READ\_MIN\_CHARS\) without requiring a proxy restart, and includes disk-verification logic to ensure truncation detection accuracy.

headroom/proxy/interceptors · high confidence

Live-zone compression for Anthropic and OpenAI endpoints with model-aware limits

The proxy now compresses requests to Anthropic \/v1/messages\, OpenAI \/v1/chat/completions\, and OpenAI \/v1/responses\ by rewriting only the latest user/tool message blocks (the live zone) while leaving cached system, tool, and historical content untouched. Anthropic requests respect the \cache\_control\_auto\_frozen\ config to determine the cache-hot floor, and Anthropic model IDs with the CLI \\[1m\]\ suffix are stripped before forwarding. OpenAI requests are compressed with provider-specific walkers, and tool definitions are deterministically sorted for pay-as-you-go auth modes. A vendored LiteLLM context-window table ensures the compressor respects each model's token limits, falling back to a conservative 128K for unknown models.

crates/headroom-proxy/src/compression · high confidence

Native AWS Bedrock InvokeModel support in Rust proxy

The Rust proxy now natively handles AWS Bedrock \InvokeModel\ and \InvokeModelWithResponseStream\ routes, replacing the previous Python \litellm\ shim. This change introduces a dedicated Bedrock module that parses the Bedrock JSON envelope (preserving \anthropic\_version\ ordering for cache safety), applies the same live-zone Anthropic compression used by the main proxy, and signs outgoing requests with AWS SigV4. For streaming responses, it includes a binary EventStream parser and a translator that converts Bedrock's binary frames into standard SSE for clients, while supporting native EventStream passthrough when requested. An auth-mode middleware ensures all Bedrock routes are classified as OAuth-equivalent for consistent compression policy gating.

crates/headroom-proxy/src/bedrock · high confidence

Native spend/savings observability and metrics for the Rust proxy

The Rust proxy now includes a built-in savings ledger and dashboard, replacing the previous reliance on external or Python-based tracking. This change introduces a new \observability\ module that records per-request token usage, calculates USD spend and savings using a vendored LiteLLM price table, and exposes the data via a new \/dashboard\ page and \/stats\ HTTP endpoints. It also adds Prometheus metrics for cache hit rates, compression ratios, and rate limits, ensuring the Rust proxy can now independently track and report cost savings and operational health.

crates/headroom-proxy/src/observability · high confidence

New Codex provider integration for Headroom

This change introduces the \headroom/providers/codex\ module, adding support for the ChatGPT Codex provider within the Headroom proxy. It includes endpoint URL builders, case-insensitive header helpers, and logic to detect ChatGPT OAuth versus API-key authentication. The integration provides specialized handlers for forwarding Codex image requests, WebSocket-based Live voice calls, and Responses subpath passthroughs, while ensuring proper header sanitization and routing decisions. Additionally, it features install-time helpers to manage configuration and a best-effort thread retagging mechanism to keep the Codex history menu consistent across the proxy boundary.

headroom/providers/codex · high confidence

New MCP demo example with documentation and test data

Added a new example in examples/mcp\_demo that demonstrates Headroom compression on Model Context Protocol (MCP) tool outputs. The change includes a README explaining how to run the demo scripts (show\_compression, show\_before\_after, run\_agent\_eval) and mock\_mcp\_servers.py which generates test data for Slack, database, log, and GitHub scenarios. The demo scripts show before/after code integration patterns and run agent evaluations to verify compression preserves information.

_examples/mcp\demo · high confidence

New SDK utility modules for case conversion, format detection, and SSE streaming

Added three new utility files to the TypeScript SDK: \case.ts\ provides functions to convert between snake\_case and camelCase (including deep object conversion) to bridge the Python proxy and TypeScript SDK naming conventions; \format.ts\ introduces structural detection and conversion logic for OpenAI, Anthropic, Vercel AI SDK, and Google Gemini message formats, ensuring media parts, tool names, and image blocks are preserved during translation to the proxy's canonical OpenAI format; \stream.ts\ implements an SSE parser that correctly handles multi-byte character decoding and ensures the final event is emitted even if the stream lacks a trailing newline. Also in this area: 1 commit (1 fix) fixing sdk/typescript; 3 commits (3 fixes) fixing sdk/typescript.

sdk/typescript/src/utils · medium confidence · unverified

New TypeScript SDK adapters for OpenAI, Anthropic, Gemini, and Vercel AI

The TypeScript SDK now includes dedicated adapter modules that automatically compress conversation history before sending requests to large language models. These adapters intercept the message-generation methods of the OpenAI, Anthropic, Google Gemini, and Vercel AI SDK clients, transparently reducing token usage while preserving the original client interface. Users can wrap their existing SDK instances with these adapters to enable automatic context compression without changing their application logic.

sdk/typescript/src/adapters · high confidence

New TypeScript type definitions for compression configuration and metrics

The SDK now includes formal TypeScript interfaces for configuring the compression pipeline and interpreting its results. Developers can use the new \CompressRequestConfig\ interface to pass per-call options such as \mode\, \targetRatio\, and \protectRecent\ to the \compress()\ function, ensuring type-safe control over compression behavior. Additionally, the SDK exposes detailed result models like \SimulationResult\, \RequestMetrics\, and \ProxyStats\, allowing applications to accurately parse token savings, cache alignment scores, and performance statistics returned by the proxy.

sdk/typescript/src/types · high confidence

New adaptive compression and lossless compaction transforms

The transforms module introduces several new capabilities for context optimization. An adaptive sizer now uses information saturation detection (Kneedle algorithm on bigram coverage) to dynamically determine the optimal number of items to keep, replacing hardcoded limits. A cold-prefix hook rewrites the prompt prefix when the cache has lapsed, dropping or deduplicating reasoning content to save tokens on cold turns. A new lossless compaction system provides format-native, reversible transformations (such as ANSI stripping, run collapsing, and repeated block folding) that require no retrieval markers, supporting a no-CCR proxy mode. Additionally, a remote Kompress compressor allows offloading ML-based compression to a hosted endpoint, and a dense line elider compresses machine-generated blobs (like minified JS) by keeping only their heads and tails.

headroom/transforms · high confidence

New cache-stabilization subsystem in the Rust proxy

The Rust proxy now includes a new \cache\_stabilization\ module that automatically optimizes request bodies and headers to improve prompt-cache hit rates for Pay-As-You-Go (PAYG) customers. This subsystem introduces several capabilities: it auto-inserts Anthropic \cache\_control\ markers and OpenAI \prompt\_cache\_key\ fields to pin cache lookups; it normalizes tool definitions by sorting them and their JSON schema keys to ensure deterministic byte-identical requests; it tracks session-sticky beta headers to prevent cache misses when clients drop tokens mid-conversation; and it provides observability by detecting volatile content (like timestamps and UUIDs) and structural drift in cached prefixes. These changes are gated to PAYG auth modes to preserve subscription stealth and include safety checks to respect customer-placed markers.

_crates/headroom-proxy/src/cache\stabilization · high confidence

New dashboard and telemetry schema for v2 tracking

This change introduces the \proxy\_telemetry\_v2\ table to capture detailed telemetry data, including new identity fields (\headroom\_stack\, \install\_mode\) and metrics like cache hit rates and compression savings. It also adds a \dashboard\_summary\ table with an automated hourly refresh function to aggregate daily and hourly usage statistics, providing a public-facing view of tokens and cost savings. Additionally, the schema simplifies cache-bust tracking by replacing previous complex columns with a single \cache\_bust\_tokens\ metric.

sql · high confidence

New developer and release utility scripts

The repository now includes a suite of new scripts in the \scripts/\ directory to streamline local development and release verification. For Windows developers, \bootstrap-windows-dev.ps1\ automates the setup of the development environment, including Python virtual environments, Rust tooling, and npm dependencies. Release engineers can use \build\_npm\_release\_assets.mjs\ and \build\_python\_release\_smoke.py\ to locally reproduce the npm and Python wheel/sdist build pipelines, ensuring artifacts are correct before pushing. Additionally, \audit\_wheel\_glibc\_symbols.py\ prevents deployment of Python wheels that reference glibc symbols newer than the declared manylinux ABI floor, addressing compatibility issues on older Linux systems. The \repro\_codex\_replay.py\ script allows operators to simulate multi-agent reconnect storms to validate proxy resilience, while \install-git-hooks.sh\ configures pre-commit and pre-push hooks to catch CI failures locally.

scripts · high confidence

New differential network capture harness for traffic analysis

Added a new Docker-based harness in the \docker/differential-network-capture\ directory that enables capturing and comparing network traffic across different execution paths. The setup includes a \docker-compose.yml\ defining services for direct API access, a headroom proxy, and upstream interception via mitmproxy, alongside a \Dockerfile.runner\ to containerize the Claude Code client. A custom Python addon (\mitm\_capture.py\) records HTTP exchanges as JSONL, automatically redacting sensitive headers and query parameters, while a shell script (\run-claude-lane.sh\) orchestrates the client execution within these controlled network lanes.

docker/differential-network-capture · high confidence

New evaluation framework to verify compression accuracy

Headroom now includes a comprehensive evaluation suite (installable via \pip install headroom-ai\[evals\]\) that proves compression preserves LLM accuracy. The framework provides a CLI and Python API to run tiered benchmarks (Tier 1–3) covering math, factual accuracy, code generation, and tool use against datasets like GSM8K, TruthfulQA, and BFCL. It supports before/after comparisons, LLM-as-judge scoring, and zero-cost compression-only tests (e.g., CCR needle retention). Users can also run session probes on recorded local conversations to measure information retention in real-world scenarios.

headroom/evals · high confidence

New examples for context compression, tabular data, and AWS Strands integration

Added a suite of new demonstration scripts and notebooks in the examples directory. The context compression notebook (07-context-compression.ipynb) and demo script (context\_compression\_demo.py) show how to use Headroom's local compression (SmartCrusher, Kompress) within a LangGraph RAG agent to reduce tool output size without extra LLM calls. The tabular\_compression\_demo.py illustrates compression on CSV, Markdown tables, and Excel spreadsheets. Additionally, new AWS Strands demos (strands\_bedrock\_demo.py, strands\_bundle\_demo.py, strands\_via\_proxy\_demo.py) and an MCP dispatch test (strands\_mcp\_dispatch\_test.py) showcase integration patterns for Bedrock, including hook-based compression, model wrapping, and proxy-based caching.

examples · high confidence

New headroom-oauth2 plugin for upstream client-credentials authentication

The new \headroom-oauth2\ plugin enables the Headroom proxy to automatically mint and inject OAuth2 client-credentials bearer tokens into upstream requests. When enabled via \--proxy-extension oauth2\ and configured with environment variables (e.g., \HEADROOM\_OAUTH2\_TOKEN\_URL\), the plugin handles token acquisition, caching, and single-flight refresh, replacing the client's \Authorization\ header with the minted bearer. It is designed to be vendor-neutral and works with any OpenAI-compatible backend that accepts bearer tokens. Crucially, the plugin ensures that local proxy routes (such as \/health\, \/metrics\, and \/admin\) are passed through untouched, preventing 502 errors when the identity provider is unreachable and avoiding unnecessary token minting for management calls. It also supports static upstream headers and fails closed on misconfiguration.

plugins/headroom-oauth2 · high confidence

New integrations for Agno, AutoGen, CrewAI, and ASGI/LiteLLM proxies

Headroom SDK now supports automatic context optimization for Agno, AutoGen, and CrewAI agent frameworks, as well as any ASGI-based proxy (such as LiteLLM). For Agno, users can wrap models with HeadroomAgnoModel or use pre/post hooks to compress conversation history. For AutoGen and CrewAI, tool outputs are automatically compressed before entering the agent's context via HeadroomToolWrapper, reducing token usage for verbose tool responses. Additionally, the new CompressionMiddleware (ASGI) and HeadroomCallback (LiteLLM) allow drop-in integration into proxy servers, supporting both local in-process compression and cloud-managed optimization via the Headroom API.

headroom/integrations · high confidence

New memory evaluation framework with LLM-as-judge scoring

Introduces a new memory evaluation framework in the \headroom.evals.memory\ module, enabling benchmarking of memory system quality using industry-standard datasets like LoCoMo. This includes tools for evaluating memory extraction quality, semantic retrieval accuracy, and end-to-end QA performance. The module provides LLM-as-judge capabilities via \create\_openai\_judge\, \create\_anthropic\_judge\, and \create\_litellm\_judge\, which score answers on a 1-5 scale based on semantic equivalence to ground truth. It also exposes V1 and V2 evaluation runners (\LoCoMoEvaluator\, \LoCoMoEvaluatorV2\) and associated configuration/result models for running these benchmarks.

headroom/evals/memory · high confidence

New network capture comparison helpers

The headroom/capture module now exposes a set of utilities for comparing network traffic captures. Users can load capture files, compare them to identify differences, and generate markdown reports of the results via the newly added compare\_captures, load\_capture\_file, and render\_markdown\_report functions.

headroom/capture · high confidence

New offline traffic audit module for measuring tuning opportunities

A new \headroom/audit\ package has been introduced to provide offline traffic audits that measure opportunity sizes before tuning defaults. This module exposes capabilities to audit Codex performance, simulate codex maturation risks, and audit read traffic, providing reports and text renderers for these analyses to help users understand potential improvements.

headroom/audit · high confidence

New reproducible devcontainer environments with memory-stack support

Developers can now launch the project in VS Code using official devcontainer configurations that provision a consistent Python, Node, and Rust (1.95.0) environment. The setup uses the \uv\ package manager for faster dependency resolution and installs Rust tooling via the official devcontainer feature to ensure correct file permissions for the \vscode\ user. A new 'memory-stack' profile is available, which automatically starts Qdrant and Neo4j sidecar containers and exposes their ports (6333, 6334, 7474, 7687) for local development. The environment is hardened to work correctly with Git worktrees by dynamically configuring \GIT\_DIR\ and \GIT\_COMMON\_DIR\ during container startup.

.devcontainer · high confidence

New structure-aware compression handlers for code and JSON

The compression module now includes dedicated structure handlers that preserve key structural elements while compressing the rest. The CodeStructureHandler uses tree-sitter (with a thread-local parser and ABI compatibility shim) to identify and preserve code signatures, imports, and class definitions, allowing function bodies to be compressed. The JSONStructureHandler preserves keys, structural syntax, booleans, and short values, while compressing long string values and whitespace. These handlers enable the LLM to retain navigational context (what fields or functions exist) while reducing token count.

headroom/compression/handlers · high confidence

New telemetry beacon deployment with privacy-preserving query tooling

This change introduces the operational infrastructure for the headroom telemetry beacon, including a Cloudflare Worker (worker.js) that ingests telemetry data into an R2 storage bucket. The worker implements a strict server-side allowlist to drop any fields not explicitly permitted, ensuring that sensitive data like source IP addresses are never stored or logged (invocation logs are disabled in wrangler.toml). It also supports gzip-compressed payloads and enforces decompression limits to prevent resource exhaustion. To support data analysis, a new query.sh script allows users to run SQL queries against the R2 corpus using DuckDB, featuring deduplication logic to aggregate session heartbeats correctly. The deployment includes a test suite (test-rollup.mjs) to verify the hourly compaction logic and validation tests for the query script.

deploy · high confidence

New wiki documentation for architecture, compression, and integrations

The wiki now includes comprehensive documentation for the Headroom SDK. New pages cover the system architecture (ARCHITECTURE.md), including the transform pipeline and Compress-Cache-Retrieve (CCR) mechanism; latency and accuracy benchmarks (LATENCY\_BENCHMARKS.md, benchmarks.md); known limitations and configuration tuning (LIMITATIONS.md); and integration guides for Agno (agno.md) and the CLI (cli.md). The API reference (api.md) and compression module docs (compression.md) are also added, providing users with detailed usage instructions, configuration options, and performance expectations.

wiki · high confidence

OpenClaw provider integration for persistent proxy wrapping

This change introduces the OpenClaw provider slice, adding install, wrap, and initialization logic to manage the OpenClaw CLI via Headroom. Users can now install and configure OpenClaw to route through a persistent proxy using the \headroom-openclaw\ npm package. The provider handles applying and reverting proxy configurations, normalizes gateway provider IDs, and defensively strips legacy configuration keys (like \mcpServers\) to prevent errors when updating OpenClaw settings.

headroom/providers/openclaw · high confidence

OpenCode provider integration with proxy routing and config management

This change introduces the OpenCode provider module, enabling Headroom to manage OpenCode's configuration and runtime environment. It adds logic to inject a 'headroom' provider into the OpenCode config file (supporting both JSON and JSONC formats with idempotent markers), allowing users to access specific models like gpt-4o and gpt-4.1 through the local proxy. The module also handles runtime setup by detecting OpenCode versions (1.x vs 2.x) to apply necessary flags like \--standalone\, and configures native providers (Anthropic, OpenAI) to route through the proxy. Additionally, it supports installing and managing a local transport plugin for broader provider coverage and ensures safe installation/uninstallation by backing up and restoring the user's original config file.

headroom/providers/opencode · high confidence

Pluggable storage backends for CompressionStore with secure SQLite default

The CCR (Compression-Cache-Retrieve) store now supports pluggable storage backends, allowing users to choose between an in-memory backend (default for direct construction) and a persistent SQLite backend (default for the proxy via \\get\_compression\_store()\\). The SQLite backend ensures data survives process restarts and is shared across multiple worker processes using WAL mode. To address security concerns, the SQLite database file and its associated WAL/SHM files are created with owner-only permissions (0600) immediately upon initialization, preventing exposure of sensitive cached content. Users can override the default backend via the \\HEADROOM\_CCR\_BACKEND\\ environment variable or specify a custom database path via \\HEADROOM\_CCR\_SQLITE\_PATH\\.

headroom/cache/backends · high confidence

Published Python dependency license and SBOM data

The sbom directory now includes a CSV file listing Python package licenses and a CycloneDX JSON Software Bill of Materials (SBOM) generated by Syft, providing transparency into third-party dependencies and their licensing terms.

sbom · high confidence

Rust proxy introduces configurable compression, header stripping, and auth-mode policy enforcement

The Rust proxy adds configuration options for compression mode (off or live\zone), a policy to strip internal x-headroom-\ headers from upstream requests (enabled by default to prevent fingerprinting), and a feature flag for per-auth-mode compression policy enforcement (enabled by default). It also implements session-sticky beta headers to preserve upstream cache keys across conversation turns, and introduces a drift detector to monitor session stability. Error handling is hardened to prevent leaking internal upstream details to clients, and specific HTTP status codes like 413 are correctly surfaced for oversized payloads.

crates/headroom-proxy/src · high confidence

Standardized development environment and release automation

The repository now includes configuration files to standardize local development and automate releases. A \.actrc\ file configures the \act\ CLI to use a specific Ubuntu runner image and reuse containers for faster local CI execution. A \.commitlintrc.json\ file enforces conventional commit message formatting via pre-commit hooks. Additionally, \.release-please-config.json\ and \.release-please-manifest.json\ are added to automate version bumping and changelog generation for the Python package and associated npm packages (SDK, OpenClaw, OpenCode) using the release-please tool.

(repo-wide) · high confidence

Support for Kimi CLI integration via local proxy

Added a new provider module for Kimi CLI that configures environment variables to route requests through the local proxy. The \build\_launch\_env\ helper sets \KIMI\_CODE\_BASE\_URL\ and \KIMI\_BASE\_URL\ to point at the proxy, enabling the Kimi CLI to use its managed coding endpoint via an OpenAI-compatible interface while preserving project context attribution.

headroom/providers/kimi · high confidence

macOS LaunchAgent deployment guide and templates for headroom proxy

Added a new example in examples/deployment/macos-launchagent that provides a complete, automated way to run the headroom proxy as a persistent macOS LaunchAgent. The package includes a plist template, an install script (with custom port and unattended options), an uninstall script, and a shell-integration helper that automatically sets ANTHROPIC\_BASE\_URL when the proxy is running. This enables automatic startup on login, crash recovery, and standard logging for macOS users. Also in this area: 3 commits (2 fixes) fixing examples.

examples/deployment · medium confidence · unverified

Architecture

Introduce modular proxy architecture with new core components

The proxy server has been restructured into a modular package under \headroom/proxy\, replacing the previous monolithic layout. This change introduces dedicated modules for authentication mode classification (\auth\_mode.py\), background compression offloading (\background\_compression.py\), beta header merging (\beta\_header\_merge.py\), context limit guarding (\context\_guard.py\), and conversation savings attribution (\conversation\_savings.py\). It also adds an audit logging system (\audit.py\) for administrative actions, a CC-Switch reconciler (\cc\_switch\_reconciler.py\) to maintain proxy routing when using Claude Code's provider switcher, and debug introspection endpoints (\debug\_introspection.py\). These components collectively improve proxy stability, observability, and compatibility with various LLM clients and upstream providers.

headroom/proxy · high confidence

Proxy handlers refactored into provider-specific mixins

The monolithic proxy handler logic has been extracted into dedicated mixin classes (Anthropic, OpenAI, Gemini, Bedrock, Batch, and Streaming) within the new \headroom/proxy/handlers\ package. This structural change isolates provider-specific request processing, compression, and streaming logic, while introducing a shared diagnostic dump utility for upstream errors that respects operator privacy settings.

headroom/proxy/handlers · high confidence

Behavioural changes

1 commit (0 fixes) modifying headroom/providers/droid

A change to existing behaviour in headroom/providers/droid — 1 commit, 2 files: “feat(wrap): add \headroom wrap droid\ for Factory Droid (\#4143)” (refs \#4143).

headroom/providers/droid · medium confidence · unverified

2 commits (1 fix) modifying headroom/providers/omp

A change to existing behaviour in headroom/providers/omp — 2 commits (1 fix), 2 files: “fix(wrap): route OMP OpenAI providers through Headroom (\#2755)”; “feat(wrap): add omp target (Oh My Pi) with models.yml override and unwrap (\#1811)” (refs \#2755, \#1811).

headroom/providers/omp · medium confidence · unverified

2 commits (1 fix) modifying headroom/providers/vertex

A change to existing behaviour in headroom/providers/vertex — 2 commits (1 fix), 4 files: “fix(vertex): explain Vertex failures in-band, correct the model/region matrix (\#2640)”; “refactor(providers): split proxy route adapters (\#1934)” (refs \#2640, \#1934).

headroom/providers/vertex · medium confidence · unverified

20 commits (9 fixes) modifying headroom/cache

A change to existing behaviour in headroom/cache — 20 commits (9 fixs), 7 files: “fix(cache): round learned TTL upper bounds up to whole seconds (\#4710)”; “feat(ccr): Redis backend, one CCR store for every replica (\#4368)”; “fix(cache): invalidate configured registry instances on replacement (\#4363)”; and 17 more (refs \#4710, \#4368, \#4363, \#4711, \#2670, …).

headroom/cache · medium confidence · unverified

4 commits (2 fixes) modifying headroom/evals/runners

A change to existing behaviour in headroom/evals/runners — 4 commits (2 fixs), 2 files: “fix(offline): make HEADROOM\_OFFLINE a real air-gap via one chokepoint (\#3729)”; “fix(evals): exclude provider failures from answer scores (\#4503)”; “Add comprehensive evaluation framework for compression accuracy”; and 1 more (refs \#3729, \#4503).

headroom/evals/runners · medium confidence · unverified

6 commits (0 fixes) modifying plugins/headroom-snip

A change to existing behaviour in plugins/headroom-snip — 6 commits, 9 files: “feat(plugins): add headroom-snip Claude Code mod that animates compression (\#3980)”; “chore: release 0.42.0 (\#4228)”; “chore: release 0.43.1 (\#4661)”; and 3 more (refs \#3980, \#4228, \#4661, \#4002, \#4643, …).

plugins/headroom-snip · medium confidence · unverified

Accurate cost savings reporting and new waste signal detection

The reporting module now uses the LiteLLM-backed ModelRegistry to calculate cost savings, ensuring that the 'savings' tile displays 'unavailable' instead of fabricating a $0.00 value when pricing data is missing. Additionally, the waste histogram now includes 'Re-served Tool Results' and 'Re-served After Compression' categories, with logic updated to exclude these from history bloat calculations to prevent double-counting. The top waste requests list is also sorted by actual tokens saved rather than total tokens before, providing a more accurate ranking of optimization opportunities.

headroom/reporting · high confidence

Centralized e2e test harness library for shared utilities

A new shared library at e2e/\_lib consolidates utilities previously scattered across end-to-end test suites. It provides cross-platform shim creation (via shims.py and companion shell/PowerShell scripts) to simulate agent binaries, PATH isolation helpers (path\_env.py) to ensure clean execution environments, assertion helpers (assertions.py) for verifying exit codes and output, and path resolution logic (paths.py) to locate agent settings files. This refactoring reduces duplication in per-command test suites like e2e/init/run.py and future install/wrap tests.

_e2e/\lib · high confidence

Dashboard static assets (Alpine, Tailwind, HTMX) are now served locally

The dashboard no longer loads Alpine.js, Tailwind CSS, and HTMX from external CDNs; instead, these libraries are bundled as local static files in the repository. This change improves reliability by removing external network dependencies and ensures the dashboard functions correctly in offline or restricted-network environments.

headroom/dashboard/static · high confidence

Deprecation of agent memory writers module

The \headroom.memory.writers\ module, which previously exported memories to formats for agents like Claude Code, Cursor, Codex, and Aider, is now deprecated and will be removed in a future release. Users should use \headroom.learn.writer\ instead, as the legacy writers are no longer wired into the application.

headroom/memory/writers · high confidence

Deprecation of the headroom.compression package API

The universal compression module in headroom/compression is now deprecated. Users importing directly from headroom.compression (e.g., compress, UniversalCompressor, MagikaDetector) will receive a DeprecationWarning, as these exports are unused internally. The recommended migration path is to use headroom.compress() for simple one-call compression or ContentRouter from headroom.transforms for advanced routing. Note that headroom.compression.detector remains functional for proxy usage (Magika preload) without warnings.

headroom/compression · high confidence

Improved BM25 relevance scoring and switched embedding model to fastembed

The BM25 scorer now uses a proper corpus-based IDF formula during batch scoring, weighting terms by their inverse document frequency to better distinguish rare, discriminative terms (like IDs) from common ones, and optimizes performance by computing the query token frequency once per batch. Additionally, the embedding scorer has switched from sentence-transformers (all-MiniLM-L6-v2) to fastembed with the BAAI/bge-small-en-v1.5 model, providing faster, ONNX-backed inference that matches the Rust implementation byte-for-byte and removes the PyTorch dependency.

headroom/relevance · high confidence

Improved storage URL parsing and consistent query pagination

The storage module now correctly handles absolute Windows paths in storage URLs (e.g., sqlite://C:/path) by using a dedicated path extraction helper. Additionally, both JSONL and SQLite storage backends now enforce a consistent, fully-defined sort order (timestamp descending, then request ID descending) for query results, ensuring that pagination with limit and offset behaves identically across backends. Input validation was also added to reject negative limit or offset values. Also in this area: Improved logging and telemetry control in Headroom.

headroom/storage · high confidence

Introduce provider-specific runtime and install helpers for Aider, Cursor, and Gemini

This change adds dedicated helper modules for the Aider, Cursor, and Gemini providers to manage environment configuration and proxy routing. For Aider and Cursor, new \install.py\ and \runtime.py\ files define how to build persistent install environments and launch variables (such as \OPENAI\_API\_BASE\ and \ANTHROPIC\_BASE\_URL\) that route through a local proxy. The Aider implementation specifically encodes the project directory as a URL prefix to enable per-project savings attribution. Cursor's helpers expose proxy targets and setup rendering logic, while Gemini's module provides a default API URL constant.

headroom/providers/aider · high confidence

OpenClaw plugin now registers ContextEngine and CCR retrieval tool with proxy-aware gateway routing

The OpenClaw plugin now exports a \{ register }\ object to ensure compatibility with the OpenClaw 2026.x plugin loader, which previously skipped bare-function exports. Upon registration, the plugin initializes a Headroom ContextEngine and registers a \headroom\_retrieve\ tool that becomes active once a proxy is available. It automatically routes upstream gateway providers through the Headroom proxy by probing the configured proxy URL and applying base URL changes in memory, deferring this routing until the proxy is ready to ensure stable connectivity.

plugins/openclaw/src/plugin · high confidence

Pricing engine now uses LiteLLM and adds DeepSeek and cache-TTL support

The pricing module now relies on LiteLLM's community-maintained database for up-to-date costs across 100+ models, deprecating the previous hardcoded OpenAI and Anthropic tables. It also introduces DeepSeek pricing (including V4/V4.1 Flash and Pro) with peak/off-peak rate handling, and adds a new prompt-cache TTL pricing structure for Anthropic that derives write costs from base input rates for 5-minute and 1-hour TTLs.

headroom/pricing · high confidence

Rust-backed DiffCompressor exposed via PyO3 bridge

The Python \headroom.\_core\ module now exposes the Rust \DiffCompressor\ implementation through a PyO3 bridge, allowing the \ContentRouter\ to route compression tasks to the in-process Rust backend instead of the previous Python port. This change maintains a one-to-one API mirror with the Python \DiffCompressor\ class (including \DiffCompressorConfig\ with fields like \max\_context\_lines\, \enable\_ccr\, and \min\_compression\_ratio\_for\_ccr\), ensuring that callers experience no behavioral difference while benefiting from the performance gains of running the hot-path compression logic in Rust without IPC overhead.

crates/headroom-py/src · high confidence

Fixes

4 commits (3 fixes) fixing crates/headroom-proxy/src/sse

A fix in crates/headroom-proxy/src/sse — 4 commits (3 fixs), 5 files: “fix(observability): wire Phase G PR-G3 RTK + proxy metrics (H-blocker)”; “feat(proxy): native spend/savings stats + dashboard for the Rust proxy (\#2321)”; “fix(proxy): track response.-prefixed item and content-part events in Responses SSE state (\#4695)”; and 1 more (refs \#2321, \#4695).

crates/headroom-proxy/src/sse · medium confidence · unverified

4 commits (3 fixes) fixing headroom/telemetry/backends

A fix in headroom/telemetry/backends — 4 commits (3 fixs), 3 files: “fix(toin): retain pending changes after filesystem save failures (\#4568)”; “fix(toin): bound private query and pattern retention”; “Add pluggable adapter hooks for CCR, Storage, and TOIN backends”; and 1 more (refs \#4568, \#4589).

headroom/telemetry/backends · medium confidence · unverified

5 commits (5 fixes) fixing headroom

A fix in headroom — 5 commits (5 fixs), 6 files: “fix(opencode): do not break every request when the proxy URL is empty or invalid (\#4750)”; “fix(proxy): keep reserved openai tool names resident during tool search deferral (\#4753)”; “fix(cache): exclude cold starts from TTL hit evidence (\#4728)”; and 2 more (refs \#4750, \#4753, \#4728, \#4727, \#4714). Also in this area: Add bundled OpenCode provider distribution.

_headroom/providers/opencode/\dist · medium confidence · unverified

Fix dashboard styling and script execution on restrictive hosts

The dashboard now reliably loads with correct styling and interactive features on environments where the system MIME type database is misconfigured (such as certain Windows registries or minimal containers). This is achieved by explicitly pinning standard MIME types for JavaScript, CSS, and JSON assets in the dashboard's static file handler, preventing browsers from blocking scripts due to incorrect Content-Type headers. Additionally, the dashboard HTML templates are now explicitly read as UTF-8 to ensure proper character encoding for all content.

headroom/dashboard · high confidence

Fixes import failures on older Linux systems by shimming missing glibc symbols

The Python package now includes a compatibility shim that resolves undefined symbol errors (such as \\_\_isoc23\strtoll\ and \\\_libc\_single\_threaded\) when importing the core library on Linux systems with glibc versions older than 2.32 or 2.38. This change ensures the wheel remains importable on older distributions (like Ubuntu 20.04) that lack the newer glibc symbols referenced by statically linked dependencies like ONNX Runtime, by providing local fallback definitions during the build process.

crates/headroom-py · high confidence

Ship transport hook-shim to route Node child-process traffic

The \headroom/providers/opencode/hook-shim/handler.js\ file is now included in the package, enabling the Headroom transport to intercept and route HTTP/HTTPS traffic spawned by Node.js child processes (via \child\_process.spawn\, \exec\, \execFile\, and \fork\). This shim injects environment variables and Node options to ensure that LLM endpoint requests generated by child processes are proxied through the Headroom proxy, while excluding loopback addresses, configured hosts, and non-LLM paths. Also in this area: 5 commits (5 fixes) fixing headroom.

headroom/providers/opencode/hook-shim · medium confidence · unverified

Stabilizes startup and runtime reliability across platforms

This release introduces several fixes to improve Headroom's stability and compatibility. It adds a dedicated module to pin the ONNX Runtime dynamic library, preventing crashes on systems lacking AVX2 support or on Windows where conflicting system DLLs can cause deadlocks. Subprocess execution is hardened with explicit UTF-8 encoding and line-ending preservation to prevent data corruption on non-UTF-8 Windows locales. A new utility for checking process liveness ensures robust handling of child processes across different operating systems. Additionally, the package now correctly identifies itself as a development build when installed from a source checkout, and introduces a cleanup mechanism to automatically remove artifacts from retired CLI context tools (rtk and lean-ctx) that may persist on user machines.

headroom · high confidence

Test coverage

11 commits adding/updating tests in tests/parity; 1699 commits adding/updating tests in tests; 8 commits adding/updating tests in e2e/wrap/tools; Add Claude session simulation and compression benchmark harnesses; Add end-to-end Dockerized test harness for \headroom init\; Added Playwright tests for the dashboard live feed; Added Rust proxy integration and end-to-end test harnesses; Added TypeScript SDK test suite; Added comprehensive test suite for LangChain integration; Added comprehensive test suite for the cache optimization module; Added comprehensive test suite for the new Hierarchical Memory system; Added comprehensive test suite for the universal compression module; Added comprehensive tests for the OpenClaw plugin; Added gateway turn contract test harness and fixtures; Added integration tests for LangGraph and AWS Strands Agents SDK; Added integration tests for the Agno agent framework; Added proxy regression tests for Anthropic, Bedrock, and compression paths; Added test coverage for headroom adapters; Added test coverage for release, CI, and PR governance scripts; Added test coverage for the MCP registry system; Added test suite for Headroom Learn session analysis and plugin scanning; Added tests for AutoGen and CrewAI tool compression integrations; Added tests for Bedrock prompt caching, cache stat surfacing, and botocore preflight guards; Added tests for CLI memory commands and utility functions; Added tests for JSONL storage paging and updated SQLite test fixtures; Added tests for Kompress ONNX export pinning and Codex replay harness; Added tests for LiteLLM callback and removed redundant LangChain tests; Added tests for SDK utility functions; Added tests for bounded tiktoken vocab loading and fallback behavior; Added tests for log redaction and HTML extraction evaluation; Expanded CLI test coverage for init, install, and MCP workflows; Expanded test coverage for code compression, content detection, and routing transforms; Expanded test coverage for provider tokenization, pricing, and metadata handling; Expanded test coverage for the install subsystem; Introduce Rust parity harness for validating Python-to-Rust ports; New e2e/wrap Docker harness for end-to-end testing; New end-to-end test suites for Docker security, installation, and Copilot integration.

Dependencies

Initial Rust workspace scaffolding and dependency lockfiles for Headroom

The project introduces a new Rust workspace containing five crates: headroom-core (the core compression engine), headroom-proxy (a transparent reverse proxy built on Axum), headroom-simulators (local provider simulators for validation), headroom-py (PyO3 bindings exposing the core to Python), and headroom-parity (a Rust-vs-Python parity harness). This change adds the initial Cargo.lock, Cargo.toml manifests, and package-lock.json files for the docs and plugin directories, establishing the foundational dependency tree and build configuration for the Rust-based components.

(dependencies) · high confidence

Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

How this codebase got here

Score

  • CAI 36 → 38 (+2.0)
  • Rubric changed (rubric-2026.10.5 → rubric-2026.11.4) — scores are not directly comparable.

Lenses

  • Code Health 59 → 53 (-6.4)
  • Architecture 96 → 94 (-2.5)
  • Maturity 81 → 91 (+9.6)
  • Readiness 62 → 62 (-0.3)
  • Security 70 → 76 (+6.8)
  • Domain Modelling 10 → 10 (+0.0)
  • Accessibility 48 → 62 (+14.3)
  • Performance 79 → 79 (+0.0)

Resolved (339)

  • Critical CVE: [GHSA redacted] (uv.lock)
  • DiffCompressor::compress_with_store (cognitive 38) (crates/headroom-core/src/transforms/diff_compressor.rs)
  • DiffCompressor::compress_with_store (cyclomatic 21) (crates/headroom-core/src/transforms/diff_compressor.rs)
  • Duplicated block (10 lines × 2) (crates/headroom-proxy/src/bedrock/invoke.rs)
  • Duplicated block (10 lines × 2) (headroom/proxy/handlers/streaming.py)
  • Duplicated block (10–13 lines × 2) (crates/headroom-proxy/src/proxy.rs)
  • Duplicated block (11 lines × 2) (headroom/ccr/tool_calls.py)
  • Duplicated block (11 lines × 2) (headroom/proxy/handlers/anthropic.py)
  • Duplicated block (11 lines × 2) (headroom/proxy/handlers/openai.py)
  • Duplicated block (12 lines × 2) (crates/headroom-core/src/transforms/smart_crusher/analyzer.rs)
  • Duplicated block (12 lines × 2) (headroom/memory/adapters/fts5.py)
  • Duplicated block (12–13 lines × 2) (headroom/proxy/savings_tracker.py)
  • Duplicated block (12–13 lines × 2) (headroom/tokenizers/base.py)
  • Duplicated block (13 lines × 2) (headroom/cli/wrap.py)
  • Duplicated block (13–14 lines × 2) (headroom/proxy/prometheus_metrics.py)
  • Duplicated block (14 lines × 2) (headroom/cli/memory.py)
  • Duplicated block (15 lines × 2) (headroom/proxy/handlers/openai.py)
  • Duplicated block (15 lines × 3) (headroom/models/registry.py)
  • Duplicated block (15 lines × 5) (headroom/models/registry.py)
  • Duplicated block (15–16 lines × 2) (crates/headroom-proxy/src/proxy.rs)
  • …and 319 more

New (410)

  • AnthropicHandlerMixin._append_proactive_expansion_after_cached_prefix (cognitive 40) (headroom/proxy/handlers/anthropic.py)
  • AnthropicHandlerMixin._append_proactive_expansion_after_cached_prefix (cyclomatic 25) (headroom/proxy/handlers/anthropic.py)
  • BatchCompressionEvaluator.evaluate_case (cognitive 20) (headroom/evals/batch_compression_eval.py)
  • BatchCompressionEvaluator.evaluate_case (cyclomatic 20) (headroom/evals/batch_compression_eval.py)
  • BeforeAfterRunner.evaluate_case (cognitive 20) (headroom/evals/runners/before_after.py)
  • BeforeAfterRunner.evaluate_case (cyclomatic 19) (headroom/evals/runners/before_after.py)
  • CodeAwareCompressor._extract_structure (cognitive 30) (headroom/transforms/code_compressor.py)
  • CodeAwareCompressor._extract_structure (cyclomatic 17) (headroom/transforms/code_compressor.py)
  • CompressionEvaluator.evaluate_case (cognitive 17) (headroom/evals/core.py)
  • CompressionEvaluator.evaluate_case (cyclomatic 17) (headroom/evals/core.py)
  • ContentRouter._compress_mixed (cyclomatic 20) (headroom/transforms/content_router.py)
  • CostTracker.record_tokens (cognitive 18) (headroom/proxy/cost.py)
  • CostTracker.record_tokens (cyclomatic 17) (headroom/proxy/cost.py)
  • Critical vulnerability: [GHSA redacted] (sbom/headroom-sbom-prod.cdx.json)
  • Critical vulnerability: [GHSA redacted] (sbom/headroom-sbom.spdx.json)
  • DiffCompressor::compress_with_ccr_source (cognitive 42) (crates/headroom-core/src/transforms/diff_compressor.rs)
  • DiffCompressor::compress_with_ccr_source (cyclomatic 22) (crates/headroom-core/src/transforms/diff_compressor.rs)
  • DirectMem0Adapter.search_memories (cognitive 16) (headroom/memory/backends/direct_mem0.py)
  • Duplicated block (10 lines × 2) (crates/headroom-proxy/src/bedrock/invoke.rs)
  • Duplicated block (10 lines × 3) (headroom/evals/batch_compression_eval.py)
  • …and 390 more

Changes since last survey

  • 300 commits — 63 feature/other, 237 fixes

By area

  • headroom/proxy — 48 commits
  • headroom/transforms — 35 commits
  • (root) — 27 commits
  • crates/headroom-core — 17 commits
  • headroom/cache — 16 commits
  • sdk/typescript — 13 commits
  • docs/content — 12 commits
  • headroom/memory — 11 commits
  • headroom/providers — 11 commits
  • headroom/cli — 10 commits
  • headroom/tokenizers — 7 commits
  • plugins/openclaw — 7 commits
  • .github/workflows — 6 commits
  • crates/headroom-proxy — 6 commits
  • plugins/opencode — 5 commits
  • e2e/wrap — 4 commits
  • tests/test_cli — 4 commits
  • examples/deployment — 3 commits
  • headroom/evals — 3 commits
  • headroom/install — 3 commits

Notable commits

  • fix: Fix(proxy) vertex model override propagation (#2367)
  • fix: fix(asgi): stop buffering when the client disconnects ([GHSA redacted]) (#4701)
  • fix: fix(backends): forward the standard service_tier param (litellm + anyllm) (#2468)
  • fix: fix(backends/litellm): keep cache_control on text blocks for Bedrock prompt caching (#4565)
  • fix: fix(beacon): enforce the allowlist below the top-level keys (#4691)
  • fix: fix(benchmarks): drop the duplicate protect_recent=0 table from the proof harness (#4754)
  • fix: fix(benchmarks): refuse a dirty or non-git --worktree in codemode_ab (#4736)
  • fix: fix(binaries): fail closed on HEADROOM_BINARIES_ALLOW_UNVERIFIED=0/false (#3218)
  • fix: fix(cache): build semantic entry before evicting so a failed embedding keeps live entries (#4581)
  • fix: fix(cache): count a tool_result with no text as replayable in the frozen prefix (#4523)
  • fix: fix(cache): exclude cold starts from TTL hit evidence (#4728)
  • fix: fix(cache): fail closed on SQLite corruption instead of deleting the store online (#4361)
  • fix: fix(cache): namespace SemanticCacheLayer by provider, model and metadata (#4473)
  • fix: fix(cache): order disk writes with result invalidation (#4766)
  • fix: fix(cache): preserve Anthropic tool-result blocks on replay (#4765)
  • fix: fix(cache): preserve OpenAI tool block metadata on cached replay (#4334)
  • fix: fix(cache): record TTL observations with relative filenames (#4711)
  • fix: fix(cache): refresh semantic cache recency on updates (#4767)
  • fix: fix(cache): reject nonpositive semantic cache capacities (#4301)
  • fix: fix(cache): restore query-only semantic cache lookups (#4709)
  • …and 280 more

Architecture

  • Unchanged — 0 containers · 1 contexts · 0 edges

Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

Survey your own repository

headroomlabs-ai/headroom was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.

About this page

  • The score is its most recent published measurement, taken on 14 November 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
  • Measured at commit 0368a872cdd5064b39888e13847200ff562ac192 — the exact code this score is about.
  • Scored under rubric-2026.11.4 — the same rubric and the same method as every other entry in this index.
  • Measured by Canine Code Analyzer (cca.canine.dev) using cca measure-2026.11.65+preprod-36d4cd83012f.