Mod của Claude Code: chúng là gì, và mod chúng tôi cài sẵn cho mọi agent

Ngày 1 tháng 10 năm 2026, Claude Code 2.1.287 ra mắt với một dòng changelog duy nhất: "Added Claude Mods". Bốn ngày sau, AgentsRoom bắt đầu nạp một mod của chúng tôi vào các agent Claude mà nó chạy.

Bài viết này giải thích mod là gì, nó làm được gì mà các điểm mở rộng cũ không làm được, cách viết, nạp và kiểm thử một mod, và những gì chúng tôi rút ra khi đưa một mod vào mọi agent Claude mà AgentsRoom khởi động. Các thông tin về Claude Code lấy từ tài liệu và changelog của nó, đọc ngày 9 tháng 11 năm 2026, với Claude Code 2.1.318 đã cài.

Câu trả lời ngắn. Mod là một plugin Claude Code có một hooks module: một tệp JavaScript hoặc TypeScript mà Claude Code gọi các hàm của nó từ bên trong tiến trình của chính mình khi một sự kiện xảy ra. Một hàm có thể để sự kiện đi qua, thay đổi nó, hoặc trả lời nó thay cho Claude Code. Đó là cách một mod vẽ một bảng, thêm một lệnh, hoặc chặn một lệnh shell trước khi nó chạy.

Mod là gì

Claude Code vốn đã có plugin: một thư mục với tệp manifest ở .claude-plugin/plugin.json, gói các skill, subagent, hook settings và máy chủ MCP lại để chúng được cài như một khối. Mod là thêm một thứ nữa mà plugin có thể chứa. Khi tệp hooks/hooks.json của plugin chỉ định một tệp mã dưới khóa modules, Claude Code nạp tệp đó và gọi hàm register mà tệp đó export. Lúc này plugin được gọi là một mod.

Bên trong register, mỗi lời gọi on(event, hook) gắn một hàm vào một sự kiện: tool.call trước khi một công cụ chạy, prompt.submit khi bạn gửi một prompt, session.start, command.run cho một lệnh slash, ui.render khi Claude Code vẽ một phần màn hình của nó, và nhiều sự kiện khác. Mỗi hook nhận ba thứ:

• $, API của mod: mọi thứ một mod có thể làm bên ngoài mã của chính nó, như $.ui, $.command, $.fs, $.process hoặc $.http.
• e, sự kiện, dưới dạng dữ liệu thuần: với một lần gọi công cụ, đó là tên công cụ và các đối số của nó.
• next, chuyển sự kiện tiếp cho các mod khác rồi tới hành vi của chính Claude Code, và trả về kết quả.

Việc hook làm gì với next quyết định chuyện gì xảy ra. Trả về next(e) nghĩa là bạn chỉ quan sát. Gọi next với một bản sao đã sửa của e nghĩa là bạn đã viết lại sự kiện. Trả về kết quả của riêng bạn mà không gọi next nghĩa là bạn đã trả lời nó: công cụ không bao giờ chạy, hoặc Claude Code không bao giờ tự vẽ phần đó.

Tài liệu cũng gọi các hàm này là hook. Chúng không phải là các hook bạn viết trong settings.json, thứ mà giờ đây Claude Code gọi là settings hooks.

Mod, hook settings, skill hay máy chủ MCP

Bốn thứ này chồng lấn nhau, và mod là thứ nặng nhất. Hãy chọn thứ nhẹ nhất làm được việc.

Một plugin có thể chứa cả bốn, nên một mod có thể đi kèm ngay cạnh skill và máy chủ MCP mà nó làm việc cùng.

Ba tệp của một mod

my-mod/
├── .claude-plugin/
│   └── plugin.json
└── hooks/
    ├── hooks.json
    └── register.ts

plugin.json là manifest plugin quen thuộc: một cái tên, một phiên bản, một mô tả. hooks.json trỏ tới mã, { "modules": ["./register.ts"] }, một đường dẫn duy nhất, tương đối so với tệp đó. register.ts là hooks module. Claude Code nạp trực tiếp .js và .ts, không cần bundler và không có bước build, và import trần duy nhất được phép là claude-code, dành cho kiểu dữ liệu và vài tiện ích.

Mod chúng tôi cài sẵn: ai đã sửa tệp này?

AgentsRoom chạy nhiều agent viết code trên cùng một repository và cho thấy, trong tab Thay đổi của nó, agent nào đã sửa tệp nào, để bạn có thể rà soát và commit công việc của từng agent riêng rẽ. Các tệp được ghi bằng công cụ Edit và Write của Claude thì dễ: Claude Code báo cáo chúng qua một hook settings. Các tệp được ghi bởi một lệnh shell thì không. Một sed -i, một heredoc, một codemod hay một rm không bao giờ đi qua công cụ tệp.

Trước khi có mod, chúng tôi phải đoán. AgentsRoom đọc transcript phiên của agent để biết mỗi lệnh Bash bắt đầu và kết thúc khi nào, rồi đối chiếu thời gian sửa đổi của tệp với các khoảng thời gian đó. Cách này đúng phần lớn thời gian, và hỏng theo ba kiểu mà chúng tôi gọi tên được:

• một tệp đã bị xóa thì không còn thời gian sửa đổi, nên một lần xóa không bao giờ được quy cho agent nào;
• một lệnh chỉ đọc như grep mở ra một khoảng thời gian mà trong đó agent có thể đã ghi bất cứ thứ gì;
• mọi thứ phụ thuộc vào định dạng transcript, thứ mà Claude Code có toàn quyền thay đổi.

Mod loại bỏ việc phải đoán. Mod agentsroom-changes của chúng tôi gắn hook vào tool.call cho hai công cụ shell. Ngay trước khi lệnh chạy, nó chụp một snapshot của repository (git status cộng với kích thước và thời gian sửa đổi của mọi đường dẫn đang thay đổi). Ngay sau đó, nó chụp snapshot thứ hai. Những đường dẫn khác nhau chính là những gì lệnh đó đã thay đổi, kể cả các lần xóa, và mod gửi chúng tới ứng dụng desktop AgentsRoom qua một endpoint HTTP cục bộ. Một lần gọi mà chính Claude Code đánh dấu là chỉ đọc thì không nhận thay đổi nào về mình.

Đây là hook, ở dạng rút gọn. Tệp đầy đủ dài 177 dòng, phần lớn là snapshot và các giới hạn của nó.

import type { Register } from 'claude-code';

const SHELL_TOOLS = new Set(['Bash', 'PowerShell']);

export const register: Register = (on) => {
  on('tool.call', async ($, e, next) => {
    if (!SHELL_TOOLS.has(e.tool)) return next(e);
    const ready = await prepare($).catch(() => null); // agent id, repo root, snapshot
    if (!ready) return next(e);                        // outside AgentsRoom: do nothing
    const callId = e.tool_use_id;
    post($, ready.agentId, { kind: 'start', callId });
    const ran = await next(e);                         // the command runs here
    const wroteNothing = ran.deny !== undefined || ran.isReadOnly === true;
    await reportEnd($, { ...ready, callId }, wroteNothing)
      .catch(() => post($, ready.agentId, { kind: 'end', callId, paths: [] }));
    return ran;                                        // Claude sees the normal result
  });
};

Ứng dụng desktop sao chép mod vào thư mục riêng của nó và khởi động mỗi agent Claude bằng claude --plugin-dir <that folder>, chỉ khi Claude Code đã cài là bản 2.1.287 trở lên. Chúng tôi phát hành nó trong AgentsRoom 1.201.0 ngày 5 tháng 10 năm 2026.

Những gì chúng tôi rút ra khi phát hành nó

Một mod không bao giờ được khiến người dùng mất một lần gọi công cụ. Hook của chúng tôi đứng trước mọi lệnh shell mà Claude chạy. Nếu nó ném lỗi, hoặc chờ mạng, công việc của Claude sẽ dừng. Mọi bước đều được bảo vệ, mỗi lần gửi tới ứng dụng desktop đều được bắn đi mà không chờ phản hồi, và lần chờ duy nhất chúng tôi chấp nhận là hai snapshot git status, mỗi cái giới hạn ở 15 giây. Một lần gửi bị mất chỉ làm mất một lần quy trách nhiệm, không bao giờ làm mất lệnh.

Không làm gì khi không ai cần đến mình. Mod đọc một biến môi trường mà AgentsRoom đặt cho các agent của nó. Khi biến này không có, chẳng hạn vì ai đó đã chép thư mục vào cấu hình riêng của họ, mọi hook đi thẳng tới next(e).

Một thư mục được nạp bằng --plugin-dir sẽ bị theo dõi. Claude Code nạp lại mod khi một tệp trong thư mục đó thay đổi, và một lần nạp lại sẽ chạy register thêm lần nữa. Điều đó quyết định cách chúng tôi cài nó: ứng dụng desktop chỉ ghi một tệp của mod khi nội dung của nó thay đổi, vì một lần ghi đè mù quáng ở mỗi lần khởi động agent sẽ nạp lại mod trong mọi console Claude đang mở.

Lường trước việc API thay đổi. Các sự kiện và phương thức có thể thay đổi giữa các bản phát hành, và chính tài liệu cũng nói vậy. Khi một mod được nạp từ --plugin-dir, Claude Code ghi các khai báo kiểu của phiên bản đang chạy vào .claude-plugin/types/; chúng tôi kiểm tra kiểu dựa trên những khai báo đó, không dựa trên một trang web. Và nếu một bản build không còn nạp được mod của chúng tôi, không có gì hỏng: mod không bao giờ báo mình sẵn sàng, và AgentsRoom quay về phương pháp cũ dựa trên transcript.

Tự viết mod của bạn

Bạn có hai cách để bắt đầu.

Nhờ Claude. Trong một phiên Claude Code tương tác, mô tả mod bạn muốn ("hiển thị nhánh git hiện tại phía trên prompt"). Claude dùng một skill tích hợp sẵn, plugin-authoring, viết mod vào một thư mục dành riêng cho phiên đó, và Claude Code hỏi bạn một lần xem có bật các mod do Claude viết hay không. Đồng ý, và mod sẽ được nạp khi lượt kết thúc, rồi được nạp lại sau mỗi lượt có thay đổi nó.

Tự viết ba tệp, rồi:

claude --plugin-dir ./my-mod       # load it for one session, hot reload on save
claude plugin validate ./my-mod    # what Claude Code reads from it, without running it
claude plugin test                 # run the mod's *.test.ts files, no session needed

claude plugin validate in ra một dòng hooks: với các sự kiện mà module của bạn xử lý và một dòng calls: với mọi phương thức API của mod mà nó gọi. Nếu một sự kiện bạn định xử lý không có trong đó, Claude Code cũng sẽ không gọi hook đó. Phân tích tĩnh có quy tắc của nó: viết đầy đủ từng lời gọi ($.ui.toast(...), không bao giờ const ui = $.ui), truyền tên sự kiện dưới dạng chuỗi ký tự cố định, và chỉ import các tệp của chính bạn bằng đường dẫn tương đối.

Để chia sẻ một mod, hãy đối xử với nó như đúng cái plugin mà nó là: gửi thư mục đi, hoặc đưa nó vào một marketplace (một repository có .claude-plugin/marketplace.json) để mọi người cài nó bằng /plugin install <name>@<marketplace>.

Những mod bạn có thể đọc ngay hôm nay

• Tích hợp sẵn trong Claude Code: /plugin, tab Installed, mục Built-in. Trong số đó có bảng /diff và trình nạp đọc AGENTS.md như chỉ dẫn của dự án, mà Anthropic công bố mã nguồn trong thư mục mods của repository anthropics/claude-code, kèm các bài kiểm thử của chúng. Cũng tích hợp sẵn, và tắt cho tới khi bạn bật nó lên: You should know, một agent phụ chỉ ra những gì bạn hoặc Claude có thể đã bỏ sót.
• Các mẫu của Anthropic, trong repository claude-code-playground: một dự báo cửa sổ ngữ cảnh được vẽ phía trên prompt, một lớp bảo vệ giữ lại một lệnh shell rủi ro và cho thấy nó sẽ thay đổi gì, và một lệnh /replay đi qua từng bước các chỉnh sửa của lượt gần nhất.
• Của chúng tôi, đã mô tả ở trên: một mod hoàn toàn không có giao diện, chỉ một hook tool.call, một hình mẫu tốt để sao chép nếu thứ bạn cần là dữ liệu chứ không phải một bảng.

Trước khi cài mod của người khác

Một mod không chạy trong sandbox. Nó chạy với quyền của bạn: nó có thể đọc và ghi tệp của bạn, đọc biến môi trường và cài đặt của bạn (kể cả khóa API), khởi chạy chương trình, gửi yêu cầu mạng, thấy mọi prompt và mọi lần gọi công cụ, và phê duyệt một lần gọi công cụ trước khi bạn được hỏi. Nếu bạn đã bật sandbox của Claude Code, nó bao các lệnh Bash mà Claude chạy, không bao các tiến trình mà một mod khởi chạy.

Vậy nên hãy đọc trước khi cài. Clone mod về và chạy claude plugin validate trên thư mục: các dòng hooks: và calls: cho bạn biết nó lắng nghe gì và chạm tới đâu, mà không chạy gì cả. Một mod chỉ vẽ một dải phía trên prompt thì không có lý do gì để gọi $.http hay $.process. Để dừng mọi mod bạn đã cài, khởi động với --safe-mode cho một phiên, hoặc đặt "disableAllHooks": true trong ~/.claude/settings.json.

Mod chạy ở đâu

Một mod có vẽ nên kiểm tra xem nó đang chạy ở đâu và lùi về dạng văn bản ở những nơi không có gì được vẽ.

Trong AgentsRoom

Bạn không phải cài gì: từ Claude Code 2.1.287, mỗi agent Claude khởi động cùng mod này, và tab Thay đổi cho thấy các tệp mà từng lệnh shell của nó đã tạo, sửa hoặc xóa, ngay cạnh agent đã làm việc đó. Với một Claude Code cũ hơn, AgentsRoom vẫn đối chiếu các lần ghi của shell từ transcript, như trước.

Cùng ý tưởng đó chạy trong các CLI khác khi có thể: oh-my-pi nhận một extension với cùng giao ước, còn các CLI khác vẫn đối chiếu các lần ghi của shell như trước đây. Nếu bạn muốn đi xa hơn với những gì Claude Code để lộ ra ở mỗi bước, hướng dẫn hook của Claude Code của chúng tôi bàn về các hook settings mà một mod đứng cạnh.

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

Mod trong Claude Code là gì?

Mod là một plugin Claude Code chứa một hooks module: một tệp JavaScript hoặc TypeScript mà Claude Code gọi các hàm của nó từ bên trong tiến trình của chính mình khi có chuyện gì đó xảy ra, chẳng hạn một lần gọi công cụ, một prompt được gửi đi hay một phần màn hình đang được vẽ. Mỗi hàm có thể để sự kiện đi qua, thay đổi nó, hoặc tự mình xử lý nó. Đó là điều cho phép một mod vẽ một bảng, thêm một lệnh hoặc giữ lại một lệnh shell rủi ro.

Cần phiên bản Claude Code nào để dùng mod?

Claude Code 2.1.287 trở lên trong terminal, phát hành ngày 1 tháng 10 năm 2026, với changelog ghi "Added Claude Mods". Tab Code của ứng dụng Claude Desktop hỗ trợ mod từ 2.1.286. Trong extension VS Code, các hook vẫn chạy, còn những gì mod vẽ ra cần extension 2.1.299 trở lên. Chạy claude --version để kiểm tra.

Mod khác hook của Claude Code ở điểm nào?

Một hook trong settings.json chạy một lệnh shell, một yêu cầu HTTP hoặc một prompt khi một sự kiện xảy ra, bên ngoài Claude Code. Các hook của một mod là những hàm chạy bên trong Claude Code. Chúng làm được những việc mà một hook settings không làm được: vẽ trong giao diện, thêm một lệnh slash chạy mà không cần một lượt của Claude, viết lại một lần gọi công cụ hoặc trả lời nó mà không chạy công cụ, và chia sẻ trạng thái giữa các hook.

Cài mod của Claude Code có an toàn không?

Một mod không chạy trong sandbox. Nó chạy với quyền của bạn, có thể đọc tệp và biến môi trường của bạn, khởi chạy chương trình, gửi yêu cầu mạng và phê duyệt một lần gọi công cụ. Chỉ cài mod từ những tác giả bạn tin tưởng, và chạy claude plugin validate trên thư mục trước: lệnh này liệt kê các sự kiện mà mod gắn hook và các lời gọi nó thực hiện, mà không chạy mod.

Tìm ví dụ về mod của Claude Code ở đâu?

Anthropic công bố mã nguồn của một số mod tích hợp sẵn, như bảng /diff và trình nạp AGENTS.md, trong thư mục mods của repository anthropics/claude-code, và các mod mẫu trong repository anthropics/claude-code-playground. Mod của AgentsRoom được mô tả trong bài này là kiểu ví dụ thứ tư: một mod không có giao diện, chỉ có một hook tool.call.

Có tắt được mod không?

Có. Tắt một mod trong tab Installed của /plugin, khởi động một phiên duy nhất với --safe-mode, hoặc đặt disableAllHooks thành true trong ~/.claude/settings.json để dừng mọi mod bạn đã cài, cùng với các hook settings của bạn. --safe-mode và disableAllHooks vẫn để các mod tích hợp sẵn chạy: những mod này được tắt từng cái một trong /plugin.