Mod Claude Code: kết luận có nguồn, số liệu đo và checklist thứ Hai

TL;DR

• Giữ ba trong số mười mod: collision-guard, model-router và auto-handoff. Mỗi mod đều cho overhead đo được gần bằng 0 trên một tác vụ đọc ở chế độ headless, và mỗi mod giải quyết một vấn đề bạn gọi tên được.
• Xóa next-steps. Nó fork phiên sau mỗi câu trả lời đủ điều kiện và tốn thêm +250 output token và +2850 ms mỗi lượt trong lần chạy của chúng tôi, kể cả trên những giao diện không bao giờ vẽ gợi ý của nó.
• Xóa cache-keeper (+1589 ms, trả tiền cho các lần ping model), recording-mode (nó che phần hiển thị, không che lịch sử đã lưu) và session-bookmarks (một bookmark mà có thể gọi model, chạy tiến trình và ghi file).
• Xóa goal-meter, repo-heatmap và flight-recorder trừ khi bạn muốn phần hiển thị. Chúng gần như không tốn gì và không cho thấy lợi ích đo được.
• Mọi mod guard đều fail open theo mặc định. Không có handler .catch, một guard bị throw sẽ bị bỏ qua và lệnh vẫn chạy.
• Mod không được sandbox. Hãy đọc kết quả của claude plugin validate trước khi cài một mod.

Các phép đo cho thấy gì

Hype và quy mô. Tweet phát hành có 4.138.918 lượt xem, 20.021 lượt thích và 13.440 bookmark khi chúng tôi chụp lại vào 2026-10-03 s11. Danh mục cộng đồng liệt kê 1018 mod trong 873 repo ứng viên, quét vào 2026-10-03 trên Claude Code 2.1.288 s9.

Một mod là một hàm gắn vào một sự kiện. Nó có thể chạy trước sự kiện, sau sự kiện, thay cho sự kiện, hoặc bao quanh nó s1. Mod yêu cầu Claude Code v2.1.287 trở lên và được bật mặc định s2.

Bảo mật trước. Nguyên văn của Anthropic: "Mods run with the same access to your machine as Claude Code itself. They aren't sandboxed" s1. Một tiến trình do mod khởi chạy sẽ chạy ngoài sandbox ngay cả khi bạn bật sandbox s2. Dù Read(.env) bị từ chối, mod vẫn có thể đọc file đó bằng $.fs.read hoặc khởi chạy một chương trình làm việc đó s6. Trong lần quét danh mục, 409 mod chạy tiến trình trên máy chủ, 167 mod ghi file, 150 mod truy cập mạng và 28 mod không qua được validate trên phiên bản này s9.

Phạm vi truy cập so với lời quảng bá. Trong lần audit tĩnh của chúng tôi, session-bookmarks gọi $.model.complete, $.process.run và $.fs.write, phạm vi truy cập nặng nhất trong bộ mod cho một tính năng bookmark. next-steps có dấu vết nhỏ nhất: không fs, không process, không env. claude plugin validate in ra các dòng calls: và env reads: dùng cho lần audit này s6.

Mod chủ lực có chi phí theo từng lượt. next-steps fork phiên bằng $.model.fork ở turn.complete, và README nói fork "costs about one short reply" s10. Gợi ý chỉ được vẽ trong terminal; các giao diện khác không hiển thị gì s10. Fork không có tùy chọn để tắt. Trong lần chạy headless của chúng tôi, nó thêm +250 output token và +2850 ms, với fork được tính vào mức dùng của phiên trong khi không có gì được hiển thị s10.

Các giới hạn được ghi trong tài liệu. Thời gian thực thi hook bị giới hạn 10 giây mỗi sự kiện, đọc và ghi $.fs 4 MiB mỗi file, và $.store tổng cộng 4 MiB JSON s3.

Guard fail open. Tài liệu nói rằng một hook không có handler .catch mà throw, timeout hoặc trả về sai dạng sẽ bị bỏ qua, và handler kế tiếp chạy thay vào đó s7. Chúng tôi đã tái hiện: một guard Bash bị throw, không có .catch, để touch ./marker-failopen.txt tạo được file. Cùng guard đó với một .catch trả về {deny} không tạo file nào. Một báo cáo thực tế gặp guard đang được bật và đang chạy nhưng không làm gì, trong khi plugin list vẫn hiển thị "enabled" s8.

Một bug đang mở trên 2.1.288: deny trả về sau await next(e) không dừng được tool, và file được ghi 3 trên 3 lần trong khi model được báo là việc ghi thất bại s5.

Mod so với hook trong settings. Một hook trong settings khởi tạo một tiến trình cho mỗi lần gọi. Chúng tôi đo chi phí khởi tạo là 2,2 ms với binary true, 8,3 ms với bash -c 'exit 0', 26,1 ms với python3 -c 'pass' và 43,1 ms với node -e ''. Qua 5.993 lần gọi tool mỗi tuần, hook node tốn 258 s. Một mod chạy trong cùng tiến trình không tốn gì trong số đó. Tài liệu khuyên dùng hook trong settings khi bạn đã có sẵn một script chặn, cho phép hoặc ghi log một sự kiện s2. Một báo cáo chuyển đổi đi từ 27 hook shell xuống 5 mod s8.

Che chỉ ở phần hiển thị. recording-mode viết lại những gì ui.render vẽ. ~/.claude/history.jsonl giữ nguyên prompt như đã gõ, và một người thử nghiệm tìm thấy chuỗi canary của anh ấy 7 lần trong các mục queue-operation của transcript s5.

Nơi mod không chạy. claude -p headless và Agent SDK có chạy hook nhưng không vẽ gì; một phiên Desktop WSL không chạy cả hai s2.

Độ tin cậy của danh mục. Một người thử nghiệm đã xuất bản một mod có nút khởi chạy một chương trình bằng $.process.run và ghi một file vào thư mục home của anh ấy. Nó được cài như mọi mod khác, không có cảnh báo nào s5. Đây là một bản proof of concept tự xuất bản, không phải một cuộc tấn công đã gặp ngoài đời thực.

Số liệu đo

Dữ liệu: 7 ngày gần nhất của một setup thật, 85 phiên, 4 dự án, 882 prompt của người dùng, 11.010 lượt của assistant, 5.993 lần gọi tool. Benchmark chạy trên Claude Code 2.1.288 (macOS).

Các dòng đánh dấu * nhiều khả năng là do sai lệch câu trả lời. recording-mode đã tắt trong lúc chạy và không chèn gì khi tắt.

Quy trình để chạy lại:

1. Cài từng mod một và xác nhận nó qua được claude plugin validate.
2. Chạy cùng một tác vụ chỉ đọc ở chế độ headless với claude -p trên haiku, lặp 3 lần cho mỗi config, và lấy trung vị của thời lượng và output token.
3. Chỉ trích dẫn độ chênh về thời lượng và output token. Chi phí USD thay đổi theo thứ tự cache giữa các config, nên hãy bỏ qua.
4. Với chi phí khởi tạo, đo thời gian 30 lần khởi tạo của từng thân hook, lấy trung vị, rồi nhân với số lần gọi tool mỗi tuần của bạn.

Việc cần làm vào thứ Hai

• Chạy claude plugin validate trên mọi mod bạn đã cài và đọc các dòng calls: và env reads:.
• Tắt mọi mod có phạm vi truy cập (process, ghi fs, gọi model) lớn hơn công việc của nó.
• Tắt next-steps nếu bạn chủ yếu làm việc trong các lần chạy headless, panel VS Code hoặc SDK, nơi gợi ý của nó không bao giờ được vẽ.
• Thêm một handler .catch trả về { deny: ... } cho mọi mod guard mà bạn dựa vào.
• Chứng minh mỗi guard fail closed: cho nó throw, chạy một lệnh tạo file marker, và kiểm tra file không xuất hiện.
• Đừng dựa vào một mod che dữ liệu để giữ bí mật khỏi ~/.claude/history.jsonl hoặc transcript. Hãy kiểm tra cả hai trên đĩa.
• Thay các hook shell theo từng lần gọi chạy node hoặc python bằng một mod chạy cùng tiến trình, hoặc bằng một binary đã biên dịch, nếu chi phí khởi tạo cộng dồn đáng kể qua số lần gọi tool mỗi tuần.
• Nắm các công tắc tắt: tắt một mod trong /plugin, --safe-mode cho một phiên, "disableAllHooks": true trong ~/.claude/settings.json cho mọi nơi.

Đọc thêm

• Tự viết mod: một hướng dẫn thực hành về mod khoảng 80 dòng, với những cạm bẫy đáng chú ý (state ở cấp module bị reset khi hot reload, nên hãy giữ dữ liệu trong $.state) s4.
• Quyết định dùng mod, hook, skill hay settings dựa trên lịch sử của chính bạn: một người dùng gợi ý nên khai thác log phiên để tìm các vấn đề lặp lại trước s12.
• Đọc danh sách sự kiện đầy đủ và các giới hạn trước khi viết một guard s3.
• Quản lý mod cho cả tổ chức nằm ngoài phạm vi ở đây. Điểm duy nhất dành cho lập trình viên làm một mình: sec-default được nạp khi máy có managed settings hoặc bạn đăng nhập bằng gói Team hoặc Enterprise, và nó không thêm hạn chế nào khác s6.
• Nguồn gốc của thiết kế, gồm một bug cô lập worktree đã sửa trong 2.1.288 và cơ chế bên trong của runtime, nằm trong thread đang mở s5.
• Các mod mẫu của Anthropic (token-weather, blast-radius, replay-theater) được liệt kê là chia sẻ không kèm hỗ trợ s2.

Nguồn

• Customize Claude Code with mods, blog của Anthropic. Vì sao nên đọc: định nghĩa chính thức và cảnh báo không sandbox bằng chính lời của Anthropic.
• Mods overview, tài liệu. Vì sao nên đọc: so sánh mod với hook, ma trận giao diện và các công tắc tắt.
• Mods reference, tài liệu. Vì sao nên đọc: danh sách sự kiện đầy đủ và các giới hạn được ghi trong tài liệu.
• Getting started with Claude Code mods, claude.dev (Addy Osmani). Vì sao nên đọc: hướng dẫn thực hành tốt nhất, với các cạm bẫy mà không nguồn nào khác đề cập.
• Mods issue #91870, GitHub. Vì sao nên đọc: báo cáo thực tế về cô lập, hành vi fail closed và rò rỉ lịch sử.
• Manage mods for your organization, tài liệu. Vì sao nên đọc: audit bằng validate và giới hạn của mọi kiểm soát bảo mật.
• React to events with a mod, tài liệu. Vì sao nên đọc: thứ tự chuỗi middleware và mặc định fail open.
• The Guard I Installed Was Enabled, Running, and Doing Nothing, blog. Vì sao nên đọc: báo cáo chuyển đổi thực tế duy nhất, từ 27 hook shell xuống 5 mod.
• awesome-claude-code-mods, GitHub. Vì sao nên đọc: quy mô hệ sinh thái và một phương pháp audit làm sẵn.
• next-steps plugin source, GitHub. Vì sao nên đọc: cơ chế thật của mod chủ lực, gồm cả fork theo từng lượt.
• ClaudeDevs release tweet, X. Vì sao nên đọc: thông báo phát hành và mức độ lan tỏa của nó.
• Avid's session-log mining workflow, X. Vì sao nên đọc: một phương pháp để quyết định nên viết hay cài gì trước khi cài bất cứ thứ gì.

FAQ

Mod có được sandbox không?

Không. Anthropic nói mod chạy với cùng quyền truy cập vào máy của bạn như chính Claude Code s1. Các chương trình do mod khởi chạy cũng chạy ngoài sandbox s2.

Chuyện gì xảy ra nếu mod guard của tôi bị crash?

Không có handler .catch, nó bị bỏ qua và lệnh vẫn chạy s7. Hãy thêm một .catch trả về { deny: ... } để nó fail closed.

Mod có tốn token không?

Chỉ khi nó gọi model. Trong mười mod chúng tôi chạy, next-steps và cache-keeper cho thấy chi phí đo được; các mod còn lại không cho thấy overhead rõ ràng trong lần chạy của chúng tôi.

Làm sao để tắt mod nhanh?

Tắt một mod trong /plugin, bắt đầu phiên với --safe-mode, hoặc đặt "disableAllHooks": true trong ~/.claude/settings.json s2. Không cách nào trong số này dừng được các mod tích hợp sẵn.

Tôi có thể kiểm tra một mod làm gì trước khi cài không?

Có. claude plugin validate liệt kê các hook, các lệnh gọi API và các biến môi trường mà nó đọc s6.