从 CLI 推荐你的插件

CLI 向 stderr 输出一行 marker，让 Claude Code 提示用户安装你的官方插件。

是什么

如果你维护一个 CLI 或 SDK，并在 Anthropic 官方 marketplace 中有对应插件，你的工具可以在检测到自己运行于 Claude Code 内部时，向 stderr 写出一行 marker，从而提示 Claude Code 用户安装该插件。Claude Code 会读取这行 marker、将其从输出中剥离，并向用户显示一次性安装提示。

本页面面向 CLI/SDK 维护者。Claude Code 会在 marker 到达模型之前就把它从命令输出中删掉，因此该 marker 不会出现在对话里，也不计入 token 用量。

怎么工作

Claude Code 对每条通过 Bash 和 PowerShell 工具运行的命令（以及 hook 命令）都将环境变量 CLAUDECODE 设为 1
你的 CLI 看到该变量后，向 stderr 写出一个自闭合的 <claude-code-hint /> 标签；在 hook 命令中该标签会被剥离并忽略，只有 Bash 和 PowerShell 工具的输出才会触发安装提示
Claude Code 收到命令输出后先扫描并移除 hint 行（在到达模型之前）
校验 hint 指向的插件位于 Anthropic 官方 marketplace
校验该插件尚未安装、且此前未提示过
显示安装提示，并指明是哪条命令发出的 hint
Claude Code 绝不会自动安装插件，始终由用户确认

怎么配置 / 用法

将输出 marker 的条件设为环境变量 CLAUDECODE，使其不会出现在真人用户的终端中，再把标签单独成行写到 stderr：

javascript

if (process.env.CLAUDECODE) {
  process.stderr.write(
    '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />\n',
  )
}

python

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)

属性说明：v（必填，协议版本，唯一支持值 1）；type（必填，唯一支持值 plugin）；value（必填，插件标识，形如 name@marketplace）。属性值可用双引号包裹或不加引号；不加引号时不能含空白；不支持转义序列。

什么时候用

--help 输出：Claude 探索陌生 CLI 时常运行 help
未知子命令错误：恰好触达 Claude 对你接口困惑的时刻
登录或鉴权成功时：用户已处于配置心态
首次运行欢迎信息：自然的 onboarding 时机

限制 / 坑

仅对官方 marketplace claude-plugins-official 中的插件生效；指向其他 marketplace 的 hint 会被静默丢弃
标签必须单独成行；嵌在某行中间会被忽略（行首尾空白允许）
Anthropic 自行决定是否收录官方 marketplace；应用内提交表单只会加入 community marketplace，而 hint 协议不检查该 marketplace
每个插件只提示一次；每个 Claude Code 会话最多出现一次 hint 提示

硬事实速查（11 条）

环境变量 CLAUDECODE 在每条 Bash/PowerShell 工具命令及 hook 命令中被设为 1
hint 行在到达模型前总会被移除，即便版本或类型无法识别，因此不计入 token 用量
Claude Code 同时扫描 stdout 与 stderr，但推荐写到 stderr，以避免污染 shell 管道
提示会指明发出 hint 的命令名，便于用户发现工具与所荐插件不匹配
用户 30 秒内无响应，提示按 No 自动消失
选择 Yes 会将插件安装到 user scope
选择 No, and don't show plugin installation hints again 会关闭该用户后续所有 hint 提示
提示展示后，Claude Code 记录该插件并不再为其提示，无论用户如何回答
跨机器上所有 CLI，每个 Claude Code 会话至多出现一次 hint 提示
Claude Code 绝不自动安装插件，始终需用户确认
推荐（但不强制）将输出条件设为 CLAUDECODE，避免 marker 出现在直接运行 CLI 的用户面前

官方出处：https://code.claude.com/docs/en/plugin-hints

从 CLI 推荐你的插件 ​

是什么 ​

怎么工作 ​

怎么配置 / 用法 ​

什么时候用 ​

限制 / 坑 ​