ModsCode日本語ブログ Claude から Mod のコード例を探す

ModsCode / 日本語ブログ / Claude Code Mods 用語集:フック・matcher・ペインなど

Claude Code Mods 用語集:フック・matcher・ペインなど

Claude Code の Mods に出てくる用語の日本語用語集。Mod、フック、hooks module、matcher、Mods API、ペイン、tier、managed settings など 35 語を一言で説明します。

Claude Code の Mods のドキュメントは、英語の用語がそのまま並びます。ここでは、公式ドキュメントに出てくる用語を、日本語で一言ずつ説明します。公式の原文は Mods のリファレンス にあり、この用語集はそこで使われている語に合わせています。

基本の言葉

Mod

Claude Code の見た目と動きを変える、プラグインの一種です。JavaScript または TypeScript のイベントハンドラ(フック)を持ちます。

プラグイン

Claude Code に機能を足す配布の単位です。Mod 以外に、スキル、サブエージェント、MCP サーバーなども同じプラグインに入れられます。Mod は、その中に modules を持つものです。

マニフェスト(plugin.json)

プラグインの名前、バージョン、説明を書くファイルです。.claude-plugin/plugin.json に置きます。Mod だからといって追加で必須になる項目はありません。

フック(hook)

イベントが起きたときに Claude Code が呼ぶ関数です。Mod のコードは、このフックを登録することでできています。なお、Claude Code の「設定ファイルのフック」も同じ名前で呼ばれるので、次の項と区別してください。

設定フック(settings hook)

settings.json などの設定ファイルに書く、シェルコマンド、HTTP リクエスト、プロンプトの形のフックです。公式ドキュメントでは、Mod の関数を単に「フック」、設定ファイルのものを「設定フック」と呼び分けています。

フックモジュール(hooks module)

Mod の入口になるコードのファイルです。hooks/hooks.json の modules が指します。register 関数を書き出します。ファイルの拡張子は .js、.mjs、.cjs、.jsx、.ts、.mts、.cts、.tsx が使えます。

register と on

register(on, options) は、Mod の読み込み時に 1 回呼ばれる関数です。引数の on を呼ぶたびに、フックが 1 つ登録されます。options には、plugin.json の userConfig で宣言した設定値が入ります。

Mods API($)

フックの最初の引数 $ です。画面に描く、コマンドを足す、ファイルを読む、プログラムを動かす、通信する、モデルを呼ぶなど、Mod が外に働きかける方法は、すべてここにあります。$.ui、$.fs、$.process のように名前空間に分かれています。

イベント(e)

フックの 2 番目の引数です。ツール名とその引数、入力したプロンプトなど、起きたことの内容が入っています。読み取り専用で、変えたいときは複製を作って next に渡します。

next

フックの 3 番目の引数で、イベントを次のハンドラに渡す関数です。次は別の Mod のフックで、いちばん最後が Claude Code 自身の動きです。next(e) は結果に解決されます。フックが next をどう使うかで、観察、書き換え、代わりに答える、の 3 つに分かれます。

matcher

on の第 2 引数に渡す絞り込みの条件です。{ tool: 'Bash' } のように書くと、イベントの項目が一致したときだけフックが呼ばれます。値、値の配列、正規表現のどれかが使えます。

イベント

tool.call

Claude がツールを使う直前のイベントです。フックは、通す、引数を変える、{ deny: 理由 } で拒否する、{ result } で代わりに答える、ができます。

tool.check

ツール呼び出しを実行してよいかを決めるイベントです。権限ルールと設定フックが決めたあとに呼ばれ、allow、ask、deny のいずれかを返せます。

prompt.submit

プロンプトが送信されるときのイベントです。書き換える、Claude だけが読める文脈を足す、送信を止める({ drop: 理由 })ができます。

session.start

セッションの開始時に、最初のプロンプトの前に呼ばれるイベントです。Mod の再読み込み後にも呼ばれます。コマンドやツールの登録は、ここで行います。

command.run

Mod が足した /コマンド が実行されるときのイベントです。{ text } を返すと、その文字が画面に出て Claude にも読まれます。

turn.step と turn.complete

「ターン」は、1 回のプロンプトに Claude が答えるまでの全体です。turn.step はモデルへの 1 回のリクエストの直前、turn.complete はターンの終わりに呼ばれます。トークンの使用量を読む、リクエストを別のモデルに向ける、などに使います。

ui.render

Claude Code が画面の一部を描く直前のイベントです。フックは描く内容(要素の木)を返します。

classic.Stop などの classic.〜

設定フックのイベントを、Mod から扱うための名前です。classic.Stop や classic.PostToolUse のように、classic. の後に設定フックのイベント名が続きます。

画面に関わる言葉

レンダーサイト(render site)

Mod が描ける場所、または描き換えられる場所のことです。ペイン、プロンプトの上の帯(AbovePrompt)、スピナー(Spinner)、ツール呼び出しの行(ToolUse)、質問ダイアログ(AskUserQuestion)などがあります。

ペイン(pane)

トランスクリプトの横のサイドバー、または、狭い端末ではプロンプトの上の枠です。$.ui.open で開き、ui.render でその中身を返します。

帯(band)

プロンプト入力の真上にある細い領域です。常にあり、すべての Mod が共有します。

スピナー(spinner)

Claude が作業している間に動く、1 行の表示です。Mod は、その語の後ろに文字を足したり、置き換えたりできます。

トースト(toast)

しばらくして消える通知です。$.ui.toast で出します。デフォルトの表示時間は 4 秒です。

要素(element)と木(tree)

ui.render のフックが返す、画面の組み立て部品です。Box、Text、Button、Input、Select、Code、Markdown などを入れ子にして木にします。ターミナルとデスクトップアプリで使える要素は違います。

サーフェス(surface)

Mod が今どのアプリで動いているかを表す値です。terminal か desktop です。

状態の保存

$.state

画面の状態を持つための、反応型の値です。/clear、/resume、/branch でデフォルトに戻ります。

$.store

Mod 専用の JSON のキーバリュー保存場所です。セッションをまたいで残り、同じマシンのすべてのセッションで共有されます。合計 4 MiB までです。

読み込みと安全に関わる言葉

--plugin-dir

プラグインのフォルダを、インストールせずに 1 セッションだけ読み込むフラグです。保存すると自動で再読み込みされます。

ホットリロード(hot reload)

ファイルを保存したときに、セッションを閉じずに Mod を読み込み直す仕組みです。再読み込みのたびにモジュールの変数は初期化されます。

tier

Mod が走る順番のグループです。prepend(組織が先に走らせる)、user(ユーザーがインストールした)、append(組織が後に走らせる)、builtin(Claude Code 内蔵)の 4 つです。先に走る Mod が、イベントを先に見て、結果を最後に見ます。

ビルトインのガード(sec-default)

Claude Code に内蔵された Mod で、/plugin では cc-plugin-sec-default と表示されます。管理設定のあるマシン、または Team / Enterprise プランでサインインしているユーザーでは、ユーザーの Mod より先に読み込まれ、組織が管理するものをユーザーの Mod から守ります。

管理設定(managed settings)

組織の管理者が配る設定です。ユーザーは変更できません。Mod の読み込みを制限する allowManagedModsOnly などはここに書きます。

--safe-mode

インストールした Mod とそのほかのカスタマイズを、1 セッションだけ無効にして起動するフラグです。問題が Mod のせいかどうかの切り分けに使います。

disableAllHooks

設定ファイルに書くと、インストールしたプラグインの Mod と、設定ファイルのフックをすべて止める設定です。組織の管理設定に書くと、組織が配った分まで止まります。

まとめ

用語を一通り見たら、実際に動くコードを見るのが近道です。最小の Mod を作る手順は 初めての Mod の作り方 にあります。全体像の説明は Mods とは です。