# context-mode: giảm tải context cho coding agent — hướng dẫn cài đặt và dùng

> context-mode là plugin local cho 10 coding agent, giúp xử lý output lớn trong sandbox và SQLite thay vì đẩy toàn bộ vào context. Plugin miễn phí, không telemetry và chạy được offline sau khi cài. Cài khá đơn giản nếu bạn dùng Node.js từ 24.15.0 và chọn đúng lệnh cho agent.

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

context-mode là plugin local giúp coding agent xử lý output lớn mà không làm đầy context window. Thay vì đưa toàn bộ log, trang web, file hoặc kết quả lệnh vào agent, plugin giữ dữ liệu trong sandbox và lập chỉ mục bằng SQLite FTS5 trên máy của bạn.

Repo phù hợp với người dùng Claude Code, Codex, Gemini CLI, Qwen Code, Pi, OpenCode, Copilot CLI, Kiro, VS Code hoặc ZCode. Điểm đáng giá nhất là plugin không cần dịch vụ hosted để hoạt động, không gửi telemetry, và README công bố mức giảm trung vị khoảng 99,4% số byte output đi vào context trong các bài benchmark đủ điều kiện.

Repo hiện có khoảng 34.020 sao và 2.336 fork. Mã nguồn chính dùng JavaScript. README mô tả plugin là miễn phí vĩnh viễn và chạy local; tuy vậy, thông tin giấy phép của repo không được ghi rõ trong tư liệu được cung cấp.

```repo
- repo | mksglu/context-mode
- kind | Plugin
- desc | Plugin local giúp coding agent giữ output công cụ ngoài context, tìm lại bằng sandbox và SQLite FTS5.
- stars | 34k
- lang | JavaScript
```

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

### Giữ output lớn ngoài context

Khi agent đọc file lớn, chạy test, xem log, gọi API hoặc tải một trang web, output thường bị đưa thẳng vào context. context-mode giữ phần output đầy đủ trong chỉ mục local, sau đó chỉ trả lại phần agent cần. Bạn có thể làm việc với dữ liệu lớn mà ít nhanh chóng chạm giới hạn context hơn.

### Cho agent tìm lại dữ liệu bằng truy vấn

Plugin cung cấp các công cụ như `ctx_execute`, `ctx_index`, `ctx_search` và `ctx_stats`. Agent có thể chạy một đoạn script ngắn để lọc, đếm hoặc tìm dữ liệu, thay vì đọc toàn bộ kết quả. Cách này phù hợp với log, JSON, danh sách issue, tài liệu kỹ thuật và kết quả kiểm thử.

### Chạy sandbox ngay trên máy

Các hook, sandbox và thao tác tìm kiếm chạy dưới dạng tiến trình local cạnh coding agent. Sau khi cài, sandbox, lập chỉ mục file và tìm kiếm dùng SQLite local cùng runtime của bạn. README nói plugin có thể hoạt động offline sau khi cài.

### Lưu dữ liệu theo từng project

Chỉ mục được lưu trên máy tại `~/.context-mode`, với một file `context.db` cho mỗi project. Bạn có thể kiểm soát dữ liệu ở local thay vì phải đưa output qua một dịch vụ trung gian.

### Có hook, MCP và skill cho nhiều agent

Tùy agent, plugin tích hợp bằng package, hook file hoặc event handler bên trong plugin. README liệt kê 10 agent được hỗ trợ: Claude Code, Codex, Gemini CLI, Qwen Code, Pi, OpenCode, Copilot CLI, Kiro, VS Code và ZCode. Mỗi agent có lệnh cài, kiểm tra, cập nhật và gỡ riêng.

### Theo dõi mức tiết kiệm bằng thống kê

Sau khi chạy một prompt, bạn có thể gọi skill thống kê tương ứng với agent. Báo cáo cho biết bao nhiêu dữ liệu đã được giữ ngoài context. README đưa ví dụ một lần gọi làm giảm từ khoảng 1.015,5 KB xuống 3,7 KB trong phần đi vào context.

### Không thu thập telemetry

README nói mọi dữ liệu sử dụng được giữ trên máy và plugin không có telemetry. Tài liệu cũng có phần liệt kê các network call mà plugin thực hiện. Đây là điểm phù hợp khi bạn xử lý code nội bộ, log vận hành hoặc dữ liệu công việc cần kiểm soát đường đi.

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

- Node.js phiên bản `24.15.0` trở lên. Đây là yêu cầu trong trường `engines` của `package.json`.
- Một trong các coding agent được README hỗ trợ: Claude Code, Codex, Gemini CLI, Qwen Code, Pi, OpenCode, Copilot CLI, Kiro, VS Code hoặc ZCode.
- Kết nối mạng khi cài package, cài extension hoặc cài plugin từ GitHub. README nói sau khi cài, sandbox, lập chỉ mục và tìm kiếm có thể chạy offline.
- Trên Windows, cần cài Git for Windows. Shell tools của plugin chạy trong Git Bash và lệnh doctor sẽ kiểm tra điều này.
- Với lộ trình npm, cần có quyền cài package global và chạy lệnh `npm`.
- Không có yêu cầu API key riêng nào được README nêu cho plugin local. Các agent hoặc công cụ bạn gọi bên trong agent có thể có yêu cầu riêng, nhưng tư liệu này không mô tả chúng.

```note
Plugin local và Context Mode Gateway là hai sản phẩm khác nhau. Gateway là dịch vụ hosted có tài khoản và subscription riêng; các bước trong bài này chỉ cài plugin local.
Dữ liệu index nằm trong ~/.context-mode trên máy của bạn. Hãy cân nhắc quyền truy cập máy và dữ liệu project trước khi cho agent xử lý log hoặc mã nguồn nhạy cảm.
```

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

```steps
- Kiểm tra môi trường | Đảm bảo Node.js đủ phiên bản và Windows có Git for Windows nếu cần
- Chọn agent | Dùng đúng lệnh cài dành cho coding agent bạn đang sử dụng
- Cài plugin | Chạy lệnh trong terminal hoặc Git Bash
- Hoàn tất setup | Dùng npm route và context-mode setup nếu agent yêu cầu
- Khởi động lại và kiểm tra | Restart agent rồi chạy /ctx-doctor hoặc lệnh doctor tương ứng
```

### Kiểm tra Node.js và terminal

Mở terminal tại thư mục bạn thường dùng cho project. Nếu đang ở Windows, dùng Git Bash khi agent hoặc shell tools yêu cầu. Trước khi cài, kiểm tra Node.js bằng lệnh phổ thông sau:

```bash
node --version
```

Kết quả cần là phiên bản từ `24.15.0` trở lên. Nếu thấp hơn, hãy nâng Node.js trước. README không ghi lệnh nâng Node.js cụ thể nên không nên tự thêm một lệnh cài đặt phiên bản vào quy trình này.

Trên Windows, cài Git for Windows rồi mở Git Bash. README không ghi lệnh cài Git for Windows, nhưng nói rõ shell tools của plugin chạy trong Git Bash và doctor sẽ kiểm tra Git for Windows.

### Cài cho Claude Code

Trong terminal có Claude Code, chạy đúng hai lệnh sau:

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

Lệnh đầu thêm marketplace của repo. Lệnh thứ hai cài plugin từ release branch `context-mode`. Sau khi cài, README cho biết Claude Code có hooks, MCP và skills.

Để kiểm tra, cập nhật hoặc gỡ:

```bash
claude plugin update context-mode@context-mode
claude plugin list
claude plugin marketplace remove context-mode
```

Lệnh kiểm tra chỉ liệt kê plugin. Việc plugin xuất hiện trong danh sách chưa thay thế cho bước chạy doctor ở phần sau.

### Cài cho Codex

Chạy các lệnh sau trong terminal có Codex:

```bash
codex plugin marketplace add mksglu/context-mode
codex plugin add context-mode@context-mode
npm i -g context-mode
context-mode setup --agents codex
```

Hai lệnh đầu cài plugin từ marketplace. Hai lệnh sau là bước một lần để cài package npm và tin cậy hook của plugin cho Codex. `context-mode setup --agents codex` sẽ lập kế hoạch, lưu cấu hình trước đó rồi áp dụng thay đổi. README nói nếu một bước kết thúc sớm, setup sẽ khôi phục cấu hình đã lưu.

Kiểm tra, cập nhật hoặc gỡ bằng:

```bash
codex plugin marketplace upgrade context-mode
codex mcp list
codex plugin remove context-mode@context-mode
```

### Cài cho Gemini CLI hoặc Qwen Code

Với Gemini CLI:

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

Kiểm tra, cập nhật hoặc gỡ:

```bash
gemini extensions update context-mode
GEMINI_CLI_TRUST_WORKSPACE=true gemini mcp list
gemini extensions uninstall context-mode
```

Với Qwen Code:

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

Các lệnh quản lý là:

```bash
qwen extensions update context-mode
qwen extensions list
qwen extensions uninstall context-mode
```

Nếu lệnh kiểm tra của Gemini báo lỗi về workspace, README đã cung cấp biến `GEMINI_CLI_TRUST_WORKSPACE=true` trong chính lệnh kiểm tra. Không tự đổi tên extension khi gỡ vì lệnh gỡ phải dùng `context-mode`.

### Cài cho Pi, OpenCode hoặc ZCode

Với Pi:

```bash
pi install npm:context-mode
pi update --extensions
pi list
pi remove npm:context-mode
```

Bốn lệnh lần lượt cài, cập nhật, kiểm tra và gỡ extension. README cho biết Pi có hooks qua event handler riêng, MCP tích hợp trong plugin và skills.

Với OpenCode:

```bash
opencode plugin add context-mode
opencode plugin update
opencode mcp list --pure
opencode mcp list --standalone
opencode plugin remove context-mode
```

Dùng `--pure` cho OpenCode 1.19 và `--standalone` cho OpenCode 2, theo ghi chú trong README. Nếu bạn chưa biết phiên bản OpenCode của mình, không nên đoán cờ kiểm tra; hãy xem phiên bản agent trước.

Với ZCode:

```bash
zcode plugins marketplace add mksglu/context-mode
zcode plugins install context-mode@context-mode
zcode plugins update context-mode@context-mode
zcode plugins list
zcode plugins uninstall context-mode@context-mode
```

### Cài cho Copilot CLI, Kiro hoặc VS Code

README dùng npm route và lệnh setup cho ba trường hợp này.

Copilot CLI:

```bash
npm i -g context-mode
context-mode setup --agents copilot-cli
context-mode upgrade
context-mode doctor --agents copilot-cli
copilot mcp list
context-mode setup --remove --agents copilot-cli
```

Kiro:

```bash
npm i -g context-mode
context-mode setup --agents kiro
context-mode upgrade
context-mode doctor --agents kiro
context-mode setup --remove --agents kiro
```

VS Code với Copilot:

```bash
npm i -g context-mode
context-mode setup --agents vscode
context-mode upgrade
context-mode doctor --agents vscode
context-mode setup --remove --agents vscode
```

Với VS Code và Kiro, setup cài hook file cho agent. Lệnh `doctor` giúp kiểm tra hook. README không yêu cầu API key riêng cho context-mode.

### Dùng npm route cho agent chưa chọn riêng

README nói npm route hoạt động cho mọi agent:

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

Nếu muốn gỡ hoàn toàn:

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

Sau khi cài xong, khởi động lại coding agent. Trong agent, chạy:

```text
/ctx-doctor
```

Mỗi kiểm tra sẽ in `PASS` hoặc một lệnh sửa lỗi. Với agent không dùng cú pháp slash, hãy dùng lệnh doctor riêng đã nêu trong các block cài đặt ở trên.

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

Cách kiểm tra chung là khởi động lại agent rồi chạy `/ctx-doctor`. Kết quả mong đợi là các mục kiểm tra in `PASS`. Nếu có mục lỗi, output sẽ đưa ra lệnh sửa theo README.

Bạn cũng có thể kiểm tra thành phần MCP bằng lệnh phù hợp với agent, chẳng hạn `codex mcp list`, `copilot mcp list`, `qwen extensions list` hoặc `claude plugin list`. Các lệnh này xác nhận plugin hoặc MCP đã được agent nhận diện, nhưng chưa chứng minh toàn bộ hook đã chạy.

Cách kiểm tra thực tế là gửi một prompt có output lớn, sau đó gọi skill thống kê. Ví dụ với Claude Code dùng `/ctx-stats`; với Codex dùng `$ctx-stats`; với Copilot CLI dùng `/ctx-stats`; với Pi dùng `/skill:ctx-stats`. Báo cáo có dòng cho biết số byte ban đầu, số byte đi vào context và phần được giữ ngoài context.

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

### Nhân viên văn phòng cần lọc dữ liệu JSON lớn

Bạn có một endpoint trả về nhiều bản ghi và muốn biết bản ghi nào có tiêu đề dài nhất. Sau khi cài plugin, gửi prompt sau cho agent:

```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 sẽ chạy code trên 5.000 bản ghi trong sandbox rồi chỉ đưa hai kết luận ngắn vào context: id và title dài nhất, cùng số lượng title chứa từ cần tìm. Đây là dạng việc plugin xử lý tốt vì bạn cần kết quả tổng hợp, không cần đọc toàn bộ JSON.

### Dev cần đọc tài liệu kỹ thuật dài

Khi cần tìm một ví dụ cụ thể trong tài liệu React, bạn có thể dùng prompt:

```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 thao tác WebFetch vào sandbox. Agent tìm ví dụ và các quy tắc trong trang, sau đó trả lại phần liên quan. Bạn không phải dán toàn bộ trang tài liệu vào cuộc trò chuyện.

### DevOps cần phân tích log xác thực

Với một file syslog dài, hãy yêu cầu agent đếm lỗi và xếp hạng máy nguồn:

```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 sẽ đếm các dòng lỗi trong sandbox, rồi trả về số lần thất bại và ba remote host đứng đầu. Cách này hữu ích khi log có hàng nghìn dòng nhưng câu hỏi chỉ cần vài số liệu.

### Nhóm phát triển theo dõi issue và test

Khi làm việc với một repository, agent có thể xử lý danh sách issue, pull request, kết quả lint hoặc log test qua các tool hiện có. Bạn có thể yêu cầu agent tìm các issue đang mở theo điều kiện, tóm tắt các pull request có check lỗi, hoặc chạy test rồi chỉ báo các test thất bại.

README benchmark minh họa các loại output như `gh issue list --json`, `gh pr list --json`, Vitest, Biome, Docker logs, Terraform plan, `git log --stat` và npm install. Kết quả trả về là phần agent cần, còn output đầy đủ vẫn nằm trong index để `ctx_search` tìm lại.


> Khi dữ liệu lớn, hãy để agent tính toán trên dữ liệu và chỉ đưa kết luận cần thiết vào context.
>
> — Ông T

### Kiểm tra mức giảm context sau mỗi lần chạy

Sau một tác vụ, gọi skill thống kê của agent. Với Claude Code dùng `/ctx-stats`, Codex dùng `$ctx-stats`, Copilot CLI dùng `/ctx-stats`, còn Pi dùng `/skill:ctx-stats`. Gemini CLI, Kiro, OpenCode, Qwen Code, VS Code và ZCode có thể yêu cầu agent gọi `ctx_stats` và hiển thị báo cáo.

Báo cáo cho biết tổng output đã trở thành bao nhiêu byte trong context, bao nhiêu byte được giữ ngoài, và ước lượng số token tương ứng. Đây là cách thực tế để biết plugin đang có ích trong project của bạn thay vì chỉ dựa vào con số benchmark.

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

### Node.js thấp hơn yêu cầu

Nếu cài package thất bại hoặc doctor một trang tin tức trường không phù hợp, kiểm tra phiên bản Node. `package.json` yêu cầu Node `24.15.0` trở lên. Hãy nâng Node rồi chạy lại đúng lệnh cài; README không cung cấp cách nâng Node cụ thể.

### Windows không có Git for Windows hoặc đang dùng sai shell

README nói shell tools chạy trong Git Bash trên Windows. Nếu hook hoặc doctor không chạy, cài Git for Windows và mở Git Bash trước khi thử lại. Không tự đổi sang một shell khác nếu chưa xác định agent hỗ trợ shell đó.

### Plugin đã cài nhưng agent chưa nhận hook

Trước tiên khởi động lại agent. Sau đó chạy `/ctx-doctor` hoặc `context-mode doctor --agents...` theo agent. Với Codex, bước `context-mode setup --agents codex` là bước một lần để tin cậy hook; thiếu bước này có thể khiến plugin chưa hoạt động đầy đủ.

### Dùng sai lệnh kiểm tra theo phiên bản agent

OpenCode có hai lệnh kiểm tra khác nhau: `opencode mcp list --pure` cho OpenCode 1.19 và `opencode mcp list --standalone` cho OpenCode 2. Gemini cũng cần biến `GEMINI_CLI_TRUST_WORKSPACE=true` trong lệnh kiểm tra theo README. Hãy dùng đúng block của agent thay vì trộn lệnh giữa các agent.

### Muốn gỡ nhưng vẫn còn cấu hình hook

Dùng lệnh gỡ đúng agent. Với npm route chung, chạy `context-mode setup --remove` trước rồi mới chạy `npm rm -g context-mode`. Với Copilot CLI, Kiro và VS Code, dùng `context-mode setup --remove --agents...` để xóa cấu hình agent tương ứng.

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

Bạn nên dùng context-mode nếu thường xuyên giao cho coding agent đọc file lớn, phân tích log, chạy test, gọi API, xem tài liệu web hoặc xử lý danh sách issue. Plugin miễn phí, chạy local, không telemetry, hỗ trợ nhiều agent và có công cụ thống kê để kiểm chứng hiệu quả. Với người làm văn phòng hoặc chủ shop có dữ liệu JSON, log bán hàng hay tài liệu dài, lợi ích chính là hỏi dữ liệu mà không phải dán toàn bộ dữ liệu vào cuộc trò chuyện.

Giới hạn là plugin cần Node.js khá mới, và trên Windows cần Git for Windows cùng Git Bash. Việc cài đặt cũng phụ thuộc agent: mỗi agent có cú pháp marketplace, extension hoặc setup riêng. README chưa cung cấp đầy đủ hướng dẫn cho mọi môi trường ngoài các agent được liệt kê.

Bạn cũng cần phân biệt plugin local với Context Mode Gateway. Gateway là dịch vụ hosted riêng có tài khoản và subscription, không phải điều kiện để dùng plugin trong bài này. Nếu tổ chức không cho phép agent chạy hook local, hoặc bạn cần chính sách quản trị tập trung, audit doanh nghiệp hay chia sẻ memory giữa nhiều phiên, tư liệu hiện có chưa đủ để kết luận context-mode đáp ứng được. Khi đó nên đánh giá giải pháp quản trị khác theo yêu cầu bảo mật của tổ chức.

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

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

README nói plugin local miễn phí vĩnh viễn và dùng được ở nhà lẫn nơi làm việc. Context Mode Gateway là dịch vụ hosted riêng, có tài khoản và subscription riêng, không phải plugin local.

### Có cần GPU hoặc API key không?

Tư liệu không nêu yêu cầu GPU hay API key riêng cho context-mode. Plugin chạy local bằng sandbox, SQLite và runtime của máy; agent hoặc công cụ bên trong agent có thể có yêu cầu riêng nhưng README này không nói.

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

Có. README nói CI kiểm tra trên Windows và yêu cầu Windows cài Git for Windows vì shell tools chạy trong Git Bash. Doctor cũng kiểm tra điều kiện này.

### Dữ liệu của tôi có được gửi lên máy chủ không?

README nói plugin không có telemetry và dữ liệu sử dụng được giữ trên máy. Index nằm trong `~/.context-mode`, mỗi project có một `context.db`; tài liệu cũng liệt kê các network call mà plugin thực hiện.

### Plugin hỗ trợ những coding agent nào?

README liệt kê Claude Code, Codex, Gemini CLI, Qwen Code, Pi, OpenCode, Copilot CLI, Kiro, VS Code và ZCode. Mỗi agent có lệnh cài và kiểm tra riêng.

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

`package.json` yêu cầu Node.js `24.15.0` trở lên. README không cung cấp lệnh cài hoặc nâng Node cụ thể.

### context-mode khác gì Context Mode Gateway?

Plugin context-mode là phần local, xử lý output công cụ trong sandbox và SQLite trên máy. Gateway là dịch vụ hosted riêng, mở rộng ý tưởng này cho toàn bộ cuộc trò chuyện với các tính năng như Recall và Memory; hai phần có tài khoản và mô hình sử dụng riêng.
