Claude Code mods入門｜作り方と最初の一歩

Claude Code に「mods」が入りました。つまり、Claude Code の見た目と動きを、短い JavaScript / TypeScript の関数で書き換えられるようになったということです。これまでの設定は、外部のコマンドを呼んで周りを整えるのが中心でした。mods では、Claude Code の内側で動く関数が、ツール呼び出しやプロンプトの送信に割り込み、画面にも描けます。

チームに一言で説明するなら、こうなります。「Claude Code 専用の拡張部品。プラグインの形で配る」。

この記事は、Claude Code の公式ドキュメントと公式の変更履歴（2026-10-05 時点）に基づきます。mod を実際に作って動かした実測は載せていません。

迷ったらこれ：3ファイルの小さな mod を1つ自作して、1セッションだけ読み込む

Claude Code を毎日使う人は、次の順で触るのが安全です。最初の5分でやることは、この3つだけです。

1. claude --version で v2.1.287 以降か確認する
2. 下の「始め方」の3ファイル（first-mod）をそのまま写す
3. claude --plugin-dir ./first-mod で1セッションだけ読み込む

理由は3つあります。

• v2.1.287 以降は標準で有効。環境変数などの事前設定は要りません
• mod の最小構成は3ファイル。Node.js のインストールもビルドも不要と公式に書かれています
• --plugin-dir なら1セッション限り。気に入らなければ次の起動で消えます

向かない人もいます。Claude Code をたまにしか使わない人、会社の管理設定で拡張が制限されている人は、無理に触る必要はありません。

Before → After

	これまで	mods が入った今
動きを変える	設定ファイルに書いたシェルコマンドが、Claude Code の外で動く	関数が Claude Code の内側で動き、入力を書き換えたり、ツールを実行せずに答えたりできる
画面を変える	できない	スピナーの横、プロンプトの上、質問ダイアログなどに描ける
配り方	設定ファイルを渡す	プラグインとして配る

mods とは何か：プラグインに入る「関数」

公式の定義では、mod は「見た目と挙動を変えるプラグイン」です。仕組みは次のとおりです。

• Claude Code は、ツール呼び出し、送信したプロンプト、画面の描画といったイベントが起きるたびに、mod が登録した関数（ハンドラ）を呼びます
• ハンドラはイベントを観察する、書き換える、肩代わりする（元の処理を呼ばずに答える）のどれかができます
• 実装の呼び名は hook です。「hook = ある出来事の前後に差し込む処理」と覚えれば足ります

mods は、Claude Code の CLI と、Desktop アプリの Code タブで動きます。ただし画面への描画が出るのは CLI と Desktop だけです。VS Code 拡張のチャット欄と claude -p（画面なしの実行）では、ハンドラは動いても描画は出ません。Desktop の WSL セッションでは動きません。

従来の hooks との違い

mods の前から、Claude Code には settings.json に書く hooks がありました。違いは「どこで動くか」です。

	mod	settings hook	skill	MCP サーバー
正体	Claude Code が自分のプロセスで呼ぶ関数	シェル・HTTP・プロンプト	指示を書いた SKILL.md	外部プロセス
画面に描けるか	できる	できない	できない	できない
書くもの	JS / TS	スクリプトと settings.json	Markdown	任意の言語
向く場面	ペイン・コマンド・イベントの書き換え	手元のスクリプトで止める・許す・記録する	同じ指示を毎回貼る	外部システムへ届く

settings hooks は非推奨になったわけではありません。mods と並んで動きます。すでに hooks で止めたり記録したりしているなら、そのままで構いません。hooks の使い方は、AIエージェント暴走対策の記事で扱っています。

標準機能の一部も mod でできている

Claude Code 自体にも組み込みの mod があります。/plugin の Installed → Built-in で確認できます。

組み込み mod	役割
cc-plugin-agents-md	AGENTS.md をプロジェクト指示として読む
cc-plugin-diff	/diff のペイン
cc-plugin-plugin-authoring	mod を作るためのスキル
cc-plugin-sec-default	組織管理の保護ガード
cc-plugin-telemetry	分析記録
cc-plugin-you-should-know	見落としの通知（後述）

GitHub の anthropics/claude-code/mods には、このうち agents-md、diff、sec-default、telemetry のソースが公開されています。書き方の実物として読めます。ただし README には「Early access」「API は予告なく変わることがある」とあります。ここで読んだ書き方が、将来そのまま通るとは限りません。

mods でできること

公式が挙げる使い道は5つです。

• 画面に描く：ペインやプロンプトの上に、タブ・ボタン・入力欄つきのバンドを出す
• Claude Code 自身の画面を差し替える：ツール行、スピナー、質問ダイアログなど
• ツール呼び出しやリクエストに割り込む：人に質問して止める、ツールを実行せずに答える、別のモデルへ送る
• コマンドを足す：ターンを起こさず即実行する /command
• 変数を共有する：同じ mod 内のハンドラ同士で値を持ち回る

公式サンプル3つ

公式は anthropics/claude-code-playground の claude-code/mods に、サンプルを3つ置いています。現状のまま共有されていて、サポートはありません。

サンプル	何をするか
token-weather	コンテキスト窓の残りの「予報」をプロンプトの上に描く
blast-radius	rm -rf や force push を止め、影響を表示して、続行・中止のボタンを出す
replay-theater	/replay で、直前のターンのファイル編集を順に再生する

「勝手に実行されて困るコマンドを、実行前に人間の目に通す」（blast-radius）、「長い作業でどれだけ文脈を使ったかが見える」（token-weather）といった場面に効きます。画面に描ける mod ならではの使い方です。

始め方と最小の書き方

1. 版を確かめる

claude --version

v2.1.287 以降が必要です。この版（2026-10-01）で「Claude Mods」が追加され、以降の 2.1.288 と 2.1.289 では mods 関連の修正と $.ui.selection() の追加が入っています。

発表前の情報には「環境変数 CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 が必要」という記述が残っています。これは早期アクセス期のものです。v2.1.287 以降では、この環境変数は無視されます。0 を設定しても mods は止まりません。

2. 3つのファイルを作る

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

それぞれの中身は次のとおりです。そのまま写して使えます。

.claude-plugin/plugin.json：プラグインの名前を name に書きます。

{
  "name": "first-mod"
}

claude- で始まるなど Anthropic 公式に見える名前は、検証（claude plugin validate）で失敗します。first-mod のような名前にしてください。

hooks/hooks.json：読み込むモジュールを modules に、相対パスで1つ書きます。

{
  "modules": ["./register.js"]
}

modules の行が無いと、mod は読み込まれません。拡張子は .js .mjs .cjs .jsx .ts .mts .cts .tsx が使えます。

register.js：読み込まれるモジュールです。ツールが呼ばれるたびに回数を数え、画面に通知を出します。値は普通の変数で持てます。

let calls = 0

export function register(on) {
  on('tool.call', async ($, e, next) => {
    calls += 1
    $.ui.toast(`tool calls: ${calls}`)
    return next(e)
  })
}

中身を何も変えずに next(e) を返しているので、Claude Code の動きは変わりません。足したのは回数を数えて表示する部分だけです。公式の最小例は、同じ回数を ui.render でスピナーの横に · tool calls: N… と出す形です。

3つの引数の役割は次のとおりです。

引数	中身
$	mods API。画面（ui）、ファイル、プロセス、HTTP など本体の機能への窓口
e	イベントの入力。凍結済みのデータで、直接は書き換えられない
next	次のハンドラ

動かし方は3通りです。

• 観察：中身を見て、そのまま next(e) を返す（上のコードがこれです）
• 書き換え：next({...e, …}) で変えた入力を渡す
• 肩代わり：next を呼ばず、{ deny: '理由' } などを返して止める

3. 読み込んで確かめる

claude --plugin-dir ./first-mod

1セッション限りの読み込みです。ファイルを保存するとホットリロードされます。/plugin に 1 mod active · first-mod のような行が出れば、読み込めています。

公式の first-mod（/tally コマンドつき）では、claude -p "/tally" --plugin-dir ./first-mod の出力例が first-mod: Claude has made 0 tool calls since this mod loaded と案内されています。

インストールした mod は版番号でキャッシュされます。手を入れながら作るときは --plugin-dir を使うのが公式の指示です。インストール済みの mod を編集しても、動くのはキャッシュ版です。

応用：入力を書き換える・止める・出力を伏せる

同じ register の形で、書き換えと肩代わりもできます。1つ目は、Bash に渡るコマンドの前後の空白を取り、rm -rf / を含むコマンドは実行させない mod です。.catch は、ハンドラが失敗したときも止める側に倒すための宣言です（理由は後述の「止める mod の落とし穴」）。

export function register(on) {
  on('tool.call', { tool: 'Bash' }, async ($, e, next) => {
    if (e.command.includes('rm -rf /')) {
      return { deny: '危険なコマンドなので止めました' }
    }
    return next({ ...e, command: e.command.trim() })
  }).catch(async ($, e, next) => ({ deny: '確認できなかったので止めました: ' + next.error.kind }))
}

2つ目は、出力の書き換えです。next(e) の結果を受け取ってから中身を変えて返します。ファイルを読む Read の結果から、sk- で始まる API キー風の文字列を伏せ字にします。

export function register(on) {
  on('tool.call', { tool: 'Read' }, async ($, e, next) => {
    const r = await next(e)
    if (r.deny || r.isError || r.result.type !== 'text') return r
    const content = r.result.file.content.replace(/sk-[a-zA-Z0-9]+/g, '[REDACTED]')
    return { result: { ...r.result, file: { ...r.result.file, content } } }
  })
}

どちらも、使うときは first-mod の register.js の中身をこのコードに置き換えるだけです。

Claude に作らせる方法

コードを書かなくても作れます。対話セッションで、欲しい mod を説明するだけです。公式の例は次のとおりです。

make a mod that shows the current git branch above the prompt

Claude は組み込みスキル plugin-authoring を使って書きます。手動で呼ぶなら /plugin-authoring です。書き先は ~/.claude/dev-mods/<セッションID>/ で、ホットリロードを有効にするか聞かれ、承認すると読み込まれます。/plugin の Installed タブで確認でき、オフにもできます。

注意が2つあります。

• Claude が書いた mod は、書いたセッションでしか読み込まれません。残したいときは、ディレクトリを自分の場所（例 ~/mods/git-branch）へコピーして、claude --plugin-dir で読みます
• 承認する人がいないセッション（claude -p、dontAsk）、ワークスペースが未信頼のとき、--safe-mode や組織設定で無効のときは、読み込まれません

プラグイン「You should know」

公式アカウントの @ClaudeDevs が案内している組み込みプラグインです。自作の first-mod とは別に、コードを書かずに試せます。Claude の出力から、見落としやすい重要な情報を拾って知らせます。

• 何をするか：長いタスクの間、横で動くサイドエージェントが見張り、見落としそうな重要事項があれば、プロンプトの上にメモで出す
• 有効にする：既定は無効です。次のコマンドで有効にします

/plugin enable cc-plugin-you-should-know@builtin

• 無効にする：/plugin から
• 出ないとき：/plugin → Installed → Show disabled に、組織で利用可能なら出ます。変更履歴によると、対象はAnthropic API を使うファーストパーティのセッションで、テレメトリがオンの場合です。契約や組織の設定によっては出ないことがあります

長いタスクを Claude に任せる場面向けの機能です。ただし上のとおり、契約やテレメトリの設定によっては何も出ません。最初の一歩は、確実に動く first-mod に絞るのがおすすめです。

入れる前に見ておく点

mod は自分の権限で動くコード

公式の説明を平たく言うと、mod は、あなたの権限で動くプログラムです。

• ファイルの読み書き、プロセスの起動、ネットワーク通信ができる
• 環境変数や設定ファイル（API キーを含む）が読める
• 送ったプロンプトと、すべてのツール呼び出しが見える
• プロンプトやツール呼び出しを書き換えたり、尋ねる前に承認したりできる
• モデルを呼んで、自分の利用枠を使える
• サンドボックスはない

許可プロンプトの表示だけは、変えられません。公式は「信頼できる作者・マーケットプレイスからだけ入れる」と明記しています。

mods 自体の追加料金は、公式ページに記載が見当たりません。ただし mod がモデルを呼べば、プランや API キーの利用枠は減ります。プランごとの使い勝手はClaude Code Pro/Max料金の記事、従量課金の備えは予算アラートの記事が参考になります。

入れる前の点検

他人の mod は、取得したファイルに対して次を実行できます。

claude plugin validate ./some-mod

hooks:（受け取るイベント）と calls:（呼ぶ API）の行が出ます。$.fs.*、$.process.*、$.http.fetch、$.env.get、$.model.complete、$.prompt.submit が並んでいたら、何をする mod か中身を読んでください。tool.call や prompt.submit を受け取る mod は、すべてのツール呼び出しとプロンプトが見えます。

「止める mod」の落とし穴

実行を止める mod を作るときは、失敗したら止まらず素通りする点に注意が必要です。

• ハンドラの持ち時間は 10 秒。ハンドラ自身のコードの稼働時間だけで、next や API 呼び出しの待ちは含みません
• prompt.edit は 50 ミリ秒、.catch は 1 秒
• 例外やタイムアウトが起きると、next を呼ぶ前なら Claude Code はそのハンドラを飛ばして続行します。止めるはずのコマンドが走ります

対策は、.catch で { deny: … } を返して、失敗時にも止める形にすることです。上の「応用」の1つ目のコードがこの形です。公式の書き方の骨組みは次のとおりです。

on('tool.call', { tool: 'Bash' }, guard)
  .catch(async ($, e, next) => ({ deny: '…' + next.error.kind }))

人に確認を求めて待つ間は、$.ui.ask の中で待てば制限に数えません。自前の Promise で待つと数えます。

組織の設定が先に効く

ハンドラは外側から順に呼ばれます。順序は、①組織の sec-default と組織が指定した mod、②ユーザーが入れた mod、③組織が後ろに足す mod、④組み込みの他の mod と本体、です。

sec-default は、組織の管理設定や deny ルールをユーザーの mod から守る組み込みガードで、ユーザーは無効化できません。読み込まれるのは、managed settings のあるマシン、または Team / Enterprise プランでサインインした場合です。組織は allowManagedModsOnly や disableSideloadFlags（--plugin-dir を拒否）で、個人の mod を締め出すこともできます。仕事用の環境では、--plugin-dir が通らない場合があります。

止め方

やりたいこと	方法
1つだけ止める	/plugin の Installed で無効化かアンインストール
1セッションの全 mod を止める	claude --safe-mode
全セッションで止める	~/.claude/settings.json に "disableAllHooks": true（settings hooks と status line も止まる）

組み込み mod は、上の方法では止まらず、それぞれ個別のスイッチがあります。

動かないとき

claude --debug のログで hooks module … loaded の行を探します。公式が挙げる原因は次のとおりです。

• 版が 2.1.287 未満
• hooks.json に modules がない
• 信頼プロンプトに答えていない
• --safe-mode で起動している
• インストール済みの mod を編集している（キャッシュ版が動く）

なお、Anthropic が遠隔で、インストール済みの mod を止める場合があります。この場合は手元の設定では戻せません。

今日やる3ステップ

1. claude --version で v2.1.287 以降か確かめる
2. first-mod の3ファイルを、上のコードのとおりに作る
3. claude --plugin-dir ./first-mod で読み込み、/plugin に 1 mod active · first-mod と出るのを確かめる

3は1セッション限りで消えるので、失敗しても戻す手間がありません。コードを書きたくなければ、Claude に「現在の git ブランチをプロンプトの上に出す mod を作って」と頼む方法もあります。契約や組織の設定で使える範囲は変わるため、仕事用の環境では管理者の方針も確かめてください。

3ファイルが動いたら、公式の mods 作成ガイドの first-mod で、/tally コマンドつきの形に広げられます。

もっと詳しく

配り方

数人なら zip かディレクトリを渡す方法があります。チームは自前の marketplace に載せ、組織は管理者が managed settings で配ります。誰にでも配るなら、公開 marketplace か Anthropic のディレクトリへの申請です。イベントやメソッドはリリースの間で変わりうるため、README には試した版を書いておくのが公式の勧めです。

テスト

claude plugin test を使うと、セッションもサインインもネットワークもなしで、*.test.ts を実行できます。

組織向けの設定一覧

設定	効果
allowManagedModsOnly	組織の mod のみ
allowManagedHooksOnly	組織の hooks のみ
disableSideloadFlags	--plugin-dir を拒否
prependPlugins / appendPlugins	組織が mod を前後に挿入

この表の4行の設定は、managed settings（組織の管理者が配る設定）に書いたときだけ有効です。個人が自分の環境で mod を止めたいときは、上の「止め方」の表を使います。

この記事で扱わなかったもの

SNS 上の第三者による作例や、コミュニティが配布する mod は、公式の記載がないため扱っていません。mod を探すときは、上の点検手順を通してから入れてください。