ui.render イベントを発火し、そのイベントに対するフックが、そこに描画する内容を返します。
次の図は、ターミナルセッション内で mod が描画できる場所を示しています。
個々の props や制限を調べるには、リファレンスを参照してください。
タブ付きのペインを作成する
このセクションでは、/hello-tabs コマンドを追加する mod を作成します。このコマンドはペインを開きます。ペインは、幅の広いフルスクリーンのターミナルではトランスクリプトの横に表示されるサイドバーで、それ以外の場合はプロンプトの上に表示される枠付きの領域です。このペインには 2 つのタブが表示され、2 つ目のタブにはカウンターに 1 を加えるボタンがあります。カウントは Claude Code を再起動した後も保持されます。
完成した mod は次のようになります。この録画では、ペインを開き、2 つ目のタブに切り替え、ボタンを何回か押してから、1 つ目のタブに戻ります。
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コマンドを追加し、以前のセッションで保存されたカウントを読み込む- そのコマンドを実行したときにペインを開く
- ペインのコンテンツ(タブの行と、開いているタブの本文)を描画する
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 であることを確認します。Claude Code がすでに描画しているものを変更する
Claude Code は、メッセージ、ツール呼び出しの行、スピナーなど、インターフェースの大部分を自ら描画します。これらの各部分も描画箇所であるため、mod でスタイルを変更したり置き換えたりできます。変更するには、次の表にある名前でui.render フックをフィルターします。
Pane、AskUserQuestion、Spinner、UserMessage、AssistantMessage、およびツール呼び出しの描画箇所は、ターミナル、Desktop アプリ、VS Code 拡張機能で機能します。その他の描画箇所がそれぞれどこで発生するかは、描画箇所の表に記載されています。
Claude Code がすでに描画している描画箇所では、フックで細部を変更したり、描画を置き換えたり、そのままにしたりできます。タブを選択すると、それぞれをスピナーに適用した例を確認できます。これらの例では、チュートリアルの mod と同様に、別のフックがカウントする calls 変数を読み取っています。
- 細部を変更する
- 描画を置き換える
- そのままにする
Claude Code の描画を維持したまま一部だけを変更するには、スピナーはアニメーションと単語を維持し、その単語の後に指定したテキストが続きます。
props を変更したイベントのコピーを next に渡します。次のフックは、スピナーの単語の後に続くテキストを変更します。next(e) は Claude Code の描画への参照 { type: 'engine', ref } を返します。その描画の内容を変更するには、細部を変更するタブのように、props を変更したイベントのコピーを next に渡します。参照はそのまま返すことも、独自の要素と並べて Box に配置することもできます。
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 が空でない場合にのみキーボードフォーカスを要求します。
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 では独自の結果を描画します。
/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 の背景であっても削除します。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 内に移動してください。/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
コードを書く
次のファイルを 独自の色を使用するには、16 進値を別の 6 桁の 16 進カラーに置き換えます。
~/.claude/skills/paper/hooks/register.js として保存します。セッションが開始されると、このコードはライトモードとダークモードの色を指定して $.theme.set を呼び出します。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 をオフにする
- Claude が mod を書いた場合:mod のディレクトリを、Claude が mod を書いたセッションの mod フォルダーの外に移動します。
- mod を
~/.claude/skills/配下に置いた場合:~/.claude/skills/paper/などの mod のディレクトリを、~/.claude/skills/の外の場所に移動します。 - mod をインストールした場合:Desktop アプリで、Manage plugins からそのプラグインを無効化またはアンインストールします。Manage plugins が表示されず、CLI がある場合は、シェルからマーケットプレイスのプラグインを無効化またはアンインストールできます。
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
- Box
- Input
Text は文字列を描画します。bold や color などのスタイルを任意で指定できます。
モジュールが
.tsx または .jsx ファイルの場合は、ツリーを JSX で記述できます。まず $.ui.resolve(e) から要素を分割代入してください。
描画が表示されない場合は、要素が受け取らない props や、子を配置できない場所にある子がツリーに含まれていないか確認してください。そのようなツリーを返すフックは失敗し、hook skipped 行に mod の名前とツリーが違反したルールが示されます。ペイン内の Text に bogusProp という名前の props がある場合、その行は次のようになります。
Desktop アプリと VS Code での Link
Desktop アプリと VS Code 拡張機能では、Link の href が次の要件を満たさない限り、プレーンテキストとして描画されます。
- スキームとホスト:
https:URL、またはhttp://localhost:3000のようなhttp://localhostURL @を含まない: パスやクエリ内の@は%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 のヒートマップを描画します。
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 を押したとき
- ユーザーがペインをクリックしたとき(ターミナルではフルスクリーンレンダリングが必要です)
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アクションを通じて、この操作に別のキーを割り当てることができます。
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行をそれに追加します。
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の間に別のセッションの書き込みが入った場合、その書き込みは失われます。
次のステップ
- イベントに反応する: ツール呼び出しとターンから描画にデータを渡します
- mods API を使用する: タイマーとモデル呼び出しから描画にデータを渡します
- 描画をテストする: テストからボタンを押し、複数のサーフェスで確認します
- 描画箇所と要素: 各描画箇所の props と各要素の props