ai-docs

Getting started with Claude Code mods

Properties1
tagsclaude-code, mods, plugins, hooks

原典: Getting started with Claude Code mods

一行要約

mod はAPI を覚えなくても、見たいものを説明すれば Claude が書き、hot reload で即座に動く。作例（context の残りを天気予報で出す Token Weather、危険なコマンドを保留する Blast Radius、直前のターンの編集を再生する Replay Theater）から、状態は $.state に置く・e.props を読む・描くものが無ければ next(e) で譲るという習慣と、コマンド文字列を見張る mod は安全網であって権限の仕組みではないことを示す。

要点

mod とは

Claude Code already lets you change a lot about how it behaves: settings, permission rules, slash commands, skills and a status line. Mods go further: they can rewrite or replace what Claude Code does, and draw custom UI. Under the hood, mods are hooks that ship inside plugins, and each one sees every event in your session as it happens.

Claude Code はすでに多くの振る舞いを変えさせてくれる —— 設定、permission ルール、スラッシュコマンド、skill、status line。mod はさらに先へ行く。Claude Code がすることを書き換えたり置き換えたりでき、独自の UI を描ける。 中身は plugin に入った hook で、それぞれがセッションのあらゆるイベントを起きたときに見る。

settings hook との違い: settings hook はイベントごとにシェルコマンドを走らせ、stdin と stdout で JSON を渡す。mod は1回読み込まれてセッションに居続ける —— 状態を持ち、イベントに合わせて更新される UI を描き、Claude Code を呼び返せる（ペインを開く、プロセスを走らせる、スラッシュコマンドやモデルが呼べるツールを登録する）。原典の言い方では、モジュールは「a sandbox of its own, with no DOM and no Node」で走り、外のものはすべて $ を通る。これは実行環境の話で、権限の隔離ではない。mods-overview と mods-admin は「Mods aren’t sandboxed」「None of these controls sandboxes a mod」と書き、mod はユーザーとしてファイル・プロセス・ネットワークに触れる。

一番の近道 —— Claude に書かせる

Notice that the prompt only describes what you want to see. You don’t need to know the API to write one.

prompt が説明しているのは、見たいものだけであることに注意してほしい。書くのに API を知っている必要は無い。

claude でセッションを始めて欲しい mod を説明し、hot reload を許可すると、ターンの終わりに出てくる。以後は「Storm を70%からにして」のように頼めば、その場で読み直される。このセッションでしか読まれず、フォルダは後で掃除されるので、残すならフォルダを外にコピーして plugin として入れる。

自分で書くときの要点

  • Claude Code v2.1.287 以降。mod は既定でオン。API はリリースごとに変わりうるので、Claude Code が mod の .claude-plugin/types/ に書く型宣言が、その版の正
  • 構成: .claude-plugin/plugin.json、hooks/hooks.json（modules にモジュールを1つ）、register(on, options) を export するモジュール。on(event, matcher?, hook)、hook は ($, e, next)
  • 描くには $.ui.resolve(e) で要素のコンストラクタを得る（描く面ごとに使える要素が少し違うので、グローバルではない）
  • $.session.usage() は status line と同じ数字を返す（context の使用量）
  • 値はモジュール変数ではなく $.state に —— hot reload は新規の読み込みなので、register が走り直し session.start が再び発火し、モジュール変数は初期化される。$.state はホストが保持するので残る。宣言は plugin の型の契約（.d.ts）に書く（書かないと claude plugin validate が直し方を名指しして止める）。描画中の $.state.get はその描画を購読するので、後の $.state.set で自動的に描き直される
  • claude plugin validate が hook と呼び出し、state の読み書きを一覧し、claude plugin test が本物のランタイムで *.test.ts を走らせる（テストで登録した hook は mod の後に走り、Claude Code の応答を差し替える）

作例が教えること

  • Blast Radius（rm -rf・git reset --hard・force push・DB の migration などを保留し、何に触れるかをペインに出して Proceed / Cancel）—— $.process.run で dry run（argv 配列で渡すのでパスがシェルとして走らない）、hook には1回の dispatch につき10秒の持ち時間があるが、$ の呼び出しの中で待つ時間は数えられない、ペインが置けないときは帯に落とす

It’s a safety net, not a permission system. It reads the command text, so $(…), aliases and scripts that call rm get past it. Use permission rules for a hard block.

これは安全網であって、権限の仕組みではない。 コマンドの文字列を読むので、$(…)・エイリアス・rm を呼ぶスクリプトはすり抜ける。確実に止めるなら permission ルールを使え。

  • Replay Theater（直前のターンの Edit / Write を1つずつ diff で再生）—— 止めも変えもせず観察だけ、turn.start と turn.complete でターンごとにまとめ、e.agentId で subagent のターンを外す、$.command.register でスラッシュコマンドを足す、Write の直前に $.fs.read で元の中身を読む

4つの習慣

  1. Claude Code が書く型に頼る（エディタと tsc -p がそのまま動く）
  2. props は e.props から読む（hasSurvey や bodyColumns。e の直下ではない）
  3. hot reload を前提に、データは $.state に
  4. 描いたものが出ないときはログを読む（claude --debug で、検証に通らない木を返した hook の行を探す）

共有

mod は plugin なので、配り方も同じ（marketplace のファイルを置いた GitHub リポジトリ）。

A mod is code that runs inside Claude Code on your machine, with the same access Claude Code has, and it’s written by its publisher, not Anthropic. So install mods the way you’d install a package: read the repo first and only install from people you trust.

mod は自分のマシンの Claude Code の中で、Claude Code と同じアクセスで動くコードで、書いたのは公開者であって Anthropic ではない。だから mod はパッケージを入れるように入れよ —— まずリポジトリを読み、信頼する人のものだけを入れよ。

Claude のディレクトリは mod を含む plugin を受け付ける（claude.ai/directory/manage から申請）。

そのまま使える具体例

Claude に書かせる prompt（原典そのまま）:

Make me a Claude Code mod called token-weather: a live forecast of my context window, shown in the band above the prompt. What it should show, on one line:
- A weather icon and word for how full the context window is: under 25% ☀ Clear (yellow), 25–49% ☁ Cloudy (cyan), 50–74% ☂ Showers (blue), 75–89% ☇ Storm (magenta), 90% and up ↯ Compact soon (red).
- The percentage used, then the tokens used out of the window, like "134.4k / 200k".
- A small chart of the last 12 turns, drawn with ▁▂▃▄▅▆▇█.
- How much the last turn added, like "▲ +98.3k last turn".
It should update after every turn.
claude --version                          # 2.1.287 or later
claude --plugin-dir ./token-weather       # フォルダを監視し、保存ごとに読み直す
claude plugin validate ./token-weather
claude plugin test ./token-weather
claude --debug                            # 描いたものが出ないとき
/plugin marketplace add your-org/my-mods
/plugin install token-weather@my-mods
/reload-plugins

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

（原典は他の sources へのリンクを本文に持たない。mod の正典は mods-overview）

バックリンク