plugin-hints.md +0 −172 deleted
File Deleted View Diff
1> ## Documentation Index
2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
3> Use this file to discover all available pages before exploring further.
4
5# Recomende seu plugin a partir de sua CLI
6
7> Emita um marcador de uma linha a partir de sua CLI para que Claude Code solicite aos usuários que instalem seu plugin oficial.
8
9Se 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.
10
11O protocolo não requer comandos extras e não altera o que sua CLI imprime para usuários fora do Claude Code.
12
13Esta página é para mantenedores de CLI e SDK. Se você está procurando instalar plugins, consulte [Descobrir e instalar plugins](/docs/pt/discover-plugins).
14
15<h2 id="how-it-works">
16 Como funciona
17</h2>
18
19Claude Code define a variável de ambiente [`CLAUDECODE`](/docs/pt/env-vars) como `1` para cada comando que executa através das ferramentas Bash e PowerShell, e para comandos de [hook](/docs/pt/hooks). A partir da v2.1.172, também define [`CLAUDE_CODE_CHILD_SESSION`](/docs/pt/env-vars) como `1` nesses mesmos subprocessos. Quando sua CLI vê uma dessas variáveis, ela escreve uma tag auto-fechável `<claude-code-hint />` para stderr. Em comandos de hook, a tag de dica é removida e ignorada. Apenas a saída das ferramentas Bash e PowerShell dispara o prompt de instalação.
20
21Quando Claude Code recebe a saída do comando, ele:
22
231. Verifica linhas de dica e as remove antes da saída chegar ao modelo
242. Verifica se a dica aponta para um plugin em um marketplace oficial da Anthropic
253. Verifica se o plugin ainda não foi instalado e não foi solicitado antes
264. Mostra ao usuário um prompt de instalação que nomeia o comando que emitiu a dica
27
28Claude Code nunca instala um plugin automaticamente. O usuário sempre confirma.
29
30<h2 id="emit-the-hint">
31 Emita a dica
32</h2>
33
34As dicas de prompt só são acionadas para plugins listados no marketplace oficial da Anthropic. Consulte [Coloque seu plugin no marketplace oficial](#get-your-plugin-into-the-official-marketplace) antes de enviar a integração.
35
36Gate a emissão em uma variável de ambiente para que o marcador seja improvável de aparecer quando um humano executa seu CLI diretamente, depois escreva a tag para stderr em sua própria linha. Escolha qual variável verificar:
37
38* `CLAUDECODE`: definida em todas as versões do Claude Code, portanto atinge a maioria das sessões. Também é definida em sessões tmux e subprocessos do servidor MCP stdio que Claude Code inicia. Extensões IDE também a definem em seus terminais integrados, onde um humano pode estar executando seu CLI diretamente.
39* `CLAUDE_CODE_CHILD_SESSION`: definida apenas em subprocessos que o próprio Claude Code gera, como chamadas de ferramenta, comandos hook e comandos da [linha de status](/docs/pt/statusline), portanto a tag normalmente não atinge um terminal humano. Um processo de longa duração que foi iniciado dentro de uma sessão, como um servidor tmux, captura a variável, portanto shells iniciados posteriormente a partir desse processo ainda mostram a tag bruta.
40
41Os exemplos a seguir fazem gate em `CLAUDECODE` para máximo alcance e emitem uma dica para um plugin chamado `example-cli` no marketplace oficial:
42
43<CodeGroup>
44 ```javascript Node.js theme={null}
45 if (process.env.CLAUDECODE) {
46 process.stderr.write(
47 '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />\n',
48 )
49 }
50 ```
51
52 ```python Python theme={null}
53 import os, sys
54
55 if os.environ.get("CLAUDECODE"):
56 print(
57 '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />',
58 file=sys.stderr,
59 )
60 ```
61
62 ```go Go theme={null}
63 if os.Getenv("CLAUDECODE") != "" {
64 fmt.Fprintln(os.Stderr,
65 `<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />`)
66 }
67 ```
68
69 ```shell Shell theme={null}
70 if [ -n "$CLAUDECODE" ]; then
71 printf '%s\n' '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />' >&2
72 fi
73 ```
74</CodeGroup>
75
76Substitua `example-cli` pelo nome do seu plugin no marketplace oficial.
77
78<h2 id="choose-where-to-emit">
79 Escolha onde emitir
80</h2>
81
82Você 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:
83
84| Posicionamento | Por que funciona |
85| :------------------------------------------- | :------------------------------------------------------------------ |
86| Saída de `--help` | Claude frequentemente executa help ao explorar uma CLI desconhecida |
87| Erros de subcomando desconhecido | Atinge o momento em que Claude está confuso sobre sua interface |
88| Sucesso de login ou autenticação | O usuário já está em uma mentalidade de configuração |
89| Mensagem de boas-vindas na primeira execução | Um momento natural de integração |
90
91<h2 id="what-the-user-sees">
92 O que o usuário vê
93</h2>
94
95Quando a dica passa em todas as verificações, Claude Code mostra um prompt como o seguinte:
96
97```text theme={null}
98─────────────────────────────────────────────────────────────
99 Recomendação de Plugin
100
101 O comando example-cli sugere instalar um plugin.
102
103 Plugin: example-cli
104 Marketplace: claude-plugins-official
105 Integração oficial para implantações example-cli
106
107 Você gostaria de instalá-lo?
108 ❯ 1. Sim, instalar example-cli
109 2. Não
110 3. Não, e não mostrar dicas de instalação de plugin novamente
111
112─────────────────────────────────────────────────────────────
113```
114
115O 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, Claude Code descarta o prompt como **Não**.
116
117A frequência do prompt é limitada, e algumas sessões nunca exibem prompts:
118
119* **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.
120* **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.
121* **Apenas sessão interativa principal**: Claude Code mostra o prompt apenas na sessão de terminal em que o usuário está digitando. Claude Code nunca solicita um comando que um [subagent](/docs/pt/sub-agents) executa, e nunca solicita quando o usuário executa Claude Code em [modo não interativo](/docs/pt/headless) com a flag `-p` ou através do [Agent SDK](/docs/pt/agent-sdk/overview). Claude Code ainda remove a linha de dica da saída do comando em todos esses casos.
122* **Exclusões de telemetria**: sessões onde a análise está desabilitada nunca exibem prompts de dica. Isso inclui sessões com `DISABLE_TELEMETRY` ou `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` definidas, e sessões em provedores de terceiros como Amazon Bedrock ou Google Cloud's Agent Platform onde a [exclusão automática de telemetria](/docs/pt/data-usage#default-behaviors-by-api-provider) se aplica.
123
124Selecionar **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.
125
126<h2 id="hint-format">
127 Formato da dica
128</h2>
129
130A dica é uma tag auto-fechável com três atributos obrigatórios.
131
132```text theme={null}
133<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />
134```
135
136| Atributo | Obrigatório | Descrição |
137| :------- | :---------- | :-------------------------------------------------- |
138| `v` | Sim | Versão do protocolo. `1` é o único valor suportado |
139| `type` | Sim | Tipo de dica. `plugin` é o único valor suportado |
140| `value` | Sim | Identificador do plugin na forma `name@marketplace` |
141
142Os 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.
143
144<h2 id="requirements">
145 Requisitos
146</h2>
147
148Claude Code impõe duas condições antes de agir em uma dica. Dicas que falham em qualquer uma das verificações são descartadas:
149
150* **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.
151* **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.
152
153A 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.
154
155As orientações restantes são recomendadas, mas não obrigatórias. Claude Code não pode observar se sua CLI as segue:
156
157* **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.
158* **Gate em uma variável de ambiente**: emita apenas quando `CLAUDECODE` ou `CLAUDE_CODE_CHILD_SESSION` estiver definido. Consulte [Emitir a dica](#emit-the-hint) para saber como as duas variáveis diferem.
159
160<h2 id="get-your-plugin-into-the-official-marketplace">
161 Coloque seu plugin no marketplace oficial
162</h2>
163
164O protocolo de dica só entra em vigor para plugins listados no marketplace oficial da Anthropic, `claude-plugins-official`. A Anthropic cura esse marketplace a seu critério, e os formulários de envio no aplicativo adicionam plugins ao [marketplace da comunidade](/docs/pt/plugins#submit-your-plugin-to-the-community-marketplace), que o protocolo de dica não verifica. Se você está trabalhando com um contato de parceiro da Anthropic, entre em contato com ele para coordenar uma listagem no marketplace oficial.
165
166<h2 id="see-also">
167 Veja também
168</h2>
169
170* [Criar plugins](/docs/pt/plugins): construa o plugin que sua CLI recomenda
171* [Criar e distribuir um marketplace de plugins](/docs/pt/plugin-marketplaces): hospede plugins fora do marketplace oficial
172* [Variáveis de ambiente](/docs/pt/env-vars): referência completa para `CLAUDECODE` e variáveis relacionadas