ai-docs

Mods overview

Properties1
tagsclaude-code, plugins, mods, hooks, security, permissions

原典: Mods overview ／ 日本語版

一行要約

mod は Claude Code のプロセスの中で動く JavaScript / TypeScript の event handler を持つ plugin で、settings hook・skill・MCP サーバにできないこと（画面を描く、ツール呼び出しやプロンプトを書き換える、確認の前に承認する）ができる。その代わり、あなたの権限でサンドボックス無しに動く。

要点

何ができるか —— 外ではなく中で動く

Settings hooks, skills, status lines, and MCP servers work from outside Claude Code: each one runs a script, or gives Claude text or tools. A mod runs inside Claude Code, so it can do things they can’t:

settings hook・skill・status line・MCP サーバは Claude Code の外から働く。どれもスクリプトを走らせるか、Claude にテキストやツールを渡すだけである。mod は Claude Code の中で動くので、それらにできないことができる。

  • 使える画面を描く —— transcript の横のペイン、プロンプトの上の帯（タブ・ボタン・テキスト欄）
  • Claude Code 自身の画面を描き直す —— ツール呼び出しの行、スピナー、Claude が質問するダイアログ
  • ツール呼び出しやリクエストに割り込む —— 確認を挟んで保留する、ツールを走らせずに答える、1つのリクエストだけ別のモデルに送る
  • コマンドで自分のコードを走らせる —— Claude のターン無しで、Claude が作業中でもすぐ走る /command
  • hook どうしでデータを共有する —— 同じファイルの変数を共有するので、ある hook が数えたものを別の hook が表示できる

用語: これらのページでは “hook” は mod の handler を指し、設定ファイルに書く従来の hook は “settings hook” と呼ぶ。

mod が届く範囲（入れる前に知る）

A mod is code that runs with your permissions. It can read and write your files, start processes, and make network requests. Install mods only from authors and marketplaces you trust.

mod はあなたの権限で動くコードである。ファイルを読み書きし、プロセスを起動し、ネットワークに出られる。信頼できる作者と marketplace からだけ入れよ。

読み込まれた mod ができること: あなたとしてマシン上で動く、秘密を読む（環境変数と設定ファイル。そこに置いた API キーも）、セッションを見る（送ったプロンプトと Claude のツール呼び出しすべて）、セッションを変える（プロンプトやツール呼び出しの書き換え、あなたが打ったかのようにプロンプトを送る、別のセッションにメッセージを送る）、聞かずに動く（確認の前にツール呼び出しを承認する）、使用量を使う（あなたのプランか API キーでモデルを呼ぶ）。

Mods aren’t sandboxed. If you turn on sandboxing, the sandbox isolates the Bash commands Claude runs, and a process that a mod starts runs outside it.

mod はサンドボックスに入らない。 sandboxing を有効にしても、隔離されるのは Claude が走らせる Bash コマンドであり、mod が起動したプロセスはその外で動く。

ツール呼び出しを承認する mod は、ask ルールが確認を出すはずの呼び出しも、自分の PreToolUse hook が止めた呼び出しも承認できる（deny ルールまで覆せる条件は permissions と mods-admin）。確認プロンプトだけは描き直せない —— プロンプトが見せる内容は変えられない。

入れる前に中身を一覧できる: plugin のディレクトリに claude plugin validate を走らせると、hooks: 行（扱うイベント）と calls: 行（Claude Code に頼むこと —— ファイル読み取り、ネットワークなど）が、実行せずに出る。

入れる・止める

  • 入れ方は plugin と同じ（/plugin install <name>@<marketplace>）。セッション中にシェルから入れたら /reload-plugins
  • mod は既定でオン。端末は v2.1.287 以降、Desktop アプリの Code タブは同梱の Claude Code が v2.1.286 以降
  • 止め方は範囲で選ぶ —— 1つなら /plugin の Installed タブで無効化・アンインストール、1セッションだけ全部なら --safe-mode（他のカスタマイズも止まる）、全セッションで自分が入れた全部なら ~/.claude/settings.json に "disableAllHooks": true（settings hook と status line も止まる。組織が管理するものは走り続ける）
  • 早期アクセスで CLAUDE_CODE_ENABLE_FUNCTION_HOOKS を設定していたら消す —— v2.1.287 以降は無視されるので、0 にしても mod は止まらない
  • 読み込まれた mod は /plugin のタブの下の薄い行（1 mod active · first-mod）で分かる

仕組み

小さな mod は3ファイル —— plugin.json（マニフェスト）、hooks/hooks.json（コードの場所を指す）、register.js（hooks module）。hook はイベントに対して Claude Code が動く前に走るので、observe（見て通す）・rewrite（変えて通す）・answer（自分で処理し、通常の動作を走らせない）のどれかを選べる。

To do anything outside its own code, such as draw, add a command, call a model, read a file, start a process, or make a network request, a hook calls the mods API. A hook has no other way to do those things, which is why Claude Code can list what a mod does before you install it.

描く、コマンドを足す、モデルを呼ぶ、ファイルを読む、プロセスを起動する、ネットワークに出る —— 自分のコードの外で何かをするには、hook は mods API を呼ぶ。他に方法は無い。だから Claude Code は、入れる前に mod が何をするかを一覧できる。

どこで動くか

どこで Claude Code を走らせるかhook が走る描いたものが出る
端末の claude（エディタの統合ターミナル、JetBrains plugin を含む）YesYes
Desktop アプリの Code タブ（WSL セッションを除く）YesYes（端末専用の要素を除く）
Desktop アプリの WSL セッションNo（WSL では plugin が使えない）No
VS Code 拡張のチャットパネルYesNo
claude -p と Agent SDKYesNo
Remote Control自分のマシンのセッションで Yes自分のマシンの端末に
cloud セッションクラウドに届く plugin なら YesNo

mod・settings hook・skill・MCP サーバの使い分け

modsettings hookskillMCP サーバ
正体Claude Code が自プロセスで呼ぶ plugin 内の関数ライフサイクルのイベントで走るシェルコマンド・HTTP・プロンプトClaude が読む指示の SKILL.mdClaude にツールを渡す外部プロセス
変えられるものツール呼び出し、プロンプト、コマンド、ターン、画面に描くものツール呼び出しやプロンプトを通すか、引数と結果、Claude への contextClaude が知ること・することClaude が持つツール
選ぶときペイン・帯・独自コマンドが欲しい、イベントを書き換えたい手元のスクリプトで止める・通す・記録する同じ指示を何度も貼っている外部システムに届く必要がある

Claude Code に組み込まれた mod

/plugin の Installed タブの Built-in に出る。更新もアンインストールもできない。 cc-plugin-agents-md（AGENTS.md をプロジェクト指示として読む）、cc-plugin-diff（/diff のペイン）、cc-plugin-plugin-authoring（mod を書く plugin-authoring skill。mod のコードは持たない）、cc-plugin-sec-default（組織が管理するものを、ユーザーが入れた mod から守るガード。ユーザーは切れない）、cc-plugin-telemetry、cc-plugin-you-should-know（長いタスクの間に横で見張る side agent。既定で無効）。

The settings and flags that stop installed mods, such as disableAllHooks, --bare, and --safe-mode, don’t stop built-in mods.

disableAllHooks・--bare・--safe-mode のように入れた mod を止める設定やフラグは、組み込みの mod は止めない。

そのまま使える具体例

claude plugin validate ./some-mod     # 入れる前に hooks: と calls: を確認する（実行しない）
claude --safe-mode                    # このセッションだけ、入れた mod を全部止める
claude --plugin-dir ./token-weather   # サンプル mod を1セッションだけ試す
/plugin install token-chart@your-org
/plugin enable cc-plugin-you-should-know@builtin

原典で言及されている関連文書

バックリンク