Headroom

1. Headroom là gì? (Headroom GitHub dùng để làm gì)

Headroom là công cụ giúp giảm lượng "token" mà trợ lý AI lập trình của bạn phải đọc. Token là đơn vị mà các dịch vụ AI dùng để tính tiền và tính giới hạn, gần tương đương một phần của từ. Khi làm việc, trợ lý AI (Claude Code, Codex, Cursor…) liên tục đọc kết quả lệnh, file log, dữ liệu JSON và lịch sử trò chuyện. Headroom đứng giữa trợ lý và nhà cung cấp AI, nén phần nội dung đó lại trước khi gửi đi, để bạn dùng ít token hơn mà câu trả lời vẫn vậy.

Nói thẳng: đây là công cụ cho lập trình viên và người đang dùng trợ lý AI lập trình qua dòng lệnh. Nó không có ứng dụng để bấm, và không giúp gì nếu bạn chỉ trò chuyện với ChatGPT hay Claude trên web.

Headroom miễn phí và mã nguồn mở (Apache-2.0) cho người dùng cá nhân. Việc nén chạy ngay trên máy bạn. Nội dung gốc được giữ lại trên máy, nên AI có thể lấy lại bản đầy đủ khi cần. Nhóm phát triển có dịch vụ triển khai riêng cho doanh nghiệp, liên hệ trực tiếp với họ nếu cần.

Hợp với bạn nếu:

• Bạn dùng trợ lý AI lập trình hằng ngày và hay chạm giới hạn, hoặc trả tiền theo token.
• Các phiên làm việc của bạn dài, có nhiều log, kết quả tìm kiếm, dữ liệu JSON.
• Bạn muốn tiết kiệm mà không phải sửa code của mình.

Chưa hợp nếu:

• Bạn chỉ hỏi đáp ngắn. Theo tài liệu, hội thoại ngắn, văn xuôi và nội dung vốn đã cô đọng hầu như không giảm được gì.
• Bạn chưa dùng trợ lý AI lập trình nào, hoặc chưa quen dòng lệnh.

2. Cần chuẩn bị gì?

• Máy tính Windows (64-bit), macOS hoặc Linux. Bản v0.39.1 có sẵn gói cài cho Windows x86_64, macOS (Apple Silicon và Intel) và Linux (x86_64, aarch64).
• Python 3.10 trở lên: ngôn ngữ mà Headroom dùng. Gói cài sẵn được dựng cho Python 3.10 đến 3.13, và tài liệu khuyên dùng 3.13. Tải ở https://www.python.org/downloads/ . Khi cài Python bạn có luôn pip, công cụ cài gói Python.
• uv (tùy chọn, được tài liệu ưu tiên): công cụ cài ứng dụng Python vào một môi trường riêng, không đụng tới các thứ khác trên máy. Tải ở https://docs.astral.sh/uv/
• Một trợ lý AI lập trình đã cài và đăng nhập sẵn, ví dụ Claude Code, Codex, Aider, Copilot CLI, OpenCode, Cline. Phí của trợ lý đó do bạn trả cho nhà cung cấp như bình thường.
• Docker (tùy chọn): nếu bạn không muốn cài Python, dự án có sẵn bản chạy trong Docker. Xem https://docs.headroomlabs.ai/docs/docker-install

Headroom không cần tài khoản hay khóa API riêng.

Phiên bản mới nhất lúc viết bài là v0.39.1, phát hành ngày 26/9/2026.

Lưu ý: Lệnh headroom chỉ có trong gói Python (PyPI). Gói headroom-ai trên npm là thư viện cho lập trình viên TypeScript, cài xong sẽ không có lệnh headroom để gõ.

3. Cách cài Headroom từng bước

Headroom không có file cài .exe hay .dmg. Cách duy nhất là cài qua dòng lệnh; các bước dưới đây là con đường ngắn nhất.

Bước 1: Kiểm tra Python

python --version

Thấy gì là đúng: một số phiên bản từ 3.10 đến 3.13. Trên macOS/Linux, nếu python không chạy thì thử python3 --version.

Bước 2: Cài Headroom

Cách dùng pip (có sẵn cùng Python, chạy được trên cả Windows, macOS và Linux):

pip install "headroom-ai[all]"

Hoặc, nếu bạn đã cài uv (tài liệu ưu tiên cách này trên macOS Apple Silicon và Linux):

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

Phần [all] nghĩa là cài đầy đủ các thành phần chính. Quá trình tải có thể mất vài phút.

Thấy gì là đúng: lệnh chạy xong không báo lỗi, và lệnh sau in ra số phiên bản:

headroom --version

Bước 3: Bọc trợ lý AI của bạn

Cách dễ nhất là lệnh wrap. Nó tự khởi động một "proxy" (trạm trung chuyển chạy trên máy bạn), rồi mở trợ lý AI đã được cấu hình để đi qua trạm đó. Ví dụ với Claude Code:

headroom wrap claude

Với trợ lý khác, thay claude bằng tên tương ứng: codex, aider, copilot, opencode, cline, continue, goose, openhands… Danh sách đầy đủ có trong README của dự án.

Thấy gì là đúng: trợ lý AI mở ra như thường lệ và bạn làm việc bình thường. Mỗi lần muốn dùng, hãy mở trợ lý qua lệnh headroom wrap thay vì mở trực tiếp.

Lưu ý: Lần đầu chạy wrap, Headroom cài thêm Serena, một công cụ mã nguồn mở giúp AI tìm code theo ngữ nghĩa, và đăng ký nó ở mức người dùng. Nếu không muốn, thêm --code-memory none vào cuối lệnh.

Riêng Cursor cần thiết lập tay: lệnh wrap khởi động proxy rồi in ra địa chỉ để bạn dán vào phần cài đặt của Cursor.

Bước 4: Kiểm tra mọi thứ đã thông

Mở một cửa sổ dòng lệnh khác và chạy:

headroom doctor

Thấy gì là đúng: lệnh kiểm tra sức khỏe báo việc định tuyến đang hoạt động.

4. Dùng lần đầu

Sau khi bọc trợ lý, bạn không phải làm gì khác. Hãy giao cho trợ lý một việc thật có nhiều dữ liệu, chẳng hạn nhờ nó đọc một file log dài và tìm dòng lỗi, hoặc khảo sát một thư mục code lớn.

Trong lúc proxy đang chạy, xem lượng token đã tiết kiệm bằng bảng điều khiển:

headroom dashboard

Trình duyệt mở trang http://localhost:8787/dashboard (địa chỉ chỉ có trên máy bạn) với số liệu theo thời gian thực. Muốn xem ngay trong dòng lệnh, dùng:

headroom savings

Đừng kỳ vọng một con số cố định. Theo bảng đo do dự án công bố, mức giảm phụ thuộc vào loại nội dung:

Tình huống đo	Token trước	Token sau	Giảm
Tìm kiếm code (100 kết quả)	17.199	13.597	21%
Gỡ lỗi sự cố hệ thống	55.957	24.340	57%
Khảo sát codebase	58.801	33.895	42%
Phân loại issue trên GitHub	46.067	32.429	30%

Dữ liệu lặp lại nhiều như mảng JSON hay dòng log giảm mạnh nhất; văn xuôi và nội dung đã cô đọng gần như không giảm.

Nếu bạn không dùng trợ lý nào trong danh sách wrap, có thể chạy riêng proxy rồi trỏ ứng dụng tương thích OpenAI của bạn về địa chỉ đó:

headroom proxy --port 8787

5. Lỗi thường gặp khi cài Headroom và cách sửa

Dấu hiệu	Nguyên nhân	Cách sửa
Gõ headroom thì máy báo không tìm thấy lệnh	Cài bằng uv nhưng thư mục chứa lệnh chưa nằm trong PATH (danh sách nơi máy tìm lệnh), hoặc bạn cài nhầm gói npm	Chạy uv tool update-shell rồi mở lại cửa sổ dòng lệnh. Nếu đã cài bằng npm, cài lại bằng pip như Bước 2
Trên Windows, cài đặt dừng giữa chừng và Windows Defender báo file sg.exe có mã độc	Đây là cảnh báo nhầm đã được ghi nhận với một gói phụ thuộc (ast-grep-cli), không phải lỗi của Headroom	Mở Windows Security, vào Virus & threat protection, Protection history, chọn mục sg.exe, bấm Restore, rồi chạy lại lệnh cài. Cách an toàn nhất theo tài liệu là chạy Headroom bằng Docker
Trên Windows, lỗi linker link.exe not found khi cài	Không có gói cài sẵn cho phiên bản Python của bạn, nên pip cố tự biên dịch từ mã nguồn	Dùng Python trong khoảng 3.10 đến 3.13 rồi cài lại, hoặc dùng bản Docker
Cài bằng pipx nhưng luôn ra phiên bản cũ	pipx đang dùng bản Python mà Headroom chưa có gói cài sẵn	Gỡ bản cũ và cài lại bằng pipx install --python python3.13 "headroom-ai[all]"
pip install báo CERTIFICATE_VERIFY_FAILED	Mạng công ty có kiểm tra SSL	Cài từ gói dựng sẵn bằng pip install --only-binary headroom-ai headroom-ai. Chi tiết: https://docs.headroomlabs.ai/docs/corporate-networks
headroom proxy không khởi động được hoặc treo	Cổng 8787 đang bị chương trình khác dùng, hoặc thiếu thành phần proxy	Thử cổng khác bằng headroom proxy --port 8788. Nếu thiếu thành phần, chạy pip install "headroom-ai[proxy]"
Bảng điều khiển không hiện mức tiết kiệm nào	Phiên làm việc toàn hội thoại ngắn, không có kết quả công cụ, hoặc dữ liệu quá nhỏ để nén	Thử một việc có nhiều kết quả lệnh, log hoặc JSON. Đây là giới hạn đã được ghi trong tài liệu: https://docs.headroomlabs.ai/docs/limitations

Trang gỡ lỗi chính thức: https://docs.headroomlabs.ai/docs/troubleshooting

6. Gỡ cài đặt / cập nhật

Cập nhật. Headroom tự biết nó được cài bằng cách nào (pip, pipx hay uv) và nâng cấp đúng cách đó:

headroom update

Chỉ muốn xem có bản mới không:

headroom update --check

Gỡ cài đặt. Làm theo thứ tự sau.

Trước hết, trả trợ lý AI về trạng thái ban đầu. Thay claude bằng tên trợ lý bạn đã bọc:

headroom unwrap claude

Nếu bạn từng đăng ký Headroom làm máy chủ MCP cho trợ lý:

headroom mcp uninstall

Cuối cùng, gỡ gói bằng chính công cụ đã dùng để cài. Nếu cài bằng pip:

pip uninstall headroom-ai

Nếu cài bằng uv:

uv tool uninstall headroom-ai

Hai lệnh gỡ cuối là lệnh chuẩn của pip và uv.

7. Câu hỏi hay gặp

Có mất tiền không? Không. Bản mã nguồn mở miễn phí cho cá nhân. Bạn vẫn trả tiền cho nhà cung cấp AI như cũ, và mục đích của Headroom là làm khoản đó nhỏ đi.

Có cần mạng không? Cần mạng lúc cài, và trợ lý AI của bạn vốn cần mạng để gọi mô hình. Việc nén thì chạy trên máy bạn.

Nội dung của tôi có bị gửi đi đâu không? Theo tài liệu, không có prompt hay nội dung file nào bị gửi đi để nén. Tuy nhiên Headroom mặc định gửi một tín hiệu thống kê ẩn danh: tỷ lệ nén, bộ đếm, tên nhà cung cấp và mô hình, hệ điều hành. Nó không gửi prompt, câu trả lời, code hay đường dẫn file. Tắt bằng cách đặt biến môi trường HEADROOM_BEACON=off hoặc DO_NOT_TRACK=1, hoặc chạy với --offline.

Nén rồi AI có trả lời sai đi không? Dự án công bố các bài đo độ chính xác cho thấy kết quả gần như không đổi, và bản gốc luôn được giữ lại trên máy để AI lấy lại khi cần. Dù vậy, hãy tự kiểm tra trên công việc của bạn trước khi tin hoàn toàn.

Máy yếu có chạy được không? Theo tài liệu, thời gian nén dưới một phần nghìn giây ở mức dữ liệu thông thường. Trên máy x86 đời cũ không có tập lệnh AVX2, Headroom tự chuyển sang cách xử lý đơn giản hơn thay vì báo lỗi.