# headroom: Giảm token cho AI agent — hướng dẫn cài đặt và dùng

> Headroom là thư viện Python, proxy và MCP server giúp nén tool output, log, file, dữ liệu RAG và lịch sử hội thoại trước khi gửi đến LLM. Bạn có thể dùng trực tiếp trong ứng dụng, chạy proxy không cần sửa code, hoặc bọc các coding agent như Claude Code, Codex và Cursor. Cài đặt khá đơn giản nếu đã có Python phù hợp; riêng từng agent có thể cần cấu hình thêm.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-11-08 · Cập nhật: 2026-11-14
- URL: https://ongt.vn/bai-viet/headroom-giam-token-cho-ai-agent

Headroom là thư viện Python giúp nén những nội dung mà AI agent đọc trước khi gửi đến mô hình ngôn ngữ lớn. Repo này xử lý tool output, log, file, dữ liệu RAG và lịch sử hội thoại, từ đó giảm số token đầu vào mà vẫn giữ thông tin cần thiết cho câu trả lời.

Bạn có thể dùng Headroom theo ba cách chính: gọi hàm `compress()` trong ứng dụng Python hoặc TypeScript, chạy một proxy cục bộ để không phải sửa code ứng dụng, hoặc dùng lệnh `headroom wrap` với các coding agent. Repo cũng cung cấp MCP server, bộ nhớ dùng chung giữa nhiều agent và cơ chế lấy lại nội dung gốc khi mô hình cần.

Điểm đáng giá nhất là dữ liệu được nén trên máy của bạn. README nói prompt và nội dung file không được gửi đi nơi khác để nén. Với nội dung lặp như JSON, log và kết quả tìm kiếm, mức tiết kiệm có thể rất lớn. Với văn bản đã cô đọng, mức tiết kiệm thường thấp hơn. Repo hiện có khoảng 79.536 sao và 6.226 fork, dùng giấy phép Apache-2.0.

```repo
- repo | headroomlabs-ai/headroom
- kind | Thư viện
- desc | Headroom nén output, log, file và dữ liệu RAG trước khi gửi đến LLM, giúp giảm token mà không cần sửa nhiều mã nguồn.
- stars | 80k
- lang | Python
- license | Apache-2.0
```

## Headroom làm được gì

### Nén nội dung trước khi gửi đến LLM

Bạn đưa danh sách message vào `compress(messages)`. Headroom tìm loại nội dung rồi chọn cách nén phù hợp. Tool message và assistant message được nén; user message được giữ nguyên theo mặc định. Cách này phù hợp với ứng dụng dùng OpenAI, Anthropic, LangChain, LiteLLM, Agno, Strands hoặc mã Python riêng.

Lợi ích thực tế là giảm lượng dữ liệu phải gửi ở mỗi lượt gọi model. Bạn có thể giảm chi phí token và giúp agent ít nhanh chạm giới hạn context hơn. Nếu muốn nén cả user message, README cho biết có thể truyền `compress_user_messages=True`.

### Chạy proxy mà không sửa code ứng dụng

Lệnh `headroom proxy --port 8787` khởi động proxy cục bộ. Ứng dụng hoặc coding agent gửi request qua proxy, còn Headroom xử lý phần nén trước khi request đi tiếp đến nhà cung cấp model.

Đây là lựa chọn tiện cho đội nhóm đang có ứng dụng chạy ổn định nhưng chưa muốn sửa luồng gọi LLM. Proxy hỗ trợ Anthropic `/v1/messages`, OpenAI-compatible `/v1/chat/completions` và `/v1/responses` theo nội dung README.

### Bọc coding agent bằng một lệnh

Lệnh `headroom wrap` có thể khởi chạy nhiều agent như Claude Code, Codex, Cursor, Copilot, Aider, OpenCode, Cline, Continue, Goose, OpenHands, Mistral Vibe, Oh My Pi, Factory Droid, Kimi CLI và ZCode. Không cần sửa mã nguồn của agent.

Khi chạy wrapper, Headroom khởi động proxy cục bộ rồi mở agent đã được cấu hình để đi qua proxy. Bạn có thể dùng `headroom unwrap <tool>` để gỡ cấu hình wrapping lâu dài. README cũng ghi rõ `headroom wrap` có phạm vi theo phiên; proxy sẽ dừng khi agent được bọc kết thúc.

### Cung cấp MCP server

Headroom có các công cụ MCP gồm `headroom_compress`, `headroom_retrieve` và `headroom_stats`. MCP client có thể dùng chúng để nén nội dung, lấy lại bản gốc và xem số liệu.

Cơ chế này hữu ích khi agent đang làm việc với dữ liệu dài nhưng đôi lúc vẫn cần xem nguyên văn. Headroom lưu bản gốc cục bộ để mô hình có thể gọi công cụ lấy lại khi cần.

### Dùng bộ nhớ chung giữa nhiều agent

Headroom hỗ trợ một kho memory dùng chung giữa Claude, Codex, Gemini và Grok, đồng thời tự loại bỏ nội dung trùng lặp. Bạn có thể chuyển qua lại giữa các agent mà vẫn giữ được phần thông tin đã lưu theo thiết kế của repo.

### Học từ các phiên làm việc thất bại

Lệnh `headroom learn` phân tích những phiên thất bại rồi ghi correction vào `CLAUDE.local.md` theo mặc định. README cũng nêu các đích khác gồm `CLAUDE.md`, `AGENTS.md`, `GEMINI.md` và `GROK.md`.

Tùy chọn `--verbosity` giúp đọc các phiên trước để ước lượng mức trả lời ngắn gọn phù hợp. Bạn có thể chạy thử ở chế độ xem trước trước khi dùng `--apply` để lưu và áp dụng kết quả.

### Giảm cả token output

Headroom không chỉ giảm token trong prompt gửi đi. Proxy còn có output shaping để hạn chế phần model viết lại những nội dung không cần thiết, chẳng hạn lời mở đầu dài hoặc đoạn code vừa đọc xong đã in lại.

Tính năng này tắt mặc định và được bật bằng biến `HEADROOM_OUTPUT_SHAPER=1`. README nhấn mạnh số liệu output saving thường là ước tính, trừ khi bạn cấu hình một phần hội thoại làm nhóm đối chứng.

## Cần chuẩn bị gì

- Python từ 3.11 trở lên. Đây là yêu cầu được khai báo trong `pyproject.toml`.
- Một cách cài gói Python như `pip` hoặc `uv` nếu bạn dùng thư viện, CLI, proxy hoặc agent wrapper.
- Node.js và npm nếu bạn chỉ dùng TypeScript SDK. README nêu gói npm là SDK để import, không cung cấp lệnh `headroom`.
- Coding agent tương ứng nếu bạn dùng `headroom wrap`, chẳng hạn Claude Code, Codex, Cursor hoặc Copilot.
- Ứng dụng LLM hiện có nếu bạn dùng `compress()` hoặc proxy. Headroom không cần API key riêng để nén và không cần tải model cho cách dùng thư viện cơ bản. Tuy nhiên, nhà cung cấp LLM hoặc agent của bạn vẫn có thể yêu cầu thông tin xác thực riêng.
- Nếu dùng Claude Code trong VS Code, cần cài proxy extra và mở đúng project trong VS Code.
- Nếu dùng GitHub Copilot subscription mode, cần đăng nhập bằng `headroom copilot-auth login`. README có hướng dẫn riêng cho Windows, Docker và CI.

README có các biến cấu hình trong `.env.example` gồm `NEO4J_AUTH`, `NEO4J_PASSWORD` và `HEADROOM_PROXY_TOKEN`. Tư liệu được cung cấp không nói mọi biến này bắt buộc cho quickstart cơ bản, vì vậy bạn chỉ nên cấu hình khi tính năng hoặc cách triển khai của mình yêu cầu.

## Cài đặt từng bước

```steps
- Chọn cách dùng | Dùng thư viện, proxy hoặc bọc coding agent
- Cài gói | Cài headroom-ai bằng pip hoặc uv
- Khởi động | Chạy compress(), proxy hoặc wrap
- Kiểm tra | Dùng doctor, perf hoặc dashboard
- Đo thực tế | Xem savings trên traffic của bạn
```

### Chọn cách dùng phù hợp

Nếu bạn đang viết ứng dụng Python gọi LLM, dùng thư viện trong cùng tiến trình là cách ngắn nhất. Nếu ứng dụng đã có sẵn và không muốn sửa mã nguồn, dùng proxy. Nếu mục tiêu là giảm token cho coding agent, dùng wrapper.

README phân biệt rõ gói Python và gói npm. CLI `headroom` chỉ có trong gói PyPI. Gói npm `headroom-ai` là TypeScript SDK để import và không có lệnh `headroom`.

### Cài bằng pip hoặc uv

Với ứng dụng Python, cài gói cơ bản bằng lệnh sau:

```bash
pip install headroom-ai
```

Lệnh này cài thư viện để bạn gọi `compress()` trong mã Python. README nói cách này không cần API key riêng và không cần tải model.

Nếu cần proxy hoặc đầy đủ tính năng CLI, README dùng extra `all`:

```bash
uv tool install --python 3.13 "headroom-ai[all]"
pip install "headroom-ai[all]"
```

Lệnh `uv tool install` cài CLI trong môi trường tự chứa, còn `pip install` cài gói có đầy đủ extra vào môi trường Python hiện tại. Nếu dùng `pip`, hãy mở terminal tại môi trường Python mà ứng dụng hoặc agent sẽ sử dụng.

Với ứng dụng TypeScript, cài SDK bằng:

```bash
npm install headroom-ai
```

Gói này chỉ cung cấp SDK TypeScript. Nếu bạn cần proxy, README yêu cầu cài thêm extra proxy của gói Python:

```bash
pip install "headroom-ai[proxy]"
```

### Dùng thư viện trong ứng dụng Python

Sau khi cài, đưa message vào `compress()` rồi gửi kết quả đến client LLM:

```python
from headroom import compress
from openai import OpenAI

messages = [{"role": "user", "content": "Analyze these results"}]
result = compress(messages, model="gpt-4o")

client = OpenAI()
response = client.chat.completions.create(model="gpt-4o", messages=result.messages)
print(f"Saved {result.tokens_saved} tokens ({result.compression_ratio:.0%})")
```

`messages` là danh sách message theo dạng OpenAI hoặc Anthropic. `model="gpt-4o"` giúp Headroom biết model được dùng. Sau đó, thay danh sách message ban đầu bằng `result.messages` khi gọi client.

Nếu mã của bạn đã có `messages` và client, phần cần thêm chủ yếu là import, gọi `compress()` và dùng `result.messages`. README cho biết user message không bị nén mặc định; nếu muốn thay đổi, truyền `compress_user_messages=True`.

Để chạy hoàn toàn không qua mạng ở phần nén, README nêu biến sau:

```bash
export HEADROOM_OFFLINE=1
```

Trên PowerShell, cú pháp đặt biến môi trường tương đương là:

```powershell
$env:HEADROOM_OFFLINE="1"
```

Biến này chỉ nên được đặt trong terminal trước khi chạy ứng dụng. Việc gọi nhà cung cấp LLM vẫn phụ thuộc vào client và cấu hình của ứng dụng.

### Chạy proxy cục bộ

Khởi động proxy bằng:

```bash
headroom proxy --port 8787
```

Proxy lắng nghe ở cổng `8787` theo đúng lệnh trong README. Giữ terminal này mở trong lúc ứng dụng hoặc agent gửi request. Sau đó cấu hình ứng dụng dùng endpoint proxy theo hướng dẫn của ứng dụng đó; README cung cấp trang hướng dẫn riêng cho từng loại client.

Nếu muốn bật giảm output token, đặt biến trước khi khởi động proxy:

```bash
export HEADROOM_OUTPUT_SHAPER=1
headroom proxy --port 8787
```

README lưu ý các switch này được đọc trực tiếp trên mỗi request. Tuy nhiên, nếu proxy đang chạy trong môi trường có biến cũ, việc export biến ở một terminal khác không tự động thay đổi môi trường ban đầu của proxy.

### Bọc coding agent

Cài đầy đủ CLI rồi chạy, ví dụ với Claude Code:

```bash
uv tool install --python 3.13 "headroom-ai[all]"
headroom wrap claude
```

Wrapper sẽ khởi động proxy cục bộ và mở agent đã cấu hình để đi qua Headroom. Thay `claude` bằng tên agent được README hỗ trợ, chẳng hạn `codex`, `cursor`, `copilot`, `aider` hoặc `opencode`.

Nếu muốn cài thêm Serena cho semantic code navigation, README cho phép:

```bash
headroom wrap claude --code-memory serena
```

Tính năng này tắt mặc định. Với Claude Code, Serena được đăng ký cho project được bọc theo phạm vi local. Tùy chọn `--code-memory-scope user` có thể làm Serena khả dụng trong mọi project theo nội dung README.

Để gỡ wrapping lâu dài, dùng:

```bash
headroom unwrap <tool>
```

Thay `<tool>` bằng tên tool thực tế. Không gõ nguyên dấu ngoặc nhọn.

Nếu muốn triển khai local theo cách turnkey, README nêu lệnh:

```bash
headroom deploy
```

Còn khi cần chọn service persistent, scheduled task, Docker runtime, scope hoặc provider target, dùng:

```bash
headroom install apply
```

Tư liệu được cung cấp không mô tả chi tiết toàn bộ tùy chọn của `install apply`, nên bạn nên xem hướng dẫn persistent installs trong repo trước khi dùng cho môi trường lâu dài.

### Đăng nhập cho Copilot

Với Copilot CLI subscription mode, chạy:

```bash
headroom copilot-auth login
headroom wrap copilot --subscription -- --model gpt-4o
```

Lệnh đầu tiên lưu token OAuth Copilot dành cho Headroom. Lệnh thứ hai khởi chạy Copilot qua proxy với model được truyền sau dấu `--`.

Với Copilot trong VS Code, README dùng:

```bash
headroom copilot-auth login
headroom wrap vscode
```

Giữ terminal chạy và dùng Copilot bình thường. README nói model picker của VS Code vẫn là nơi quyết định model.

Nếu dùng Claude Code trong VS Code, cài proxy extra rồi chạy:

```bash
pip install "headroom-ai[proxy]"
headroom wrap vscode-claude
```

Tùy chọn model 1M là:

```bash
headroom wrap vscode-claude --1m
```

README yêu cầu reload cửa sổ VS Code ở lần chạy đầu tiên.

## Kiểm tra đã chạy được chưa

Sau khi cài CLI, chạy kiểm tra sức khỏe:

```bash
headroom doctor
```

README mô tả lệnh này là health check để xác nhận routing hoạt động. Nếu dùng proxy, chạy thêm:

```bash
headroom perf
headroom dashboard
```

`headroom perf` giúp kiểm tra hiệu năng. `headroom dashboard` hiển thị mức tiết kiệm trực tiếp, nhưng proxy phải đang chạy.

Nếu dùng thư viện Python, kết quả `compress()` có các trường `messages`, `tokens_saved` và `compression_ratio`. Đoạn mã mẫu in ra số token đã tiết kiệm và tỷ lệ nén. Đây là dấu hiệu rõ ràng nhất cho thấy hàm đã xử lý được message.

Nếu muốn đo theo traffic của chính mình, README nêu:

```bash
headroom savings
```

Không nên lấy một con số benchmark làm cam kết cho mọi ứng dụng. README nói dữ liệu lặp như JSON array và log thường tiết kiệm nhiều hơn prose hoặc output vốn đã cô đọng.

Để chạy proof benchmark có seed cố định, dùng:

```bash
uv run python benchmarks/index_proof_table.py --seed 20260902
```

Các số liệu trong README cho bốn tình huống dao động từ 21% đến 57% token đầu vào được tiết kiệm. README cũng ghi compression có chi phí dưới một mili-giây trong những phép đo được nêu.

## Dùng vào việc thật

### Chủ shop phân tích log đơn hàng bằng ứng dụng Python

Một chủ shop có ứng dụng gửi danh sách kết quả đơn hàng và log vận hành đến LLM để tìm nguyên nhân đơn bị treo. Các log thường lặp lại nhiều trường JSON, nên có thể dùng `compress()` trước khi gọi model.

Cách làm là giữ nguyên danh sách message mà ứng dụng đang dùng, gọi `result = compress(messages, model="gpt-4o")`, rồi truyền `result.messages` vào `client.chat.completions.create()`. Sau đó in `result.tokens_saved` để theo dõi chi phí.

Kết quả mong đợi là prompt ngắn hơn, đặc biệt khi log có nhiều dòng hoặc JSON lặp. Phần user message được giữ nguyên theo mặc định, giúp câu hỏi của chủ shop không bị thay đổi.

### Nhân viên văn phòng dùng agent để đọc tài liệu dài

Một nhân viên văn phòng dùng coding agent hoặc MCP client để xử lý nhiều file và kết quả công cụ. Thay vì để toàn bộ output dài đi thẳng đến model, có thể cài `headroom-ai[all]`, sau đó chạy proxy hoặc `headroom wrap` với agent đang dùng.

Agent vẫn làm việc qua lệnh quen thuộc. Headroom nén tool output trước khi chuyển tiếp. Khi model cần văn bản đầy đủ, MCP tool `headroom_retrieve` có thể lấy lại bản gốc theo cơ chế CCR mà repo cung cấp.

Điểm cần nhớ là proxy phải còn chạy trong suốt phiên làm việc. Nếu dùng wrapper, proxy có phạm vi theo phiên và sẽ dừng cùng agent.

> Khi dữ liệu lặp lại nhiều, hãy để Headroom xử lý trước khi bạn phải trả tiền cho từng token.
>
> — Ông T

### Dev giảm token cho Claude Code hoặc Codex

Một dev đang dùng Claude Code hoặc Codex để khám phá codebase có thể chạy:

```bash
headroom wrap claude
```

hoặc:

```bash
headroom wrap codex
```

Headroom khởi động proxy và định tuyến phiên agent qua lớp nén. Dev không phải sửa source code của agent. Nếu cần semantic code navigation, có thể thêm `--code-memory serena` khi dùng wrapper theo đúng khả năng README nêu.

Kết quả phù hợp nhất khi agent đọc nhiều kết quả tìm kiếm, log và đoạn code lặp. README ghi nhận bốn kịch bản agent có mức giảm input token từ 21% đến 57%, nhưng mức thực tế còn tùy dữ liệu.

### Đội phát triển muốn đo hiệu quả trước khi áp dụng rộng

Đội phát triển có thể chạy `headroom doctor`, `headroom perf` và `headroom dashboard` sau khi khởi động proxy. Sau đó dùng `headroom savings` trên traffic của mình để biết mức tiết kiệm thực tế.

Nếu muốn thử giảm phần model viết lại, đặt `HEADROOM_OUTPUT_SHAPER=1` rồi chạy proxy. Có thể dùng:

```bash
headroom output-savings
```

README cho biết kết quả mặc định là ước tính và hiển thị khoảng tin cậy. Nếu cần số đo thực tế hơn, cấu hình `HEADROOM_OUTPUT_HOLDOUT=0.1` để giữ lại 10% hội thoại làm nhóm đối chứng.

## Lỗi hay gặp và cách xử lý

### Cài xong nhưng không có lệnh `headroom`

Nguyên nhân thường là bạn chỉ cài gói npm hoặc chỉ cài `pip install headroom-ai` trong một môi trường khác với terminal đang dùng. README xác nhận CLI chỉ đi kèm gói PyPI, còn npm package chỉ là TypeScript SDK.

Hãy cài `headroom-ai[all]` bằng `uv tool install` hoặc `pip`, rồi mở lại terminal nếu cần. Nếu chỉ viết ứng dụng TypeScript, hãy import SDK thay vì tìm lệnh CLI.

### Python không đáp ứng yêu cầu

`pyproject.toml` yêu cầu Python từ 3.11. Nếu môi trường cũ hơn, lệnh cài có thể thất bại hoặc không chạy đúng.

Kiểm tra lại Python đang được terminal sử dụng và chuyển sang Python phù hợp. README quickstart cho CLI dùng Python 3.13 với `uv`.

### Proxy chạy nhưng ứng dụng vẫn không đi qua Headroom

Proxy chỉ có tác dụng khi ứng dụng hoặc agent được cấu hình gửi request qua nó. Với coding agent, dùng `headroom wrap <tool>` để wrapper thiết lập routing. Với ứng dụng riêng, cần làm theo hướng dẫn proxy của client tương ứng.

Hãy giữ terminal chạy `headroom proxy --port 8787`, sau đó kiểm tra bằng `headroom doctor` và xem dashboard. Nếu dùng `headroom wrap`, nhớ rằng proxy sẽ kết thúc khi phiên agent kết thúc.

### Dùng sai endpoint OpenAI-compatible

README cảnh báo `headroom wrap` mặc định định tuyến traffic OpenAI-compatible đến `https://api.openai.com/v1`. Nếu bạn dùng DeepSeek, Together, OpenRouter hoặc gateway tự host mà không đổi endpoint, key có thể bị gửi đến OpenAI và nhận lỗi `401 Incorrect API key provided`.

Với provider khác, truyền `--openai-api-url` hoặc đặt `OPENAI_TARGET_API_URL` trước khi wrapping theo đúng hướng dẫn README. Hãy kiểm tra endpoint trước khi chạy với key thật.

### Số token tiết kiệm thấp hơn kỳ vọng

Headroom không nén mọi loại nội dung ở cùng một mức. README nói JSON array và log lặp thường giảm mạnh, còn prose hoặc output vốn đã cô đọng có thể giảm rất ít.

Đừng dùng số benchmark có sẵn để suy ra kết quả chắc chắn cho dữ liệu của bạn. Chạy `headroom savings` trên traffic thực tế và xem dashboard để có con số phù hợp hơn.

### Không thấy output shaping thay đổi câu trả lời

Tính năng này tắt mặc định. Bạn cần đặt `HEADROOM_OUTPUT_SHAPER=1` trước khi khởi động proxy. Nếu proxy đã chạy với môi trường cũ, việc export biến ở terminal khác có thể không tác động đến proxy đó.

README cho biết wrapper có thể hot-sync một số thiết lập qua loopback trong trường hợp proxy được tái sử dụng, nhưng proxy dùng chung có thể áp dụng override toàn cục. Hãy kiểm tra đúng tiến trình proxy trước khi đánh giá kết quả.

```note
Headroom chạy phần nén trên máy của bạn, nhưng nội dung sau khi nén vẫn được gửi đến nhà cung cấp LLM theo cấu hình ứng dụng. Không đưa API key vào prompt hoặc file log. Kiểm tra endpoint và quyền truy cập trước khi dùng proxy với dữ liệu kinh doanh nhạy cảm.
```

## Có nên dùng không

Headroom đáng thử nếu bạn đang trả nhiều chi phí cho input token, thường xuyên gửi log hoặc JSON lớn, hoặc muốn giảm context cho coding agent mà không sửa nhiều mã nguồn. Repo có nhiều lựa chọn: thư viện inline, proxy, wrapper, MCP server, memory dùng chung và dashboard theo dõi.

Khả năng nén cục bộ là điểm mạnh quan trọng với đội ngại đưa dữ liệu sang dịch vụ trung gian. Cơ chế CCR cũng giúp cân bằng giữa prompt ngắn và khả năng lấy lại bản gốc. README còn đưa số đo accuracy và benchmark, trong đó các bài kiểm tra được nêu không cho thấy thay đổi đáng kể ở GSM8K và vẫn đạt kết quả cao ở các bài tool hoặc QA tương ứng.

Giới hạn là mức tiết kiệm phụ thuộc mạnh vào dữ liệu. Văn bản tự nhiên đã ngắn có thể không giảm nhiều. Proxy cũng thêm một thành phần cần vận hành, còn wrapper có khác biệt theo từng agent. Nếu bạn chỉ có một ứng dụng nhỏ với prompt ngắn, chi phí cài và theo dõi có thể không đáng kể so với phần token tiết kiệm.

Bạn cũng nên thận trọng khi dùng persistent deployment, Copilot subscription mode hoặc provider không phải OpenAI. Endpoint, token và phạm vi cấu hình cần được kiểm tra riêng. Với ứng dụng TypeScript, cần nhớ npm package không cung cấp CLI; bạn sẽ phải dùng SDK hoặc cài thêm proxy Python.

Tóm lại, đây là lựa chọn phù hợp cho dev, đội AI và người vận hành coding agent có nhiều output lặp. Hãy bắt đầu bằng `compress()` hoặc `headroom wrap`, chạy `headroom savings` trên dữ liệu thật, rồi mới quyết định có cần proxy persistent, MCP hoặc output shaping hay không.

## Câu hỏi thường gặp

### Headroom có miễn phí không?

Tư liệu được cung cấp không nêu chính sách giá hoặc giới hạn sử dụng. README có gói Python `headroom-ai`, gói npm `headroom-ai`, proxy và các cách chạy local, nhưng chưa đủ thông tin để kết luận mọi tính năng đều miễn phí.

### Có cần GPU hoặc tải model về máy không?

README nói cách dùng thư viện cơ bản không cần tải model. Tư liệu không yêu cầu GPU cho quickstart, vì vậy chưa có cơ sở để nói GPU là bắt buộc.

### Có chạy được trên Windows không?

README xác nhận Windows device authentication cho Copilot đã được live-test và hướng dẫn chạy `headroom copilot-auth login` trên Windows. Tư liệu được cung cấp chưa mô tả đầy đủ ma trận hỗ trợ Windows cho mọi chế độ khác.

### Headroom có cần API key riêng không?

Với `compress()` cơ bản, README nói không cần API key riêng. Tuy nhiên, ứng dụng hoặc agent vẫn có thể cần thông tin xác thực của nhà cung cấp LLM; khi dùng Copilot subscription mode, bạn cần chạy `headroom copilot-auth login`.

### Dữ liệu có an toàn không?

README nói compression chạy trên máy và prompt hoặc nội dung file không được gửi đi nơi khác để nén. Sau đó dữ liệu đã nén vẫn có thể được gửi đến nhà cung cấp LLM theo cấu hình ứng dụng, nên bạn cần tự kiểm tra endpoint, token và dữ liệu nhạy cảm.

### Headroom khác gì việc tự rút gọn prompt?

Headroom tự phát hiện loại nội dung và chọn bộ nén cho JSON, source code hoặc prose. Nó còn có proxy, wrapper cho coding agent, MCP server và CCR để lấy lại bản gốc, nên phạm vi rộng hơn việc tự viết một prompt ngắn hơn.

### Có cần sửa mã nguồn ứng dụng hoặc coding agent không?

Không cần sửa mã nguồn khi dùng proxy hoặc `headroom wrap` theo README. Nếu dùng thư viện inline, bạn cần thêm lời gọi `compress(messages)` và truyền `result.messages` vào client LLM.
