پلاگینت را از CLI خودت پیشنهاد بده

اگر یک CLI یا SDK نگه می‌داری و پلاگینی در مارکت‌پلیسِ رسمیِ Anthropic داری، ابزارت می‌تواند به کاربرانِ Claude Code پیشنهاد کند آن پلاگین را نصب کنند. وقتی CLIت تشخیص دهد که درونِ Claude Code اجرا می‌شود، یک نشانگرِ تک‌خطی به stderr می‌نویسد. Claude Code نشانگر را می‌خواند، از خروجی حذفش می‌کند و به کاربر یک پرامپتِ نصبِ یک‌باره نشان می‌دهد.

Claude Code خطِ hint را پیش از فرستادن به مدل از خروجیِ دستور حذف می‌کند، پس نشانگر هرگز در گفتگو ظاهر نمی‌شود و به مصرفِ توکن شمرده نمی‌شود. این پروتکل به هیچ دستورِ اضافه‌ای نیاز ندارد و چیزی را که CLIت برای کاربرانِ بیرونِ Claude Code چاپ می‌کند تغییر نمی‌دهد.

این صفحه برای نگه‌دارندگانِ CLI و SDK است. اگر دنبالِ نصبِ پلاگین هستی، کشف و نصبِ پلاگین‌ها را ببین.

چطور کار می‌کند

Claude Code متغیرِ محیطیِ CLAUDECODE را برای هر دستوری که از طریقِ ابزارهای Bash و PowerShell اجرا می‌کند و برای دستورهای hook روی 1 تنظیم می‌کند. از v2.1.172 همچنین CLAUDE_CODE_CHILD_SESSION را در همان زیرفرایندها روی 1 تنظیم می‌کند. وقتی CLIت یکی از این متغیرها را ببیند، یک تگِ خودبسته‌ی <claude-code-hint /> به stderr می‌نویسد. در دستورهای hook تگِ hint حذف و نادیده گرفته می‌شود. فقط خروجیِ ابزارهای Bash و PowerShell پرامپتِ نصب را آغاز می‌کند.

وقتی Claude Code خروجیِ دستور را دریافت می‌کند:

به دنبالِ خطوطِ hint می‌گردد و پیش از رسیدنِ خروجی به مدل حذفشان می‌کند
بررسی می‌کند که hint یک پلاگین در یک مارکت‌پلیسِ رسمیِ Anthropic را هدف می‌گیرد
بررسی می‌کند که پلاگین از قبل نصب نشده و پیش‌تر برایش پرامپت نشده باشد
به کاربر یک پرامپتِ نصب نشان می‌دهد که دستورِ تولیدکننده‌ی hint را نام می‌برد

Claude Code هرگز پلاگینی را خودکار نصب نمی‌کند. کاربر همیشه تأیید می‌کند.

hint را منتشر کن

انتشار را به یک متغیرِ محیطی مشروط کن تا نشانگر بعید باشد وقتی انسانی مستقیماً CLIت را اجرا می‌کند ظاهر شود، سپس تگ را روی خطِ مخصوصِ خودش به stderr بنویس. انتخاب کن کدام متغیر را بررسی کنی:

CLAUDECODE: روی هر نسخه‌ی Claude Code تنظیم می‌شود، پس به بیشترین نشست‌ها می‌رسد. همچنین در نشست‌های tmux و زیرفرایندهای سرورِ stdio MCP که Claude Code آغاز می‌کند تنظیم می‌شود، و افزونه‌های IDE آن را در ترمینال‌های یکپارچه‌شان تنظیم می‌کنند، جایی که ممکن است انسانی مستقیماً CLIت را اجرا کند.
CLAUDE_CODE_CHILD_SESSION: فقط در زیرفرایندهایی تنظیم می‌شود که خودِ Claude Code spawn می‌کند، مثلِ tool callها، دستورهای hook و دستورهای status line، پس تگ معمولاً به یک ترمینالِ انسانی نمی‌رسد. فرایندی بادوام که درونِ یک نشست آغاز شده، مثلِ یک سرورِ tmux، متغیر را می‌گیرد، پس shellهایی که بعداً از آن فرایند راه می‌افتند هنوز تگِ خام را نشان می‌دهند. به Claude Code نسخه‌ی v2.1.172 یا بالاتر نیاز دارد، پس نشست‌های روی نسخه‌های قدیمی‌تر hint را از دست می‌دهند.

مثال‌های زیر برای بیشترین دسترسی به CLAUDECODE مشروط شده‌اند و یک hint برای پلاگینی به نامِ 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" />`)
}

[ -n "$CLAUDECODE" ] &&
  printf '%s\n' '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />' >&2

example-cli را با نامِ پلاگینت در مارکت‌پلیسِ رسمی جایگزین کن.

انتخاب کن کجا منتشر کنی

تو کنترل می‌کنی کدام مسیرهای کد hint را منتشر می‌کنند. Claude Code بر اساسِ پلاگین deduplicate می‌کند، پس انتشار روی هر فراخوانی هیچ ضرری ندارد. نقاطِ تماسی که خوب کار می‌کنند عبارت‌اند از:

محل	چرا کار می‌کند
خروجیِ `--help`	Claude اغلب help را هنگامِ کاوشِ یک CLI ناآشنا اجرا می‌کند
خطاهای زیردستورِ ناشناخته	به لحظه‌ای می‌رسد که Claude درباره‌ی رابطت سردرگم است
موفقیتِ login یا auth	کاربر همین حالا در ذهنیتِ راه‌اندازی است
پیامِ خوشامدِ اولین اجرا	یک لحظه‌ی طبیعیِ onboarding

کاربر چه می‌بیند

وقتی hint از همه‌ی بررسی‌ها بگذرد، 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

─────────────────────────────────────────────────────────────

پرامپت دستوری را که hint را تولید کرد نام می‌برد تا کاربران بتوانند ناهماهنگی بینِ ابزار و پلاگینی که پیشنهاد می‌دهد را تشخیص دهند. اگر کاربر ظرفِ ۳۰ ثانیه پاسخ ندهد، پرامپت به‌عنوانِ No کنار می‌رود.

تناوبِ پرامپت محدود است:

یک‌بار به‌ازای هر پلاگین: پس از نشان‌دادنِ پرامپت، Claude Code پلاگین را ثبت می‌کند و دیگر هرگز برایش پرامپت نمی‌دهد، صرفِ‌نظر از پاسخِ کاربر.
یک‌بار به‌ازای هر نشست: در میانِ همه‌ی CLIها روی دستگاه، حداکثر یک پرامپتِ hint در هر نشستِ Claude Code ظاهر می‌شود.

انتخابِ Yes پلاگین را در scopeِ user نصب می‌کند. انتخابِ No, and don’t show plugin installation hints again همه‌ی پرامپت‌های آینده‌ی hint را برای کاربر غیرفعال می‌کند.

قالبِ hint

hint یک تگِ خودبسته با سه ویژگیِ الزامی است.

<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />

ویژگی	الزامی	توضیح
`v`	بله	نسخه‌ی پروتکل. `1` تنها مقدارِ پشتیبانی‌شده است
`type`	بله	نوعِ hint. `plugin` تنها مقدارِ پشتیبانی‌شده است
`value`	بله	شناسه‌ی پلاگین در قالبِ `name@marketplace`

مقادیرِ ویژگی می‌توانند با دابل‌کوتیشن نقل‌قول شوند یا بدونِ نقل‌قول بمانند. مقادیرِ بدونِ نقل‌قول نمی‌توانند فاصله داشته باشند. دنباله‌های escape پشتیبانی نمی‌شوند.

الزامات

Claude Code پیش از عمل بر اساسِ یک hint دو شرط را اعمال می‌کند. hintهایی که هرکدام از این بررسی‌ها را رد کنند کنار گذاشته می‌شوند:

خطِ مخصوصِ خود: تگ باید خطِ مخصوصِ خودش را اشغال کند. تگی که وسطِ خط جاسازی شده، مثلاً درونِ یک statementِ لاگ، نادیده گرفته می‌شود. فاصله‌ی ابتدا و انتهای خط مجاز است.
مارکت‌پلیسِ رسمی: مقدارِ value باید به پلاگینی در یک مارکت‌پلیسِ تحتِ کنترلِ Anthropic مثلِ claude-plugins-official ارجاع دهد. hintهایی که به مارکت‌پلیس‌های دیگر اشاره می‌کنند بی‌سروصدا کنار گذاشته می‌شوند.

خطِ hint همیشه پیش از رسیدن به مدل از خروجی حذف می‌شود، حتی وقتی نسخه یا نوع ناشناخته باشد، پس نشانگر هرگز به مصرفِ توکن شمرده نمی‌شود.

راهنماییِ باقی‌مانده توصیه‌شده است ولی اعمال نمی‌شود. Claude Code نمی‌تواند مشاهده کند که CLIت آن را رعایت می‌کند یا نه:

به stderr بنویس: stderr تگ را بیرونِ پایپ‌لاین‌های shell مثلِ example-cli deploy | jq نگه می‌دارد. Claude Code هر دو جریان را اسکن می‌کند، پس stdout هم کار می‌کند.
به یک متغیرِ محیطی مشروط کن: فقط وقتی CLAUDECODE یا CLAUDE_CODE_CHILD_SESSION تنظیم است منتشر کن. برای اینکه این دو متغیر چطور فرق دارند، hint را منتشر کن را ببین.

پلاگینت را به مارکت‌پلیسِ رسمی برسان

پروتکلِ hint فقط برای پلاگین‌های فهرست‌شده در مارکت‌پلیسِ رسمیِ Anthropic، یعنی claude-plugins-official، اثر می‌گذارد. Anthropic آن مارکت‌پلیس را به صلاحدیدِ خودش گردآوری می‌کند، و فرم‌های ثبتِ درون‌اپ به‌جایش پلاگین‌ها را به مارکت‌پلیسِ جامعه اضافه می‌کنند که پروتکلِ hint آن را بررسی نمی‌کند. اگر با یک تماسِ شریکِ Anthropic در ارتباطی، برای هماهنگیِ یک لیستینگ در مارکت‌پلیسِ رسمی با او تماس بگیر.

همچنین ببین

ساختِ پلاگین‌ها: پلاگینی را که CLIت پیشنهاد می‌دهد بساز
ساخت و توزیعِ یک مارکت‌پلیسِ پلاگین: پلاگین‌ها را بیرونِ مارکت‌پلیسِ رسمی میزبانی کن
متغیرهای محیطی: مرجعِ کاملِ CLAUDECODE و متغیرهای مرتبط