Skip to main content

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Se você mantém uma CLI ou SDK e tem um plugin no marketplace oficial da Anthropic, sua ferramenta pode solicitar aos usuários do Claude Code que instalem esse plugin. Sua CLI escreve um marcador de uma linha para stderr quando detecta que está sendo executada dentro do Claude Code. Claude Code lê o marcador, remove-o da saída e mostra ao usuário um prompt de instalação única. Claude Code remove a linha de dica da saída do comando antes de enviá-la ao modelo, portanto o marcador nunca aparece na conversa e não é contado para o uso de tokens. O protocolo não requer comandos extras e não altera o que sua CLI imprime para usuários fora do Claude Code. Esta página é para mantenedores de CLI e SDK. Se você está procurando instalar plugins, consulte Descobrir e instalar plugins.

​
Como funciona

Claude Code define a variável de ambiente CLAUDECODE como 1 para cada comando que executa através das ferramentas Bash e PowerShell. Quando sua CLI vê essa variável, ela escreve uma tag <claude-code-hint /> auto-fechável para stderr. Quando Claude Code recebe a saída do comando, ele:
  1. Verifica linhas de dica e as remove antes da saída chegar ao modelo
  2. Verifica se a dica aponta para um plugin em um marketplace oficial da Anthropic
  3. Verifica se o plugin ainda não foi instalado e não foi solicitado antes
  4. Mostra ao usuário um prompt de instalação que nomeia o comando que emitiu a dica
Claude Code nunca instala um plugin automaticamente. O usuário sempre confirma.

​
Emita a dica

Gate a emissão na variável de ambiente CLAUDECODE para que o marcador nunca apareça no terminal de um usuário humano. Em seguida, escreva a tag para stderr em sua própria linha. Os exemplos a seguir emitem uma dica para um plugin chamado example-cli no marketplace oficial: 
if (process.env.CLAUDECODE) {
  process.stderr.write(
    '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />\n',
  )
}
Substitua example-cli pelo nome do seu plugin no marketplace oficial.

​
Escolha onde emitir

Você controla quais caminhos de código emitem a dica. Claude Code deduplica por plugin, portanto emitir em cada invocação não tem desvantagem. Os pontos de contato que funcionam bem incluem:
PosicionamentoPor que funciona
Saída de --helpClaude frequentemente executa help ao explorar uma CLI desconhecida
Erros de subcomando desconhecidoAtinge o momento em que Claude está confuso sobre sua interface
Sucesso de login ou autenticaçãoO usuário já está em uma mentalidade de configuração
Mensagem de boas-vindas na primeira execuçãoUm momento natural de integração

​
O que o usuário vê

Quando a dica passa em todas as verificações, Claude Code mostra um prompt como o seguinte: 
─────────────────────────────────────────────────────────────
  Recomendação de Plugin

    O comando example-cli sugere instalar um plugin.

    Plugin: example-cli
    Marketplace: claude-plugins-official
    Integração oficial para implantações example-cli

    Você gostaria de instalá-lo?
    ❯ 1. Sim, instalar example-cli
      2. Não
      3. Não, e não mostrar dicas de instalação de plugin novamente

─────────────────────────────────────────────────────────────
O prompt nomeia o comando que produziu a dica para que os usuários possam detectar uma incompatibilidade entre a ferramenta e o plugin que ela recomenda. Se o usuário não responder dentro de 30 segundos, o prompt é descartado como Não. A frequência do prompt é limitada:
  • Uma vez por plugin: após o prompt ser exibido, Claude Code registra o plugin e nunca o solicita novamente, independentemente da resposta do usuário.
  • Uma vez por sessão: em todas as CLIs da máquina, no máximo um prompt de dica aparece por sessão do Claude Code.
Selecionar Sim instala o plugin no escopo do usuário. Selecionar Não, e não mostrar dicas de instalação de plugin novamente desabilita todos os prompts de dica futuros para o usuário.

​
Formato da dica

A dica é uma tag auto-fechável com três atributos obrigatórios. 
<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />
AtributoObrigatórioDescrição
vSimVersão do protocolo. 1 é o único valor suportado
typeSimTipo de dica. plugin é o único valor suportado
valueSimIdentificador do plugin na forma name@marketplace
Os valores dos atributos podem ser citados com aspas duplas ou deixados sem aspas. Valores sem aspas não podem conter espaços em branco. Sequências de escape não são suportadas.

​
Requisitos

Claude Code impõe duas condições antes de agir em uma dica. Dicas que falham em qualquer uma das verificações são descartadas:
  • Linha própria: a tag deve ocupar sua própria linha. Uma tag incorporada no meio da linha, por exemplo dentro de uma instrução de log, é ignorada. Espaço em branco à esquerda e à direita na linha é permitido.
  • Marketplace oficial: o value deve fazer referência a um plugin em um marketplace controlado pela Anthropic, como claude-plugins-official. Dicas que apontam para outros marketplaces são silenciosamente descartadas.
A linha de dica é sempre removida da saída antes de chegar ao modelo, mesmo quando a versão ou tipo não é reconhecido, portanto o marcador nunca é contado para o uso de tokens. As orientações restantes são recomendadas, mas não obrigatórias. Claude Code não pode observar se sua CLI as segue:
  • Escrever para stderr: stderr mantém a tag fora de pipelines de shell, como example-cli deploy | jq. Claude Code verifica ambos os fluxos, portanto stdout também funciona.
  • Gate em CLAUDECODE: emita apenas quando a variável de ambiente CLAUDECODE estiver definida. Isso evita que o marcador apareça para usuários que executam sua CLI diretamente.

​
Coloque seu plugin no marketplace oficial

O protocolo de dica só entra em vigor para plugins listados no marketplace oficial da Anthropic. Para enviar um plugin, use um dos formulários de envio no aplicativo: Se você está trabalhando com um contato de parceiro da Anthropic, entre em contato com ele para coordenar a listagem.

​
Veja também