Tổng quan về Mods

Mod là một plugin thay đổi cách Claude Code hiển thị và hoạt động. Mod được viết bằng các event handler JavaScript hoặc TypeScript: Claude Code gọi một handler khi có event xảy ra, chẳng hạn một tool call, một prompt vừa được gửi, hoặc một phần của giao diện đang được vẽ, và handler có thể quan sát event đó, thay đổi nó, hoặc xử lý thay luôn. Dùng mod để thêm tính năng của riêng bạn vào Claude Code, ví dụ một pane vẽ biểu đồ mức sử dụng context sau mỗi request. Cấu trúc file của một mod và ví dụ đầy đủ nằm ở phần Cách một mod hoạt động.

Mod làm được gì

Settings hooks, skills, status line và MCP server đều tác động từ bên ngoài Claude Code: mỗi loại chạy một script, hoặc đưa cho Claude thêm text hay tool. Mod chạy bên trong Claude Code, nên làm được những việc mà các cơ chế kia không làm được:

Vẽ giao diện tương tác được: một pane bên cạnh transcript hoặc một dải (band) phía trên ô prompt, có tab, nút bấm và ô nhập liệu. Xem Vẽ giao diện bằng mod.
Vẽ lại giao diện của chính Claude Code: thay thế hoặc đổi style những phần Claude Code tự vẽ, như dòng hiển thị một tool call, spinner, hoặc hộp thoại Claude dùng để hỏi bạn. Xem Thay đổi những gì Claude Code đã vẽ sẵn.
Can thiệp vào một tool call hoặc một request: ví dụ giữ một tool call lại trong lúc hỏi ý user, trả lời luôn mà không chạy tool, hoặc gửi một request sang model khác. Xem Chặn hoặc thay đổi tool call và Theo dõi một turn.
Chạy code của bạn khi gõ command: một /command chạy hàm của bạn ngay lập tức, không cần Claude bắt đầu turn, kể cả khi Claude đang làm việc. Xem Thêm command hoặc tool.
Chia sẻ dữ liệu giữa các hook: các hook của một mod dùng chung biến trong file của nó, nên thứ mà hook này ghi lại thì hook khác có thể hiển thị. Ví dụ, một hook đếm số tool call còn hook khác hiển thị con số đó cạnh spinner, hoặc một hook đọc token usage của từng request còn hook khác vẽ biểu đồ trong pane. Xem Phản ứng với event.

Mods chạy trong Claude Code CLI và trong tab Code của ứng dụng Claude Desktop. Xem Mods chạy ở đâu để biết mod hoạt động ra sao ở các nơi khác, như VS Code extension, claude -p và cloud session. Nếu một settings hook, skill hay MCP server đã làm được việc bạn cần, hãy so sánh chúng trước khi viết mod. Để quản lý mods cho cả tổ chức, xem Quản lý mods cho tổ chức.

Lấy một mod

Có ba cách để bắt đầu với mod:

Dùng mod bạn đã có sẵn: một số tính năng của chính Claude Code là mod, ví dụ /diff. Xem Các mod tích hợp sẵn trong Claude Code.
Tự tạo: mô tả thứ bạn muốn trong một session Claude Code, và Claude sẽ viết mod. Xem Nhờ Claude viết mod. Để hiểu code của một mod hoạt động thế nào, hãy tự viết một mod.
Cài đặt: xem Cài đặt hoặc cập nhật mod, hoặc thử một mod mẫu.

Cài đặt hoặc cập nhật mod

Mod được cài như một plugin, từ một marketplace. Bạn ghi tên plugin, dấu @, rồi tên marketplace. Hai ví dụ dưới đây cài plugin token-chart từ marketplace your-org:

Trong một session Claude Code, chạy /plugin install token-chart@your-org.
Trong shell, chạy claude plugin install token-chart@your-org.

Trang Install plugins mô tả marketplace, scope, VS Code extension, ứng dụng Desktop và cách giữ plugin luôn được cập nhật. Tất cả đều áp dụng nguyên vẹn cho plugin có chứa mod.

Nếu bạn cài hoặc cập nhật mod từ shell trong lúc một session đang mở, hãy chạy /reload-plugins trong session đó để nạp mod. Nếu không, mod sẽ được nạp ở lần khởi động Claude Code tiếp theo.

Thử một mod mẫu

Anthropic chia sẻ các mod mẫu trong thư mục claude-code/mods của repository claude-code-playground. Mỗi mod là một plugin hoàn chỉnh, và README của nó ghi lại cách mod được xây dựng. Repository chia sẻ các mod này nguyên trạng, không kèm hỗ trợ.

token-weather: vẽ “dự báo thời tiết” cho context window của bạn ngay phía trên ô prompt
blast-radius: giữ lại một shell command rủi ro, như rm -rf hay force push, cho bạn xem nó sẽ thay đổi những gì, kèm nút để tiếp tục hoặc hủy
replay-theater: thêm command /replay để xem lại từng bước các chỉnh sửa file Claude đã làm trong turn vừa rồi

Mod mẫu cũng chạy với quyền của bạn. Để xem một mod làm gì trước khi nạp nó, hãy liệt kê hook và lời gọi của nó.

Để thử, clone repository rồi nạp thư mục của mod cho một session bằng --plugin-dir. Để chắc chắn mod đã được nạp, xem session đã nạp những mod nào.

Để giữ lại mod dùng lâu dài, thêm thư mục claude-code/mods của bản clone làm marketplace, rồi cài mod từ claude-code-playground-mods. Marketplace này trỏ tới bản clone của bạn, nên nếu bạn di chuyển hoặc xóa bản clone thì mod sẽ không còn được nạp.

Quyết định có nên tin một mod

Mod là code chạy với quyền của bạn, bên trong Claude Code. Chỉ cài mod từ tác giả và marketplace mà bạn tin tưởng.

Mod có thể truy cập những gì

Mod chạy với quyền của bạn, nên trước khi cài, bạn cần biết nó truy cập được những gì. Khi đã được nạp, một mod có thể:

Hành động trên máy bạn với danh nghĩa của bạn: đọc và ghi file ở bất cứ đâu tài khoản của bạn có quyền, khởi chạy chương trình và gửi network request
Đọc các thông tin bí mật: biến môi trường và settings file, kể cả API key bạn lưu ở một trong hai nơi đó
Thấy toàn bộ session: mọi prompt bạn gửi và mọi tool call Claude thực hiện
Thay đổi session: viết lại một prompt hoặc một tool call, gửi một prompt như thể chính bạn gõ, hoặc gửi tin nhắn sang một session khác của bạn
Hành động mà không hỏi bạn: duyệt (approve) một tool call trước khi bạn được hỏi
Tiêu tốn usage của bạn: gọi model bằng gói (plan) hoặc API key của bạn

Mod không chạy trong sandbox. Nếu bạn bật sandboxing, sandbox chỉ cô lập các lệnh Bash mà Claude chạy, còn process do mod khởi chạy thì nằm ngoài sandbox.

Một mod có khả năng duyệt tool call có thể duyệt cả call lẽ ra phải hỏi theo một rule ask, hoặc call đã bị một PreToolUse hook của chính bạn chặn. Trang Extend permissions with hooks liệt kê những gì một mod như vậy được phép duyệt, kể cả trường hợp nó duyệt được một call bị rule deny từ chối.

Mod có thể đổi style phần lớn giao diện Claude Code, nhưng không đụng được vào permission prompt. Nó không thể thay đổi những gì một permission prompt hiển thị cho bạn.

Liệt kê những gì mod làm trước khi cài

Trước khi cài một mod, bạn có thể liệt kê những event nó xử lý và những gì nó yêu cầu Claude Code làm, như đọc file hay gửi network request, mà không cần chạy nó. Trước tiên hãy lấy file của plugin về, ví dụ bằng cách clone repository. Sau đó, trong shell, chạy claude plugin validate trên thư mục của plugin:

claude plugin validate ./some-mod

Các dòng hooks: và calls: trong output cho biết mod xử lý những event nào và yêu cầu Claude Code làm gì. Phần Xem xét những gì mod có thể làm có ví dụ output và những lời gọi cần để ý.

Bật hoặc tắt mods

Mods yêu cầu Claude Code v2.1.287 trở lên, và được bật sẵn theo mặc định. Trong shell, chạy claude --version để kiểm tra, và cập nhật Claude Code nếu phiên bản của bạn cũ hơn.

Để tắt mods, chọn tắt bao nhiêu mod và tắt trong bao lâu. Để bật lại, hoàn tác đúng thay đổi đó:

Một mod: disable hoặc gỡ plugin chứa nó trong tab Installed của /plugin
Mọi mod đã cài, trong một session: khởi động Claude Code với --safe-mode, cờ này cũng tắt các tùy biến khác của bạn
Mọi mod bạn đã cài, trong mọi session: đặt "disableAllHooks": true trong ~/.claude/settings.json. Settings hooks và status line tùy chỉnh của bạn cũng ngừng chạy. Những gì tổ chức của bạn quản lý thì vẫn tiếp tục chạy.

Nếu bạn dùng Claude Code thông qua một tổ chức, administrator cũng có thể giới hạn những mod nào được nạp. Administrator bắt đầu từ phần Chặn mod do user cài.

disableAllHooks và allowManagedModsOnly của tổ chức chỉ dừng mod, phần còn lại của plugin vẫn giữ nguyên: plugin vẫn được cài, và skills, commands, agents, MCP server của nó vẫn được nạp. Các setting và cờ khác thì tác động rộng hơn. Trang disableAllHooks và What runs under allowManagedHooksOnly liệt kê mỗi cái tác động thế nào lên plugin và settings hooks của nó.

Để biết mods có nạp được trên máy bạn hay không, xem Kiểm tra mods có nạp được không.

Xem session đã nạp những mod nào

Để xem một session terminal đã nạp những mod nào, chạy /plugin tại prompt của Claude Code. Một dòng chữ mờ dưới các tab cho biết số lượng và tên mod, ví dụ 1 mod active · first-mod. Nếu mod bạn đã cài không có tên ở đó, xem Tìm hiểu vì sao mod không làm gì.

Cách một mod hoạt động

Mod là một plugin có code đăng ký các event handler, gọi là hook. Claude Code chạy một hook khi event tương ứng xảy ra, ví dụ khi Claude gọi một tool hoặc khi spinner được vẽ. Một mod nhỏ gồm ba file:

first-mod/
├── .claude-plugin/
│   └── plugin.json
└── hooks/
    ├── hooks.json
    └── register.js

plugin.json: manifest của plugin
hooks.json: trỏ tới file code của bạn
register.js: code của bạn, gọi là hooks module. File này cho Claude Code biết cần chạy hàm nào của bạn khi có event nào.

Dưới đây là một register.js hoàn chỉnh. Nó đếm số tool call Claude thực hiện và hiển thị con số đó cạnh spinner trong lúc Claude làm việc, kiểu Thinking · tool calls: 3….

// Biến đếm, dùng chung cho hai hook bên dưới
let calls = 0

// Claude Code gọi hàm này một lần khi mod được nạp
export function register(on) {
  // Chạy mỗi khi Claude sắp dùng một tool
  on('tool.call', async ($, e, next) => {
    calls += 1
    // Yêu cầu Claude Code vẽ lại giao diện để hiện con số mới
    $.ui.invalidate('ui.render')
    // Để tool chạy như bình thường
    return next(e)
  })

  // Chạy mỗi khi Claude Code vẽ spinner
  on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
    // Giữ nguyên spinner của Claude Code, thêm con số vào sau chữ của nó
    return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })
  })
}

File này đăng ký hai hook, và cả hai đều dùng biến calls khai báo ở đầu file:

Hook tool.call chạy mỗi khi Claude sắp dùng một tool. Nó cộng calls thêm một, yêu cầu Claude Code vẽ lại giao diện, rồi để tool chạy bình thường.
Hook ui.render chạy mỗi khi Claude Code vẽ spinner. Nó giữ nguyên spinner của Claude Code và thêm con số vào sau chữ.

Video dưới đây cho thấy mod đang hoạt động. Hãy để ý dòng spinner phía trên ô prompt: trong lúc Claude liệt kê một thư mục và đọc hai file, dòng này lần lượt hiện Thinking · tool calls: 1…, rồi 2…, rồi 3….

Hook có thể làm gì với một event

Claude Code chạy hook của bạn trước khi xử lý event, nên hook quyết định điều gì xảy ra tiếp theo. Hook có thể:

Quan sát (observe): ghi nhận điều đang diễn ra và để nó tiếp tục mà không thay đổi gì, giống hook tool.call trong ví dụ
Viết lại (rewrite): thay đổi event trước khi nó đi tiếp, giống hook ui.render khi thêm con số vào spinner
Trả lời (answer): tự xử lý event, để hành vi mặc định không chạy nữa, ví dụ từ chối một command

Để làm bất cứ việc gì ngoài phạm vi code của chính nó, như vẽ giao diện, thêm command, gọi model, đọc file, khởi chạy process hay gửi network request, hook phải gọi mods API. Hook không có cách nào khác để làm những việc đó, và đây là lý do Claude Code có thể liệt kê những gì một mod làm trước khi bạn cài nó.

Code cho từng lựa chọn nằm ở Phản ứng với event. Những gì hook có thể gọi nằm ở Dùng mods API.

Mods chạy ở đâu

Hook của mod chạy trong mọi loại session có nạp plugin đó. Phần vẽ giao diện thì hẹp hơn: chỉ terminal và ứng dụng Desktop mới hiển thị pane, band và các dòng đã được thay thế của mod. Bảng dưới đây liệt kê từng nơi bạn có thể chạy Claude Code:

Nơi bạn chạy Claude Code	Hook có chạy không	Phần mod vẽ có hiển thị không
`claude` trong terminal, kể cả terminal tích hợp của editor và JetBrains plugin	Có	Có
Tab Code của ứng dụng Desktop, trừ WSL session	Có	Có, trừ các element mà bảng element đánh dấu chỉ dành cho terminal
Một WSL session trong ứng dụng Desktop	Không, vì plugin không khả dụng trong WSL session	Không
Khung chat của VS Code extension	Có	Không
`claude -p` và Agent SDK	Có	Không
Remote Control từ claude.ai hoặc ứng dụng mobile	Có, trong session trên máy của bạn	Trong terminal trên máy của bạn
Một cloud session	Có, với plugin được mang lên cloud session	Không

Một mod có vẽ giao diện có thể kiểm tra nó đang chạy trong ứng dụng nào, và chuyển sang ghi một dòng vào transcript hoặc trả lời bằng text của command ở những nơi không vẽ được gì.

Quản lý mods cho tổ chức

Administrator quyết định mods có được chạy không và những mod nào được chạy, thông qua managed settings. Trang Quản lý mods cho tổ chức mô tả điều gì xảy ra theo mặc định, cách xem xét một mod, và cách thực thi policy bằng một mod của riêng bạn.

So sánh mods, settings hooks, skills và MCP server

Mods, settings hooks, skills và MCP server có phần chồng lấn nhau. Bảng dưới cho biết mỗi loại là gì và khi nào nên chọn.

	Mod	Settings hook	Skill	MCP server
Là gì	Các hàm trong một plugin, được Claude Code gọi ngay trong process của nó	Một shell command, HTTP request hoặc prompt mà Claude Code chạy tại một lifecycle event	Một file `SKILL.md` chứa chỉ dẫn để Claude đọc	Một process hoặc service bên ngoài cung cấp tool cho Claude
Thay đổi được gì	Tool call, prompt, command, turn, và những gì giao diện vẽ ra	Tool call hoặc prompt có được đi tiếp không, tham số và kết quả của tool call, và context thêm cho Claude	Những gì Claude biết và làm	Claude có những tool nào
Vẽ được giao diện không	Có	Không	Không	Không
Bạn viết bằng gì	JavaScript hoặc TypeScript	Một script và một mục trong `settings.json`	Markdown	Một server bằng ngôn ngữ bất kỳ
Chọn khi	Bạn muốn có pane, band phía trên prompt, command tùy chỉnh, hoặc viết lại một event	Bạn muốn chặn, cho phép hoặc ghi log một event bằng script có sẵn	Bạn cứ phải dán đi dán lại cùng một đoạn chỉ dẫn vào chat	Claude cần truy cập một hệ thống bên ngoài

Mỗi loại còn lại có trang riêng: Hooks, Skills và MCP. Một plugin có thể chứa tất cả, nên mod có thể được phát hành chung một plugin với skill và MCP server.

Các mod tích hợp sẵn trong Claude Code

Một số tính năng của chính Claude Code là mod. Để xem session của bạn có những mod nào, chạy /plugin tại prompt của Claude Code rồi vào tab Installed, các mod này nằm dưới mục Built-in. Bạn không thể cập nhật hay gỡ mod tích hợp sẵn, và cột cuối của bảng cho biết cách tắt từng cái. Dòng mods active không tính các mod tích hợp sẵn.

Bảng dưới liệt kê từng mục theo tên mà /plugin hiển thị:

Tên trong `/plugin`	Chức năng	Bật ở đâu	Cách tắt
`cc-plugin-agents-md`	Nạp `AGENTS.md` làm chỉ dẫn cho project	Mọi session, trừ những session không đọc được `AGENTS.md`	Disable trong `/plugin`, hoặc chọn những file chỉ dẫn được nạp
`cc-plugin-diff`	Tiếp quản `/diff` và vẽ pane của nó	Các session terminal tương tác	Disable trong `/plugin`. `/diff` vẫn còn, và phiên bản tích hợp sẵn trong Claude Code sẽ xử lý command này.
`cc-plugin-plugin-authoring`	Cung cấp cho Claude skill `plugin-authoring` để viết mod. Plugin này chỉ chứa một skill, không có code mod.	Trừ khi Anthropic đã tắt các mod đã cài từ xa	Disable trong `/plugin`
`cc-plugin-sec-default`	Bảo vệ những gì tổ chức của bạn quản lý khỏi các mod do user cài	Nơi guard được nạp	Không tắt được. Administrator đặt thứ tự trong managed settings
`cc-plugin-telemetry`	Gửi các bản ghi analytics mà Claude Code và các mod tích hợp sẵn ghi lại	Bất cứ nơi nào analytics của Claude Code đang bật	Disable trong `/plugin`, hoặc tắt analytics, ví dụ bằng `DISABLE_TELEMETRY`
`cc-plugin-you-should-know`	Chạy một agent phụ “để mắt giúp bạn” trong lúc Claude làm các task dài. Khi thấy điều gì đáng biết mà bạn có thể bỏ lỡ, nó hiện một ghi chú phía trên ô prompt.	Tắt theo mặc định. Có trong `/plugin` -> Installed -> Show disabled nếu tổ chức của bạn được dùng. Bật bằng `/plugin enable cc-plugin-you-should-know@builtin`.	Disable trong `/plugin`

Các setting và cờ dùng để dừng mod đã cài, như disableAllHooks, --bare và --safe-mode, không dừng được mod tích hợp sẵn.

Đọc mã nguồn các mod tích hợp sẵn

Mã nguồn của một số mod trên được công khai trong thư mục mods của repository Claude Code. Mỗi cái là một plugin hoàn chỉnh, có hooks module và test:

diff: pane của /diff, với các nút gắn vào keyboard action và phần cuộn do mod tự xử lý
agents-md: nạp AGENTS.md làm chỉ dẫn cho project, có một option userConfig
sec-default: guard được mô tả ở Mặc định sẽ như thế nào, một hình mẫu cho mod thực thi policy
telemetry: thêm các method mà mod khác có thể gọi, và phát hành kèm type của chúng

Đọc tiếp

Tạo một mod: xây dựng một mod đếm tool call, hiển thị con số cạnh spinner và thêm một command, đồng thời làm quen vòng lặp sửa code rồi reload
Vẽ giao diện bằng mod: pane, band phía trên prompt, nút bấm, ô nhập liệu và state
Phản ứng với event: tool call, prompt, turn, và thứ tự các mod chạy
Dùng mods API: command, tool, gọi model, timer và file
Kiểm thử mod: test tự động chạy không cần session
Xử lý sự cố mod: các lý do khiến mod không làm gì, và debug log
Quản lý mods cho tổ chức: mặc định, managed settings, xem xét mod và policy mod
Tham chiếu Mods: event, method, element và giới hạn

Bài tiếp theo: Tạo một mod - Nhờ Claude viết mod, hoặc tự viết mod đầu tiên từng bước.

Th.S Trần Huy Phúc

Kỹ sư phần mềm @Adnovum & Bumbii Academy

Học Tiếng Anh với Bumbii English