Claude Media
Claude Code plugin hintsで自作CLIに公式プラグインを推薦させる
Claude Codeチュートリアル

Claude Code plugin hintsで自作CLIに公式プラグインを推薦させる

Claude Codeはstderrに書かれた1行のマーカーを読み取り、CLIやSDKの利用者へ公式プラグインのインストールを提案します。実装手順と表示頻度の制限までを扱います。

読了目安 約16分

Claude Code plugin hintsで自作CLIに公式プラグインを推薦させる

CLIやSDKを保守していて、Anthropicが運営するclaude-plugins-officialマーケットプレイスに自分のプラグインを持っているなら、そのツール自身からClaude Codeの利用者にインストールを提案できます。plugin hintsと呼ばれるこの仕組みは、CLIがstderrに1行のマーカーを書き出すだけで動きます。追加のコマンドは要らず、Claude Code以外の場所で実行したときの出力は変わりません。

plugin hintsとは何か

plugin hintsとは、CLIが自分の実行環境がClaude Code内であると検知したときに、<claude-code-hint />という自己閉じタグをstderrへ書き出し、Claude Codeがそれを読み取ってユーザーに1回だけインストール提案を出すプロトコルです。仕組みが対象にするのはこのマーケットプレイスに載っているプラグインだけで、コミュニティマーケットプレイスのプラグインでは発火しません。

Claude CodeはBashツールとPowerShellツールで実行するすべてのコマンド、そしてhookコマンドでCLAUDECODEという環境変数を1に設定します。v2.1.172以降は、これらと同じサブプロセスでCLAUDE_CODE_CHILD_SESSIONも1に設定します。CLIがどちらかの変数を検知すると、<claude-code-hint />タグをstderrへ書き出します。hookコマンドの中で出力されたヒントタグは取り除かれ、無視されます。インストール提案が実際に出るのは、Bash・PowerShellツールの出力からだけです。

Claude Codeはコマンド出力を受け取ると、次の順で処理します。

  1. ヒント行を探し、モデルに渡す前に取り除く
  2. ヒントが指すプラグインがclaude-plugins-officialに存在するか確認する
  3. そのプラグインが未インストールで、まだ提案されたことがないか確認する
  4. 発行元のコマンド名を添えたインストール提案をユーザーに表示する

Claude Codeがプラグインを自動でインストールすることはありません。インストールするかどうかは常にユーザーが選びます。

この仕組みが埋めるのは「自分のCLIに対応プラグインがあることを、利用者がそもそも知らない」という発見のギャップです。CLIとプラグインを別々に案内していると、Claude Code内でツールを使っている最中の利用者には気づかれにくくなります。plugin hintsはその案内を、実行そのものが生む出力に埋め込みます。

ヒントをstderrへ出力する

ヒント発行は、このマーケットプレイスに掲載済みのプラグインでしか効果を発揮しません。実装に入る前に、後述の「Anthropicのマーケットプレイスに掲載する」を済ませておく必要があります。

環境変数の有無でゲートを掛け、タグは単独の行としてstderrへ書きます。人間が直接CLIを実行したときにマーカーが出てしまわないようにするための条件分岐です。どちらの変数を見るかは用途で選びます。

変数特徴
CLAUDECODE特徴すべてのClaude Codeバージョンで設定されるため最も多くのセッションに届く。tmuxセッションやClaude Codeが起動するstdio MCPサーバーのサブプロセスでも設定される。IDE拡張の統合ターミナルでも設定されるため、人間が直接CLIを叩く場面にも出うる
CLAUDE_CODE_CHILD_SESSION特徴Claude Code自身が起動したサブプロセス(ツール呼び出し・hookコマンド・statuslineコマンド)だけに設定されるため、人間の端末には通常届かない。ただしtmuxサーバーのような長寿命プロセスがセッション内で起動された場合、その変数を保持し続けるため、あとから同じプロセスから起動されたシェルには生のタグが見えることがある。Claude Code v2.1.172以降が必要で、それより前のバージョンのセッションではヒントが届かない

次の例はCLAUDECODEをゲートに使い、claude-plugins-officialにあるexample-cliというプラグインのヒントを出力します。

if (process.env.CLAUDECODE) {
  process.stderr.write(
    '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />\n',
  )
}
import os, sys
 
if os.environ.get("CLAUDECODE"):
    print(
        '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />',
        file=sys.stderr,
    )
if os.Getenv("CLAUDECODE") != "" {
    fmt.Fprintln(os.Stderr,
        `<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />`)
}
if [ -n "$CLAUDECODE" ]; then
  printf '%s\n' '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />' >&2
fi

example-cliの部分を、このマーケットプレイスに登録した自分のプラグイン名に置き換えます。

ヒントの形式

ヒントは3つの必須属性を持つ自己閉じタグです。

属性必須説明
v必須必須説明プロトコルバージョン。サポートされる値は1のみ
type必須必須説明ヒントの種類。サポートされる値はpluginのみ
value必須必須説明name@marketplace形式のプラグイン識別子

属性値はダブルクォートで囲んでも、クォートなしでも構いません。クォートなしの値には空白を含められず、エスケープシーケンスもサポートされません。

Claude Codeが有効なヒントとして受理するには2つの条件を満たす必要があり、どちらか一方でも欠けるとタグは無視されます。

  • 単独行であること: タグは行全体を占める必要があります。ログ出力の途中に埋め込まれたタグのように、行の一部にあるものは無視されます。行頭・行末の空白は許容されます
  • 公式マーケットプレイスであること: valueはclaude-plugins-officialのようなAnthropic管理下のマーケットプレイスを指す必要があります。他のマーケットプレイスを指すヒントは黙って破棄されます

バージョンや種類が未対応の値であっても、ヒント行は必ずモデルに届く前に取り除かれます。マーカー自体がトークン消費として数えられることはありません。

以下は強制されませんが、守っておくことが推奨される項目です。Claude Code側はCLIがこれに従っているかを検証できません。

  • stderrへ書く: stderrに書けばexample-cli deploy | jqのようなシェルパイプラインの出力を汚しません。Claude Codeは両方のストリームを走査するため、stdoutに書いても動作はします
  • 環境変数でゲートする: CLAUDECODEかCLAUDE_CODE_CHILD_SESSIONが設定されているときだけ発行します

どこでヒントを出すか

ヒントを発行するコード経路は自分で選べます。Claude Codeはプラグイン単位で重複排除するため、呼び出しのたびに発行しても不利益はありません。相性の良いタイミングは次のとおりです。

配置場所効く理由
--helpの出力効く理由Claudeは見慣れないCLIを調べるとき、ヘルプをよく実行する
未知のサブコマンドのエラー効く理由Claudeがインターフェースを把握できていない瞬間に届く
ログイン・認証成功時効く理由ユーザーがすでにセットアップの心構えでいる
初回起動時のウェルカムメッセージ効く理由自然なオンボーディングの瞬間になる

ユーザーに表示される内容

ヒントがすべてのチェックを通ると、Claude Codeは次のような提案を表示します。

─────────────────────────────────────────────────────────────
  Plugin recommendation
 
    The example-cli command suggests installing a plugin.
 
    Plugin: example-cli
    Marketplace: claude-plugins-official
    Official integration for example-cli deployments
 
    Would you like to install it?
    ❯ 1. Yes, install example-cli
      2. No
      3. No, and don't show plugin installation hints again
 
─────────────────────────────────────────────────────────────

提案には発行元のコマンド名が表示されるため、ユーザーはツールと提案されたプラグインの組み合わせに違和感があればすぐに気づけます。30秒以内に応答が無いと、Claude Codeは提案を「No」として扱い閉じます。

表示頻度はどこまで制限されるか

提案が表示される頻度には複数の上限があり、そもそも一度も出ないセッションもあります。

  • プラグインごとに1回: 一度提案が表示されると、Claude Codeはそのプラグインを記録し、ユーザーの回答に関わらず二度と提案しません
  • セッションごとに1回: マシン上のすべてのCLIを合わせて、1つのClaude Codeセッションにつき最大1回しか提案は出ません
  • メインの対話セッションのみ: Claude Codeが提案を表示するのは、ユーザーが直接入力している端末セッションだけです。サブエージェントが実行するコマンドでは提案されず、-pフラグを使う非対話モードやAgent SDK経由の実行でも提案されません。いずれの場合もコマンド出力からヒント行自体は取り除かれます
  • テレメトリを無効化している場合: 分析が無効なセッションでは提案自体が表示されません。DISABLE_TELEMETRYやCLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFICを設定したセッション、そしてAmazon BedrockやGoogle Cloud's Agent Platformのようにテレメトリの自動オプトアウトが適用されるサードパーティ経由のセッションもここに含まれます

「Yes」を選ぶとプラグインはuserスコープにインストールされます。「No, and don't show plugin installation hints again」を選ぶと、そのユーザーに対する今後のヒント提案がすべて無効になります。

Anthropicのマーケットプレイスに掲載する

plugin hintsのプロトコルが効果を持つのは、claude-plugins-officialというマーケットプレイスに載っているプラグインだけです。Anthropicはこのマーケットプレイスを自らの裁量でキュレーションしており、アプリ内のプラグイン投稿フォームはコミュニティマーケットプレイスへの追加であって、plugin hintsのプロトコルが確認する先ではありません。Anthropicのパートナー窓口とやり取りがあるなら、そこを通じて掲載を調整するのが確実な経路です。

よくある質問

hookコマンドの中でヒントを出したらどうなりますか

hookコマンドの出力に含まれるヒントタグは取り除かれ、無視されます。インストール提案につながるのはBashツールとPowerShellツールの出力だけです。

stdoutにヒントを書いても動きますか

動きます。Claude Codeは両方のストリームを走査します。ただしstdoutに書くとシェルパイプラインの出力にマーカーが混ざる可能性があるため、stderrへ書くことが推奨されています。

コミュニティマーケットプレイスのプラグインでも使えますか

使えません。valueがclaude-plugins-official以外を指すヒントは黙って破棄されます。コミュニティマーケットプレイスへの掲載だけでは対象になりません。

ユーザーが一度断ったプラグインは、あとで再提案されますか

されません。提案が一度表示されると、ユーザーの回答に関わらずそのプラグインは二度と提案されなくなります。

複数のCLIが同時にヒントを出したらどうなりますか

1つのClaude Codeセッションで表示される提案は最大1回です。複数のCLIがマシン上で同時にヒントを出しても、表示されるのはそのうちの1件だけです。

IDE拡張の統合ターミナルで人間が直接CLIを実行した場合はどうなりますか

CLAUDECODEはIDE拡張の統合ターミナルでも設定されるため、人間が直接CLIを叩いた場合でもヒントが出る可能性があります。この場面を避けたいなら、Claude Code自身が起動したサブプロセスだけに設定されるCLAUDE_CODE_CHILD_SESSIONをゲートに使う方法があります。ただしこちらはv2.1.172以降のセッションでしか届きません。

まとめ

plugin hintsは、自作のCLIやSDKからClaude Codeの利用者にプラグインを提案できる仕組みで、実装側が用意するのは環境変数を見て<claude-code-hint />をstderrへ書くだけの1行です。効果を持つのはclaude-plugins-officialに掲載済みのプラグインに限られ、提案の頻度もプラグインごと・セッションごとに厳しく制限されています。CLI保守者は発行タイミングの選定とこのマーケットプレイスへの掲載申請を、プラグイン自体の作り方はClaude Codeプラグイン完全ガイドを参照してください。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →