Gợi ý cài plugin từ CLI của bạn

Nếu bạn duy trì một CLI hoặc SDK và có plugin trong marketplace chính thức của Anthropic, công cụ của bạn có thể gợi ý user Claude Code cài plugin đó. CLI của bạn ghi một marker một dòng ra stderr khi phát hiện đang chạy trong Claude Code. Claude Code đọc marker, strip nó khỏi output, và hiện cho user một prompt cài đặt một lần.

Claude Code strip dòng hint này khỏi output lệnh trước khi gửi cho model, nên marker không bao giờ xuất hiện trong conversation và không tính vào token usage. Giao thức không yêu cầu lệnh phụ nào và không đổi những gì CLI của bạn in ra cho user bên ngoài Claude Code.

Trang này dành cho người duy trì CLI/SDK. Nếu bạn muốn cài plugin, xem Khám phá và cài plugin.

Cách hoạt động

Claude Code đặt biến môi trường CLAUDECODE=1 cho mọi lệnh chạy qua tool Bash và PowerShell, và cho lệnh hook. Từ v2.1.172, nó cũng đặt CLAUDE_CODE_CHILD_SESSION=1 trong các subprocess đó. Khi CLI của bạn thấy một trong hai biến này, nó ghi một tag tự đóng <claude-code-hint /> ra stderr. Trong lệnh hook, hint tag bị strip và bỏ qua - chỉ output từ tool Bash và PowerShell kích hoạt prompt cài đặt.

Khi nhận output lệnh, Claude Code:

1. Quét tìm dòng hint và loại bỏ trước khi tới model
2. Kiểm tra hint trỏ tới plugin trong marketplace chính thức của Anthropic
3. Kiểm tra plugin chưa cài và chưa từng được hỏi trước đó
4. Hiện prompt cài đặt nêu tên lệnh đã phát ra hint

Claude Code không bao giờ tự cài plugin - user luôn phải xác nhận.

Phát ra hint

Prompt hint chỉ kích hoạt cho plugin trong marketplace chính thức Anthropic. Xem Đưa plugin vào marketplace chính thức trước khi ship tích hợp.

Gate việc phát hint theo một biến môi trường để marker khó xuất hiện khi người dùng chạy CLI trực tiếp, sau đó ghi tag ra stderr trên một dòng riêng. Chọn biến để kiểm tra:

• CLAUDECODE: đặt trên mọi bản Claude Code, nên tiếp cận nhiều session nhất. Cũng đặt trong session tmux và subprocess MCP server dạng stdio mà Claude Code khởi động. IDE extension cũng đặt nó trong terminal tích hợp, nơi một người có thể đang tự chạy CLI của bạn.
• CLAUDE_CODE_CHILD_SESSION: chỉ đặt trong subprocess do chính Claude Code spawn (tool call, hook, lệnh statusline), nên tag thường không tới terminal của người dùng thật. Yêu cầu Claude Code v2.1.172 trở lên.

Ví dụ dưới đây gate theo CLAUDECODE để tiếp cận rộng nhất, phát hint cho plugin tên example-cli trong marketplace chính thức:

Node.js

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,
    )

Shell

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

Thay example-cli bằng tên plugin của bạn trong marketplace chính thức.

Chọn nơi phát hint

Bạn kiểm soát code path nào phát hint. Claude Code deduplicate theo plugin, nên phát ở mọi lần gọi không có nhược điểm. Các điểm chạm hiệu quả:

Vị trí	Vì sao hiệu quả
Output --help	Claude thường chạy help khi khám phá một CLI lạ
Lỗi subcommand không xác định	Đúng lúc Claude đang bối rối về interface của bạn
Đăng nhập/xác thực thành công	User đang ở tâm thế thiết lập
Thông báo welcome lần chạy đầu	Thời điểm onboarding tự nhiên

Điều user thấy

Khi hint qua mọi kiểm tra, Claude Code hiện một prompt tương tự:

─────────────────────────────────────────────────────────────
  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

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

Prompt nêu tên lệnh đã phát ra hint để user phát hiện nếu công cụ và plugin gợi ý không khớp. Nếu user không phản hồi trong 30 giây, Claude Code tự bỏ qua như chọn No.

Tần suất prompt bị giới hạn:

• Một lần cho mỗi plugin: sau khi hiện prompt, Claude Code ghi nhớ và không hỏi lại, bất kể user trả lời gì.
• Một lần mỗi session: tối đa một hint prompt xuất hiện mỗi session Claude Code, tính trên mọi CLI trên máy.
• Opt-out telemetry: session tắt analytics không bao giờ hiện hint prompt, gồm session đặt DISABLE_TELEMETRY hoặc CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, và session trên provider bên thứ ba (Bedrock, Vertex…) do opt-out telemetry tự động.

Chọn Yes cài plugin ở user scope. Chọn No, and don’t show plugin installation hints again tắt mọi hint prompt tương lai cho user đó.

Định dạng hint

Hint là một tag tự đóng với ba thuộc tính bắt buộc:

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

Thuộc tính	Bắt buộc	Mô tả
v	Có	Phiên bản giao thức. 1 là giá trị duy nhất được hỗ trợ
type	Có	Loại hint. plugin là giá trị duy nhất được hỗ trợ
value	Có	ID plugin dạng name@marketplace

Giá trị thuộc tính có thể quote bằng dấu ngoặc kép hoặc để trần. Giá trị không quote không được chứa khoảng trắng. Không hỗ trợ escape sequence.

Yêu cầu

Claude Code enforce hai điều kiện trước khi xử lý hint. Hint không đạt sẽ bị bỏ qua:

• Trên dòng riêng: tag phải nằm trên dòng riêng của nó. Tag nhúng giữa dòng (ví dụ trong một log statement) bị bỏ qua.
• Marketplace chính thức: value phải trỏ tới plugin trong marketplace do Anthropic kiểm soát như claude-plugins-official. Hint trỏ tới marketplace khác bị âm thầm bỏ qua.

Dòng hint luôn bị loại khỏi output trước khi tới model, kể cả khi version hoặc type không nhận diện được, nên marker không bao giờ tính vào token usage.

Phần còn lại là khuyến nghị, không bắt buộc - Claude Code không thể quan sát CLI của bạn có tuân theo hay không: ghi ra stderr (giữ tag khỏi shell pipeline), và gate theo một biến môi trường.

Đưa plugin vào marketplace chính thức

Giao thức hint chỉ có hiệu lực cho plugin trong marketplace chính thức của Anthropic, claude-plugins-official. Anthropic tự quyết định việc curate marketplace này, và các form submit trong app đưa plugin vào community marketplace thay vào đó - giao thức hint không kiểm tra marketplace đó. Nếu bạn đang làm việc với một đối tác Anthropic, liên hệ họ để phối hợp niêm yết vào marketplace chính thức.

Nguồn

Dịch và biên soạn từ Recommend your plugin from your CLI.