Claude Code mod：它是什麼，以及我們給每個代理都裝上的那個 mod

2026 年 10 月 1 日，Claude Code 2.1.287 發布，更新日誌只有一行：「Added Claude Mods」。四天後，AgentsRoom 開始把我們的一個 mod 載入進它執行的 Claude 代理裡。

本文講清楚 mod 是什麼，它能做哪些舊擴展點做不到的事，如何編寫、載入和測試一個 mod，以及我們在 AgentsRoom 啟動的每個 Claude 代理裡裝上一個 mod 學到了什麼。關於 Claude Code 的事實均來自其文件和更新日誌，閱讀日期為 2026 年 11 月 9 日，所裝版本為 Claude Code 2.1.318。

簡短回答。 mod 是一個帶 hooks module 的 Claude Code 外掛。hooks module 是一個 JavaScript 或 TypeScript 檔案，事件發生時，Claude Code 會在自己的程序裡呼叫它的函式。函式可以放行事件、修改事件，或者代替 Claude Code 應答。mod 就是這樣繪製面板、新增命令，或者在 shell 命令執行前把它攔下。

mod 是什麼

Claude Code 早就有外掛：一個在 .claude-plugin/plugin.json 放了清單的資料夾，把技能、子代理、settings hook 和 MCP 伺服器打包在一起，作為一個整體安裝。mod 是外掛能裝的又一樣東西。當外掛的 hooks/hooks.json 在 modules 鍵下指定一個程式碼檔案時，Claude Code 會載入這個檔案，並呼叫它匯出的 register 函式。這時這個外掛就叫 mod。

在 register 裡，每次呼叫 on(event, hook) 都會把一個函式掛到一個事件上：工具執行前的 tool.call、你傳送提示詞時的 prompt.submit、session.start、斜槓命令對應的 command.run、Claude Code 繪製螢幕某一部分時的 ui.render，等等。每個 hook 都會收到三樣東西：

• $，mods API：mod 在自身程式碼之外能做的一切，比如 $.ui、$.command、$.fs、$.process 或 $.http。
• e，事件本身，是普通資料：對一次工具呼叫來說，就是工具名和它的引數。
• next，把事件傳給其他 mod，再交給 Claude Code 自己的行為，並返回結果。

hook 怎麼處理 next，決定了接下來發生什麼。返回 next(e)，你只是旁觀。用修改過的 e 副本呼叫 next，你就改寫了事件。不呼叫 next、直接返回你自己的結果，你就替它應答了：工具根本不會執行，或者 Claude Code 自己的繪製不會發生。

文件也把這些函式叫作 hook。它們不是你寫在 settings.json 裡的那種 hook，後者如今被 Claude Code 稱為 settings hook。

mod、settings hook、技能還是 MCP 伺服器

這四者有重疊，而 mod 是其中最重的。選能完成任務的最輕的那個。

一個外掛可以同時裝下這四樣，所以 mod 可以和它配合的技能、MCP 伺服器一起發布。

mod 的三個檔案

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

plugin.json 是常規的外掛清單：名稱、版本、描述。hooks.json 指向程式碼，{ "modules": ["./register.ts"] }，寫一個相對於該檔案的路徑。register.ts 就是 hooks module。Claude Code 直接載入 .js 和 .ts，不需要打包器，也沒有建置步驟，唯一允許的裸匯入是 claude-code，用於型別和幾個輔助函式。

我們發布的 mod：這個檔案是誰改的？

AgentsRoom 在同一個儲存庫上執行多個編碼代理，並在「更改」分頁裡顯示哪個代理改了哪個檔案，這樣你就能單獨審查並提交每個代理的工作。用 Claude 的 Edit 和 Write 工具寫的檔案很好辦：Claude Code 會透過 settings hook 報告它們。用 shell 命令寫的檔案就不行了。sed -i、heredoc、codemod 或 rm 都不經過任何檔案工具。

在有 mod 之前，我們靠猜。AgentsRoom 讀取代理的會話記錄，得知每條 Bash 命令何時開始、何時結束，再拿檔案的修改時間去對這些時間視窗。大多數時候管用，但有三種說得出名字的失敗：

• 被刪除的檔案沒有修改時間，所以刪除從來沒被歸屬；
• 像 grep 這樣的唯讀命令也會開啟一個時間視窗，代理在這期間可能寫了任何東西；
• 它依賴會話記錄的格式，而 Claude Code 可以隨意改變這個格式。

mod 消除了猜測。我們的 agentsroom-changes mod 為兩個 shell 工具掛鉤 tool.call。命令執行前一刻，它給儲存庫拍一張快照（git status，加上每個有改動路徑的大小和修改時間）；執行後一刻，再拍一張。有差異的路徑就是這條命令改動的內容，刪除也包括在內，mod 透過一個本地 HTTP 端點把它們發給 AgentsRoom 桌面應用。被 Claude Code 自己標記為唯讀的呼叫不認領任何檔案。

下面是精簡後的 hook。完整檔案有 177 行，大部分是快照及其上限的處理。

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
  });
};

桌面應用把 mod 複製到自己的資料夾裡，並且只在已安裝的 Claude Code 為 2.1.287 或更新版本時，用 claude --plugin-dir <that folder> 啟動每個 Claude 代理。我們在 2026 年 10 月 5 日的 AgentsRoom 1.201.0 中發布了它。

發布過程中學到的

mod 絕不能讓使用者損失一次工具呼叫。 我們的 hook 擋在 Claude 執行的每條 shell 命令前面。它一旦拋錯或等待網路，Claude 的工作就會停下。每一步都有保護，每次發往桌面應用的請求都是發出即不管，我們唯一接受的等待是兩次 git status 快照，每次上限 15 秒。丟掉一次請求只損失一次歸屬，絕不會損失命令本身。

不需要你的時候，什麼都別做。 mod 會讀取 AgentsRoom 為它的代理設定的一個環境變數。如果沒有這個變數，比如有人把資料夾複製到了自己的環境裡，每個 hook 都會直接走 next(e)。

用 --plugin-dir 載入的資料夾會被監視。 資料夾裡的檔案一變，Claude Code 就會重新載入 mod，而每次重新載入都會再執行一次 register。這決定了我們的安裝方式：桌面應用只在內容變化時才寫 mod 檔案，因為每次啟動代理都無腦重寫一遍，會讓每個已經開啟的 Claude 主控台都重新載入這個 mod。

做好 API 會變的準備。 事件和方法可能在版本之間變化，文件自己也這麼說。從 --plugin-dir 載入 mod 時，Claude Code 會把當前執行版本的型別宣告寫進 .claude-plugin/types/；我們以它為準做型別檢查，而不是以某個網頁為準。而且如果某個版本不再載入我們的 mod，也不會壞掉什麼：mod 永遠不會報告就緒，AgentsRoom 就退回原來的會話記錄方法。

自己寫一個

有兩種入門方式。

讓 Claude 來寫。 在互動式 Claude Code 會話裡描述你想要的 mod（「在提示詞上方顯示當前 git 分支」）。Claude 會使用內建技能 plugin-authoring，把 mod 寫進這次會話的一個資料夾，Claude Code 會問你一次是否啟用 Claude 寫的 mod。答應之後，mod 會在這一輪結束時載入，之後每一輪改動它都會重新載入。

自己寫這三個檔案，然後：

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 會列印一行 hooks:，列出你的模組處理的事件，再列印一行 calls:，列出它呼叫的每個 mods API 方法。如果你本想處理的某個事件不在其中，Claude Code 也不會呼叫那個 hook。靜態分析有規則：每次呼叫都寫完整（$.ui.toast(...)，絕不寫 const ui = $.ui），事件名以字串字面量傳入，只透過相對路徑匯入你自己的檔案。

要分享一個 mod，就把它當作外掛來對待：直接傳送資料夾，或者把它列進一個外掛市場（一個帶 .claude-plugin/marketplace.json 的儲存庫），別人就能用 /plugin install <name>@<marketplace> 安裝。

現在就能讀的 mod

• Claude Code 內建：/plugin，Installed 分頁，Built-in 區域。其中包括 /diff 面板，以及把 AGENTS.md 當作專案指令讀取的載入器，Anthropic 把它們的原始碼連同測試公開在 anthropics/claude-code 儲存庫的 mods 資料夾裡。同樣內建、但要你啟用才會開啟的是 You should know，一個旁路代理，會指出你或 Claude 可能漏掉的東西。
• Anthropic 的示例，在 claude-code-playground 儲存庫裡：繪製在提示詞上方的上下文視窗預測，一個攔下有風險的 shell 命令並展示它會改動什麼的守衛，以及一條逐步回看上一輪編輯的 /replay 命令。
• 我們的，上文已介紹：一個完全沒有介面、只有一個 tool.call hook 的 mod。如果你需要的是資料而不是面板，這是個值得照抄的形態。

安裝別人的 mod 之前

mod 沒有沙箱隔離。它以你的權限執行：可以讀寫你的檔案，讀取你的環境變數和設定（包括 API 金鑰），啟動程式，發起網路請求，看到每一條提示詞和每一次工具呼叫，還能在詢問你之前就批准一次工具呼叫。即使你開啟了 Claude Code 的沙箱，它覆蓋的也是 Claude 執行的 Bash 命令，而不是 mod 啟動的程序。

所以安裝前先讀一讀。克隆這個 mod，對資料夾執行 claude plugin validate：hooks: 和 calls: 兩行會告訴你它監聽什麼、觸達什麼，而不執行任何東西。一個只在提示詞上方畫橫條的 mod，沒有理由呼叫 $.http 或 $.process。要停掉你安裝的所有 mod，可以用 --safe-mode 啟動單次會話，或者在 ~/.claude/settings.json 裡設定 "disableAllHooks": true。

mod 在哪裡執行

會繪製內容的 mod 應當檢查自己執行在哪裡，在什麼都不繪製的地方退回到文字。

在 AgentsRoom 中

你不用安裝任何東西：從 Claude Code 2.1.287 起，每個 Claude 代理啟動時都帶著這個 mod，「更改」分頁會在執行操作的代理旁邊，顯示它的每條 shell 命令建立、修改或刪除的檔案。在更舊的 Claude Code 上，AgentsRoom 照舊從會話記錄裡匹配 shell 寫入。

同樣的思路也在其他能支援的 CLI 中執行：oh-my-pi 有一個遵循同樣約定的擴展，其他 CLI 則照舊用以前的方式匹配 shell 寫入。如果你想更深入地利用 Claude Code 在每一步暴露的資訊，我們的 Claude Code hook 指南介紹了與 mod 並列的 settings hook。

常見問題

Claude Code 裡的 mod 是什麼？

mod 是一個包含 hooks module 的 Claude Code 外掛。hooks module 是一個 JavaScript 或 TypeScript 檔案，每當發生某件事，比如一次工具呼叫、一條提交的提示詞或螢幕某一部分要繪製時，Claude Code 都會在自己的程序裡呼叫它的函式。每個函式都可以放行事件、修改事件，或者自己處理它。正因如此，mod 才能繪製面板、新增命令，或者攔下一條有風險的 shell 命令。

使用 mod 需要哪個版本的 Claude Code？

終端裡需要 Claude Code 2.1.287 或更高版本，它於 2026 年 10 月 1 日發布，更新日誌裡寫著「Added Claude Mods」。Claude Desktop 應用的 Code 分頁從 2.1.286 起支援。在 VS Code 擴展裡，hook 可以執行，而要顯示 mod 繪製的內容，需要擴展 2.1.299 或更高版本。執行 claude --version 即可檢視。

mod 和 Claude Code hook 有什麼區別？

寫在 settings.json 裡的 hook 會在事件觸發時，在 Claude Code 外部執行一條 shell 命令、一個 HTTP 請求或一條提示詞。mod 的 hook 是在 Claude Code 內部執行的函式。它們能做 settings hook 做不到的事：在介面上繪製、新增無需 Claude 輪次就能執行的斜槓命令、改寫一次工具呼叫或不執行工具直接給出應答，以及在 hook 之間共享狀態。

安裝 Claude Code mod 安全嗎？

mod 沒有沙箱隔離。它以你的權限執行，可以讀取你的檔案和環境變數、啟動程式、發起網路請求，並批准一次工具呼叫。只安裝你信任的作者寫的 mod，並且先對資料夾執行 claude plugin validate：它會在不執行 mod 的情況下，列出 mod 掛鉤的事件和它發起的呼叫。

在哪裡能找到 Claude Code mod 的示例？

Anthropic 在 anthropics/claude-code 儲存庫的 mods 資料夾裡公開了部分內建 mod 的原始碼，比如 /diff 面板和 AGENTS.md 載入器，並在 anthropics/claude-code-playground 儲存庫裡提供示例 mod。本文介紹的 AgentsRoom mod 是第四類示例：一個沒有介面、只有一個 tool.call hook 的 mod。

可以關閉 mod 嗎？

可以。在 /plugin 的 Installed 分頁裡停用單個 mod，用 --safe-mode 啟動單次會話，或者在 ~/.claude/settings.json 裡把 disableAllHooks 設為 true，就能停掉你安裝的所有 mod，連同你的 settings hook 一起。--safe-mode 和 disableAllHooks 不會停掉內建 mod：它們要在 /plugin 裡逐個關閉。