Claude Mods の全体像 .

Mods とは.

Claude Code の振る舞いと見た目を、TypeScript / JavaScript の関数で書き換えるプラグインです。

土台は function hook という仕組みです。イベントごとに async 関数を登録し、Express や Koa のミドルウェアのように重ねて合成します。mod は「hooks/hooks.json がこのモジュールを 1 つ指しているプラグイン」で、配布もインストールも普通のプラグインと同じです。

従来の hooks との違い

• ・ターミナルは v2.1.287 以降、デスクトップアプリは v2.1.286 以降で既定でオン（フラグ不要）
• ・従来の settings の hooks はそのまま動きます。mod からは classic.PreToolUse などとしてフックできます

基本形.

モジュールは register(on, options) を export し、その中で on(イベント名, マッチャー?, フック) を呼びます。フックはすべて ($, e, next) の形です。

export function register(on) {
  on("tool.call", { tool: "Bash" }, async ($, e, next) => {
    if (e.command.includes("git push --force")) {
      return { deny: "force push は使わないでください" } // 本体の代わりに答える
    }
    const r = await next(e) // 後ろのフックと本体を実行
    $.ui.toast("Bash ran") // 結果を見てから反応する
    return r
  }).catch(($, e, next) =>
    next.called ? next(e) : { deny: "ガードが失敗したので止めました" })
}

next の 4 つの使い方

• return next(e) そのまま通す
• return next({ ...e, text }) 入力を書き換えて通す
• return { deny: "…" } 本体を動かさずに答える（拒否など）
• const r = await next(e); … 結果を見てから反応する・結果を書き換える

チェーン.

同じイベントにフックした mod は 5 つの tier に並び、外側から順に呼ばれます。下りで各 mod が e を書き換え、最後に Claude Code 本体（core）が既定の答えを出し、上りで各 mod が結果を書き換えます。外側にいるほど権限が強い と覚えておけば十分です。

1. prepend 組織ポリシー prependPlugins
2. user あなたが入れた mod ハッカソンで作るのはここ
3. append 組織ポリシー appendPlugins
4. builtin バイナリ同梱の mod sec-default, diff など
5. core Claude Code 本体 既定の答えを出す

組織は prepend と append の両端を持てます。個人の端末で作る mod は user tier に入ります。

イベント.

on("イベント名", マッチャー?, フック) で受け取ります。各イベントについて「いつ発火するか」と「フックで何を返せるか」をまとめました。マッチャーで対象を絞れます（例: on("tool.call", { tool: "Bash" }, …)）。

1 ターンの流れ

1. session.start 起動
2. prompt.submit 送信
3. turn.start ターン開始
4. turn.step モデルに問い合わせ
5. tool.call ツール実行前
6. tool.check 許可判定
7. ui.render 画面に描く
8. turn.complete ターン終了
9. session.end 終了

$ API.

$ はフックの第 1 引数で、mod が外の世界に触れる唯一の手段です。$.名詞.動詞(…) の形で、省略せずに書きます。呼び出しそれぞれもイベントなので、他の mod から横取りできます（on("fs.read", …) など）。

$.state と $.store の使い分け

引数と戻り値の正確な形は、mod を読み込むと .claude-plugin/types/claude-code/index.d.ts に書き出される型定義が正です。

描画.

on("ui.render", { component: "描画箇所" }, …) で、Claude Code の画面の決まった場所を自分の UI にできます。まず「どこに描けるか」を画面の図で見てから、使える要素と書き方を確認します。

よく使う 4 つの表示

• A ペイン $.ui.open({ id, title }) + ui.render { component: "Pane" } 全画面表示では横にドック、それ以外はプロンプト欄の上に開く。タブで複数持てる
• B 帯 ui.render { component: "AbovePrompt" } プロンプト欄の真上の一帯。Button や Input も置ける。全 mod で共有
• C ステータスライン $.ui.status(text) 画面下の行に短い文字列を出す。undefined で消す。どのフックからでも呼べる
• D トースト $.ui.toast(text) 通知バーに数秒だけ出す。どのフックからでも呼べる

どこに描けるか

青枠はハッカソンで特に使いやすい 2 か所（AbovePrompt と Pane）です。図はイメージです。

使える要素

const { Box, Text, Button } = $.ui.resolve(e) で取り出します。画面（e.surface）ごとに使える要素が違います。

書き方は 4 通り

• 包む const drawn = await next(e) を自分の Box の子に入れて、前後に足す
• 置き換える next を呼ばずに自分のツリーを返す
• props を変える next({ ...e, props: { ...e.props, … } }) で本体の描画に渡す値だけ変える
• 何もしない 描くものがないときは return next(e)

例: ツール結果の下に一行とボタンを足す（包む）

on("ui.render", { component: "ToolResult" }, async ($, e, next) => {
  const { Box, Text, Button } = $.ui.resolve(e)
  const drawn = await next(e) // 本体（と内側の mod）が描いたもの
  return Box({ flexDirection: "column", children: [
    drawn,
    Text({ dimColor: true, children: "↳ reviewed" }),
    Button({ label: "copy", hotkey: "c", onPress: () => $.ui.toast("copied") }),
  ] })
})

ペインを作る（公式サンプル）

コマンド登録 → ペインを開く → 値を書く → 描く、の 4 ステップです。ツール呼び出しを記録してサイドパネルに一覧します。

import { atom, read, update } from "claude-code"
import type { Register } from "claude-code"
import type { ToolCall } from "../types"

const PANE = "tool-calls"
const calls = atom({ plugin: "tool-calls", key: "calls" } as const, [])

export const register: Register = on => {
  // 1. コマンドを登録し、ペインを開く
  on("session.start", async ($, e, next) => {
    await $.command.register({ name: "tool-calls", description: "Show tool calls" })
    void $.ui.open({ id: PANE, title: "Tool calls" })
    return next(e)
  })

  // 2. 自作コマンドに答える
  on("command.run", { command: "tool-calls" }, async $ => {
    await $.ui.open({ id: PANE, title: "Tool calls" })
    return { text: "Tool calls pane opened." }
  })

  // 3. 値を $.state に書く（読んでいる描画が自動で描き直される）
  on("tool.call", async ($, e, next) => {
    await update($, calls, list => [...list, { id: e.tool_use_id, tool: e.tool }].slice(-200))
    return next(e)
  })

  // 4. ペインの中身を描く
  on("ui.render", { component: "Pane", requestId: PANE }, async ($, e) => {
    const { Box, Text } = $.ui.resolve(e)
    const list = await read($, calls)
    return (
      <Box flexDirection="column">
        {list.length === 0 && <Text dimColor>No tool calls yet.</Text>}
        {list.map(call => <Text>{call.tool}</Text>)}
      </Box>
    )
  })
}

// types/index.d.ts（plugin.json の "types" で指す）
export type ToolCall = { id: string; tool: string }

declare module "claude-code" {
  interface PluginState {
    "tool-calls": { calls: ToolCall[] }
  }
}

描画のルール

• ・要素は $.ui.resolve(e) から取り出す（グローバルにはない）。.tsx なら JSX でも書ける
• ・Pane と AbovePrompt は e.props.bodyColumns の幅に合わせて描く
• ・描画中に $.state.get した値は、$.state.set されると自動で描き直される。手動なら $.ui.invalidate("ui.render")
• ・描画中に $.state.set は呼べない。ボタンの onPress や別のイベントから書く
• ・検証に通らないツリー（その画面にない要素など）は描かれず、本体の描画に戻る。理由はトランスクリプトに薄字で出る
• ・描画が出るのはターミナルとデスクトップアプリ（Code タブ）。e.surface で出し分けられる

3 つの型.

作りたいもののほとんどは、次の 3 つのどれか、または組み合わせです。

export function register(on) {
  on("tool.call", { tool: "Bash" }, async ($, e, next) => {
    if (e.command.includes("git push --force")) {
      return { deny: "force push は使わないでください" } // 本体の代わりに答える
    }
    const r = await next(e) // 後ろのフックと本体を実行
    $.ui.toast("Bash ran") // 結果を見てから反応する
    return r
  }).catch(($, e, next) =>
    next.called ? next(e) : { deny: "ガードが失敗したので止めました" })
}

const turns = { plugin: "turn-counter", key: "turns" }

export function register(on) {
  on("turn.complete", async ($, e, next) => {
    const r = await next(e)
    if (!e.agentId) {
      const { value = 0 } = await $.state.get(turns)
      await $.state.set(turns, value + 1)
    }
    return r
  })

  on("ui.render", { component: "AbovePrompt" }, async ($, e, next) => {
    const { value = 0 } = await $.state.get(turns) // 描画中の get が購読になる
    if (value === 0) return next(e)
    const { Text } = $.ui.resolve(e)
    return Text({ dimColor: true, children: `このセッション ${value} ターン目` })
  })
}

export function register(on) {
  on("prompt.submit", async ($, e, next) => {
    const notes = await $.store.get("notes").catch(() => undefined)
    if (typeof notes !== "string") return next(e)
    // モデルだけが読む文脈を足す（画面には出ない）
    return next({ ...e, context: [...(e.context ?? []), notes] })
  })
}

はじめかた.

A. Claude に書いてもらう（最短）

1. Claude Code で /plugin-authoring を実行し、「こういう mod を作って」と頼む
2. 「Enable hot reloading for this session?」と聞かれたら Enable for this session を選ぶ
3. ターンが終わると読み込まれる。以降は修正を頼むたびにホットリロード
4. /plugin で読み込まれているか確認

B. 自分で書く

my-mod/
├── .claude-plugin/
│   └── plugin.json      { "name": "my-mod", "version": "0.1.0", "description": "…" }
├── hooks/
│   ├── hooks.json       { "modules": ["./register.ts"] }
│   └── register.ts      export function register(on, options) { … }
├── types/index.d.ts     $.state を使うときだけ（plugin.json の "types" で指す）
└── tests/*.test.ts      claude plugin test で実行

• claude --plugin-dir ./my-mod その 1 セッションだけ読み込む。保存するとホットリロード
• claude plugin validate ./my-mod フックしたイベント、呼んでいる $、拒否される箇所を一覧（--strict --json）
• claude plugin test ./my-mod *.test.ts を本物のランタイムで実行
• tsc -p ./my-mod 読み込み後に .claude-plugin/types/ に型が出るので型チェックできる
• /plugin · /reload-plugins 読み込み中の mod を確認 · 再読み込み

C. 配る

mod のリポジトリに marketplace.json を置けば、そのまま配布できます。

// .claude-plugin/marketplace.json（mod のリポジトリ直下）
{
  "name": "my-mods",
  "owner": { "name": "you" },
  "plugins": [{ "name": "my-mod", "source": "./" }]
}

使う側はターミナルの Claude Code で:

/plugin install my-mod --marketplace <owner>/<repo>

ハマりどころ.

• 読み込まれない 信頼していないフォルダでは、エラーも出さずに読み込まれません。/plugin で「1 mod active」と出るか確認します。
• $ は省略せず書く $.ui.toast(…) のように名詞と動詞をそのまま書きます。const ui = $.ui のような書き方や import() は読み込みで拒否されます。
• 状態の置き場所 保存のたびに register が再実行され、モジュール変数は消えます。画面に出す値は $.state、次回の起動でも使う値は $.store に置きます。
• 描画中は書けない ui.render の中で $.state.set は使えません。ボタンの onPress や別のイベントから書きます。
• 時間の上限 フック自身の実行は 1 イベント 10 秒まで（next や $ を待つ時間は数えない）。.catch は 1 秒です。
• ガードには .catch .catch がないと、フックが例外を投げたときに止めたかった操作がそのまま通ります。
• 変数名 h JSX はタグを h(…) の呼び出しに変換します。.tsx でローカル変数に h という名前を付けると描画が壊れます。
• $ の reject await した $ 呼び出しの reject を放置すると mod 全体が外れます。.catch で受けておきます。
• 名前 plugin.json の name を claude- で始めると validate で弾かれます。
• 描画が出る場所 描画が出るのはターミナルとデスクトップアプリ（Code タブ）。VS Code のチャットや claude -p ではフックだけが動きます。
• 組織の端末 Team / Enterprise や管理端末では sec-default が外側に入り、個人の mod が触れない箇所があります。v2.1.299 から /plugin と validate がスキップされたフックを表示します。

アイデア.

何を作るか迷ったときのたたき台です。右側は使う API の目安です。

最近の変更.

v2.1.296〜v2.1.299 で入った主な変更です。

• v2.1.299 $.prompt.media（添付画像・文書の中身を読む）と $.session.identity() を追加。どちらも managed settings で入れた mod だけが使えます。
• v2.1.299 Text に size · weight · mono · tabular を追加（bold は weight に置き換え予定）。Box の余白に xs〜xl の段階指定。
• v2.1.299 turn.start がサブエージェントとチームメイトのターンでも発火（メインでは e.agentId なし）。agent.spawn が終了したサブエージェントの再開でも発火（e.resume）。
• v2.1.299 skill.prompt の e にフロントマター・ソース・ファイルパス。session.append に queue の経路。
• v2.1.299 止められる操作は、フックに渡せないとき通さずに拒否する（fail-closed）。組織管理でスキップされたフックを /plugin と validate が表示。
• v2.1.296 $.http.fetch の 4 MiB 上限が HEAD を拒否しなくなった（2.1.299 で 204 · 205 · 304 も対象外に）。

API は early access で、リリースごとに変わることがあります。

リンク.

• 公式: Mods の概要
• 公式: Mod を作る
• 公式: リファレンス
• 組み込み mod のソース（anthropics/claude-code/mods）
• Claude Mods チートシート（1 枚の早見表）
• 解説記事: Claude Mods 完全ガイド