Mod của Claude Code: một file nhỏ viết lại những gì bạn thấy

Hãy hình dung bạn quay một video nấu ăn ngay trong bếp nhà mình. Sau lưng bạn, cửa tủ lạnh dán đầy giấy tờ: hoá đơn tiền điện, phiếu lương, lịch học có ghi tên con bạn. Bạn không muốn gỡ hết xuống; bạn chỉ mong máy quay tự làm mờ mấy tờ giấy đó trong lúc quay. Căn bếp vẫn y nguyên. Chỉ có hình ảnh là thay đổi.

Đó chính là vấn đề tôi gặp lần đầu quay demo Claude Code. Terminal là căn bếp: giá trị trong .env trôi qua, một địa chỉ email hiện ra trong kết quả của một công cụ, một con số lộ ra trong file. Mod của Claude Code chính là chiếc máy quay biết làm mờ.

Tóm lại trong một câu: mod là một file JavaScript hoặc TypeScript nhỏ chạy bên trong phiên Claude Code, nơi nó có thể quan sát những gì đang diễn ra, trả lời thay Claude Code, hoặc viết lại những gì được vẽ lên màn hình.

Mod thực chất là gì

Claude Code vốn đã cho bạn chỉnh khá nhiều thứ: cài đặt, quy tắc quyền, lệnh slash, skill, dòng trạng thái. Mod tiến thêm một bước. Theo hướng dẫn chính thức, mod là một plugin Claude Code có phần hành vi nằm trong một module JavaScript hoặc TypeScript. Thư mục là một plugin bình thường với manifest .claude-plugin/plugin.json, file hooks/hooks.json chỉ định đúng một module trong modules, và module đó export register(on, options).

Bên trong register, mỗi lần gọi on(event, matcher?, hook) là thêm một hook. Các sự kiện bao gồm lời gọi công cụ, prompt vừa gửi, lúc một lượt bắt đầu và kết thúc, lúc phiên mở và đóng, lệnh slash, và ui.render, được kích hoạt cho từng mảnh giao diện khi nó được vẽ. Module chạy trong sandbox riêng, không có DOM cũng không có Node, nên mọi thứ nó làm bên ngoài đều đi qua $, tức API của mod.

Khác biệt với hook khai báo trong cài đặt là điều đáng nhớ. Hook trong cài đặt chạy một lệnh shell cho mỗi sự kiện và trao đổi JSON qua stdin, stdout. Còn mod được nạp một lần và ở lại trong phiên: nó giữ được trạng thái, vẽ giao diện cập nhật theo sự kiện, mở một khung (pane), chạy tiến trình, đăng ký lệnh slash hoặc một công cụ mà mô hình có thể gọi. Chính Anthropic cũng dùng mod cho Claude Code: phần hỗ trợ AGENTS.md và khung /diff được viết dưới dạng mod, mã nguồn công khai trong repo anthropics/claude-code, thư mục mods/.

Bạn cần Claude Code 2.1.287 trở lên. Ở bản này mod được bật sẵn, nhưng API có thể đổi giữa các phiên bản: mỗi lần nạp mod, Claude Code ghi các khai báo kiểu (type) của bản bạn đang dùng vào thư mục .claude-plugin/types/ của mod, và đó mới là tài liệu chuẩn cho phiên bản của bạn.

Một mắt xích trong chuỗi

Mọi hook đều có cùng một hình dạng. Đây là ví dụ nguyên văn trong hướng dẫn:

on("tool.call", { tool: "Bash" }, async ($, e, next) => {
  // $    the mods API: ui, session, state, store, fs, process, clock, http, tool, command, model, ...
  // e    this event's input, as plain data
  // next passes e to the other plugins and then to Claude Code's own behavior
  return next(e);
});

Các hook nối thành một chuỗi, giống middleware trong một web server. Hook của bạn chạy, next(e) chuyển sự kiện cho plugin kế tiếp, và ở cuối chuỗi Claude Code làm việc mà nó vốn sẽ làm. Ở vị trí đó, một hook chỉ có đúng ba nước đi.

Quan sát: gọi await next(e) trước, rồi xem kết quả, chẳng hạn để đo một chỉ số sau mỗi lượt. Viết lại: truyền đi một sự kiện đã sửa, next({ ...e, command }), để phần còn lại của chuỗi thấy một thứ khác. Trả lời: trả về { deny } mà không gọi next, tức là từ chối một lời gọi công cụ hoặc tự mình phục vụ một lệnh. Mọi việc một mod làm đều là sự kết hợp của ba nước đi này.

Hai ví dụ trong hướng dẫn chính thức

Hướng dẫn dựng Token Weather, khoảng 80 dòng, vẽ một dòng phía trên ô nhập: bản dự báo thời tiết trực tiếp của cửa sổ context. ☀ Clear dưới 25 %, ☁ Cloudy, ☂ Showers, ☇ Storm từ 75 %, ↯ Compact soon từ 90 % trở lên. Trong đoạn ghi hình của hướng dẫn, dải này đi từ 18 % lên 67 % rồi 81 % của một cửa sổ 200k sau ba lượt. Đây là quan sát thuần tuý: nó đọc $.session.usage() sau mỗi lượt rồi vẽ lại.

Ví dụ thứ hai, Blast Radius, dùng nước đi thứ ba. Khi Claude gọi Bash với rm -rf, git reset --hard, git clean, một lần force push hay một migration cơ sở dữ liệu, nó giữ lời gọi lại, tính xem lệnh sẽ đụng tới những gì, rồi mở một khung có Proceed và Cancel. Trong bản demo, nó giữ rm -rf build và liệt kê 9 file (1,1 MB) sẽ bị xoá. Bấm Cancel thì Claude nhận một lời từ chối kèm lý do. Hướng dẫn nói thẳng giới hạn của nó: nó đọc văn bản của lệnh, nên $(…), alias và các script gọi rm vẫn lọt qua. Đây là tấm lưới an toàn, không phải hệ thống phân quyền; muốn chặn cứng thì dùng quy tắc quyền.

Recording Mode: màn hình thay đổi, dữ liệu thì không

Mod giải quyết đúng chuyện căn bếp của tôi không nằm trong hướng dẫn. Recording Mode đến từ một repo cộng đồng của Nate Herk, giấy phép MIT. Bạn gõ /rec trước khi bấm quay, và nó áp dụng cho mọi cuộc chat đang mở trong vòng 3 giây; /rec off tắt nó ở mọi nơi.

Khi đang bật, nó che trên màn hình các khoá API và token, mọi giá trị trong file .env của thư mục dự án hoặc thư mục cha, email, tên người, số điện thoại, địa chỉ, số thẻ và số tài khoản, số tiền, và các con số đứng cạnh những từ như revenue hay payroll. /rec strict che thêm mọi con số lớn và mọi tỉ lệ phần trăm. Nó khoá các file .env, khoá SSH và khoá cloud, thư mục bộ nhớ của Claude và các tài liệu tài chính, đồng thời hiện một chấm ● REC màu đỏ phía trên ô nhập.

Điểm mấu chốt nằm trong README: kết quả từ các công cụ mail, chat, lịch, CRM hay tài chính bị ẩn trên màn hình, nhưng Claude vẫn nhận kết quả thật. Chỉ màn hình thay đổi. Đó đúng là cánh cửa tủ lạnh ở đầu bài: căn bếp không suy suyển, chỉ máy quay làm mờ.

Để thử

Trước hết, kiểm tra phiên bản: 2.1.287 trở lên.

claude --version

Sau đó thêm repo mod của cộng đồng, sau khi đã đọc nó.

claude plugin marketplace add nateherkai/claude-code-mods

Cài Recording Mode, mở một chat mới, rồi gõ /rec trước khi quay.

claude plugin install recording-mode@nateherk-mods

Để tuỳ biến, /rec config tạo một file config.json trong ~/.claude/mods-data/recording-mode/, nơi bạn liệt kê những cái tên luôn cần che, tên của chính bạn để vẫn hiển thị, và các đường dẫn riêng tư mà Claude không được mở trong lúc quay.

Tự viết mod của mình

Bạn không cần học API mới bắt đầu được. Chạy claude, mô tả mod bạn muốn bằng lời thường, và đồng ý hot reload khi được hỏi: mod hiện ra khi lượt kết thúc, và mỗi lần chỉnh sau đó đều được nạp lại tại chỗ. Hướng dẫn khuyên giữ dữ liệu trong $.state thay vì biến của module, vì mỗi lần nạp lại sẽ chạy lại register. Và vì mod chỉ là một plugin, bạn chia sẻ nó như một plugin: một repo GitHub có file marketplace là đủ.

Tóm lại

Mod là một mắt xích trong chuỗi nối giữa những gì xảy ra trong phiên làm việc và những gì Claude Code làm hoặc hiển thị. Quan sát, viết lại, trả lời: ba nước đi là đủ cho một bản tin thời tiết của context, một chốt chặn trước rm -rf, hay một chiếc máy quay làm mờ bí mật của bạn. Hãy bắt đầu với Recording Mode trước buổi demo tới, rồi mô tả mod của riêng bạn cho Claude.