# billion-context: nén ngữ cảnh cho phiên AI coding dài hàng tháng — hướng dẫn cài đặt và dùng

> billion-context là một plugin/proxy nén ngữ cảnh cho các agent lập trình như Claude Code, pi, opencode, codex. Nó chen vào giữa agent và API mô hình, để chính mô hình tự gom đoạn hội thoại cũ thành bản tóm tắt chi tiết, nhờ vậy phiên dài không bị tràn cửa sổ. Cài bằng một lệnh npm (cần Node 20 trở lên) nên không khó, nhưng phần cấu hình theo từng client khá nhiều.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-09-09 · Cập nhật: 2026-11-14
- URL: https://ongt.vn/bai-viet/billion-context-nen-ngu-canh-phien-ai-coding-dai

billion-context là một plugin nén ngữ cảnh cho các agent lập trình. Nó đứng giữa agent của bạn (Claude Code, pi, opencode, codex…) và API của mô hình, rồi viết lại luồng hội thoại để phần cũ được gom thành bản tóm tắt gọn. Lệnh điều khiển của nó tên là `bili`.

Vấn đề nó giải quyết rất quen với ai hay làm việc lâu với AI. Phiên chat dài thì ngữ cảnh phình to, tiền token tăng theo, và khi vượt cửa sổ ngữ cảnh thì phiên bắt đầu kém đi hoặc chết hẳn. Thay vì cắt cụt, billion-context để chính mô hình quyết định lúc nào nên nén và nén đoạn nào. Tác giả mô tả mục tiêu là chạy một phiên đơn kéo dài hàng tháng, và cửa sổ khoảng 100K là đủ.

Bạn nên đọc bài này nếu đang dùng agent lập trình hằng ngày và hay gặp cảnh phải mở phiên mới, giải thích lại từ đầu. Điểm đáng giá nhất là nén kiểu tăng dần và có thể hoàn lại, nên bạn không mất chi tiết vĩnh viễn. Repo hiện có khoảng 7174 sao và 588 fork, và vẫn được cập nhật trong vài tháng gần đây.

```repo
- repo | ranxianglei/billion-context
- kind | CLI
- desc | Công cụ nén ngữ cảnh đứng giữa agent lập trình và API mô hình, giúp một phiên làm việc chạy hàng ngày mà không tràn cửa sổ ngữ cảnh.
- stars | 7.2k
- lang | TypeScript
```

## billion-context làm được gì

Cơ chế chính là proxy chèn thêm bốn công cụ quản lý ngữ cảnh vào cuộc hội thoại. Mô hình tự gọi chúng khi thấy ngữ cảnh đầy dần:

- **`compress`**: gom một đoạn tin nhắn thành bản tóm tắt chi tiết. Lợi ích là phần việc đã xong không còn chiếm chỗ, nhưng ý chính vẫn nằm trong lịch sử.
- **`decompress`**: khôi phục đoạn đã nén khi bạn cần lại chi tiết chính xác. Nhờ đó nén không phải là quyết định một chiều.
- **`search_context`**: tìm theo từ khoá trong các bản tóm tắt và các tin nhắn đang hiển thị. Hợp khi bạn nhớ mang máng đã bàn chuyện gì đó từ hôm trước.
- **`acp_status`**: xem tổng quan mức dùng ngữ cảnh và đoạn nào còn nén được.

Tác giả nhấn mạnh ba điểm khác với bộ tóm tắt có sẵn của từng công cụ: nén theo từng đoạn nhỏ (tăng dần), có thể giải nén theo nhu cầu, và giữ nguyên phần đầu (prefix) để cache của nhà cung cấp vẫn trúng. README ghi một phiên khoẻ mạnh giữ tỉ lệ trúng prefix-cache khoảng 95–97%, và bản thân việc nén tốn không quá 2%.

Ngoài ra, repo đi kèm một bài báo nghiên cứu (thư mục `paper/`) và các bản đánh giá độc lập. Theo README, trên bộ thử nghiệm 1.500 câu hỏi, billion-context đứng đầu ở ContextBench và giảm khoảng 58,3% chi phí so với đưa toàn bộ ngữ cảnh vào. Đây là số liệu do tác giả công bố, bạn nên xem như tham khảo.

Bảng tương thích khá rộng: pi, opencode, omp, dsh, kimi, hermes, zcode, claude, codex, jcode, gemini, iflow, qwen, antigravity, mcode, aider, copilot, amp, kiro, crush, zed, goose. Với công cụ không có hook ngữ cảnh, README bảo dùng `bili <client>` hoặc tiền tố `/bili/`.

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

- **Node.js 20 trở lên**: `package.json` yêu cầu `>=20`. Cần có `npm` đi kèm.
- **Một agent lập trình đang dùng được**: ví dụ Claude Code, pi, opencode, codex… billion-context không thay agent, nó chỉ đứng giữa agent và API.
- **Tài khoản/API key của chính agent đó**: README đoạn mình có không nói billion-context đòi key riêng. Bạn vẫn dùng đăng nhập hoặc key sẵn có của client.
- **Hệ điều hành**: README hướng dẫn riêng cho Linux/macOS và Windows. Repo còn có `Dockerfile` ở thư mục gốc nếu bạn thích chạy bằng container.
- **Phần cứng**: tư liệu không nhắc yêu cầu GPU. Đây là proxy chạy trên máy bạn nên mình nghĩ không cần, nhưng README chưa khẳng định.

```note
proxy này nhìn thấy toàn bộ nội dung hội thoại giữa bạn và mô hình, gồm cả mã nguồn và có thể cả key. Chỉ cài từ nguồn bạn tin, và đừng dùng nó trên máy chứa dữ liệu mật nếu chưa đọc kỹ cách nó hoạt động.
```

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

```steps
- Kiểm tra Node | Đảm bảo máy có Node 20 trở lên
- Cài billion-context | Chạy một lệnh npm để có lệnh bili
- Kiểm tra PATH | Chắc chắn lệnh bili gọi được trong terminal
- Chọn cách dùng | Plugin gốc, launcher hoặc đổi URL
- Khởi động agent | Chạy client như bình thường hoặc qua bili
```

### Kiểm tra Node

Mở terminal (Terminal trên macOS/Linux, PowerShell trên Windows) và xem phiên bản Node. Cần từ 20 trở lên.

```bash
node --version
```

### Cài billion-context

Với Linux/macOS, README khuyên cài vào thư mục người dùng. Cách này không cần `sudo`, không đụng cấu hình npm, và tính năng tự cập nhật của `bili` không bị lỗi quyền.

```bash
npm install -g billion-context --prefix=~/.local
```

Với nvm hoặc Homebrew Node, thư mục mặc định đã thuộc quyền người dùng, nên chạy lệnh thường là đủ:

```bash
npm install -g billion-context
```

Trên Windows, README ghi thư mục mặc định (`%APPDATA%\npm`) cũng ghi được, nên dùng lệnh thường:

```powershell
npm install -g billion-context
```

Lệnh này cài ra `bili`. Tên `bili-proxy` được giữ làm bí danh.

### Kiểm tra PATH

Với cách cài có `--prefix=~/.local`, lệnh `bili` nằm ở `~/.local/bin`. Hầu hết bản Linux đã có thư mục này trong PATH. Nếu gõ `bili` mà báo không tìm thấy, thêm dòng sau vào `~/.bashrc` hoặc `~/.zshrc`, rồi mở lại terminal:

```bash
export PATH="$HOME/.local/bin:$PATH"
```

Bạn gặp `EACCES` vì trước đây cài bằng prefix thuộc quyền root? README bảo cài lại với `--prefix=~/.local` và tránh `sudo`. Các lần cài lại sau này cũng nên thêm cờ đó.

### Chọn cách dùng

README đưa ra ba hướng. Chọn một:

- **Plugin gốc**: `bili plugin install <client>`. bili trở thành plugin bên trong client, bạn cứ mở client như thường.
- **Launcher**: gõ `bili <client>`, nó bật proxy và client cùng lúc mà không sửa file cấu hình thật của bạn.
- **Đổi URL**: thêm tiền tố địa chỉ proxy + `/bili/` vào baseURL của client. Cách này dùng được với mọi client.

Ví dụ cài dạng plugin gốc cho các client được README liệt kê:

```bash
bili plugin install pi
bili plugin install omp
bili plugin install opencode
bili plugin install dsh
bili plugin install kimi
bili plugin install hermes
bili plugin install zcode
```

Muốn gỡ thì dùng:

```bash
bili plugin remove <client>
```

Bản cấu hình gốc được sao lưu thành file `.bili-bak`.

Nếu bạn dùng Claude Code, repo này còn là một marketplace plugin. Gõ lần lượt trong Claude Code:

```bash
/plugin marketplace add ranxianglei/billion-context
/plugin install billion-context@billion-context
/billion-context:bili-setup
```

Lệnh cuối chạy `bili plugin install claude` giúp bạn và nhắc bạn khởi động lại.

### Khởi động agent

Với launcher, chỉ cần gõ tên client sau `bili`:

```bash
bili claude
bili codex
bili opencode
```

Với codex có lưu ý riêng: nếu dùng `bili plugin install codex` thì phải chạy bili trước, vì phần vỏ MCP không tự bật proxy. Launcher `bili codex` là cách đầy đủ nhất.

Cổng mạng: `bili start` (chạy tay) dùng cổng `8787`. Các launcher và hook tự bật proxy sẽ dùng vùng cổng bắt đầu từ `18787`, trùng thì tự nhảy sang cổng kế. Bạn thường không phải chỉnh gì.

Quan trọng: plugin gốc (`bili plugin install ...`) và các extension độc lập (`billion-context-pi`, `opencode-acp`) loại trừ nhau. Bật cả hai sẽ nén hai lần. Trình cài đặt sẽ thay các mục cũ giúp bạn, nhưng bản cài ở cấp dự án thì bạn phải gỡ tay.

Phần chi tiết cho từng client README dẫn sang `docs/clients.md`. Cấu hình nâng cao có trong `CONFIGURATION.md` ở gốc repo. Mục chạy bằng Docker README nhắc tới nhưng đoạn mình có đã bị cắt, nên bạn mở thẳng README để xem.

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

Tư liệu mình có không ghi lệnh kiểm tra phiên bản riêng, nên mình chỉ nêu những gì chắc chắn:

1. Gõ `bili` trong terminal. Nếu báo không tìm thấy lệnh thì quay lại bước PATH.
2. Chạy client qua `bili claude` (hoặc client bạn chọn) và làm việc như bình thường. Nếu client mở lên và trả lời được, proxy đang thông.
3. Trong phiên làm việc, gõ `/acp` hoặc `/acp-cache`. README nói hai lệnh này dùng để xem phân tích cache. Bạn cũng có thể nhờ mô hình gọi `acp_status` để xem mức dùng ngữ cảnh.
4. Sau khi phiên đã dài, nhìn tỉ lệ trúng cache. README nói mức khoẻ mạnh là khoảng 95–97%.

Chưa thấy nén ngay sau vài tin nhắn đầu là bình thường, vì mô hình chỉ nén khi ngữ cảnh bắt đầu lớn.

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

### Lập trình viên làm một dự án lớn nhiều ngày

Bạn đang refactor một codebase lớn bằng Claude Code. Cứ vài giờ là ngữ cảnh đầy, phải mở phiên mới và dặn lại bối cảnh. Với billion-context, bạn chạy:

```bash
bili claude
```

Bạn làm việc như thường. Khi ngữ cảnh lớn dần, mô hình tự gọi `compress` để gom các bước đã xong thành bản tóm tắt. Kết quả là bạn giữ được một phiên liền mạch lâu hơn, và vẫn có thể bảo mô hình tìm lại một quyết định cũ.

> Không phải cắt bỏ ký ức, mà là gấp nó lại để khi cần thì mở ra.
>
> — Ông T

### Người mới muốn cắm vào Claude Code thật nhanh

Bạn không thích gõ `bili` mỗi lần và muốn cài một lần cho xong. Dùng đường marketplace trong Claude Code:

```bash
/plugin marketplace add ranxianglei/billion-context
/plugin install billion-context@billion-context
/billion-context:bili-setup
```

Sau khi khởi động lại Claude Code, bạn mở nó như thường ngày. README ghi plugin này không tự thêm hook hay MCP riêng nên không bị đăng ký trùng.

### Người đang trả tiền theo token và muốn kiểm tra cache

Bạn thấy hoá đơn API cao bất thường trong phiên dài. Trong phiên làm việc, gõ:

```bash
/acp-cache
```

README nói nếu tỉ lệ trúng cache thấp kéo dài, các nguyên nhân thường gặp theo thứ tự là: cache phía nhà cung cấp hết hạn, đổi mô hình giữa chừng, lỗi của bili (nên báo cho tác giả), hoặc không rõ. Việc biết nguyên nhân giúp bạn tránh đổi mô hình giữa phiên một cách vô ý.

### Dùng với công cụ không có plugin

Bạn xài aider, Gemini CLI hoặc Goose, những công cụ không có chỗ cắm plugin. README chỉ dùng launcher:

```bash
bili aider
bili gemini
bili goose
```

Với các công cụ này, bili làm việc ở tầng mạng nên một số tính năng bên trong vòng lặp có thể bị hạn chế. README ghi rõ aider và gemini không có chế độ native. Chi tiết từng công cụ xem `docs/clients.md`.

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

- **`EACCES` khi cài npm**: do thư mục cài đặt thuộc quyền root. Cách an toàn là cài lại với `npm install -g billion-context --prefix=~/.local`, không dùng `sudo`.
- **Gõ `bili` báo không tìm thấy lệnh**: thư mục `~/.local/bin` chưa nằm trong PATH. Thêm `export PATH="$HOME/.local/bin:$PATH"` vào `~/.bashrc` hoặc `~/.zshrc` rồi mở terminal mới.
- **Bị nén hai lần, phản hồi lạ**: bạn đang bật cả plugin gốc lẫn extension độc lập như `billion-context-pi` hoặc `opencode-acp`. Chạy lại `bili plugin install <client>` để trình cài thay mục cũ. Nếu bản cũ nằm ở cấp dự án, gỡ tay.
- **Tỉ lệ cache thấp kéo dài**: dùng `/acp` hoặc `/acp-cache` để xem nguyên nhân. Kiểm tra xem bạn có đổi mô hình giữa chừng không, và nhớ rằng cache phía nhà cung cấp cũng có hạn.
- **Cổng bị chiếm**: nếu `bili start` không lên cổng `8787`, kiểm tra xem tiến trình nào đang giữ cổng. Các launcher tự nhảy sang cổng khác bắt đầu từ `18787`.

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

**Điểm mạnh.** Cách nén tăng dần, có thể hoàn lại, giữ cache là cách tiếp cận đáng thử cho người hay chạy phiên dài. Danh sách client được hỗ trợ rất rộng. Số liệu tác giả công bố, từ nghiên cứu thực tế dài tháng đến các bài đánh giá, cho thấy họ làm khá nghiêm túc. Repo có tài liệu riêng cho cấu hình, vòng đời và kỹ thuật.

**Giới hạn.** Số lượng chế độ cài (plugin gốc, launcher, đổi URL) và ghi chú riêng cho từng client khiến người mới dễ rối. Với các client chỉ dùng được qua launcher hoặc cert-MITM, bạn phải chấp nhận proxy can thiệp tầng mạng. README hiện không ghi rõ giấy phép ở phần mình có, dù repo có file `LICENSE` (riêng bài báo là MIT), nên nếu dùng trong công ty, bạn nên mở file đó ra xem. Mọi con số hiệu quả là do tác giả công bố, bạn nên tự đo trên phiên của mình.

**Khi nào chọn cách khác.** Nếu bạn chỉ chat ngắn, phiên hiếm khi chạm giới hạn ngữ cảnh, thì không cần thêm một lớp proxy. Nếu dữ liệu quá nhạy cảm và bạn không muốn thêm bất kỳ thành phần nào đứng giữa, hãy dùng chức năng tóm tắt có sẵn của client. Còn nếu phiên của bạn thường xuyên tràn hoặc tốn token, đây là công cụ đáng cài thử trước.

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

### billion-context có miễn phí không?

Gói npm billion-context cài được bằng lệnh npm thông thường và README không nhắc phí bản quyền. Tuy vậy bạn vẫn phải trả tiền API cho mô hình mà agent của bạn gọi. Về giấy phép, đoạn README mình có không ghi rõ, repo có file LICENSE để bạn tự kiểm tra.

### Có cần GPU không?

Tư liệu không nêu yêu cầu GPU. billion-context là proxy/plugin viết bằng TypeScript, chạy trên Node 20 trở lên, và mô hình vẫn chạy ở phía nhà cung cấp API. Chưa có thông tin chi tiết hơn về phần cứng.

### Chạy trên Windows được không?

Được. README có hướng dẫn riêng cho Windows: thư mục npm mặc định thuộc quyền người dùng nên chỉ cần chạy npm install -g billion-context. Mức hỗ trợ cụ thể cho từng client trên Windows bạn xem thêm trong docs/clients.md.

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

Công cụ đứng giữa agent và API mô hình, nên nó nhìn thấy nội dung hội thoại. README đoạn mình có không bàn về bảo mật dữ liệu, nên chưa có kết luận. Hãy đọc mã nguồn và tài liệu kỹ thuật trước khi dùng với dự án nhạy cảm.

### Khác gì tính năng tóm tắt có sẵn của Claude Code hay các agent khác?

Theo tác giả, nén ở đây là tăng dần, có thể giải nén lại khi cần và giữ nguyên prefix để cache vẫn trúng. Bộ tóm tắt có sẵn của client thường không có cả ba đặc điểm này. Chính mô hình quyết định khi nào và nén đoạn nào.

### Nên chọn plugin gốc hay launcher?

Plugin gốc (bili plugin install) cài một lần rồi mở client như bình thường, nhưng chỉ có cho một số client như pi, omp, opencode, dsh, kimi, hermes, zcode và claude. Launcher (bili <client>) không đụng file cấu hình thật và dùng được với nhiều client hơn. Đừng bật cả plugin gốc lẫn extension độc lập cùng lúc vì sẽ nén hai lần.

### Cần Node phiên bản nào?

package.json yêu cầu Node từ phiên bản 20 trở lên. Kiểm tra bằng lệnh node --version trước khi cài.
