# Context-mode: giữ output công cụ ngoài context của AI — hướng dẫn cài đặt và dùng

> Context Mode là plugin miễn phí, chạy trên máy bạn, giúp trợ lý lập trình AI như Claude Code, Codex, Gemini CLI không bị ngập bởi kết quả đọc file, chạy lệnh hay tải trang web. Kết quả đầy đủ được lưu vào một chỉ mục SQLite cục bộ, AI chỉ nhận phần nó cần. Cài khá dễ: mỗi agent có một hai dòng lệnh, nhưng cần Node 24.15.0 trở lên.

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

Context Mode là một plugin miễn phí, chạy ngay trên máy bạn, dành cho các trợ lý lập trình AI như Claude Code, Codex hay Gemini CLI. Nó chặn phần "rác" quen thuộc: mỗi lần AI đọc file, chạy lệnh hay tải một trang web, toàn bộ kết quả bị nhét vào context window (bộ nhớ làm việc của AI). Context Mode đưa việc đó vào một sandbox, cất kết quả đầy đủ trong một chỉ mục SQLite cục bộ, rồi chỉ đưa cho AI đúng phần nó hỏi.

Bạn nên quan tâm nếu hay dùng AI để viết code, đọc log, tra tài liệu và thấy phiên làm việc nhanh đầy, AI bắt đầu "quên" hoặc tốn token. Repo hiện có khoảng 34 nghìn sao và 2.334 fork, vẫn được cập nhật trong vài tháng gần đây. Tác giả nói plugin không gửi dữ liệu sử dụng đi đâu (zero telemetry).

Điểm đáng giá nhất là con số do chính README công bố: trên các phép đo có kết quả thô từ 10 KB trở lên, câu trả lời đưa vào context nhỏ hơn kết quả gốc khoảng 99,4% (số trung vị). Bạn không cần đổi cách làm việc: cài xong, AI tự dùng các công cụ mới.

```repo
- repo | mksglu/context-mode
- kind | Plugin
- desc | Plugin miễn phí chạy cục bộ, giữ kết quả công cụ ra khỏi context của AI lập trình nhờ sandbox và tìm kiếm SQLite; hỗ trợ Claude Code, Codex, Gemini CLI.
- stars | 34k
- lang | JavaScript
```

## Context Mode làm được gì

Mục này tóm các tính năng chính theo lợi ích thực tế, không chép lại README.

### Giữ kết quả công cụ ngoài context

Khi AI đọc một file lớn, chạy `git log` hay tải một trang tài liệu dài, kết quả thường chiếm rất nhiều chỗ. Plugin chạy các việc đó trong sandbox cục bộ và chỉ trả về phần AI cần. Phiên làm việc dài hơn trước khi đầy, và bạn tốn ít token hơn.

### Lưu toàn bộ vào chỉ mục tìm kiếm cục bộ

Kết quả đầy đủ không bị vứt. Nó nằm trong SQLite trên máy bạn, mỗi dự án một file `context.db` trong thư mục `~/.context-mode`. Khi cần, AI dùng `ctx_search` để đọc lại đúng đoạn cần, nên không mất thông tin.

### Bộ công cụ ctx

README nhắc đến ba công cụ chính mà agent dùng: `ctx_execute` (chạy code hoặc lệnh trong sandbox), `ctx_index` (đưa nội dung vào chỉ mục) và `ctx_search` (tìm trong chỉ mục). Ngoài ra còn `ctx_batch` và `ctx_stats` (báo cáo mức tiết kiệm).

### Thinking in Code

Thay vì đọc cả đống dữ liệu, AI viết một đoạn script ngắn để xử lý, và chỉ phần script in ra mới vào context. Ví dụ đếm bản ghi trong 5.000 dòng JSON chỉ cần trả về hai con số.

### Chạy cục bộ, hỗ trợ nhiều agent

Hook, sandbox và tìm kiếm đều chạy như tiến trình trên máy bạn. README cho biết sau khi cài, plugin vẫn chạy khi offline, vì dùng SQLite cục bộ và runtime của chính bạn. Plugin hỗ trợ 10 agent: Claude Code, Codex, Gemini CLI, Qwen Code, Pi, OpenCode, Copilot CLI, Kiro, VS Code (Copilot) và ZCode.

```note
Plugin miễn phí và chạy cục bộ. Context Mode Gateway là một dịch vụ riêng, chạy trên máy chủ, có tài khoản và gói đăng ký riêng. Bài này chỉ nói về plugin cục bộ, bạn không cần Gateway để dùng nó.
```

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

Theo tư liệu, bạn cần:

- **Node 24.15.0 trở lên.** Đây là yêu cầu `engines` trong package.json. Kiểm tra bằng `node -v`.
- **Một trong các agent được hỗ trợ**, đã cài sẵn và chạy được trên máy: Claude Code, Codex, Gemini CLI, Qwen Code, Pi, OpenCode, Copilot CLI, Kiro, VS Code (Copilot) hoặc ZCode.
- **Nếu dùng Windows: cài thêm Git for Windows.** Các công cụ shell của plugin chạy trong Git Bash, và lệnh kiểm tra (doctor) cũng xem bạn đã có nó chưa.

Tư liệu không nhắc đến API key riêng cho plugin, cũng không yêu cầu GPU. Bạn vẫn cần tài khoản hoặc quyền dùng agent mà bạn chọn, nhưng việc đó nằm ngoài repo này.

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

```steps
- Kiểm tra Node | Chạy node -v, cần 24.15.0 trở lên (Windows: cài thêm Git for Windows)
- Chọn agent | Mỗi agent có lệnh cài riêng, hoặc dùng đường npm chung cho mọi agent
- Chạy lệnh cài | Dán lệnh của agent bạn dùng vào terminal
- Khởi động lại agent | Đóng rồi mở lại để plugin được nạp
- Chạy /ctx-doctor | Xem từng mục báo PASS hoặc có lệnh sửa kèm theo
```

### Bước 1: Kiểm tra phiên bản Node

Mở terminal (Windows: PowerShell hoặc Git Bash) và chạy:

```bash
node -v
```

Nếu số hiện ra nhỏ hơn 24.15.0, bạn cần nâng Node trước. Đây là chỗ người mới hay vấp nhất.

### Bước 2: Cài theo agent bạn dùng

Mỗi agent một lệnh. Bạn chỉ chạy khối của agent mình đang dùng.

**Claude Code.** Lệnh đầu thêm kho plugin, lệnh sau cài plugin:

```sh
claude plugin marketplace add mksglu/context-mode
claude plugin install context-mode@context-mode
```

**Codex.** Ngoài hai lệnh plugin, README yêu cầu một bước chạy một lần để tin cậy hook của plugin:

```sh
codex plugin marketplace add mksglu/context-mode
codex plugin add context-mode@context-mode
# one-time step: trust the plugin hooks
npm i -g context-mode
context-mode setup --agents codex
```

**Gemini CLI:**

```sh
gemini extensions install https://github.com/mksglu/context-mode
```

**Qwen Code:**

```sh
qwen extensions install https://github.com/mksglu/context-mode:context-mode
```

**Pi:**

```sh
pi install npm:context-mode
```

**OpenCode:**

```sh
opencode plugin add context-mode
```

**Copilot CLI, Kiro, VS Code (Copilot):** cài gói npm toàn cục rồi chạy setup với tên agent tương ứng. Ví dụ Copilot CLI:

```sh
npm i -g context-mode
context-mode setup --agents copilot-cli
```

Với Kiro thay bằng `--agents kiro`, với VS Code thay bằng `--agents vscode`. ZCode có lệnh riêng:

```sh
zcode plugins marketplace add mksglu/context-mode
zcode plugins install context-mode@context-mode
```

Nếu agent của bạn không có lệnh riêng, hoặc bạn muốn một cách chung, README ghi đường npm này dùng được cho mọi agent:

```sh
npm i -g context-mode
context-mode setup
```

Lệnh `setup` hiển thị kế hoạch, lưu lại cấu hình cũ, rồi mới áp dụng. Nếu một bước dừng giữa chừng, nó khôi phục cấu hình đã lưu. Vì vậy chạy lại `setup` cũng chính là cách sửa lỗi cài.

### Bước 3: Khởi động lại agent

Đóng agent đang chạy rồi mở lại. Nếu không khởi động lại, plugin thường chưa được nạp và bạn sẽ tưởng cài hỏng.

### Bước 4: Chạy kiểm tra

Trong agent, gõ lệnh sau (xem phần kế tiếp để biết kết quả mong đợi):

```text
/ctx-doctor
```

### Cập nhật và gỡ cài đặt

Ví dụ với Claude Code:

```sh
# update
claude plugin update context-mode@context-mode
# check
claude plugin list
# remove
claude plugin marketplace remove context-mode
```

Nếu bạn cài theo đường npm, gỡ bằng:

```sh
context-mode setup --remove
npm rm -g context-mode
```

Các agent khác có lệnh cập nhật và gỡ riêng. Bạn xem trong phần Install của README hoặc trong hướng dẫn cài trên trang chủ dự án.

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

Sau khi khởi động lại agent, chạy `/ctx-doctor`. Theo README, mỗi mục kiểm tra sẽ in PASS, hoặc đưa ra một lệnh để sửa. Tất cả PASS tức là cài đã ổn.

Với Copilot CLI, Kiro hoặc VS Code, bạn cũng có thể kiểm tra từ terminal. Ví dụ:

```sh
context-mode doctor --agents copilot-cli
```

Để thấy tận mắt mức tiết kiệm, hãy dán một câu hỏi bất kỳ (xem phần dùng thật) rồi chạy skill thống kê. Lệnh khác nhau theo agent:

- Claude Code, Copilot CLI, VS Code: `/ctx-stats`
- Codex: `$ctx-stats`
- Pi: `/skill:ctx-stats`
- Gemini CLI, Kiro, OpenCode, Qwen Code, ZCode: gõ `Call ctx_stats and show me the report.`

Báo cáo mẫu trong README trông như sau (đoạn đầu):

```text
context-mode stats
────────────────────────────────────────────────────────────────────────────────

This session · 1 call · <1m active
  1015.5 KB became 3.7 KB: 1011.8 KB kept out (99.6%)
```

Bạn thấy dòng kiểu "X KB became Y KB" tức là plugin đang làm việc.

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

Bạn không phải gõ lệnh đặc biệt. Cứ yêu cầu agent như bình thường, hook sẽ tự chuyển việc nặng sang sandbox. Dưới đây là các tình huống bám theo ví dụ trong README.

### Đọc tài liệu web dài mà không đốt token

Bạn là lập trình viên mới học React và muốn xem ví dụ chính xác trong trang tài liệu rất dài. Dán vào agent:

```text
On https://react.dev/reference/react/useEffect, show me the example that connects to a chat server and cleans up, and list the rules for the dependency array.
```

Hook gửi việc tải trang sang sandbox, agent tìm trong trang đúng ví dụ và các quy tắc. README ghi kết quả thô khoảng 601.984 B, chỉ 20.860 B vào context, tiết kiệm 96,5%. Bạn nhận câu trả lời gọn mà vẫn còn chỗ cho phần còn lại của phiên.

### Phân tích file log

Bạn là nhân viên IT được giao đếm lần đăng nhập thất bại trong một file syslog. Thay vì dán cả file vào chat, bạn đưa đường dẫn hoặc URL của file:

```text
Here is a Linux syslog sample: https://raw.githubusercontent.com/logpai/loghub/master/Linux/Linux_2k.log. How many authentication failures does it contain, and which 3 remote hosts caused the most?
```

Agent đếm trong sandbox trên 1.999 dòng log và chỉ trả về con số cùng ba địa chỉ. README ghi 216.485 B thô còn 566 B vào context (tiết kiệm 99,7%).

> Agent không cần đọc cả núi dữ liệu, chỉ cần đọc câu trả lời.
>
> — Ông T

### Xử lý dữ liệu JSON lớn

Bạn làm báo cáo và cần số liệu nhanh từ một API trả về hàng nghìn bản ghi. Ví dụ trong README:

```text
Fetch https://jsonplaceholder.typicode.com/photos. Which photo has the longest title (give its id and title), and how many photos have a title that contains the word "est"?
```

Agent chạy code trên 5.000 bản ghi trong sandbox và trả về hai đáp án ngắn. README ghi 1.039.898 B thô còn 393 B vào context, tiết kiệm 99,96%. Đây là trường hợp tốt nhất trong bốn ví dụ vì câu trả lời chỉ là hai dữ kiện ngắn.

### Gỡ lỗi cả buổi với nhiều kết quả lớn

Bạn là dev đang debug: chạy test, xem log container, liệt kê issue và pull request bằng GitHub CLI. Mỗi lệnh thường xả hàng chục đến hàng trăm KB. Trong bảng đo của README, chạy 1.106 test bằng Vitest từ 62.909 B còn 429 B vào context, còn `gh issue list --json` cho 40 issue từ 182.943 B còn 850 B. Một buổi debug đầy đủ với 8 kết quả và 3 lần tìm kiếm đi từ 281.261 B xuống 3.266 B. Bạn làm việc như thường, và chỉ cần dùng `ctx_search` khi muốn đọc lại phần đã cất.

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

### Cài xong nhưng agent không thấy plugin

Thường là do chưa khởi động lại agent. Đóng hẳn và mở lại, rồi chạy `/ctx-doctor`. Nếu vẫn lỗi, chạy lại `context-mode setup`; README nói setup cũng chính là bước sửa chữa.

### Node quá cũ

Tư liệu yêu cầu Node từ 24.15.0. Nếu `node -v` ra số nhỏ hơn, lệnh cài hoặc setup có thể báo lỗi. Cách xử lý an toàn là nâng Node lên bản đủ mới rồi cài lại.

### Windows thiếu Git Bash

Trên Windows, các công cụ shell của plugin chạy trong Git Bash. Nếu `/ctx-doctor` báo lỗi mục này, hãy cài Git for Windows rồi chạy doctor lại.

### Codex chưa tin cậy hook

Với Codex, README có bước chạy một lần để tin cậy hook của plugin. Nếu bạn chỉ chạy hai lệnh `codex plugin ...` mà bỏ qua `npm i -g context-mode` và `context-mode setup --agents codex`, hook có thể chưa hoạt động. Hãy chạy đủ các lệnh rồi kiểm tra bằng `codex mcp list`.

### Lệnh agent không được nhận ra

Nếu terminal báo không tìm thấy `claude`, `codex`, `gemini`... thì agent chưa được cài hoặc chưa nằm trong PATH. Hãy cài và chạy thử agent trước, rồi mới cài plugin.

```note
Mỗi dự án có một file context.db trong ~/.context-mode, chứa nội dung file, log hoặc trang web mà agent đã xử lý. Nếu nội dung nhạy cảm (khoá, dữ liệu khách hàng), đừng gửi file này cho người khác và nên xoá khi không cần.
```

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

**Điểm mạnh.** Miễn phí, chạy cục bộ, không telemetry theo lời tác giả, hỗ trợ tới 10 agent và có số đo công khai (bảng use case, bench) mà bạn có thể tự chạy lại. Cài chỉ một hai dòng lệnh, và có `/ctx-doctor` để xác nhận. Nếu bạn hay để AI đọc file lớn, log dài, trang tài liệu dài, đây là loại plugin cho cảm nhận khác biệt ngay trong phiên đầu.

**Giới hạn.** Cần Node 24.15.0 trở lên, nên máy cũ có thể phải nâng Node trước. Trên Windows cần thêm Git for Windows. Các con số tiết kiệm trong README đo trên các tác vụ cụ thể bằng một mô hình thử nghiệm; công việc của bạn có thể ra tỷ lệ khác, nhất là khi câu trả lời cần dài. Nhóm tìm kiếm (retrieval) trong bảng bench cũng chỉ tiết kiệm trung vị khoảng 77,2%, thấp hơn nhóm sandbox. Phần giấy phép: README mô tả là source-available, nhưng tư liệu bài này không ghi rõ tên giấy phép, nên nếu dùng trong công ty, bạn nên đọc file LICENSE trong repo.

**Khi nào chọn cách khác.** Nếu bạn chỉ dùng AI để chat ngắn, không đọc file hay chạy lệnh lớn, plugin gần như không đem lại nhiều lợi ích. Nếu bạn muốn trí nhớ chia sẻ giữa nhiều phiên và nhiều công cụ, README nói đó là việc của Context Mode Gateway, một dịch vụ riêng có tài khoản và gói đăng ký, chứ không phải plugin cục bộ này.

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

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

Có. README nói plugin miễn phí mãi mãi, dùng được ở nhà và ở công ty, theo giấy phép source-available. Context Mode Gateway là dịch vụ khác, chạy trên máy chủ và có gói đăng ký riêng, bạn không cần nó để dùng plugin.

### Có cần GPU hay API key riêng không?

Tư liệu không yêu cầu GPU và cũng không nhắc đến API key riêng cho plugin. Bạn chỉ cần Node 24.15.0 trở lên và một agent được hỗ trợ đã cài sẵn. Quyền dùng bản thân agent là chuyện riêng của agent đó.

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

Có. README nói CI chạy setup, doctor, hook và kiểm tra MCP trên Linux, macOS và Windows. Trên Windows bạn cần cài thêm Git for Windows, vì các công cụ shell chạy trong Git Bash.

### Dữ liệu của tôi có được gửi đi đâu không?

Theo tác giả, plugin là zero telemetry và giữ mọi dữ liệu sử dụng trên máy bạn. Chỉ mục nằm trong thư mục ~/.context-mode, mỗi dự án một file context.db. README còn có mục Security and privacy liệt kê từng lệnh gọi mạng, nhưng phần đó nằm ngoài đoạn tư liệu mình đọc được.

### Hỗ trợ những agent nào?

10 agent: Claude Code, Codex, Gemini CLI, Qwen Code, Pi, OpenCode, Copilot CLI, Kiro, VS Code (Copilot) và ZCode. Mỗi agent có lệnh cài riêng, và đường npm (npm i -g context-mode rồi context-mode setup) dùng được cho mọi agent.

### Làm sao biết plugin thực sự tiết kiệm được bao nhiêu?

Chạy skill thống kê sau khi agent làm một việc. Với Claude Code là /ctx-stats, với Codex là $ctx-stats, còn các agent khác có lệnh riêng như trong README. Báo cáo cho thấy dung lượng trước và sau khi qua plugin.

### Nó khác gì việc tự cắt ngắn kết quả bằng tay?

Tư liệu mô tả plugin lưu toàn bộ kết quả vào chỉ mục SQLite cục bộ, nên AI vẫn tìm lại được phần bị bỏ qua bằng ctx_search. Cắt ngắn bằng tay thì phần cắt đi là mất. Tư liệu không so sánh trực tiếp với công cụ cụ thể nào khác.
