context-mode: giảm 99% dữ liệu vào context — hướng dẫn cài đặt và dùng

Tóm tắt nhanh
context-mode là plugin local cho các coding agent như Claude Code, Codex, Gemini CLI và Copilot CLI. Plugin giữ output đầy đủ trong SQLite trên máy, chỉ đưa phần cần thiết vào context nên README ghi nhận mức giảm trung vị 99,4%. Cài đặt chủ yếu qua npm hoặc lệnh riêng của từng agent, nhưng cần Node.js từ 24.15.0 và Git for Windows nếu dùng Windows.
context-mode là plugin local giúp coding agent xử lý file lớn, log dài, trang web và kết quả lệnh mà không đưa toàn bộ dữ liệu vào context window. Plugin chạy sandbox trên máy bạn, lưu dữ liệu vào SQLite FTS5 rồi cho agent tìm lại đúng phần cần dùng.
Repo này phù hợp với lập trình viên 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à dữ liệu không phải gửi về dịch vụ hosted của tác giả. README nói plugin không telemetry, chạy offline sau khi cài và giữ usage data trên máy. Repo hiện có khoảng 34.020 sao và 2.336 fork.
Khi agent đọc một file vài chục KB, chạy lệnh sinh ra hàng trăm KB log hoặc lấy một API response rất lớn, context-mode giữ phần lớn output bên ngoài context. Agent vẫn có thể tìm kiếm và lấy lại đoạn liên quan khi cần. README ghi nhận mức giảm trung vị 99,4% số byte của 36 mẫu có output từ 10 KB trở lên.
mksglu/context-mode
Plugin local giúp 10 coding agent xử lý output lớn mà không làm đầy context, với sandbox và tìm kiếm SQLite FTS5.
I.context-mode làm được gì
Giữ output lớn ngoài context window. Hook của plugin phát hiện output từ công cụ, sandbox hoặc lệnh chạy dài rồi thay phần output lớn bằng kết quả ngắn hơn. Agent không phải “cõng” cả log, toàn bộ HTML hay JSON dài trong mỗi lượt suy luận.
Chạy mã trong sandbox cục bộ. Thay vì yêu cầu agent đọc hết dữ liệu, plugin cho agent viết một đoạn script ngắn để lọc, đếm, nhóm hoặc tính toán. Chỉ phần script in ra mới đi vào context. Cách này hữu ích khi bạn cần một vài con số từ hàng nghìn bản ghi.
Lưu dữ liệu trong SQLite trên máy. Mỗi project có một cơ sở dữ liệu context riêng trong thư mục
~/.context-mode. Output đầy đủ vẫn được giữ lại để tìm kiếm, thay vì bị mất sau khi đã rút gọn.Tìm lại nội dung bằng tìm kiếm cục bộ. Agent có thể dùng
ctx_indexđể lập chỉ mục vàctx_searchđể lấy lại phần liên quan. Bạn có thể hỏi về một đoạn log hoặc một trang tài liệu mà không cần đưa cả nguồn vào cửa sổ context.Hỗ trợ nhiều coding agent. README có hướng dẫn riêng cho Claude Code, Codex, Gemini CLI, Qwen Code, Pi, OpenCode, Copilot CLI, Kiro, VS Code và ZCode. Mỗi agent có cách đăng ký plugin, hook và MCP khác nhau.
Có bộ công cụ MCP và skill đi kèm. Sau khi cài, agent có thể dùng
ctx_execute,ctx_index,ctx_search,ctx_batchvàctx_statstùy trường hợp. Các skill giúp kiểm tra kết quả và xem lượng dữ liệu đã được giữ ngoài context.Có lệnh doctor để kiểm tra cài đặt. Sau khi khởi động lại agent, bạn chạy
/ctx-doctortrong agent. Mỗi kiểm tra sẽ inPASShoặc đưa ra lệnh sửa tương ứng.Không cần dịch vụ hosted để dùng plugin. Context Mode plugin là phần local và miễn phí theo README. Context Mode Gateway là dịch vụ hosted riêng, có tài khoản và gói đăng ký riêng; hai phần này không nên nhầm với nhau.
II.Cần chuẩn bị gì
Bạn cần Node.js từ phiên bản 24.15.0 trở lên. Đây là yêu cầu được khai báo trong package.json. Plugin được cài dưới dạng gói npm có tên context-mode và cung cấp lệnh context-mode.
Nếu dùng Windows, README yêu cầu cài Git for Windows vì các shell tool chạy trong Git Bash và lệnh doctor sẽ kiểm tra thành phần này. Tư liệu được cung cấp không nêu yêu cầu GPU, API key, tài khoản bắt buộc hay cơ sở dữ liệu bên ngoài.
Bạn cũng cần cài sẵn ít nhất một coding agent được plugin hỗ trợ nếu muốn dùng plugin trong agent đó. Tên lệnh cài đặt phụ thuộc agent. README có các lệnh riêng cho từng agent và một đường npm dùng được cho mọi agent.
Plugin chạy local. README nói hook, sandbox và tìm kiếm chạy cạnh agent; dữ liệu index nằm trong ~/.context-mode, với một file context.db cho mỗi project. Plugin hoạt động offline sau khi cài, trong phạm vi sandbox, lập chỉ mục và tìm kiếm local.
Plugin local không đồng nghĩa mọi dữ liệu nguồn đều an toàn tuyệt đối. Agent vẫn có thể truy cập dữ liệu theo quyền của chính agent và các công cụ bạn bật. Hãy kiểm tra lệnh trước khi cho chạy trên mã nguồn riêng tư, log chứa thông tin nhạy cảm hoặc thư mục có quyền rộng.
III.Cài đặt từng bước
- Chọn cách càiDùng npm cho mọi agent hoặc lệnh riêng của agent
- Cài pluginĐăng ký context-mode vào coding agent
- Cấp quyền hookChạy setup nếu agent yêu cầu trust hook
- Khởi động lạiMở lại agent để nạp MCP, hook và skill
- Kiểm traChạy /ctx-doctor hoặc lệnh doctor tương ứng
A.Cài theo đường npm dùng cho mọi agent
Đây là cách ngắn nhất nếu bạn muốn dùng context-mode với agent mà README hỗ trợ nhưng chưa muốn chọn lệnh tích hợp riêng.
npm i -g context-mode
context-mode setupLệnh đầu tiên cài gói context-mode trên toàn máy và tạo lệnh context-mode. Lệnh thứ hai thiết lập plugin cho các agent mà công cụ nhận diện được. README nói setup cũng là cách sửa cấu hình: công cụ hiện kế hoạch, lưu cấu hình trước đó rồi áp dụng kế hoạch. Nếu một bước dừng sớm, cấu hình đã lưu sẽ được khôi phục.
Trên Windows, mở Git Bash sau khi đã cài Git for Windows. Nếu chạy từ PowerShell, hãy lưu ý README nói các shell tool của plugin chạy trong Git Bash. Người mới thường vấp ở chỗ cài Node.js nhưng terminal cũ chưa nhận PATH; khi đó hãy đóng rồi mở lại terminal trước khi chạy lệnh.
B.Cài cho Claude Code
Nếu bạn dùng Claude Code, README cung cấp cách cài qua marketplace của Claude Code:
claude plugin marketplace add mksglu/context-mode
claude plugin install context-mode@context-modeLệnh đầu thêm marketplace chứa plugin. Lệnh sau cài plugin từ nhánh phát hành context-mode. README xác nhận Claude Code nhận được hook, MCP và skill từ gói plugin.
Nếu cần cập nhật hoặc kiểm tra:
claude plugin update context-mode@context-mode
claude plugin listNếu muốn gỡ:
claude plugin marketplace remove context-modeC.Cài cho Codex
Với Codex, dùng các lệnh sau:
codex plugin marketplace add mksglu/context-mode
codex plugin add context-mode@context-mode
npm i -g context-mode
context-mode setup --agents codexHai lệnh đầu thêm marketplace và cài plugin. Hai lệnh sau cài gói npm rồi chạy setup cho Codex. README gọi đây là bước một lần để trust plugin hooks. Nếu Codex hỏi quyền hoặc chưa nhận hook, hãy chạy đúng bước context-mode setup --agents codex rồi khởi động lại Codex.
Kiểm tra MCP bằng:
codex mcp listCập nhật và gỡ bằng:
codex plugin marketplace upgrade context-mode
codex plugin remove context-mode@context-modeD.Cài cho Gemini CLI và Qwen Code
Gemini CLI dùng lệnh:
gemini extensions install https://github.com/mksglu/context-mode
gemini extensions update context-mode
GEMINI_CLI_TRUST_WORKSPACE=true gemini mcp list
gemini extensions uninstall context-modeLệnh đầu cài extension. Lệnh thứ hai cập nhật. Lệnh kiểm tra đặt biến GEMINI_CLI_TRUST_WORKSPACE=true trong chính lệnh rồi liệt kê MCP. Lệnh cuối gỡ extension.
Qwen Code dùng:
qwen extensions install https://github.com/mksglu/context-mode:context-mode
qwen extensions update context-mode
qwen extensions list
qwen extensions uninstall context-modeVới cả hai agent, hãy chạy các lệnh trong terminal nơi lệnh gemini hoặc qwen đã hoạt động trước đó. README không yêu cầu API key riêng cho context-mode.
E.Cài cho Pi, OpenCode, Copilot CLI, Kiro, VS Code và ZCode
Pi dùng:
pi install npm:context-mode
pi update --extensions
pi list
pi remove npm:context-modeOpenCode dùng:
opencode plugin add context-mode
opencode plugin update
opencode mcp list --pure
opencode mcp list --standalone
opencode plugin remove context-modeREADME ghi chú --pure dành cho OpenCode 1.19 và --standalone dành cho OpenCode 2. Bạn nên dùng đúng lệnh tương ứng với phiên bản OpenCode của mình.
Copilot CLI dùng:
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-cliKiro dùng:
npm i -g context-mode
context-mode setup --agents kiro
context-mode upgrade
context-mode doctor --agents kiro
context-mode setup --remove --agents kiroVS Code với Copilot dùng:
npm i -g context-mode
context-mode setup --agents vscode
context-mode upgrade
context-mode doctor --agents vscode
context-mode setup --remove --agents vscodeZCode dùng:
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-modeSau khi cài một trong các agent trên, hãy khởi động lại agent. README khuyên chạy /ctx-doctor trong agent sau khi khởi động lại. Nếu bạn cài bằng npm route cho nhiều agent, có thể dùng context-mode setup --agents <agent> để thiết lập riêng từng agent; chỉ dùng giá trị agent được README nêu như codex, copilot-cli, kiro hoặc vscode.
F.Gỡ cài đặt theo đường npm
Nếu bạn dùng cách cài chung, gỡ thiết lập rồi gỡ gói npm:
context-mode setup --remove
npm rm -g context-modeLệnh setup remove xóa cấu hình plugin khỏi agent. Lệnh npm xóa gói toàn cục. Nếu bạn chỉ muốn cập nhật, README có lệnh context-mode upgrade cho các agent dùng đường npm.
IV.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à mỗi mục in PASS, hoặc hiển thị một lệnh sửa nếu có vấn đề. Với Codex, bạn có thể xem MCP bằng codex mcp list. Với Copilot CLI, dùng cả context-mode doctor --agents copilot-cli và copilot mcp list.
Để kiểm tra chức năng thực tế, gửi một prompt có dữ liệu lớn cho agent. README đưa ví dụ lấy dữ liệu JSON, đếm bản ghi và chỉ trả về hai thông tin ngắn. Sau đó chạy skill thống kê của agent. Claude Code dùng /ctx-stats, Codex dùng $ctx-stats, Copilot CLI dùng /ctx-stats, Pi dùng /skill:ctx-stats; một số agent khác yêu cầu gọi ctx_stats.
Báo cáo thống kê có tiêu đề context-mode stats, số lượt gọi, dung lượng trước và sau, phần trăm byte được giữ ngoài context và số token ước tính. Nếu thấy các dòng như With context-mode nhỏ hơn nhiều so với Without context-mode, plugin đang hoạt động đúng.
V.Dùng vào việc thật
A.Chủ shop cần lọc dữ liệu đơn hàng lớn
Một chủ shop có thể đưa cho agent một file JSON chứa hàng nghìn đơn hàng rồi yêu cầu tìm tổng số đơn, nhóm theo trạng thái hoặc tìm đơn có giá trị cao nhất. Prompt nên nêu rõ trường cần trả về, chẳng hạn: “Đọc file đơn hàng này, tìm 10 đơn có tổng tiền cao nhất và chỉ trả về mã đơn, tổng tiền, trạng thái.”
Agent có thể xử lý dữ liệu trong sandbox và chỉ đưa bảng 10 dòng vào context. Bạn không cần dán toàn bộ file vào cuộc trò chuyện. Nếu kết quả chưa đủ, có thể hỏi tiếp để tìm lại dữ liệu đã index.
B.Nhân viên văn phòng cần đọc log hoặc báo cáo dài
Khi một hệ thống xuất ra log dài, bạn có thể yêu cầu: “Trong log này, đếm số lần đăng nhập thất bại và liệt kê ba máy gửi nhiều lỗi nhất.” Đây là kiểu công việc phù hợp với ctx_execute: agent viết mã ngắn để đếm và nhóm dữ liệu, thay vì đọc từng dòng.
Kết quả nhận được thường chỉ là các con số và tên máy cần thiết. README có ví dụ tương tự với một syslog gần 2.000 dòng, trong đó phần đưa vào context chỉ là kết quả đếm và nhóm ngắn.
C.Lập trình viên cần tra tài liệu web dài
Bạn có thể gửi prompt: “Trên trang tài liệu này, tìm ví dụ kết nối tới chat server và phần cleanup, sau đó liệt kê quy tắc của dependency array.” Plugin đưa WebFetch vào sandbox, lập chỉ mục trang rồi tìm đoạn phù hợp.
Cách này hữu ích khi trang tài liệu có hàng trăm KB nhưng bạn chỉ cần một ví dụ hoặc vài quy tắc. README ghi nhận với một trang tài liệu React, phần output đến context nhỏ hơn đáng kể so với nội dung thô.
D.Dev cần phân tích GitHub, test hoặc lint
Trong một project, bạn có thể yêu cầu agent liệt kê issue, pull request, chạy test verbose, lint cả thư mục hoặc xem log Git dài. Ví dụ: “Chạy test và chỉ cho tôi các test thất bại, kèm file và nguyên nhân đầu tiên.”
README có các benchmark cho gh issue list, gh pr list, Vitest, Biome, Docker logs, Terraform plan và git log --stat. Plugin giữ output đầy đủ trong index, còn context nhận phần agent cần để tổng hợp kết quả.
Khi dữ liệu lớn, hãy để agent tìm phần cần thiết thay vì bắt nó đọc tất cả.
Ông T
VI.Lỗi hay gặp và cách xử lý
A.Node.js thấp hơn yêu cầu
Nếu npm báo không tương thích engine hoặc lệnh context-mode không chạy, hãy kiểm tra phiên bản Node.js đang được terminal dùng. package.json yêu cầu Node.js từ 24.15.0. Sau khi nâng cấp Node.js, mở terminal mới rồi chạy lại lệnh cài.
B.Windows thiếu Git for Windows hoặc đang dùng sai shell
README nói shell tools chạy trong Git Bash trên Windows và doctor sẽ kiểm tra Git for Windows. Nếu setup hoặc doctor báo thiếu shell tool, cài Git for Windows rồi mở Git Bash. Tránh đoán thêm biến môi trường hoặc đường dẫn ngoài những gì công cụ hiển thị.
C.Plugin đã cài nhưng agent chưa thấy MCP
Hãy khởi động lại agent trước. Sau đó chạy lệnh kiểm tra tương ứng như codex mcp list, copilot mcp list, qwen extensions list hoặc /ctx-doctor. Với Codex, nếu chưa trust hook, chạy lại context-mode setup --agents codex.
D.Doctor không trả về PASS
Đọc đúng lệnh sửa mà doctor in ra rồi chạy lại kiểm tra. README nói setup lưu cấu hình trước và có thể khôi phục khi một bước dừng sớm, nên không nên tự tay xóa file cấu hình agent khi chưa biết file nào đang được dùng.
E.Kết quả thống kê khác ví dụ trong README
Kết quả phụ thuộc dữ liệu, agent, công cụ, phiên bản và prompt. Trang web, trang tin, log và API response có thể thay đổi. Các con số benchmark trong README là kết quả đo theo những mẫu cụ thể, không phải cam kết mọi lần chạy đều giảm đúng một tỷ lệ.
VII.Có nên dùng không
Bạn nên dùng nếu thường làm việc với output lớn, log, file dữ liệu, tài liệu web, GitHub issue hoặc kết quả test dài. Plugin có lợi rõ nhất khi context window bị đầy nhanh và agent bắt đầu quên yêu cầu trước đó. Việc chạy local, không telemetry và hỗ trợ nhiều agent cũng phù hợp với nhóm muốn giữ dữ liệu trong máy.
Điểm mạnh là cách cài tương đối rõ, có setup, doctor, MCP, skill thống kê và cơ chế lưu index theo project. README cũng có benchmark cho nhiều loại công việc thay vì chỉ đưa một ví dụ. Repo đang tiếp tục được cập nhật và hiện có khoảng 34.020 sao cùng 2.336 fork.
Giới hạn là bạn vẫn phải cài đúng Node.js, trên Windows cần Git for Windows, và mỗi agent có lệnh tích hợp khác nhau. Plugin không làm cho agent hiểu dữ liệu tốt hơn một cách tự động; prompt vẫn cần nói rõ muốn lọc, đếm hay tìm gì. Dữ liệu index nằm trên máy, nên bạn vẫn cần quản lý quyền truy cập và thông tin nhạy cảm.
README được cung cấp không ghi rõ giấy phép của repo. Vì vậy, nếu doanh nghiệp cần rà soát điều khoản pháp lý trước khi triển khai rộng, hãy kiểm tra trực tiếp file giấy phép và chính sách nội bộ trong repo. Nếu bạn chỉ cần tìm kiếm tài liệu nhỏ, output ngắn hoặc không dùng coding agent được hỗ trợ, cách đọc trực tiếp có thể đơn giản hơn.
Câu hỏi thường gặp
context-mode có miễn phí không?
README nói plugin local miễn phí lâu dài và source mở trên GitHub. Context Mode Gateway là dịch vụ hosted riêng, có tài khoản và gói đăng ký riêng; đó không phải điều kiện để dùng plugin local.
Có cần API key hoặc tài khoản riêng không?
Tư liệu được cung cấp không nêu API key hay tài khoản riêng cho context-mode. Bạn cần một coding agent được hỗ trợ và cài plugin theo đúng lệnh của agent đó.
Có cần GPU không?
README không nêu yêu cầu GPU. Plugin chạy các hook, sandbox, SQLite và tìm kiếm trên máy; tư liệu cũng không ghi yêu cầu phần cứng đặc biệt khác.
Có chạy được trên Windows không?
Có. README nói CI kiểm tra setup trên Windows và yêu cầu Git for Windows vì shell tools chạy trong Git Bash. Bạn cũng cần Node.js từ 24.15.0 trở lên.
Dữ liệu có được gửi lên máy chủ không?
README nói plugin local, lưu index trong `~/.context-mode` và zero telemetry. Tuy vậy, dữ liệu nguồn vẫn có thể được công cụ hoặc coding agent xử lý theo cấu hình của chính bạn; hãy kiểm tra quyền truy cập trước khi dùng với dữ liệu nhạy cảm.
Plugin hỗ trợ những coding agent nào?
README có hướng dẫn cho 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.
Tại sao kết quả của tôi không giảm đúng 99,4%?
99,4% là mức giảm trung vị trong benchmark của README với các mẫu output từ 10 KB trở lên. Kết quả thực tế phụ thuộc loại dữ liệu, công cụ, prompt và agent; output nhỏ hoặc yêu cầu trả về nhiều nội dung sẽ có mức giảm khác.


