メインコンテンツへスキップ
mod は Claude Code 内に独自のインターフェースを描画したり、Claude Code がすでに描画しているインターフェースの一部を変更したりできます。mod が描画できる各場所は描画箇所と呼ばれ、ペイン、プロンプト上部の帯、スピナーなどがあります。Claude Code は描画箇所を描画しようとするたびに ui.render イベントを発火し、そのイベントに対するフックが、そこに描画する内容を返します。 次の図は、ターミナルセッション内で mod が描画できる場所を示しています。 フルスクリーン描画での Claude Code のターミナルセッションの図。mod は、右側のサイドバーとしてのペイン、トランスクリプト右上のトースト、トランスクリプト内のログ行、プロンプト上部の帯、プロンプト下のステータスラインを追加できます。mod はメッセージ、ツール呼び出しの行、スピナーを再描画できます。プロンプトは Claude Code 自身のものです。 フルスクリーン描画での Claude Code のターミナルセッションの図。mod は、右側のサイドバーとしてのペイン、トランスクリプト右上のトースト、トランスクリプト内のログ行、プロンプト上部の帯、プロンプト下のステータスラインを追加できます。mod はメッセージ、ツール呼び出しの行、スピナーを再描画できます。プロンプトは Claude Code 自身のものです。 幅の狭いターミナルでは、ペインはトランスクリプトの横ではなくプロンプトの上に配置されます。 ここから始める前に、最初の mod を作成してください。まず、2 つのタブとカウンターを持つペインを作成する実例から始め、その後、変更したい各要素のセクションを読んでください。
個々の props や制限を調べるには、リファレンスを参照してください。

タブ付きのペインを作成する

このセクションでは、/hello-tabs コマンドを追加する mod を作成します。このコマンドはペインを開きます。ペインは、幅の広いフルスクリーンのターミナルではトランスクリプトの横に表示されるサイドバーで、それ以外の場合はプロンプトの上に表示される枠付きの領域です。このペインには 2 つのタブが表示され、2 つ目のタブにはカウンターに 1 を加えるボタンがあります。カウントは Claude Code を再起動した後も保持されます。 完成した mod は次のようになります。この録画では、ペインを開き、2 つ目のタブに切り替え、ボタンを何回か押してから、1 つ目のタブに戻ります。
タブは横に並んだ 2 つのボタンです。mod はどちらがアクティブかを記録し、そのタブのコンテンツを行の下に描画します。
1

プラグインを作成する

mod は、マニフェスト、コードを指し示す hooks.json、そしてコードファイルを持つプラグインです。それぞれについては mod を作成するで説明しています。hello-tabs という名前のディレクトリを作成し、その中に .claude-plugin と hooks ディレクトリを作成してから、最初の 2 つのファイルを保存します。マニフェストを hello-tabs/.claude-plugin/plugin.json として保存します。
hello-tabs/.claude-plugin/plugin.json
hello-tabs/hooks/hooks.json でエントリポイントを指定します。
hello-tabs/hooks/hooks.json
2

コードを書く

次のリストは、各フックが何をするかをコード内に現れる順に示しています。
  • /hello-tabs コマンドを追加し、以前のセッションで保存されたカウントを読み込む
  • そのコマンドを実行したときにペインを開く
  • ペインのコンテンツ(タブの行と、開いているタブの本文)を描画する
モジュールレベルの 2 つの変数 tab と count がペインの状態を保持します。これを hello-tabs/hooks/register.js として保存します。
hello-tabs/hooks/register.js
各フックは、コードからは明らかでない処理も行います。
  • session.start は、セッション間で永続化されるキーバリューストアである $.store から保存されたカウントも読み込みます。
  • command.run は、ペインが存在することを Claude Code に伝えるだけです。ペインを開いただけでは何も描画されません。Claude Code はその後 ui.render を発火して、ペインに何を表示するかを問い合わせます。
  • ui.render は要素ツリー(他のボックス、テキスト、ボタンを保持する Box)を返し、実行されるたびに tab と count からツリーを構築し直します。
ボタンを押すとその onPress コールバックが実行され、変数が変更されて redraw が呼び出されます。すると Claude Code が ui.render フックを再度実行し、フックは新しい値から新しいツリーを構築します。インタラクティブな描画はすべてこのレンダーサイクルを使用します。つまり、コールバックが状態を変更し、フックが新しい状態から再びレンダリングします。
3

ペインを開く

シェルで claude --plugin-dir ./hello-tabs を実行して Claude Code を起動します。Claude Code のプロンプトで /hello-tabs を実行します。上部に 1: One と 2: Two が表示されたペインが開きます。2 を押してから、Add one のホットキーである a を何回か押します。カウントが増えます。
4

カウントが保存されたことを確認する

Esc を押してペインを閉じ、セッションを終了します。シェルで同じ claude --plugin-dir ./hello-tabs コマンドを使って Claude Code を再度起動し、Claude Code のプロンプトで /hello-tabs を実行します。カウントは中断したときの値のままです。カウントをクリアするには、mod から $.store.delete('count') を呼び出します。各種類の値がどれだけの期間保持されるかについては、状態を保持するを参照してください。

描画する場所を選ぶ

ui.render フックが描画する描画箇所を選ぶには、matcher と呼ばれるフィルターを on の 2 番目の引数として渡します。{ component: 'Pane' } を渡すと、フックはペインに対してのみ実行されます。フック内では、e.component が描画箇所の名前、e.surface が描画しているアプリ、e.props が描画箇所固有のデータを表します。ペインの場合、e.requestId はペインを開いたときの id です。 ペインとバンドは、mod が内容を描画するまで空です。タブを選択すると、それぞれが何であり、どのように描画するかを確認できます。
ペインは、幅の広いフルスクリーンのターミナルではトランスクリプトの横に表示されるサイドバーで、それ以外の場合はプロンプトの上に表示される枠付きの領域です。複数のペインが開いている場合は、それぞれにタイトルを表示するタブが付きます。ペインは、$.ui.open({ id: 'hello-tabs' }) のように、mod が任意の id を指定して $.ui.open を呼び出したときに表示されます。その他のフィールドや、ペインが幅の広いターミナルを待つ場合については、適切なタイミングでペインを開くを参照してください。ペインに描画するには、{ component: 'Pane' } でフィルターし、e.requestId が自分の id であることを確認します。
mod は、トランスクリプトに独自の行を配置することもできます。

Claude Code がすでに描画しているものを変更する

Claude Code は、メッセージ、ツール呼び出しの行、スピナーなど、インターフェースの大部分を自ら描画します。これらの各部分も描画箇所であるため、mod でスタイルを変更したり置き換えたりできます。変更するには、次の表にある名前で ui.render フックをフィルターします。 Pane、AskUserQuestion、Spinner、UserMessage、AssistantMessage、およびツール呼び出しの描画箇所は、ターミナル、Desktop アプリ、VS Code 拡張機能で機能します。その他の描画箇所がそれぞれどこで発生するかは、描画箇所の表に記載されています。 Claude Code がすでに描画している描画箇所では、フックで細部を変更したり、描画を置き換えたり、そのままにしたりできます。タブを選択すると、それぞれをスピナーに適用した例を確認できます。これらの例では、チュートリアルの mod と同様に、別のフックがカウントする calls 変数を読み取っています。
Claude Code の描画を維持したまま一部だけを変更するには、props を変更したイベントのコピーを next に渡します。次のフックは、スピナーの単語の後に続くテキストを変更します。
スピナーはアニメーションと単語を維持し、その単語の後に指定したテキストが続きます。
これらの描画箇所では、自分の mod より後に実行される mod が独自のツリーを返していない限り、next(e) は Claude Code の描画への参照 { type: 'engine', ref } を返します。その描画の内容を変更するには、細部を変更するタブのように、props を変更したイベントのコピーを next に渡します。参照はそのまま返すことも、独自の要素と並べて Box に配置することもできます。
Claude の作業中、スピナーはこれまでどおりアニメーションし、その下に under the spinner が表示されます。 権限プロンプトは描画箇所ではないため、mod でその表示内容を変更することはできません。質問ダイアログ AskUserQuestion は描画箇所であるため、Claude が質問するときに mod でそのダイアログを変更できます。ダイアログ用のツリーには参照をちょうど 1 回だけ含め、独自の要素はその上に配置する必要があります。そうでない場合、Claude Code は独自のダイアログを描画します。

適切なタイミングでペインを開く

ペインは mod が開いたときにのみ表示されます。どのように、いつ開くかによって、キーボードフォーカスを取得するかどうか、どれだけの領域を求めるか、幅の狭いターミナルで表示されるかどうかが決まります。 ペインを開くには、任意の id を指定して $.ui.open を呼び出します。id はペインの名前です。ui.render フックはこの id を確認し、ペインを閉じる際にも再度渡します。別の mod がその id でペインを開いている場合、呼び出しは拒否されます。
ペインを閉じるには、開いたときの id を指定して $.ui.close を呼び出します。
$.ui.open は id のほかに、次の省略可能なフィールドを受け取ります。 VS Code 拡張機能は rows と columns を無視し、ペインのサイズを自ら決定します。 focus、closeOnEscape、holdToasts は省略可能で、true のみを受け付けます。指定しない場合は省略してください。false を渡すと、ui.open: focus is true or left out のようなエラーがスローされます。これらのいずれかを条件付きで設定するには、条件が成り立つ場合にのみフィールドを追加します。次の呼び出しは、items が空でない場合にのみキーボードフォーカスを要求します。
Claude の作業中にコマンドでペインを開けるようにするには、コマンドを登録する際に immediate: true を追加します。これがない場合、ターン中に入力されたコマンドはターンが終わるまで待機します。

ダイアログの背後でトーストを保留する

ペインがユーザーが回答して閉じるダイアログである場合は、$.ui.open に holdToasts: true を渡すと、ユーザーが判断している間にトーストが表示されなくなります。ターミナルでは、そのペインが表示されている間は保留が続き、その間に発生したトーストは保留が終わるまで待機します。 Claude Code は、自分の mod が $.ui.toast で発生させるトーストだけでなく、他の mod のトーストや Claude Code 自身の短時間の通知も保留します。開いたままにするペインではこのフィールドを省略し、ユーザーがそれらを引き続き確認できるようにしてください。

ペインが幅の広いターミナルを待つ場合

ユーザーの操作なしに mod が開いたペインは、幅の狭いターミナルでは表示されないため、小さな画面を占有することはありません。表示されるかどうかは、何がペインを開いたかによって決まります。
  • ユーザーの操作によって開かれた場合(ユーザーが実行したコマンドや押したボタンなど)、ペインは幅に関係なく表示されます
  • mod が自ら開いた場合(タイマーや turn.start フックからなど)、ペインは幅が 144 列以上のターミナルでのみ表示されます。ユーザーがそのペインを一度自分で開いた後は、110 列あれば十分です。
ペインが表示されると、$.ui.open は { isPlaced: true } に解決されます。ペインが待機している場合、isPlaced は false になり、reason にはその理由を示す文字列が入ります。待機中のペインは、ユーザーがペインを開くかターミナルの幅を広げると表示されます。ペインを開かずに何かが利用可能であることを伝えるには、$.ui.toast('Your message') を呼び出してトースト通知を表示します。

VS Code 拡張機能で描画する

VS Code 拡張機能では、拡張機能のバージョン 2.1.299 以降で、mod が描画する内容がチャットパネルに表示されます。Amazon Bedrock 上のセッションなど、機能フラグを取得しないセッションでは、2.1.304 以降が必要です。パネル向けの ui.render フックでは、e.surface は vscode です。パネルがどの描画箇所と要素を描画し、どの props を無視するかについては、描画箇所と要素の表を参照してください。 mod をターミナルだけでなくパネルでも機能させるには、次の違いを考慮してください。
  • ペイン:幅が 800 ピクセル以上のパネルでは、ペインは会話の横にドッキングされ、e.props.placement は 'dock'、e.viewport.isFullscreen は true になります。それより狭いパネルでは、ペインはプロンプトボックスの上に描画され、placement は 'inline' になり、ペインは 12 行を表示した後にスクロールします。
  • トーストとステータスライン:これらはプロンプトボックスのすぐ上にある 1 つのスタックにまとめて配置され、パネルが狭い場合はペインも一緒に配置されます。ステータスラインは mod ごとに 1 つです。権限リクエストやダイアログが表示されている間、スタックは非表示になります。
  • ラベル:パネルは mod が描画または書き換えた内容を枠で囲み、From the token-chart plugin や Edited by the token-chart plugin のようにプラグイン名のラベルを付けます。
  • キーボード:ボタンにはホットキーがないため、ユーザーはボタンをクリックするか、ボタンにフォーカスがあるときに Enter キーを押します。
  • キーボードフォーカス:パネルがペインの focus: true 要求を受け入れるのは、パネルにフォーカスがあり、Claude がアイドル状態で待機中の質問がなく、プロンプトボックスが空の場合のみです。
  • 質問ダイアログ:AskUserQuestion では、パネルは独自の質問カードを維持し、その上に指定した要素を描画します。next に渡した props はカードを変更しません。
  • プロンプトの候補:パネルはプロンプトボックスの薄い候補テキストを Claude 自身の候補用に確保しているため、$.prompt.suggest は isShown: false で解決され、何も表示しません。
  • テキストの上限:パネルはステータスラインを 200 文字または 2 行で、トーストを 500 文字で切り詰めます。

トランスクリプトに行を配置する

行とは、ターミナルで mod がトランスクリプトの最新のメッセージの後に追加する 1 行です。会話が進んでもその位置にとどまり、Claude からは見えません。$.ui.place には Claude Code v2.1.314 以降が必要です。
1

行を配置する

id を指定して $.ui.place を呼び出します。id は、build-status のように行に付ける任意の名前です。1~64 文字の英字、数字、_、- で指定でき、mod がトランスクリプトに配置する行ごとに固有の id が必要です。
2

行を描画する

Placed 描画箇所で行を描画します。
次の例では、/build-status コマンドを追加します。ユーザーがこのコマンドを実行すると、mod は Build: passing を表示する行を追加します。例を短くするためにテキストは固定されていますが、実際の mod では独自の結果を描画します。
この例を試すには、このコードを mod に記述します。ターミナルのセッションで、Claude Code のプロンプトで /build-status を実行します。トランスクリプトの末尾に Build: passing が行として表示されます。 この呼び出しで常に行が表示されるとは限らず、行が後で消えることもあるため、mod で次のケースに対処してください。
  • 結果:ターミナルが行を描画した場合は { isPlaced: true, requestId } になります。それ以外の場合、isPlaced は false になり、reason には no attached surface draws placed rows yet のようにその理由が入ります。理由の 1 つに、mod が同時に持てる行数の上限があります。
  • 同じ id での 2 回目の呼び出し:最初の行がまだトランスクリプトにある間は、呼び出しは行を追加せず、その行の requestId で解決されます。行の表示内容を変更するには、行を再描画します。
  • 行が消えるとき:会話が終了したとき、ユーザーがその行より前まで巻き戻したとき、またはフルスクリーン描画以外で会話がコンパクト化されたときです。--resume では行は元に戻りません。行を再度表示するには、もう一度 $.ui.place を呼び出します。

会話の背後に背景を配置する

$.theme.set と $.theme.clear は、Claude Code v2.1.319 で削除された $.ui.backdrop を置き換えるものです。$.ui.backdrop({ id: 'your-backdrop' }) はこのセクションの例にあるような $.theme.set の呼び出しに、$.ui.backdrop(undefined) は $.theme.clear() に変更してください。$.theme.clear() は、どの mod の背景であっても削除します。
Desktop アプリまたはモバイルアプリで会話の背後に背景を配置するには、backdrop を指定して $.theme.set を呼び出し、Backdrop 描画箇所で背景を描画します。背景を外すには、$.theme.clear() を呼び出します。ターミナルは背景を描画しません。$.theme.set と $.theme.clear には Claude Code v2.1.319 以降が必要です。 この例には Claude Code v2.1.323 以降が必要なため、まずバージョンを確認してください。この mod は、セッションの開始時に背景を設定して描画し、背景を外す /plain コマンドを追加します。
v2.1.323 より前では、$.theme.set の呼び出しと e.props で scene の代わりに id を記述し、overrideColorScheme を colorScheme として backdrop 内に移動してください。
この例を試すには、このコードを mod に記述し、Desktop アプリまたはモバイルアプリでセッションを開始します。背景を外すには、Claude Code のプロンプトで /plain を実行します。トランスクリプトには mod の名前に続けて the theme is cleared が表示されます。たとえば、night-sky という名前の mod では night-sky: the theme is cleared と表示されます。 backdrop が受け取る内容、呼び出しの結果からわかること、他の mod が変更できることを確認してください。
  • backdrop のフィールド:scene は、フックが描画する背景に付ける任意の名前です。その他のフィールドと overrideColorScheme については、ビルドに対応する型を参照してください。
  • 背景が描画されるかどうか:セッションに接続された Desktop アプリまたはモバイルアプリが背景を描画すると応答した場合、$.theme.set は isDrawn: true で解決されます。それ以外の場合、isDrawn は false になり、reason にはその理由が入ります。
  • セッションごとに 1 つのテーマ:$.theme.set を呼び出す mod はセッションの背景と色を置き換え、$.theme.clear() を呼び出す mod はそれらを削除します。どの mod が設定したものであっても同様です。$.theme.clear() は、ユーザーが求めた場合にのみ呼び出してください。

Desktop アプリの色を変更する

mod で Desktop アプリの Code タブの色を変更するには、Claude に mod を依頼するか、自分で mod を書きます。どちらの方法でも Code タブで Claude Code v2.1.324 以降が必要なため、まずそこでバージョンを確認してください。ターミナルの Claude Code は独自の色を維持します。

色を変更する mod を Claude に依頼する

1

色を説明する

Code タブでローカルセッションを開始し、希望する色を Claude に伝えます。たとえば、make a mod that makes the app cream in light mode and dark brown in dark mode と入力します。Claude が mod のファイルを書きます。
2

mod を承認する

mod のファイルとホットリロードについて Claude Code が尋ねる質問に回答します。それぞれの回答の効果については、Claude に mod を依頼するを参照してください。
3

色を確認する

mod が読み込まれると、Code タブの色が変わります。色を調整するには、変更したい内容を Claude に伝えます。何も変わらない場合は、mod の色が表示されない場合の対処を参照してください。

色を変更する mod を自分で書く

makeColors は、いくつかの 16 進カラーからテーマを作成する関数です。次の手順では、これを使用する paper という名前の mod を作成します。
1

Claude に makeColors をコピーしてもらう

Code タブでローカルセッションを開始し、copy make-colors.js and make-colors.d.ts from your plugin-authoring skill into ~/.claude/skills/paper/hooks/ と入力します。両方のファイルがそのディレクトリにあることを確認してください。
2

マニフェストと hooks.json を保存する

mod を自分で書くから .claude-plugin/plugin.json と hooks/hooks.json を ~/.claude/skills/paper/ に保存し、両方のファイルで first-mod を paper に変更します。~/.claude/skills/ 配下の mod は、セッションを開始すると読み込まれます。
3

コードを書く

次のファイルを ~/.claude/skills/paper/hooks/register.js として保存します。セッションが開始されると、このコードはライトモードとダークモードの色を指定して $.theme.set を呼び出します。
独自の色を使用するには、16 進値を別の 6 桁の 16 進カラーに置き換えます。
4

色を確認する

Code タブで新しいローカルセッションを開始します。この例の値では、背景はライトモードではクリーム色、ダークモードでは濃い茶色になります。何も変わらない場合は、mod の色が表示されない場合の対処を参照してください。

Desktop アプリで mod の色が表示されない場合の対処

Claude Desktop v5.11492.5 以前で Claude アカウントの代わりにサードパーティプロバイダーを使用している場合、Code タブは独自の色を維持するため、次の確認は不要です。それ以外の場合で、mod の色が Code タブに表示されない、または消えてしまう場合は、次の原因を確認してください。
  • 古いバージョン:Desktop アプリを更新して再起動し、Code タブで新しいローカルセッションを開始します。Claude が mod を書いた場合は、そのセッションでもう一度依頼してください。
  • mod が読み込まれていない:Claude が mod を書いた場合は、Claude に mod を依頼するで mod が読み込まれるタイミングを確認してください。自分で書いた場合は、ファイルとそのパスを色を変更する mod を自分で書くと比較してください。
  • 拒否されたテーマ:mod の makeColors の呼び出しを実行するよう Claude に依頼します。呼び出しがエラーをスローした場合、または problems リストに Desktop won't paint this theme で始まる項目がある場合は、Claude にテーマを修正してもらいます。mod をインストールした場合は、Claude が見つけた内容を mod の作成者に送ってください。
  • 別の $.theme の呼び出し:セッション内のいずれかの mod が $.theme.set または $.theme.clear() を呼び出すと、以前の呼び出しで設定された色と背景は消えます。自分の mod では、colors と backdrop を同じ $.theme.set の呼び出しで渡してください。テーマを設定する mod は一度に 1 つだけ使用してください。

Desktop アプリから mod の色を削除する

Code タブから mod の色を外すには、まず mod をオフにします。オンのままの mod は、色を再び設定する可能性があります。
1

mod をオフにする

2

新しいセッションを開始する

Code タブで新しいローカルセッションを開始します。
3

残っている色を削除する

それでも色が残っている場合は、Code タブから Settings を開き、そこで code appearance を検索します。検索結果を開き、Remove colors を選択します。

要素からツリーを構築する

ui.render フックが返すのは要素ツリーです。これは描画する内容の記述で、ボックス、テキスト、コントロールを互いに入れ子にして構成します。描画内容を記述すると、Claude Code はユーザーが開いているアプリ(ターミナル、Desktop アプリ、VS Code 拡張機能のいずれか)でそれをレンダリングします。 要素を取得するには、フック内で const { Box, Text, Button } = $.ui.resolve(e) のように $.ui.resolve(e) を呼び出します。各要素は関数です。関数に props を渡し、その中に入れる要素や文字列を children に入れます。 タブを選択すると、最もよく使われる各要素と、ターミナルでの描画結果を確認できます。
Text は文字列を描画します。bold や color などのスタイルを任意で指定できます。
インターフェースギャラリーには、ほとんどの要素のサンプルとスクリーンショットがあります。次の表に主な要素を示します。 モジュールが .tsx または .jsx ファイルの場合は、ツリーを JSX で記述できます。まず $.ui.resolve(e) から要素を分割代入してください。 描画が表示されない場合は、要素が受け取らない props や、子を配置できない場所にある子がツリーに含まれていないか確認してください。そのようなツリーを返すフックは失敗し、hook skipped 行に mod の名前とツリーが違反したルールが示されます。ペイン内の Text に bogusProp という名前の props がある場合、その行は次のようになります。
Desktop アプリと VS Code 拡張機能では、Link の href が次の要件を満たさない限り、プレーンテキストとして描画されます。
  • スキームとホスト: https: URL、または http://localhost:3000 のような http://localhost URL
  • @ を含まない: パスやクエリ内の @ は %40 と記述します
  • 表記: ホストの後の / がない点を除き、new URL(href).href が返すものと同じであること。つまり、大文字のホスト、スペース、https: URL での :443 は除外されます。
ターミナルでは、これらの要件は適用されません。

Client が失敗した場合

ターミナルでは、Client が実行するファイルが失敗すると、my-mod: Client client/spinner.js: boom のような薄く表示された行が Client の代わりに表示され、描画の残りの部分は引き続き表示されます。 mod が ui.fault を処理する場合、Claude Code はその後サイトを再度描画します。

色付きセルのグリッドを描画する

ターミナルでヒートマップ、スパークライン、ゲームボードを描画する場合は、セルごとに Box を使うのではなく、Raster を 1 つ描画します。Raster は key、columns と rows によるサイズ、そしてすべてのセルをパックした base64 文字列である cells を受け取ります。各セルは 3 つの数値、つまり文字のコードポイント、文字色、背景色で構成されます。色は 16 進数の 24 ビット RGB 値で、たとえば赤なら 0xc62828 です。その範囲より 1 大きい値 0x01000000 は、ターミナルのデフォルトを意味します。 ターミナル以外のアプリには Raster がないため、e.surface を確認して、そこではテキストを描画します。次のペイン本体は 3×2 のヒートマップを描画します。
ターミナルでは、ペインにグリッドが表示されます。 ターミナル内のペインに、色付きブロックの小さなグリッドが 2 行 3 列で表示されている。上の行は緑、琥珀色、赤。下の行は緑、緑、琥珀色。 変更するのは rows 配列の部分で、cellsOf がそれをパックされた文字列に変換します。フックは id が heat のペインでのみ描画するため、hello-tabs の例がペインを開くのと同じように、コマンドから $.ui.open({ id: 'heat' }) でペインを開いてください。 各文字の幅は 1 セルである必要があります。すでに画面上にある Raster をアニメーションさせるには、ペインの id を requestId として、Raster の key、同じサイズ、新しいセルを指定して $.ui.blit を呼び出します。この例では $.ui.blit({ requestId: 'heat', key: 'grid', columns: 3, rows: 2, cells: cellsOf(newRows) }) となります。これにより、ui.render フックを再実行することなく、その 1 つの要素だけが再描画されます。

押下と入力に応答する

ユーザーがボタンを押したとき、フィールドに入力したとき、または mod が描画したリストから選択したとき、Claude Code はそのコントロールのコールバックを呼び出します。コールバックはモジュール内で実行されます。各コントロールはそれぞれ独自のコールバックを受け取ります。
  • Button: onPress(e) を受け取ります。e.surface は押下が発生したアプリです
  • Input: onSubmit(value) と onInput(value) を受け取ります
  • Select: onSelect(value) を受け取り、選択肢は options に指定します。これは一意の値を持つ 1 つ以上の選択肢のリストで、たとえば [{ value: 'sm', label: 'Small' }, { value: 'lg', label: 'Large' }] のようになります

key が必要なコントロール

すべての Input と Select に、key: 'size' のような key props を付けてください。Button は、label props または単一の文字列の子を持つ場合は key を省略できます。その場合、キーは label の値またはその文字列になります。 テストと別の mod は、コントロールをそのキーで識別します。
  • テスト: テストは、キーを使ってコントロールを押したり入力したりします。
  • 別の mod: Claude Code は、コントロールのコールバックを実行する前に、e.element にコントロールのキーを含めて ui.press、ui.input、または ui.select を発火します。別の mod のフックもそのイベントに対して実行できます。そのフックは、ユーザーが Input に入力した内容を確認でき、そのテキストを変更したり、コールバックが実行されないようにしたりできます。mods API には、その mod がボタンを押すためのメソッドはありません。
needs a key または is drawn twice というメッセージが表示された場合は、そのメッセージから原因を特定してください。

キーボードフォーカスとホットキー

mod 自身がキーボードを読み取ることはありません。ユーザーがキーを押すと、Claude Code がそのキーをどのコントロール宛てかを判断し、そのコントロールのコールバックが実行されます。バンド上の数字ホットキーまたは action バインディングを除き、これはペインまたはバンドがキーボードフォーカスを持っている間にのみ発生します。それ以外のときは、キーはプロンプトに送られます。 VS Code 拡張機能では、ボタンにホットキーはありません。ユーザーはボタンをクリックするか、ボタン上で Enter を押し、フィールドには直接入力します。

ペインがキーボードフォーカスを得る方法

ペインは次の場合にキーボードフォーカスを得ます。
  • mod がコマンドまたは押下から focus: true を指定してペインを開いたとき
  • ユーザーが Ctrl+X に続けて Tab を押したとき
  • ユーザーがペインをクリックしたとき(ターミナルではフルスクリーンレンダリングが必要です)
Claude Code が focus: true を許可するのは、プロンプトが空で、ほかに何もキーボードフォーカスを持っていない場合に限られます。ユーザーが入力中に開いたペインは、そのキー入力を奪いません。

各キーの動作

次の表は、ペインまたはバンドがキーボードフォーカスを持っている間の各キーの動作を示しています。 mod は Tab や矢印キーをほかの操作に割り当てることはできないため、ゲームでは w、a、s、d で操作します。

ホットキーと最初のフォーカスを設定する

  • hotkey: ユーザーが 1 つのキーで Button を押せるようにするには、hotkey: 'a' のように、1 桁の数字または 1 文字の小文字を hotkey に指定します
  • autoFocus: ペインを開いたときにどのコントロールがフォーカスを持つかを選ぶには、そのコントロールに autoFocus: true を追加します。VS Code 拡張機能では autoFocus は何もしません。コントロールはこの props を省略した場合と同じように描画されるため、何も変更する必要はありません。この props は true のみを受け付けるため、ほかのコントロールでは省略してください。
ホットキーの表示方法は、ボタンとアプリによって異なります。 ターミナルでは、ユーザーが押すべきキーがわかるように、角括弧付きボタンのラベルでキーを示すか、plain: true を使用してください。Button のその他のルール(action、バンド上の数字ホットキー、1 つのホットキーに 2 つのボタンを割り当てる場合)については、要素リファレンスを参照してください。

ユーザーがバンドを折りたたんだとき

ターミナルでは、mod がバンドに描画している間、ユーザーはバンドを 1 行に折りたたんで邪魔にならないようにできます。
  • [-] をクリックする: バンドが展開されている間、Claude Code はバンドの最初の行の右端にこのマークを描画します。フルスクリーンレンダリングでは、ユーザーはこれをクリックしてバンドを折りたたみます。
  • Ctrl+X に続けて Ctrl+A を押す: プロンプト、バンド、ペインのいずれがキーボードフォーカスを持っている場合でも機能します。ユーザーは abovePrompt:toggle アクションを通じて、この操作に別のキーを割り当てることができます。
折りたたまれたバンドは、mod がそこに描画しているものをすべて非表示にし、代わりに薄い 1 行を表示します。この行には、ユーザーが割り当てているとおりに、バンドを展開するキーが示されます。
同じキー、またはフルスクリーンレンダリングではその行をクリックすることで、バンドは再び展開されます。それまでは、バンド内のボタンを押す手段はありません。ホットキーも、空のプロンプトに入力した数字も、ボタンの action のキーボードショートカットも機能しません。ユーザーがバンドを折りたたんだときにバンドがキーボードフォーカスを持っていた場合、フォーカスはプロンプトに戻り、折りたたまれている間は Ctrl+X に続けて Tab を押してもバンドはスキップされます。 バンドは、/clear の後も含め、ユーザーが展開するまで折りたたまれたままで、次回 Claude Code を起動したときに再び展開されます。mod はバンドを展開できません。ユーザーが応答する必要があるものを表示する場所を、バンドだけにしないでください。バンドが折りたたまれている間だけそれを別の場所に表示するには、実行され続ける ui.render フックで e.props.isCollapsed を読み取ってください。isCollapsed には Claude Code v2.1.321 以降が必要です。

入力を受け取り、項目ごとに行を描画する

多くのペインは、テキストフィールドとその下のリストで構成されます。このセクションの例はメモペインです。メモを入力して Enter を押すと追加され、各メモにはそれを削除する x ボタンがあります。メモを 2 つ追加すると、ターミナルはペインを次のように描画します。
上部の枠線にある ✕ は、ペインを閉じるための Claude Code 独自のマークです。 この例では次の手法を使用しています。
  • 入力を受け取る: Input は、ユーザーが Enter を押したときにフィールドのテキストを引数として onSubmit(value) を呼び出し、変更のたびに onInput(value) を呼び出します
  • リストを描画する: データを 1 件につき 1 行にマッピングし、各行のボタンにそれぞれ独自の key を付けます
次のフックがペインの内容を描画します。
ペインを試すには:
  • メモを追加する: 1 行入力して Enter を押します。その行が新しい行として表示され、フィールドは空になります。
  • メモを削除する: メモの x ボタンにフォーカスが移るまで Tab を押し、Enter を押します。x はボタンのラベルでありホットキーではないため、その文字を入力してもボタンは押されません。
各変更は hello-tabs と同じレンダリングサイクルに従います。コールバックが notes を変更し、redraw を呼び出して、リストを $.store に保存します。ユーザーがメモを入力している間にフックがペインを再度描画しても、フックが毎回同じ value を渡している限り、フィールドはユーザーのテキストを保持します。ユーザーのテキストを独自のテキストに置き換えるには、異なる value を渡してください。 この例ではメモを保存しますが、読み込みはしません。次のセッションでメモを復元するには、hello-tabs が count を読み取るのと同じ方法で、session.start フックでメモを読み取ってください。 フィールドの行 Note: Type a note and press Enter ⏎ add は、次の props で構成されています。 Input を送信しても、コールバックが $.prompt.submit を呼び出さない限り、ターンは開始されません。

サイトを再描画する

描画はスナップショットです。ui.render フックが最後に実行したときに返したものを表示します。何か新しいものを表示するには、フックを再度実行する必要があります。Claude Code はいくつかの変更に対して再度実行し、mod は残りを要求します。

Claude Code が要求なしで再描画するとき

Claude Code はサイトの props が変更されるか、ターミナルの幅が変更されるときに ui.render フックを再度実行します。サイト内の Client が失敗し、mod が ui.fault を処理する場合、Claude Code は ui.fault フックが返った後にフックをもう一度実行するため、ui.render フックはその Client を除外できます。タイマーでフックを実行しません。モジュール内の変数が変更されたときは判断できません。

データが変更されたときに再描画する

データが変更された後にサイトを再度描画するには、$.ui.invalidate('ui.render') を呼び出します。このペインは押下をカウントします。ボタンのコールバックは count を変更し、再描画を要求します。
各押下はペイン内の数字を上げます。hello-tabs の例は同じ呼び出しを redraw 関数にラップします。 $.stateに保持する値は呼び出しを必要としません。値を書くことはそれを読むサイトを再描画するためです。

タイマーで再描画する

時計、カウントダウン、またはセッション外の値を最新に保つには、スケジュールで再描画します。モジュールの session.start フックでタイマーを開始します。モジュールが既に 1 つを持っている場合、hello-tabs のように、$.clock.every行をそれに追加します。
これで Claude Code は 1 秒に 1 回 ui.render フックを実行します。タイマーはモジュールがリロードされた後に停止し、モジュールの新しいインスタンスが独自のタイマーを開始します。

サイトが再描画できる頻度

Claude Code はサイトの再描画の頻度を制限するため、mod はデータが変更されるたびに $.ui.invalidate を呼び出すことができます。各サイトが再描画できる頻度については、制限テーブルを参照してください。 制限より速く来る呼び出しは 1 つの再描画に結合されます。その再描画はフックを 1 回実行し、フックはその時点でのデータを読むため、最新の値が表示され、その間の値は表示されません。アニメーションは制限より速く実行できません。

状態を保持する

mod が値をどこに保持するかによって、その値がどれだけ持続するかが決まります。モジュールが再読み込みされるまで、セッションが終了するまで、またはセッションをまたいで持続します。値を持続させる必要がある期間に応じて選択してください。 $.store.get(key) は値または undefined に解決され、$.store.set(key, value) は任意の JSON 値を受け取ります。

$.state に値を保持する

$.state はセッションの間値を保持し、再描画も自動で行います。これはリアクティブな状態です。値を読み取る ui.render フックはその値を購読するため、値を書き込むたびに Claude Code がその箇所を再描画し、$.ui.invalidate を呼び出す必要はありません。また、$.state 内の値はモジュールの再読み込み後も残りますが、変数は残りません。 設定するには、値を宣言し、マニフェストでその宣言を指定してから、各値を定義して使用します。以下の例では、hello-tabs の count を $.state に移します。

値を宣言する

型宣言ファイルで値を宣言します。外側のキーはプラグインの名前で、その下の各エントリが値とその型です。これを hello-tabs/types/index.d.ts として保存します。
hello-tabs/types/index.d.ts

マニフェストで宣言を指定する

claude plugin validate がそのファイルに照らしてコードをチェックできるように、マニフェストにファイルのパスを指定した types フィールドを追加します。
hello-tabs/.claude-plugin/plugin.json

値を定義、読み取り、書き込む

モジュール内で、各値をデフォルト値とともに定義し、描画時に読み取り、コールバックから書き込みます。atom は値とそのデフォルトに名前を付け、read は値を返し、update は値を書き込みます。この 3 つのヘルパーが $.state.get と $.state.set を代わりに呼び出します。
ui.render フックが count を読み取ったため、ボタンがそれを書き込むたびに Claude Code はフックを再実行します。 コードには次のルールが適用されます。
  • plugin と key は文字列リテラルで記述する:claude plugin validate はソースからそれらを読み取ります
  • 各 atom 呼び出しの結果を const で保持する:count を let で宣言すると、検証が takes a source the scan can read で失敗します
  • すべての値を型宣言ファイルで宣言する:宣言しないと、検証が hello-tabs.count is not declared で失敗します
  • コールバックまたは別のイベントのフックから書き込む:ui.render フックは状態を読み取れますが書き込めないため、onPress、onSubmit、または別のイベントのフックから書き込みます

hello-tabs を $.state を使うように変更する

hello-tabs の count を $.state に移すには、それを使用しているすべての行を変更します。
  • モジュールの先頭:import 行を追加し、let count = 0 を atom の行に置き換えます
  • ui.render フック内:tabButton の前に read の行を追加し、Text 内で 'Count: ' + n を描画します
  • Add one ボタン内:onPress を複数のセッションから保存するにあるものに置き換えます。これはカウントを書き込むだけでなく保存も行います
  • session.start フック内:saved を読み取る 2 行を、/clear の後に保存済みの値を再度読み込むにある loadCount の呼び出しに置き換えます
tab は引き続き変数なので、タブボタンの redraw はそのまま残します。

/clear の後に保存済みの値を再度読み込む

mod が session.start で保存済みの値を $.store から $.state にコピーする場合、/clear、/resume、/branch の後に再度コピーする必要があります。これらのコマンドはすべての $.state の値をデフォルトにリセットし、session.start は再度発火しません。一方、classic.SessionStart はそれぞれの後に e.source が clear、resume、fork に設定された状態で発火するため、そのフックで値を再度コピーします。そうしないと、描画にはデフォルトが表示され、$.state の値を保存するコールバックが保存済みの内容をデフォルトで上書きしてしまいます。 次のコードは、両方のフックから count を読み込みます。これは count が atom で update がインポートされている、$.state 版の hello-tabs を前提としています。loadCount を register の上に置き、既存の session.start フックに loadCount の呼び出しを追加します。classic.SessionStart は起動時とコンテキスト圧縮の後にも発火しますが、これらは $.state をリセットしないため、source のフィルターでフックを 3 つのリセットに限定しています。
両方のフックを配置すると、/clear の後にペインには 0 ではなく保存済みのカウントが表示され、次に Add one を押すと保存済みのカウントに加算されます。 loadCount は保存済みの値で $.state 内の値を上書きし、session.start はモジュールが再読み込みされるたびに再度発火します。ストアが古くならないように、Add one ボタンのように変更のたびに保存してください。 セッションなしで再読み込みを確認するには、/clear の後に描画をテストします。

複数のセッションから保存する

マシン上で mod を実行するすべてのセッションは、1 つの $.store を共有します。get の後に set を行う操作はアトミックではありません。2 つのセッションがそれぞれ値を読み取り、変更して書き戻すと競合が発生し、2 回目の書き込みが 1 回目を置き換えます。 これが起こる可能性を下げるには、次のようにします。
  • 各項目に専用のキーを与える:set は自身のキーだけを変更するため、異なるキーに書き込むセッション同士は互いを上書きしません
  • 書き込む直前に再度読み取る:複数のセッションが変更する値については、コールバック内でキーを get し、session.start で読み込んだコピーではなく、その値から新しい値を作ります。それでも、get と set の間に別のセッションの書き込みが入った場合、その書き込みは失われます。
次のボタンは、ストアが現在保持している値に 1 を加算してから、描画を更新します。
このセッションの開始後に別のセッションが自分のボタンを 3 回押していた場合、このボタンを押すとその 3 回分を含むカウントが表示され、保存されます。

次のステップ