Headroom — Nén Token Cho AI Agent
Headroom nén dữ liệu AI agent từ 60-95% cho JSON và 15-20% cho coding agent — reversible, không cần thay đổi code.
Mọi AI coding agent đều đối mặt với cùng một vấn đề: chi phí token. Mỗi kết quả tool call, mỗi file đọc vào, mỗi đoạn log đều bị nhồi vào context window và tính phí theo token. Với các nhóm sử dụng Claude Code, Cursor hay Codex trên codebase lớn, chi phí này tích tụ thành số tiền thực sự — và cả những cơn đau đầu về context window.
Headroom là một lớp nén token mã nguồn mở, local-first, nằm giữa AI agent của bạn và nhà cung cấp LLM, nén mọi thứ AI agent đọc — kết quả tool call, log, chunk RAG, file và lịch sử hội thoại — trước khi chúng đến API.
Headroom là gì?#
Headroom là engine tối ưu hóa context đạt 60–95% tiết kiệm token trên dữ liệu JSON và 15–20% tiết kiệm cho coding agent trong khi vẫn giữ nguyên câu trả lời và độ chính xác về hành vi. Nó hoàn toàn có thể đảo ngược — dữ liệu gốc được cache local và có thể lấy lại khi LLM cần dữ liệu đầy đủ.
Nó hoạt động ở bốn chế độ:
- Proxy mode — proxy không cần thay đổi code (
headroom proxy --port 8787) - Agent wrap — wrapper một lệnh cho Claude Code, Codex CLI, Cursor và 18+ agent khác
- Python/TypeScript library — gọi
compress()inline trong code của bạn - MCP server — cung cấp công cụ nén cho bất kỳ agent tương thích MCP nào
Dự án được xây dựng với lõi Python + mở rộng Rust (qua PyO3), mang lại cả sự linh hoạt và hiệu suất native cho xử lý AST và nén.
Tại sao Headroom quan trọng#
Tiết kiệm token là thực tế#
| Loại dữ liệu | Nén | Phương pháp |
|---|---|---|
| Kết quả JSON tool | 60–95% | SmartCrusher — nén JSON vạn năng |
| File code | AST-aware | CodeCompressor cho Python, JS/TS, Go, Rust, Java, C/C++, Perl |
| Văn bản | Transformer v2 | Kompress-v2-base (huấn luyện trên agentic traces) |
| Hình ảnh | 40–90% | ML router + OCR (RapidOCR/SigLIP) |
| Phiên coding agent | 15–20% | Kết hợp tất cả bộ nén |
An toàn với KV-Cache của nhà cung cấp#
Live-Zone Compression của Headroom chỉ nén các byte mới đến (kết quả tool mới, lượt mới nhất) trong khi giữ phần prefix đã đóng băng byte-identical. Điều này rất quan trọng vì KV-cache của nhà cung cấp (như Anthropic prompt caching) cache dựa trên khớp prefix chính xác theo byte. Nếu bạn thay đổi prefix, bạn phá hủy cache. Headroom không bao giờ làm điều đó.
Nén có thể đảo ngược#
Khi LLM cần dữ liệu đã được cắt gọn, hệ thống CCR (Cached Context Retrieval) của Headroom lưu trữ dữ liệu gốc local trong SQLite hoặc Redis và chèn các thẻ truy xuất nhẹ (<<ccr:HASH>>). Agent có thể gọi headroom_retrieve để lấy lại dữ liệu gốc khi cần.
Giảm output token#
Headroom không chỉ nén những gì bạn gửi — nó cũng cắt bớt những gì model viết lại thông qua:
- Verbosity steering — thêm hướng dẫn ngắn gọn vào prompt
- Effort routing — giảm ngân sách suy luận trên các bước thông thường như đọc file
Tích hợp#
18+ AI coding agent (qua headroom wrap):
Claude Code, Codex CLI, Cursor, Aider, GitHub Copilot CLI, OpenCode, Cline, Continue, OpenClaw, Goose, OpenHands, Mistral Vibe, Oh My Pi, và ZCode.
SDK & Framework: Anthropic SDK, OpenAI SDK, Vercel AI SDK, LiteLLM, LangChain, Agno, Strands Agents SDK, FastAPI/ASGI middleware
Cài đặt#
# Python (khuyến nghị qua uv)
uv tool install --python 3.13 "headroom-ai[all]"
# Hoặc qua pip
pip install "headroom-ai[all]"
# TypeScript SDK
npm install headroom-aiBắt đầu nhanh#
Proxy mode (không thay đổi code)#
headroom proxy --port 8787
# Trỏ LLM client của bạn đến http://localhost:8787Agent wrap mode#
headroom wrap claude
# Claude Code bây giờ tự động gửi đầu vào đã nén
headroom unwrap claude # Để hoàn tácSử dụng thư viện inline#
from headroom import compress
compressed = compress(large_json_payload)Cách hoạt động#
Agent / App → Headroom Proxy / Library → LLM Provider- Nhận đầu vào — các prompt messages hoặc luồng tool payload bị chặn lại
- CacheAligner — kiểm tra và cảnh báo về nội dung dễ thay đổi có thể phá vỡ KV-cache prefix
- ContentRouter — phát hiện loại nội dung (Magika/phân tích heuristic) và chọn bộ nén tối ưu
- CCR — lưu trữ chuỗi gốc local, chèn thẻ truy xuất
- Chuyển tiếp payload đã tối ưu đến LLM
Tính năng headroom learn#
Headroom khai thác các phiên làm việc thất bại local và tự động ghi các chỉnh sửa vào file cấu hình memory agent (CLAUDE.local.md, AGENTS.md). Agent trở nên thông minh hơn về lỗi của chính nó theo thời gian.
Cross-Agent Memory#
Kho lưu trữ context dùng chung, đã khử trùng lặp, hoạt động trên nhiều AI coding agent trên cùng một máy. Claude Code, Cursor và Codex có thể chia sẻ memory chung mà không trùng lặp context.
So sánh#
| Tính năng | Headroom | Native provider compaction | Prompt caching proxies |
|---|---|---|---|
| Tỷ lệ nén | 60–95% (JSON), 15–20% (code) | Thay đổi (mất context) | Không (chỉ cache) |
| Có thể đảo ngược | ✅ CCR retrieval | ❌ Mất context | ❌ |
| KV-cache an toàn | ✅ CacheAligner | ✅ Cùng provider | ✅ Cùng provider |
| Giảm output | ✅ Verbosity steering | ❌ | ❌ |
| Memory xuyên agent | ✅ Shared context store | ❌ | ❌ |
| Tự học | ✅ headroom learn | ❌ | ❌ |
| Tích hợp agent | 18+ | Khác nhau | Khác nhau |
| Thay đổi code | Không (proxy/wrap) | Không | Không |
Tổng kết#
Headroom giải quyết một sự kém hiệu quả cơ bản trong phát triển hỗ trợ AI: gửi dữ liệu dài dòng, chưa nén đến API LLM. Với nén 60–95% trên JSON, truy xuất có thể đảo ngược, nén an toàn với KV-cache, và tích hợp không cần thay đổi code, nó là một trong những công cụ tiết kiệm chi phí thực tế nhất cho bất kỳ nhóm nào sử dụng AI coding agent ở quy mô lớn.
Được cấp phép Apache 2.0, local-first và có thể mở rộng qua Python + Rust — Headroom là một bản nâng cấp dễ dàng cho bất kỳ quy trình làm việc AI agent nào.