context-mode: giữ output công cụ ngoài ngữ cảnh agent — hướng dẫn cài đặt và dùng
Bài này là một góc nhìn khác về mksglu/context-mode — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: 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 cục bộ, miễn phí, cho các coding agent như Claude Code, Codex, Gemini CLI, Copilot CLI. Plugin chạy lệnh trong sandbox, lưu toàn bộ kết quả vào SQLite trên máy bạn và chỉ đưa cho agent phần agent hỏi. Cài không khó: cần Node 24.15.0 trở lên và vài dòng lệnh theo từng agent.
Context Mode là một plugin miễn phí, chạy ngay trên máy bạn, dành cho các coding agent như Claude Code, Codex, Gemini CLI, Copilot CLI và vài agent khác. Việc nó làm là giữ phần output dài (nội dung file, kết quả lệnh, trang web) ra khỏi cửa sổ ngữ cảnh của agent. Agent vẫn làm được việc, nhưng không phải "đọc" cả đống chữ thô.
Vấn đề này ai dùng agent lập trình cũng gặp. Agent đọc một file lớn, chạy một lệnh in ra hàng nghìn dòng, hoặc tải một trang tài liệu dài. Tất cả đều nhét vào ngữ cảnh. Ngữ cảnh đầy nhanh, tốn token, và agent dễ quên mất đoạn đầu cuộc trò chuyện. Context Mode chạy phần việc nặng đó trong một sandbox cục bộ, lưu bản đầy đủ vào chỉ mục SQLite, rồi chỉ trả về phần agent cần.
Bạn nên đọc bài này nếu bạn dùng agent lập trình hằng ngày và thấy phiên làm việc dài hay bị "đầy". Điểm đáng giá nhất: README ghi chỉ mục nằm trong thư mục ~/.context-mode trên máy bạn, plugin không gửi số liệu sử dụng đi đâu (zero telemetry), và dùng được offline sau khi cài. Repo hiện có khoảng 34 nghìn sao (33.999) và 2.334 fork.
mksglu/context-mode
Plugin miễn phí chạy trên máy bạn, chặn output công cụ dài khỏi cửa sổ ngữ cảnh của coding agent để agent đỡ tốn token và ít bị loãng.
I.Context Mode làm được gì
A.Chạy việc nặng trong sandbox
Khi agent cần đọc một file lớn hoặc chạy lệnh dài, hook của plugin chuyển việc đó sang sandbox (công cụ ctx_execute). Agent không đọc cả file. Nó chạy một đoạn mã ngắn trên dữ liệu, và chỉ kết quả in ra mới đi vào ngữ cảnh. README gọi cách này là "Thinking in Code". Lợi ích thực tế: hỏi "có bao nhiêu dòng lỗi" thì agent nhận về một con số, không phải một nghìn dòng log.
B.Lập chỉ mục và tìm lại khi cần
Toàn bộ output đầy đủ vẫn được giữ trong SQLite trên máy bạn. Agent dùng ctx_index để lưu và ctx_search để tìm lại. Nghĩa là không mất dữ liệu: nếu agent cần chi tiết mà lần đầu chưa lấy, nó tìm lại được, không phải chạy lại lệnh.
C.Chặn ngay từ các công cụ quen thuộc
Hook xử lý nhiều loại đầu vào: đọc file, WebFetch, lệnh Bash như curl hay git log, và cả output của công cụ khác khi vượt ngưỡng. Bạn không phải đổi thói quen. Cứ nhờ agent như bình thường.
D.Số liệu đo được
Trong bảng bench của README, những dòng có output thô từ 10 KB trở lên cho kết quả trung vị nhỏ hơn khoảng 99,4%. Ví dụ đọc một trang snapshot trình duyệt 136.514 B còn 463 B vào ngữ cảnh, liệt kê 40 issue bằng gh issue list --json từ 182.943 B còn 850 B. Đây là số đo của tác giả trên máy của họ, bạn đừng coi là cam kết cho mọi trường hợp.
E.Chạy với nhiều agent
README liệt kê 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, bên dưới mình ghi đủ.
F.Có sẵn lệnh xem mức tiết kiệm
Plugin có skill thống kê (ctx_stats), cho bạn thấy đã giữ bao nhiêu KB ra khỏi ngữ cảnh. Rất tiện để tự kiểm chứng, khỏi phải tin lời quảng cáo.
II.Cần chuẩn bị gì
Theo README và package.json, bạn cần:
- Node 24.15.0 trở lên. Đây là yêu cầu trong trường
enginescủapackage.json. Kiểm tra bằngnode --version. - Một coding agent đã cài sẵn trong danh sách ở trên (ví dụ Claude Code).
- Trên Windows: Git for Windows. README nói các công cụ shell chạy trong Git Bash, và lệnh doctor có kiểm tra điều này.
- npm, nếu bạn cài theo đường npm (thường đi kèm Node).
Tư liệu không nói plugin cần API key riêng hay GPU. Plugin chạy bằng SQLite và runtime có sẵn trên máy bạn. Bản thân agent bạn dùng thì vẫn cần tài khoản của nó như bình thường.
Plugin Context Mode miễn phí và chạy cục bộ. Còn "Context Mode Gateway" là dịch vụ riêng, có tài khoản và gói đăng ký riêng. Bài này chỉ nói về plugin. Đừng nhầm hai thứ khi thấy chữ "Gateway" trong tài liệu.
III.Cài đặt từng bước
- Kiểm tra NodeChạy node --version, cần 24.15.0 trở lên
- Chọn agent của bạnMỗi agent có lệnh cài riêng trong README
- Chạy lệnh càiDán lệnh tương ứng vào terminal
- Khởi động lại agentĐóng và mở lại để plugin nạp hook
- Chạy /ctx-doctorXem các mục kiểm tra báo PASS
A.Kiểm tra phiên bản Node
Mở terminal (PowerShell hoặc Git Bash trên Windows, Terminal trên macOS/Linux) và chạy:
node --versionNếu số hiện ra nhỏ hơn 24.15.0, bạn cần cập nhật Node trước. Đây là chỗ người mới hay vấp nhất: cài xong mà plugin không chạy vì Node quá cũ. Trên Windows, nhớ cài thêm Git for Windows.
B.Cài theo agent của bạn
Mỗi agent dùng một lệnh khác nhau. Dưới đây là các lệnh nguyên văn từ README. Bạn chỉ cần chạy khối của agent mình dùng.
Claude Code. Lệnh đầu thêm "kho" plugin, lệnh sau cài plugin:
claude plugin marketplace add mksglu/context-mode
claude plugin install context-mode@context-modeCodex. Ngoài hai lệnh plugin còn một bước một lần để tin cậy hook của plugin:
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 codexGemini CLI:
gemini extensions install https://github.com/mksglu/context-modeQwen Code:
qwen extensions install https://github.com/mksglu/context-mode:context-modePi:
pi install npm:context-modeOpenCode:
opencode plugin add context-modeCopilot CLI:
npm i -g context-mode
context-mode setup --agents copilot-cliKiro:
npm i -g context-mode
context-mode setup --agents kiroVS Code (Copilot):
npm i -g context-mode
context-mode setup --agents vscodeZCode:
zcode plugins marketplace add mksglu/context-mode
zcode plugins install context-mode@context-modeVới các lệnh npm i -g context-mode: cờ -g nghĩa là cài toàn cục, nên lệnh context-mode dùng được ở mọi thư mục. Lệnh context-mode setup --agents ... sau đó ghi cấu hình vào agent tương ứng.
C.Hoặc dùng đường npm chung
README ghi đường npm dùng được cho mọi agent:
npm i -g context-mode
context-mode setupREADME mô tả setup cũng là công cụ sửa lỗi: nó hiện kế hoạch, lưu cấu hình cũ, rồi mới áp dụng. Nếu giữa chừng bị dừng, nó khôi phục lại cấu hình đã lưu. Nghe yên tâm hơn nhiều so với việc tự sửa file cấu hình bằng tay.
D.Khởi động lại agent
Đóng agent rồi mở lại. Nếu không khởi động lại, hook chưa được nạp và bạn sẽ không thấy tác dụng gì.
E.Gỡ cài đặt (khi cần)
Với Claude Code:
claude plugin marketplace remove context-modeVới đường npm chung:
context-mode setup --remove
npm rm -g context-modeMuốn cập nhật thì mỗi agent có lệnh riêng. Ví dụ Claude Code dùng claude plugin update context-mode@context-mode; các agent cài qua npm dùng context-mode upgrade.
IV.Kiểm tra đã chạy được chưa
Sau khi khởi động lại agent, chạy lệnh sau ngay trong agent:
/ctx-doctorTheo README, mỗi mục kiểm tra sẽ in ra PASS, hoặc in ra một lệnh sửa lỗi cho bạn chạy. Thấy toàn PASS là xong.
Với các agent cài qua npm, bạn còn kiểm tra được từ terminal, ví dụ:
context-mode doctor --agents copilot-cliVới Claude Code, claude plugin list cho biết plugin đã được cài chưa. Với Codex là codex mcp list, với Gemini CLI là GEMINI_CLI_TRUST_WORKSPACE=true gemini mcp list.
Bước thứ hai là xem số liệu tiết kiệm. Sau khi agent làm xong một việc, chạy lệnh thống kê. Trong Claude Code, Copilot CLI và VS Code (Copilot) là /ctx-stats. Codex dùng $ctx-stats, Pi dùng /skill:ctx-stats. Các agent còn lại, bạn gõ: Call ctx_stats and show me the report. README cho ví dụ báo cáo kiểu "1015.5 KB became 3.7 KB", tức là hơn 1 MB output thô chỉ còn vài KB vào ngữ cảnh.
V.Dùng vào việc thật
Plugin không có giao diện riêng. Bạn nói chuyện với agent như thường, hook tự lo phần còn lại. Dưới đây là các tình huống bám theo ví dụ README.
A.Dev đọc tài liệu thư viện dài
Bạn đang viết React và cần xem cách useEffect dọn dẹp kết nối. Trang tài liệu rất dài. Bạn nhờ agent:
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 WebFetch vào sandbox, agent tìm trong trang đúng ví dụ và các quy tắc. README ghi lần chạy này có 601.984 B thô, chỉ 20.860 B vào ngữ cảnh. Bạn nhận được đúng đoạn cần, ngữ cảnh vẫn còn rộng cho việc code.
B.Phân tích file log lớn
Bạn là người vận hành một hệ thống nhỏ, có file syslog gần 2.000 dòng. Bạn không muốn đổ cả file cho agent. Bạn hỏi:
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 rồi chỉ trả lời hai điều bạn hỏi. README ghi 216.485 B thô, 566 B vào ngữ cảnh.
Agent không cần đọc cả đống dữ liệu, nó chỉ cần viết đoạn mã đủ để trả lời câu bạn hỏi.
Ông T
C.Thống kê dữ liệu JSON
Bạn làm việc với API trả về hàng nghìn bản ghi. Thay vì dán cả JSON vào khung chat, bạn nhờ:
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 mã trên 5.000 bản ghi trong sandbox và trả về hai đáp án ngắn. README ghi 1.039.898 B thô, 393 B vào ngữ cảnh. Đây là trường hợp tốt nhất trong các ví dụ vì đáp án chỉ là vài dòng.
D.Phiên debug dài với nhiều lệnh
Bạn debug cả buổi: chạy test, đọc git log, xem log container. Bình thường ngữ cảnh sẽ đầy sau vài vòng. Với plugin, các lệnh như git log --stat, docker logs, vitest run --reporter=verbose được xử lý trong sandbox. README đo một phiên gồm 8 output và 3 lần tìm kiếm: 281.261 B thô, 3.266 B vào ngữ cảnh. Bạn làm việc được lâu hơn trong cùng một phiên, và có thể gõ /ctx-stats để xem mình đã tiết kiệm bao nhiêu.
VI.Lỗi hay gặp và cách xử lý
A.Cài xong nhưng plugin không hoạt động
Nguyên nhân hay gặp nhất là chưa khởi động lại agent, hoặc Node thấp hơn 24.15.0. Hãy chạy node --version, nâng Node nếu cần, khởi động lại agent rồi chạy /ctx-doctor. Mục nào không PASS sẽ kèm lệnh sửa, bạn làm theo.
B.Trên Windows báo thiếu shell
README nói các công cụ shell chạy trong Git Bash và doctor có kiểm tra. Nếu doctor báo lỗi ở mục này, hãy cài Git for Windows, mở lại terminal rồi chạy lại doctor.
C.Lệnh context-mode không được nhận ra
Bạn đã chạy npm i -g context-mode mà terminal báo không tìm thấy lệnh? Thường là terminal chưa nạp lại đường dẫn sau khi cài. Đóng terminal, mở cái mới và thử lại. Nếu vẫn không được, tư liệu chưa nói thêm. Bạn xem Install guide và Doctor guide trên trang dự án.
D.Codex chưa cho hook chạy
Với Codex, README có một bước "trust the plugin hooks" làm một lần: chạy npm i -g context-mode rồi context-mode setup --agents codex. Nếu bạn chỉ chạy hai lệnh codex plugin ... mà bỏ bước này thì hook có thể chưa hoạt động.
E.Không rõ plugin có đang giúp gì không
Đôi khi bạn hỏi một câu nhỏ, output vốn đã ngắn nên khó thấy khác biệt. Hãy làm một việc có output lớn (đọc file dài, tải trang web) rồi chạy /ctx-stats để xem số liệu thật. README cũng thừa nhận có dòng bench chỉ 6.917 B (Context7) thì mức giảm thấp hơn hẳn.
VII.Có nên dùng không
Điểm mạnh. Plugin miễn phí, chạy cục bộ, README ghi zero telemetry và dữ liệu nằm trong ~/.context-mode. Hỗ trợ tới 10 agent, và README nói CI kiểm tra cài đặt, doctor, hook và kết nối MCP cho cả 10 agent trên Linux, macOS và Windows. Có lệnh thống kê để tự kiểm chứng. Repo vẫn được cập nhật trong vài tháng gần đây.
Giới hạn. Yêu cầu Node khá mới (24.15.0 trở lên). Mỗi agent một cách cài, người mới dễ chọn nhầm khối lệnh. Các con số tiết kiệm đến từ bench của chính tác giả trên một máy cụ thể, kết quả của bạn sẽ khác tùy việc. Phần giấy phép: README nói "source-available", nhưng tư liệu mình có không ghi rõ loại giấy phép, nên nếu dùng ở công ty hãy tự đọc file LICENSE trong repo.
Khi nào chọn cách khác. Nếu bạn chỉ chat ngắn với agent, ít khi đọc file lớn hay chạy lệnh dài, plugin này mang lại ít giá trị. Nếu bạn cần chia sẻ "trí nhớ" giữa nhiều phiên và nhiều công cụ, đó là việc của Context Mode Gateway, một dịch vụ riêng có đăng ký. Plugin được nói ở bài này không làm việc đó.
Nói chung, nếu bạn dùng agent lập trình mỗi ngày và hay bị đầy ngữ cảnh, đây là plugin đáng thử: cài vài phút, gỡ cũng dễ, và bạn tự đo được hiệu quả ngay trên máy mình.
Câu hỏi thường gặp
context-mode có miễn phí không?
Có. README ghi plugin miễn phí mãi mãi, dùng được ở nhà lẫn ở chỗ làm. Riêng Context Mode Gateway là dịch vụ khác, có tài khoản và gói đăng ký riêng, không nằm trong plugin này.
context-mode chạy được trên Windows không?
Có. README nói CI chạy kiểm tra trên Linux, macOS và Windows. Trên Windows bạn cần thêm Git for Windows vì các công cụ shell chạy trong Git Bash, và lệnh doctor sẽ kiểm tra điều này.
Cần cài phiên bản Node nào?
package.json yêu cầu Node 24.15.0 trở lên. Bạn kiểm tra bằng lệnh node --version trước khi cài.
Dữ liệu của tôi có được gửi đi đâu không?
Theo README, plugin giữ toàn bộ dữ liệu sử dụng trên máy bạn, mỗi dự án có một file context.db trong thư mục ~/.context-mode, và không có telemetry. README cũng 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ó, bạn nên đọc trực tiếp trong repo.
Những agent nào dùng được?
README liệt kê 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, ngoài ra có đường npm chung là npm i -g context-mode rồi context-mode setup.
Làm sao biết plugin đã cài thành công?
Khởi động lại agent rồi chạy /ctx-doctor. Mỗi mục kiểm tra sẽ in PASS hoặc một lệnh sửa lỗi. Sau đó bạn có thể chạy lệnh thống kê như /ctx-stats (Claude Code) để xem đã giữ bao nhiêu KB ra khỏi ngữ cảnh.
Cần GPU hoặc API key riêng không?
Tư liệu không nhắc tới GPU hay API key riêng cho plugin. README nói sandbox, lập chỉ mục và tìm kiếm chạy bằng SQLite cục bộ và các runtime có sẵn trên máy bạn.


