CLI에서 플러그인 추천 힌트 보내기

기준일: 2026-07-26
공식 기준: Recommend your plugin from your CLI

개요

공식 Anthropic 마켓플레이스에 플러그인이 있는 CLI/SDK 유지보수자는, Claude Code 안에서 실행 중임을 감지하면 한 줄 마커를 stderr에 써서 사용자에게 플러그인 설치 프롬프트를 띄울 수 있습니다. Claude Code는 마커를 읽고 출력에서 제거한 뒤 일회성 설치 프롬프트를 보여 줍니다.

힌트 줄은 모델로 보내지기 전에 제거되므로 대화에 나타나지 않고 토큰에도 포함되지 않습니다. 프로토콜은 추가 명령이 필요 없고, Claude Code 밖에서 사람이 CLI를 돌릴 때의 출력도 바꾸지 않습니다.

대상: CLI/SDK 유지보수자. 플러그인 설치만 필요하면 Discover and install plugins.

핵심 개념

항목	내용
감지 변수	`CLAUDECODE=1` (전 버전). v2.1.172+ 에서는 `CLAUDE_CODE_CHILD_SESSION=1`도 동일 서브프로세스에 설정
마커	self-closing `<claude-code-hint />` 태그, stderr 한 줄
대상 플러그인	공식 Anthropic 마켓플레이스 플러그인만
설치	자동 설치 없음. 사용자가 항상 확인
훅 명령	힌트 태그는 제거·무시. Bash/PowerShell 도구 출력만 설치 프롬프트 트리거

상세

동작 방식

Claude Code는 Bash·PowerShell 도구와 hook 명령에 CLAUDECODE=1을 설정합니다. v2.1.172부터 같은 서브프로세스에 CLAUDE_CODE_CHILD_SESSION=1도 설정합니다. CLI가 이 변수 중 하나를 보면 stderr에 <claude-code-hint />를 씁니다.

명령 출력을 받으면 Claude Code는:

힌트 줄을 스캔해 모델에 전달하기 전 제거
힌트가 공식 Anthropic 마켓플레이스 플러그인을 가리키는지 확인
이미 설치됐거나 이전에 프롬프트한 플러그인이 아닌지 확인
힌트를 낸 명령 이름을 포함한 설치 프롬프트 표시

힌트 방출

힌트 프롬프트는 공식 Anthropic 마켓플레이스 플러그인에만 동작합니다. 통합을 배포하기 전에 공식 마켓플레이스 등재를 확인하세요.

환경 변수로 게이트해 사람이 CLI를 직접 실행할 때 마커가 거의 나오지 않게 한 뒤, 태그 한 줄을 stderr에 씁니다.

변수	특징
`CLAUDECODE`	모든 Claude Code 버전. 가장 넓은 세션 도달. tmux·stdio MCP 서브프로세스·IDE 통합 터미널에도 설정될 수 있어 사람이 직접 CLI를 돌리는 경우에도 잡힐 수 있음
`CLAUDE_CODE_CHILD_SESSION` (v2.1.172+)	Claude Code가 직접 띄운 서브프로세스(도구 호출, hook, status line)에만 설정. 사람 터미널에 거의 안 감. 세션 안에서 시작한 장기 프로세스(예: tmux 서버)가 변수를 캡처하면 이후 셸에 raw 태그가 보일 수 있음. 구버전 세션은 힌트 누락

최대 도달을 위해 CLAUDECODE를 게이트하는 예 (example-cli@claude-plugins-official):

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를 공식 마켓플레이스 플러그인 이름으로 바꿉니다.

어디에 방출할지

플러그인 단위로 중복 제거되므로 매 호출 방출도 문제없습니다. 잘 맞는 지점:

위치	이유
`--help` 출력	낯선 CLI 탐색 시 Claude가 help를 자주 실행
알 수 없는 서브커맨드 오류	인터페이스 혼란 순간에 도달
로그인/인증 성공	설정 마인드셋
첫 실행 welcome	자연스러운 온보딩

사용자에게 보이는 내용

모든 검사를 통과하면 대략 다음 프롬프트가 뜹니다.

─────────────────────────────────────────────────────────────
  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초 무응답 시 No로 닫힙니다.

빈도 제한:

플러그인당 1회: 프롬프트가 한 번 뜨면 답과 무관하게 다시 안 뜸
세션당 1회: 머신上的 모든 CLI 합쳐 세션당 힌트 프롬프트 최대 1회
텔레메트리 옵트아웃: DISABLE_TELEMETRY 또는 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 설정 세션, 그리고 Bedrock·Google Cloud Agent Platform 등 자동 텔레메트리 옵트아웃이 적용되는 세션에서는 힌트 프롬프트 없음

Yes는 사용자 스코프에 설치. No, and don't show… 는 이후 모든 힌트 프롬프트를 끕니다.

힌트 형식

필수 속성 3개의 self-closing 태그:

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

속성	필수	설명
`v`	예	프로토콜 버전. 지원 값: `1`만
`type`	예	힌트 종류. 지원 값: `plugin`만
`value`	예	`name@marketplace` 형태 플러그인 식별자

속성 값은 큰따옴표 또는 unquoted. unquoted는 공백 불가. 이스케이프 시퀀스 미지원.

강제 요건

아래를 실패하면 힌트는 버려집니다.

단독 줄: 태그가 그 줄 전체여야 함. 로그 중간 삽입 무시. 앞뒤 공백 허용
공식 마켓플레이스: value가 claude-plugins-official 같은 Anthropic 제어 마켓플레이스 플러그인을 가리켜야 함. 다른 마켓플레이스는 조용히 드롭

버전·type이 인식되지 않아도 힌트 줄은 항상 모델 전달 전 제거되어 토큰에 포함되지 않습니다.

권장(강제 아님):

stderr에 쓰기: example-cli deploy | jq 같은 파이프라인에서 태그 분리. Claude Code는 양쪽 스트림을 스캔하므로 stdout도 동작
환경 변수 게이트: CLAUDECODE 또는 CLAUDE_CODE_CHILD_SESSION일 때만 방출

공식 마켓플레이스에 플러그인 올리기

힌트 프로토콜은 공식 마켓플레이스 claude-plugins-official 등재 플러그인에만 효과가 있습니다. Anthropic이 재량으로 큐레이션하며, 앱 내 제출 폼은 community marketplace로 가므로 힌트 검사 대상이 아닙니다. Anthropic 파트너 담당이 있으면 공식 등재를 조율하세요.

체크리스트

플러그인이 claude-plugins-official에 있다
CLAUDECODE(또는 v2.1.172+ CLAUDE_CODE_CHILD_SESSION) 게이트 후 stderr 한 줄에 태그를 쓴다
value가 name@marketplace 형식이다
태그가 단독 줄이다
자동 설치를 기대하지 않고 사용자 확인 UX를 설명한다

다음 단계

기준일

문서 작성·동기화 기준일: 2026-07-26
원문: https://code.claude.com/docs/en/plugin-hints

CLI에서 플러그인 추천 힌트 보내기

기준일: 2026-07-26
공식 기준: Recommend your plugin from your CLI

개요

대상: CLI/SDK 유지보수자. 플러그인 설치만 필요하면 Discover and install plugins.

핵심 개념

항목	내용
감지 변수	`CLAUDECODE=1` (전 버전). v2.1.172+ 에서는 `CLAUDE_CODE_CHILD_SESSION=1`도 동일 서브프로세스에 설정
마커	self-closing `<claude-code-hint />` 태그, stderr 한 줄
대상 플러그인	공식 Anthropic 마켓플레이스 플러그인만
설치	자동 설치 없음. 사용자가 항상 확인
훅 명령	힌트 태그는 제거·무시. Bash/PowerShell 도구 출력만 설치 프롬프트 트리거

상세

동작 방식

명령 출력을 받으면 Claude Code는:

힌트 줄을 스캔해 모델에 전달하기 전 제거
힌트가 공식 Anthropic 마켓플레이스 플러그인을 가리키는지 확인
이미 설치됐거나 이전에 프롬프트한 플러그인이 아닌지 확인
힌트를 낸 명령 이름을 포함한 설치 프롬프트 표시

힌트 방출

힌트 프롬프트는 공식 Anthropic 마켓플레이스 플러그인에만 동작합니다. 통합을 배포하기 전에 공식 마켓플레이스 등재를 확인하세요.

환경 변수로 게이트해 사람이 CLI를 직접 실행할 때 마커가 거의 나오지 않게 한 뒤, 태그 한 줄을 stderr에 씁니다.

변수	특징
`CLAUDECODE`	모든 Claude Code 버전. 가장 넓은 세션 도달. tmux·stdio MCP 서브프로세스·IDE 통합 터미널에도 설정될 수 있어 사람이 직접 CLI를 돌리는 경우에도 잡힐 수 있음
`CLAUDE_CODE_CHILD_SESSION` (v2.1.172+)	Claude Code가 직접 띄운 서브프로세스(도구 호출, hook, status line)에만 설정. 사람 터미널에 거의 안 감. 세션 안에서 시작한 장기 프로세스(예: tmux 서버)가 변수를 캡처하면 이후 셸에 raw 태그가 보일 수 있음. 구버전 세션은 힌트 누락

최대 도달을 위해 CLAUDECODE를 게이트하는 예 (example-cli@claude-plugins-official):

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를 공식 마켓플레이스 플러그인 이름으로 바꿉니다.

어디에 방출할지

플러그인 단위로 중복 제거되므로 매 호출 방출도 문제없습니다. 잘 맞는 지점:

위치	이유
`--help` 출력	낯선 CLI 탐색 시 Claude가 help를 자주 실행
알 수 없는 서브커맨드 오류	인터페이스 혼란 순간에 도달
로그인/인증 성공	설정 마인드셋
첫 실행 welcome	자연스러운 온보딩

사용자에게 보이는 내용

모든 검사를 통과하면 대략 다음 프롬프트가 뜹니다.

─────────────────────────────────────────────────────────────
  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초 무응답 시 No로 닫힙니다.

빈도 제한:

플러그인당 1회: 프롬프트가 한 번 뜨면 답과 무관하게 다시 안 뜸
세션당 1회: 머신上的 모든 CLI 합쳐 세션당 힌트 프롬프트 최대 1회
텔레메트리 옵트아웃: DISABLE_TELEMETRY 또는 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 설정 세션, 그리고 Bedrock·Google Cloud Agent Platform 등 자동 텔레메트리 옵트아웃이 적용되는 세션에서는 힌트 프롬프트 없음

Yes는 사용자 스코프에 설치. No, and don't show… 는 이후 모든 힌트 프롬프트를 끕니다.

힌트 형식

필수 속성 3개의 self-closing 태그:

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

속성	필수	설명
`v`	예	프로토콜 버전. 지원 값: `1`만
`type`	예	힌트 종류. 지원 값: `plugin`만
`value`	예	`name@marketplace` 형태 플러그인 식별자

속성 값은 큰따옴표 또는 unquoted. unquoted는 공백 불가. 이스케이프 시퀀스 미지원.

강제 요건

아래를 실패하면 힌트는 버려집니다.

단독 줄: 태그가 그 줄 전체여야 함. 로그 중간 삽입 무시. 앞뒤 공백 허용
공식 마켓플레이스: value가 claude-plugins-official 같은 Anthropic 제어 마켓플레이스 플러그인을 가리켜야 함. 다른 마켓플레이스는 조용히 드롭

버전·type이 인식되지 않아도 힌트 줄은 항상 모델 전달 전 제거되어 토큰에 포함되지 않습니다.

권장(강제 아님):

stderr에 쓰기: example-cli deploy | jq 같은 파이프라인에서 태그 분리. Claude Code는 양쪽 스트림을 스캔하므로 stdout도 동작
환경 변수 게이트: CLAUDECODE 또는 CLAUDE_CODE_CHILD_SESSION일 때만 방출

공식 마켓플레이스에 플러그인 올리기

체크리스트

플러그인이 claude-plugins-official에 있다
CLAUDECODE(또는 v2.1.172+ CLAUDE_CODE_CHILD_SESSION) 게이트 후 stderr 한 줄에 태그를 쓴다
value가 name@marketplace 형식이다
태그가 단독 줄이다
자동 설치를 기대하지 않고 사용자 확인 UX를 설명한다

다음 단계

기준일

문서 작성·동기화 기준일: 2026-07-26
원문: https://code.claude.com/docs/en/plugin-hints

CLI에서 플러그인 추천 힌트 보내기

개요

핵심 개념

상세

동작 방식

힌트 방출

어디에 방출할지

사용자에게 보이는 내용

힌트 형식

강제 요건

공식 마켓플레이스에 플러그인 올리기

체크리스트

다음 단계

기준일

관련 가이드

CLI에서 플러그인 추천 힌트 보내기

개요

핵심 개념

상세

동작 방식

힌트 방출

어디에 방출할지

사용자에게 보이는 내용

힌트 형식

강제 요건

공식 마켓플레이스에 플러그인 올리기

체크리스트

다음 단계

기준일

관련 가이드