Documentation — Spybara

agent-sdk/hooks.md +10 −10

Details

24 </Step>24 </Step>

25 25

26 <Step title="O SDK coleta hooks registrados">26 <Step title="O SDK coleta hooks registrados">

27 O SDK verifica se há hooks registrados para esse tipo de evento. Isso inclui hooks de callback que você passa em `options.hooks` e hooks de comando shell de arquivos de configuração quando a entrada [`settingSources`](/pt/agent-sdk/typescript#setting-source) ou [`setting_sources`](/pt/agent-sdk/python#setting-source) correspondente está habilitada, o que é o padrão para opções `query()`.27 O SDK verifica se há hooks registrados para esse tipo de evento. Isso inclui hooks de callback que você passa em `options.hooks` e hooks de comando shell de arquivos de configuração quando a entrada [`settingSources`](/pt/agent-sdk/typescript#settingsource) ou [`setting_sources`](/pt/agent-sdk/python#settingsource) correspondente está habilitada, o que é o padrão para opções `query()`.

28 </Step>28 </Step>

29 29

30 <Step title="Matchers filtram quais hooks são executados">30 <Step title="Matchers filtram quais hooks são executados">

225 225

226Cada callback de hook recebe três argumentos:226Cada callback de hook recebe três argumentos:

227 227

228* **Dados de entrada:** um objeto tipado contendo detalhes do evento. Cada tipo de hook tem sua própria forma de entrada (por exemplo, `PreToolUseHookInput` inclui `tool_name` e `tool_input`, enquanto `NotificationHookInput` inclui `message`). Veja as definições de tipo completas nas referências do SDK [TypeScript](/pt/agent-sdk/typescript#hook-input) e [Python](/pt/agent-sdk/python#hook-input).228* **Dados de entrada:** um objeto tipado contendo detalhes do evento. Cada tipo de hook tem sua própria forma de entrada (por exemplo, `PreToolUseHookInput` inclui `tool_name` e `tool_input`, enquanto `NotificationHookInput` inclui `message`). Veja as definições de tipo completas nas referências do SDK [TypeScript](/pt/agent-sdk/typescript#hookinput) e [Python](/pt/agent-sdk/python#hookinput).

229 * Todas as entradas de hook compartilham `session_id`, `cwd` e `hook_event_name`.229 * Todas as entradas de hook compartilham `session_id`, `cwd` e `hook_event_name`.

230 * `agent_id` e `agent_type` são preenchidos quando o hook é acionado dentro de um subagente. Em TypeScript, estes estão na entrada de hook base e disponíveis para todos os tipos de hook. Em Python, eles estão em `PreToolUse`, `PostToolUse` e `PostToolUseFailure` apenas.230 * `agent_id` e `agent_type` são preenchidos quando o hook é acionado dentro de um subagente. Em TypeScript, estes estão na entrada de hook base e disponíveis para todos os tipos de hook. Em Python, eles estão em `PreToolUse`, `PostToolUse` e `PostToolUseFailure` apenas.

231* **ID de uso de ferramenta** (`str | None` / `string | undefined`): correlaciona eventos `PreToolUse` e `PostToolUse` para a mesma chamada de ferramenta.231* **ID de uso de ferramenta** (`str | None` / `string | undefined`): correlaciona eventos `PreToolUse` e `PostToolUse` para a mesma chamada de ferramenta.

236Seu callback retorna um objeto com duas categorias de campos:236Seu callback retorna um objeto com duas categorias de campos:

237 237

238* **Campos de nível superior** controlam a conversa: `systemMessage` injeta uma mensagem na conversa visível ao modelo, e `continue` (`continue_` em Python) determina se o agente continua executando após este hook.238* **Campos de nível superior** controlam a conversa: `systemMessage` injeta uma mensagem na conversa visível ao modelo, e `continue` (`continue_` em Python) determina se o agente continua executando após este hook.

239* **`hookSpecificOutput`** controla a operação atual. Os campos dentro dependem do tipo de evento de hook. Para hooks `PreToolUse`, é aqui que você define `permissionDecision` (`"allow"`, `"deny"` ou `"ask"`), `permissionDecisionReason` e `updatedInput`. No SDK TypeScript, `permissionDecision` também aceita `"defer"` para encerrar a consulta e [retomar depois](/pt/hooks#defer-a-tool-call-for-later); este valor não está disponível no SDK Python. Para hooks `PostToolUse`, você pode definir `additionalContext` para anexar informações ao resultado da ferramenta, ou `updatedToolOutput` para substituir completamente a saída da ferramenta antes de Claude vê-la.239* **`hookSpecificOutput`** controla a operação atual. Os campos dentro dependem do tipo de evento de hook. Para hooks `PreToolUse`, é aqui que você define `permissionDecision` (`"allow"`, `"deny"`, `"ask"` ou `"defer"`), `permissionDecisionReason` e `updatedInput`. Retornar `"defer"` encerra a consulta para que você possa [retomá-la depois](/pt/hooks#defer-a-tool-call-for-later). Para hooks `PostToolUse`, você pode definir `additionalContext` para anexar informações ao resultado da ferramenta, ou `updatedToolOutput` para substituir completamente a saída da ferramenta antes de Claude vê-la.

240 240

241Retorne `{}` para permitir a operação sem alterações. Hooks de callback do SDK usam o mesmo formato de saída JSON que [hooks de comando shell do Claude Code](/pt/hooks#json-output), que documenta cada campo e opção específica do evento. Para as definições de tipo do SDK, veja as referências do SDK [TypeScript](/pt/agent-sdk/typescript#sync-hook-json-output) e [Python](/pt/agent-sdk/python#sync-hook-json-output).241Retorne `{}` para permitir a operação sem alterações. Hooks de callback do SDK usam o mesmo formato de saída JSON que [hooks de comando shell do Claude Code](/pt/hooks#json-output), que documenta cada campo e opção específica do evento. Para as definições de tipo do SDK, veja as referências do SDK [TypeScript](/pt/agent-sdk/typescript#synchookjsonoutput) e [Python](/pt/agent-sdk/python#synchookjsonoutput).

242 242

243<Note>243<Note>

244 Quando múltiplos hooks ou regras de permissão se aplicam, **deny** tem prioridade sobre **defer**, que tem prioridade sobre **ask**, que tem prioridade sobre **allow**. Se qualquer hook retornar `deny`, a operação é bloqueada independentemente de outros hooks.244 Quando múltiplos hooks ou regras de permissão se aplicam, **deny** tem prioridade sobre **defer**, que tem prioridade sobre **ask**, que tem prioridade sobre **allow**. Se qualquer hook retornar `deny`, a operação é bloqueada independentemente de outros hooks.

326</CodeGroup>326</CodeGroup>

327 327

328<Note>328<Note>

329 Ao usar `updatedInput`, você também deve incluir `permissionDecision: 'allow'`. Sempre retorne um novo objeto em vez de mutar o `tool_input` original.329 Ao usar `updatedInput`, você também deve incluir `permissionDecision: 'allow'` para aprovar automaticamente a entrada modificada ou `permissionDecision: 'ask'` para mostrá-la ao usuário. Com `'defer'`, `updatedInput` é ignorado. Sempre retorne um novo objeto em vez de mutar o `tool_input` original.

330</Note>330</Note>

331 331

332### Adicionar contexto e bloquear uma ferramenta332### Adicionar contexto e bloquear uma ferramenta

489 489

490### Rastrear atividade de subagente490### Rastrear atividade de subagente

491 491

492Use hooks `SubagentStop` para monitorar quando subagentes terminam seu trabalho. Veja o tipo de entrada completo nas referências do SDK [TypeScript](/pt/agent-sdk/typescript#hook-input) e [Python](/pt/agent-sdk/python#hook-input). Este exemplo registra um resumo cada vez que um subagente é concluído:492Use hooks `SubagentStop` para monitorar quando subagentes terminam seu trabalho. Veja o tipo de entrada completo nas referências do SDK [TypeScript](/pt/agent-sdk/typescript#hookinput) e [Python](/pt/agent-sdk/python#hookinput). Este exemplo registra um resumo cada vez que um subagente é concluído:

493 493

494<CodeGroup>494<CodeGroup>

495 ```python Python theme={null}495 ```python Python theme={null}

621 621

622### Encaminhar notificações para Slack622### Encaminhar notificações para Slack

623 623

624Use hooks `Notification` para receber notificações do sistema do agente e encaminhá-las para serviços externos. Notificações são disparadas para tipos de evento específicos: `permission_prompt` (Claude precisa de permissão), `idle_prompt` (Claude está aguardando entrada), `auth_success` (autenticação concluída) e `elicitation_dialog` (Claude está solicitando ao usuário). Cada notificação inclui um campo `message` com uma descrição legível por humanos e opcionalmente um `title`.624Use hooks `Notification` para receber notificações do sistema do agente e encaminhá-las para serviços externos. Notificações são disparadas para tipos de evento específicos: `permission_prompt` (Claude precisa de permissão), `idle_prompt` (Claude está aguardando entrada), `auth_success` (autenticação concluída), `elicitation_dialog` (Claude está solicitando ao usuário), `elicitation_response` (o usuário respondeu a uma elicitação) e `elicitation_complete` (uma elicitação foi fechada). Cada notificação inclui um campo `message` com uma descrição legível por humanos e opcionalmente um `title`.

625 625

626Este exemplo encaminha cada notificação para um canal Slack. Requer uma [URL de webhook de entrada do Slack](https://api.slack.com/messaging/webhooks), que você cria adicionando um app ao seu espaço de trabalho Slack e habilitando webhooks de entrada:626Este exemplo encaminha cada notificação para um canal Slack. Requer uma [URL de webhook de entrada do Slack](https://api.slack.com/messaging/webhooks), que você cria adicionando um app ao seu espaço de trabalho Slack e habilitando webhooks de entrada:

627 627

727* Verifique se seu padrão de matcher corresponde exatamente ao nome da ferramenta727* Verifique se seu padrão de matcher corresponde exatamente ao nome da ferramenta

728* Certifique-se de que o hook está sob o tipo de evento correto em `options.hooks`728* Certifique-se de que o hook está sob o tipo de evento correto em `options.hooks`

729* Para hooks não baseados em ferramentas como `Stop` e `SubagentStop`, matchers correspondem a campos diferentes (veja [padrões de matcher](/pt/hooks#matcher-patterns))729* Para hooks não baseados em ferramentas como `Stop` e `SubagentStop`, matchers correspondem a campos diferentes (veja [padrões de matcher](/pt/hooks#matcher-patterns))

730* Hooks podem não ser disparados quando o agente atinge o limite [`max_turns`](/pt/agent-sdk/python#claude-agent-options) porque a sessão termina antes que hooks possam ser executados730* Hooks podem não ser disparados quando o agente atinge o limite [`max_turns`](/pt/agent-sdk/python#claudeagentoptions) porque a sessão termina antes que hooks possam ser executados

731 731

732### Matcher não filtra como esperado732### Matcher não filtra como esperado

733 733

769 };769 };

770 ```770 ```

771 771

772* Você também deve retornar `permissionDecision: 'allow'` para que a modificação de entrada tenha efeito772* Você também deve retornar `permissionDecision: 'allow'` ou `'ask'` para que a modificação de entrada tenha efeito

773 773

774* Inclua `hookEventName` em `hookSpecificOutput` para identificar qual tipo de hook a saída é774* Inclua `hookEventName` em `hookSpecificOutput` para identificar qual tipo de hook a saída é

775 775

776### Hooks de sessão não disponíveis em Python776### Hooks de sessão não disponíveis em Python

777 777

778`SessionStart` e `SessionEnd` podem ser registrados como hooks de callback do SDK em TypeScript, mas não estão disponíveis no SDK Python (`HookEvent` os omite). Em Python, eles estão disponíveis apenas como [hooks de comando shell](/pt/hooks#hook-events) definidos em arquivos de configuração (por exemplo, `.claude/settings.json`). Para carregar hooks de comando shell de sua aplicação SDK, inclua a fonte de configuração apropriada com [`setting_sources`](/pt/agent-sdk/python#setting-source) ou [`settingSources`](/pt/agent-sdk/typescript#setting-source):778`SessionStart` e `SessionEnd` podem ser registrados como hooks de callback do SDK em TypeScript, mas não estão disponíveis no SDK Python (`HookEvent` os omite). Em Python, eles estão disponíveis apenas como [hooks de comando shell](/pt/hooks#hook-events) definidos em arquivos de configuração (por exemplo, `.claude/settings.json`). Para carregar hooks de comando shell de sua aplicação SDK, inclua a fonte de configuração apropriada com [`setting_sources`](/pt/agent-sdk/python#settingsource) ou [`settingSources`](/pt/agent-sdk/typescript#settingsource):

779 779

780<CodeGroup>780<CodeGroup>

781 ```python Python theme={null}781 ```python Python theme={null}

agent-sdk/modifying-system-prompts.md +431 −0 created

Details

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.

5# Modificando prompts do sistema

7> Escolha entre a predefinição `claude_code` e um prompt do sistema personalizado, e personalize o comportamento com CLAUDE.md, estilos de saída, append ou um prompt totalmente personalizado.

9Os prompts do sistema definem o comportamento, as capacidades e o estilo de resposta do Claude. Comece pela predefinição `claude_code` para ferramentas de codificação tipo CLI ou IDE onde um humano observa e orienta o trabalho. Escreva seu próprio prompt para agentes com uma superfície, identidade ou modelo de permissão diferentes.

11Esta página cobre:

13* [Como os prompts do sistema funcionam](#how-system-prompts-work), com uma tabela de decisão para escolher entre a predefinição, a predefinição com `append` e um prompt personalizado

14* [Personalize o comportamento do agente](#customize-agent-behavior) com arquivos CLAUDE.md, estilos de saída, `append` ou uma string personalizada

15* [Compare as quatro abordagens](#compare-the-four-approaches) por persistência, escopo e o que elas preservam

16* [Combine abordagens](#combine-approaches) para sobrepor métodos de personalização

18## Como os prompts do sistema funcionam

20Um prompt do sistema é o conjunto inicial de instruções que molda como o Claude se comporta ao longo de uma conversa. O Agent SDK tem três pontos de partida para isso:

22* **Padrão mínimo**: quando você não define `systemPrompt` em TypeScript ou `system_prompt` em Python, o SDK usa um prompt mínimo que cobre chamadas de ferramentas, mas omite as diretrizes de codificação do Claude Code, estilo de resposta e contexto do projeto. Isso difere de `claude -p`, que usa o prompt completo do Claude Code por padrão. Se você está migrando da CLI e quer um comportamento correspondente, defina o preset `claude_code`.

23* **Preset `claude_code`**: o prompt do sistema completo que a CLI do Claude Code usa, com instruções de uso de ferramentas, diretrizes de estilo e formatação de código, regras de tom de resposta e verbosidade, instruções de segurança e proteção, e contexto sobre o diretório de trabalho e ambiente. Defina `systemPrompt: { type: "preset", preset: "claude_code" }` em TypeScript ou `system_prompt={"type": "preset", "preset": "claude_code"}` em Python, opcionalmente com `append` para adicionar suas próprias instruções no final.

24* **String personalizada**: um prompt que você escreve por conta própria. O SDK envia apenas o que você fornece.

26### Decida sobre um ponto de partida

28O fator decisivo é o quão próximo seu agente se assemelha ao Claude Code: um agente de codificação operando em um repositório, com um humano observando a saída em streaming e direcionando o trabalho. Quanto mais seu produto se afastar disso, mais você vai querer escrever seu próprio prompt.

30| Você está construindo | Use | O que você obtém |

31| :---------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |

32| Uma ferramenta de codificação tipo CLI ou IDE onde um humano observa e direciona, e os padrões do Claude Code são o que você quer | Preset `claude_code` | O prompt completo do Claude Code: orientação de ferramentas, regras de segurança, respostas amigáveis ao terminal, consciência de convenções de repositório |

33| O mesmo tipo de ferramenta, mais regras específicas do produto como padrões de codificação, formato de saída ou contexto de domínio | Preset `claude_code` com `append` | Tudo acima, com suas instruções adicionadas após o preset. Nada é removido, então essa é a customização de menor risco |

34| Um agente com uma superfície, identidade ou modelo de permissão diferente, ou um agente não-codificação | String de prompt personalizado | Apenas o que você escreve. Você assume a responsabilidade de substituir a orientação de ferramentas e instruções de segurança que seu agente ainda precisa |

35| Um loop de chamada de ferramentas fino sem persona de agente, onde você fornece todo o comportamento no prompt do usuário | Nenhuma opção `systemPrompt` | O padrão mínimo: suporte a chamadas de ferramentas e nada mais |

37"Diferente do Claude Code" geralmente significa um dos seguintes:

39* **Superfície diferente**: a saída não é lida em um terminal pela pessoa que a acionou. UIs de chat, consumidores de saída estruturada e automação não-codificação cada uma precisa de um prompt que corresponda a como sua saída é renderizada e revisada. Automação de codificação desatendida, como um job de CI que corrige erros de lint ou revisa diffs, ainda se encaixa no preset porque o trabalho em si é o que o preset foi escrito para.

40* **Identidade diferente**: o agente não deve se apresentar como Claude Code. Um bot de suporte, um assistente de análise de dados ou qualquer agente específico de domínio precisa de seu próprio nome, escopo e persona.

41* **Modelo de permissão diferente**: o agente é executado autonomamente sem um humano aprovando cada etapa, ou opera em um conjunto restrito de recursos. O prompt do Claude Code assume que um humano está no loop com acesso a um conjunto completo de ferramentas.

42* **Tarefas não-codificação**: a maior parte do prompt do Claude Code é orientação de codificação. Para agentes de pesquisa, conteúdo ou operações, essa orientação compete com as instruções que você realmente precisa.

44A [tabela de comparação](#compare-the-four-approaches) mostra o que cada método de customização preserva.

46## Personalizar o comportamento do agente

48Estilos de saída, `append`, e uma string de prompt personalizada cada um alteram o prompt do sistema diretamente. CLAUDE.md segue um caminho diferente: o SDK o lê e injeta seu conteúdo na conversa como contexto do projeto, não no prompt do sistema, então ele molda o comportamento junto com qualquer prompt do sistema que você escolher. [Skills](/pt/agent-sdk/skills), [hooks](/pt/agent-sdk/hooks), e [permissions](/pt/agent-sdk/permissions) também moldam o comportamento fora do prompt do sistema e são cobertos em suas próprias páginas.

50### Arquivos CLAUDE.md para instruções em nível de projeto

52Os arquivos CLAUDE.md fornecem ao Claude contexto e instruções persistentes do projeto. O SDK injeta seu conteúdo na conversa, não no prompt do sistema, então funcionam com qualquer configuração de prompt do sistema. Para saber o que colocar em CLAUDE.md, onde colocá-lo e como escrever instruções eficazes, veja [How Claude remembers your project](/pt/memory). Esta seção cobre o que é específico do SDK: como CLAUDE.md é carregado.

54O SDK lê CLAUDE.md quando a fonte de configuração correspondente está habilitada: `'project'` carrega `CLAUDE.md` ou `.claude/CLAUDE.md` do diretório de trabalho, e `'user'` carrega `~/.claude/CLAUDE.md`. As opções padrão de `query()` habilitam ambas as fontes, então CLAUDE.md é carregado automaticamente. Se você definir `settingSources` em TypeScript ou `setting_sources` em Python explicitamente, inclua as fontes que você precisa. O carregamento de CLAUDE.md é controlado por fontes de configuração, não pela predefinição `claude_code`.

56#### Carregar CLAUDE.md com o SDK

58Para carregar CLAUDE.md, defina `settingSources` para incluir o nível onde seu CLAUDE.md reside. O exemplo abaixo carrega um CLAUDE.md em nível de projeto junto com a predefinição `claude_code`, então Claude tem tanto o prompt completo do agente de codificação quanto as convenções do seu projeto:

60<CodeGroup>

61 ```typescript TypeScript theme={null}

62 import { query } from "@anthropic-ai/claude-agent-sdk";

64 const messages = [];

66 for await (const message of query({

67 prompt: "Add a new React component for user profiles",

68 options: {

69 systemPrompt: {

70 type: "preset",

71 preset: "claude_code" // Use Claude Code's system prompt

72 },

73 settingSources: ["project"] // Loads CLAUDE.md from project

74 }

75 })) {

76 messages.push(message);

77 }

79 // Now Claude has access to your project guidelines from CLAUDE.md

80 ```

82 ```python Python theme={null}

83 from claude_agent_sdk import query, ClaudeAgentOptions

85 messages = []

87 async for message in query(

88 prompt="Add a new React component for user profiles",

89 options=ClaudeAgentOptions(

90 system_prompt={

91 "type": "preset",

92 "preset": "claude_code", # Use Claude Code's system prompt

93 },

94 setting_sources=["project"], # Loads CLAUDE.md from project

95 ),

96 ):

97 messages.append(message)

99 # Now Claude has access to your project guidelines from CLAUDE.md

100 ```

101</CodeGroup>

102

103CLAUDE.md é persistente em todas as sessões em um projeto, compartilhado com sua equipe através do git, e descoberto automaticamente sem alterações de código. Não é carregado se você passar um array `settingSources` vazio.

104

105### Estilos de saída para configurações persistentes

106

107Estilos de saída são configurações salvas que modificam o prompt do sistema do Claude. Eles são armazenados como arquivos markdown e podem ser reutilizados em sessões e projetos.

108

109#### Criar um estilo de saída

110

111Um estilo de saída é um arquivo markdown com um `name` e `description` em seu frontmatter, seguido pelo conteúdo do prompt. Salve-o em `~/.claude/output-styles/` para um estilo em nível de usuário disponível em cada projeto, ou `.claude/output-styles/` em seu repositório para um estilo em nível de projeto que você pode fazer commit e compartilhar com sua equipe.

112

113O exemplo abaixo define uma persona de revisão de código. Salve-o como `~/.claude/output-styles/code-reviewer.md` para torná-lo disponível em todos os projetos:

114

115```markdown ~/.claude/output-styles/code-reviewer.md theme={null}

116---

117name: Code Reviewer

118description: Thorough code review assistant

119---

120

121You are an expert code reviewer.

122

123For every code submission:

1241. Check for bugs and security issues

1252. Evaluate performance

1263. Suggest improvements

1274. Rate code quality (1-10)

128```

129

130#### Ativar um estilo de saída

131

132Uma vez criado, ative estilos de saída via:

133

134* **CLI**: execute `/config` e selecione um estilo de saída

135* **Configurações**: defina `outputStyle` em `.claude/settings.local.json`

136* **TypeScript SDK**: defina `options.outputStyle` para o nome do estilo

137

138O SDK Python não tem uma opção para selecionar um estilo de saída programaticamente. Para implantações apenas de código onde você não pode escrever em `.claude/settings.local.json`, use `append` ou uma string de prompt personalizada.

139

140**Nota para usuários do SDK:** Estilos de saída são carregados quando você inclui `settingSources: ['user']` ou `settingSources: ['project']` (TypeScript) / `setting_sources=["user"]` ou `setting_sources=["project"]` (Python) em suas opções.

141

142### Adicionar à predefinição `claude_code`

143

144Você pode usar a predefinição Claude Code com uma propriedade `append` para adicionar suas instruções personalizadas enquanto preserva toda a funcionalidade integrada.

145

146<CodeGroup>

147 ```typescript TypeScript theme={null}

148 import { query } from "@anthropic-ai/claude-agent-sdk";

149

150 const messages = [];

151

152 for await (const message of query({

153 prompt: "Help me write a Python function to calculate fibonacci numbers",

154 options: {

155 systemPrompt: {

156 type: "preset",

157 preset: "claude_code",

158 append: "Always include detailed docstrings and type hints in Python code."

159 }

160 }

161 })) {

162 messages.push(message);

163 if (message.type === "assistant") {

164 console.log(message.message.content);

165 }

166 }

167 ```

168

169 ```python Python theme={null}

170 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage

171

172 messages = []

173

174 async for message in query(

175 prompt="Help me write a Python function to calculate fibonacci numbers",

176 options=ClaudeAgentOptions(

177 system_prompt={

178 "type": "preset",

179 "preset": "claude_code",

180 "append": "Always include detailed docstrings and type hints in Python code.",

181 }

182 ),

183 ):

184 messages.append(message)

185 if isinstance(message, AssistantMessage):

186 print(message.content)

187 ```

188</CodeGroup>

189

190#### Melhorar o cache de prompt entre usuários e máquinas

191

192Por padrão, duas sessões que usam a mesma predefinição `claude_code` e texto `append` ainda não podem compartilhar uma entrada de cache de prompt se forem executadas de diretórios de trabalho diferentes. Isso ocorre porque a predefinição incorpora contexto por sessão no prompt do sistema antes do seu texto `append`: o diretório de trabalho, se é um repositório git, a plataforma, o shell ativo, a versão do SO, e caminhos de auto-memória. Qualquer diferença nesse contexto produz um prompt do sistema diferente e uma falha de cache. O conteúdo de CLAUDE.md não afeta o cache do prompt do sistema porque o SDK o injeta na conversa, não no prompt do sistema.

193

194Para tornar o prompt do sistema idêntico em sessões, defina `excludeDynamicSections: true` em TypeScript ou `"exclude_dynamic_sections": True` em Python. O contexto por sessão se move para a primeira mensagem do usuário, deixando apenas a predefinição estática e seu texto `append` no prompt do sistema para que configurações idênticas compartilhem uma entrada de cache em usuários e máquinas.

195

196<Note>

197 `excludeDynamicSections` requer `@anthropic-ai/claude-agent-sdk` v0.2.98 ou posterior, ou `claude-agent-sdk` v0.1.58 ou posterior para Python. Aplica-se apenas ao formulário de objeto predefinido e não tem efeito quando `systemPrompt` é uma string.

198</Note>

199

200O exemplo a seguir emparelha um bloco `append` compartilhado com `excludeDynamicSections` para que uma frota de agentes executados de diretórios diferentes possa reutilizar o mesmo prompt do sistema em cache:

201

202<CodeGroup>

203 ```typescript TypeScript theme={null}

204 import { query } from "@anthropic-ai/claude-agent-sdk";

205

206 for await (const message of query({

207 prompt: "Triage the open issues in this repo",

208 options: {

209 systemPrompt: {

210 type: "preset",

211 preset: "claude_code",

212 append: "You operate Acme's internal triage workflow. Label issues by component and severity.",

213 excludeDynamicSections: true

214 }

215 }

216 })) {

217 // ...

218 }

219 ```

220

221 ```python Python theme={null}

222 from claude_agent_sdk import query, ClaudeAgentOptions

223

224 async for message in query(

225 prompt="Triage the open issues in this repo",

226 options=ClaudeAgentOptions(

227 system_prompt={

228 "type": "preset",

229 "preset": "claude_code",

230 "append": "You operate Acme's internal triage workflow. Label issues by component and severity.",

231 "exclude_dynamic_sections": True,

232 },

233 ),

234 ):

235 ...

236 ```

237</CodeGroup>

238

239**Tradeoffs:** o diretório de trabalho, a flag de repositório git, a plataforma, o shell ativo, a versão do SO, e caminhos de auto-memória ainda chegam ao Claude, mas como parte da primeira mensagem do usuário em vez do prompt do sistema. Instruções na mensagem do usuário têm peso marginalmente menor do que o mesmo texto no prompt do sistema, então Claude pode depender delas menos fortemente ao raciocinar sobre o diretório atual ou caminhos de auto-memória. Ative esta opção quando a reutilização de cache entre sessões for mais importante do que contexto de ambiente maximamente autoritário.

240

241Para a flag equivalente no modo CLI não interativo, veja [`--exclude-dynamic-system-prompt-sections`](/pt/cli-reference).

242

243### Prompts do sistema personalizados

244

245Você pode fornecer uma string personalizada como `systemPrompt` para substituir completamente o padrão pelas suas próprias instruções.

246

247<CodeGroup>

248 ```typescript TypeScript theme={null}

249 import { query } from "@anthropic-ai/claude-agent-sdk";

250

251 const customPrompt = `You are a Python coding specialist.

252 Follow these guidelines:

253 - Write clean, well-documented code

254 - Use type hints for all functions

255 - Include comprehensive docstrings

256 - Prefer functional programming patterns when appropriate

257 - Always explain your code choices`;

258

259 const messages = [];

260

261 for await (const message of query({

262 prompt: "Create a data processing pipeline",

263 options: {

264 systemPrompt: customPrompt

265 }

266 })) {

267 messages.push(message);

268 if (message.type === "assistant") {

269 console.log(message.message.content);

270 }

271 }

272 ```

273

274 ```python Python theme={null}

275 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage

276

277 custom_prompt = """You are a Python coding specialist.

278 Follow these guidelines:

279 - Write clean, well-documented code

280 - Use type hints for all functions

281 - Include comprehensive docstrings

282 - Prefer functional programming patterns when appropriate

283 - Always explain your code choices"""

284

285 messages = []

286

287 async for message in query(

288 prompt="Create a data processing pipeline",

289 options=ClaudeAgentOptions(system_prompt=custom_prompt),

290 ):

291 messages.append(message)

292 if isinstance(message, AssistantMessage):

293 print(message.content)

294 ```

295</CodeGroup>

296

297## Comparação das quatro abordagens

298

299Os quatro métodos de personalização diferem em onde vivem, como são compartilhados e o que preservam da predefinição `claude_code`.

300

302| --------------------------- | ---------------------- | ------------------- | ------------------------- | -------------------------------- |

310| **Controle de versão** | Com projeto | Sim | Com código | Com código |

312

313"Com append" significa usar `systemPrompt: { type: "preset", preset: "claude_code", append: "..." }` em TypeScript ou `system_prompt={"type": "preset", "preset": "claude_code", "append": "..."}` em Python. CLAUDE.md não altera o prompt do sistema em si: o SDK injeta seu conteúdo na conversa como contexto do projeto.

314

315## Casos de uso e melhores práticas

316

317### Quando usar CLAUDE.md

318

319Use CLAUDE.md para instruções que devem se aplicar a cada sessão em um projeto, independentemente de qual prompt do sistema a sessão usa: padrões de codificação, comandos comuns, contexto de arquitetura e convenções de equipe. CLAUDE.md é confirmado em seu repositório, portanto permanece sincronizado com o código que descreve. Consulte [Quando adicionar a CLAUDE.md](/pt/memory#when-to-add-to-claude-md) para orientação completa.

320

321Os arquivos CLAUDE.md são carregados quando a fonte de configuração `project` está habilitada, o que é o padrão para as opções padrão de `query()`. Se você definir `settingSources` em TypeScript ou `setting_sources` em Python explicitamente, inclua `'project'` para continuar carregando CLAUDE.md em nível de projeto.

322

323### Quando usar estilos de saída

324

325Os estilos de saída são para personas que você deseja reutilizar em toda a CLI e SDK sem alterar o código da aplicação. Como vivem como arquivos em `.claude/output-styles`, a mesma persona está disponível em `/config` na CLI e em qualquer sessão SDK que carregue a fonte de configuração correspondente.

326

327**Melhor para:**

328

329* Mudanças de comportamento persistentes em sessões

330* Configurações compartilhadas em equipe

331* Assistentes especializados como revisor de código, cientista de dados ou assistente DevOps

332* Modificações de prompt complexas que precisam de versionamento

333

334**Exemplos:**

335

336* Criar um assistente dedicado de otimização SQL

337* Construir um revisor de código focado em segurança

338* Desenvolver um assistente de ensino com pedagogia específica

339

340### Quando usar `systemPrompt` com append

341

342Use `append` quando a predefinição `claude_code` já se adequa ao seu produto e você só precisa adicionar instruções extras. Você mantém a orientação de ferramentas, regras de segurança e convenções de codificação da predefinição sem reimplementá-las.

343

344**Melhor para:**

345

346* Adicionar padrões de codificação ou preferências específicas

347* Personalizar formatação de saída

348* Adicionar conhecimento específico do domínio

349* Modificar verbosidade de resposta

350* Aprimorar o comportamento padrão do Claude Code sem perder instruções de ferramentas

351

352### Quando usar `systemPrompt` personalizado

353

354Use um prompt personalizado quando a superfície, identidade ou modelo de permissão do seu agente diferir do Claude Code, conforme descrito em [Decidir sobre um ponto de partida](#decide-on-a-starting-point). Você define o conjunto completo de instruções, incluindo qualquer orientação de ferramentas e regras de segurança que seu agente precisa.

355

356**Melhor para:**

357

358* Controle completo sobre o comportamento do Claude

359* Tarefas especializadas de sessão única

360* Testar novas estratégias de prompt

361* Situações onde ferramentas padrão não são necessárias

362* Construir agentes especializados com comportamento único

363

364## Combinando abordagens

365

366Esses métodos se compõem. Um estilo de saída persistente ou CLAUDE.md define o comportamento de longa duração, e `append` adiciona instruções específicas da sessão sem tocar na configuração salva.

367

368### Combinar um estilo de saída com adições específicas da sessão

369

370O exemplo abaixo assume que um estilo de saída Code Reviewer já está ativo. O bloco `append` adiciona áreas de foco específicas da sessão sobre a persona, para que uma única sessão de revisão possa priorizar OAuth e armazenamento de tokens sem alterar o estilo de saída salvo:

371

372<CodeGroup>

373 ```typescript TypeScript theme={null}

374 import { query } from "@anthropic-ai/claude-agent-sdk";

375

376 // Assuming "Code Reviewer" output style is active (via /config or settings)

377 // Add session-specific focus areas

378 const messages = [];

379

380 for await (const message of query({

381 prompt: "Review this authentication module",

382 options: {

383 systemPrompt: {

384 type: "preset",

385 preset: "claude_code",

386 append: `

387 For this review, prioritize:

388 - OAuth 2.0 compliance

389 - Token storage security

390 - Session management

391 `

392 }

393 }

394 })) {

395 messages.push(message);

396 }

397 ```

398

399 ```python Python theme={null}

400 from claude_agent_sdk import query, ClaudeAgentOptions

401

402 # Assuming "Code Reviewer" output style is active (via /config or settings)

403 # Add session-specific focus areas

404 messages = []

405

406 async for message in query(

407 prompt="Review this authentication module",

408 options=ClaudeAgentOptions(

409 system_prompt={

410 "type": "preset",

411 "preset": "claude_code",

412 "append": """

413 For this review, prioritize:

414 - OAuth 2.0 compliance

415 - Token storage security

416 - Session management

417 """,

418 }

419 ),

420 ):

421 messages.append(message)

422 ```

423</CodeGroup>

424

425## Veja também

426

427* [Estilos de saída](/pt/output-styles): criar, gerenciar e compartilhar estilos de saída para a CLI, incluindo o formato de arquivo e locais de armazenamento

428* [Como Claude se lembra do seu projeto](/pt/memory): o que colocar em CLAUDE.md, onde colocá-lo e como escrever instruções de projeto eficazes

429* [Referência do SDK TypeScript](/pt/agent-sdk/typescript): o tipo `Options` completo, incluindo `systemPrompt`, `settingSources` e `outputStyle`

430* [Referência do SDK Python](/pt/agent-sdk/python): o tipo `ClaudeAgentOptions` completo, incluindo `system_prompt` e `setting_sources`

431* [Configurações](/pt/settings): a referência `settings.json`, incluindo onde estilos de saída e outras configurações são armazenados

agent-sdk/typescript.md +1 −0

Details

396| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | Configurações de servidor MCP |396| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | Configurações de servidor MCP |

398| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | Defina o formato de saída para resultados de agente. Veja [Structured outputs](/pt/agent-sdk/structured-outputs) para detalhes |398| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | Defina o formato de saída para resultados de agente. Veja [Structured outputs](/pt/agent-sdk/structured-outputs) para detalhes |

399| `outputStyle` | `string` | `undefined` | Nome de um [estilo de saída](/pt/output-styles) para ativar para a sessão. O estilo deve existir em um local `settingSources` carregado, como `.claude/output-styles/`. Veja [Ativar um estilo de saída](/pt/agent-sdk/modifying-system-prompts#activate-an-output-style) |

399| `pathToClaudeCodeExecutable` | `string` | Auto-resolvido do binário nativo agrupado | Caminho para executável Claude Code. Apenas necessário se dependências opcionais foram puladas durante a instalação ou sua plataforma não está no conjunto suportado |400| `pathToClaudeCodeExecutable` | `string` | Auto-resolvido do binário nativo agrupado | Caminho para executável Claude Code. Apenas necessário se dependências opcionais foram puladas durante a instalação ou sua plataforma não está no conjunto suportado |

agent-sdk/user-input.md +47 −1

Details

12 12

13Para perguntas de esclarecimento, Claude gera as perguntas e opções. Seu papel é apresentá-las aos usuários e retornar suas seleções. Você não pode adicionar suas próprias perguntas a este fluxo; se precisar perguntar algo aos usuários, faça isso separadamente na lógica do seu aplicativo.13Para perguntas de esclarecimento, Claude gera as perguntas e opções. Seu papel é apresentá-las aos usuários e retornar suas seleções. Você não pode adicionar suas próprias perguntas a este fluxo; se precisar perguntar algo aos usuários, faça isso separadamente na lógica do seu aplicativo.

14 14

15O callback pode permanecer pendente indefinidamente. A execução permanece pausada até que seu callback retorne, e o SDK apenas cancela a espera quando a própria consulta é cancelada. Se um usuário puder levar mais tempo para responder do que seu processo pode razoavelmente permanecer em execução, o SDK TypeScript suporta o [hook `defer`](/pt/hooks#defer-a-tool-call-for-later), que permite que o processo saia e retome mais tarde a partir da sessão persistida; esta opção não está disponível no SDK Python.15O callback pode permanecer pendente indefinidamente. A execução permanece pausada até que seu callback retorne, e o SDK apenas cancela a espera quando a própria consulta é cancelada. Se um usuário puder levar mais tempo para responder do que seu processo pode razoavelmente permanecer em execução, retorne a decisão do [hook `defer`](/pt/hooks#defer-a-tool-call-for-later), que permite que o processo saia e retome mais tarde a partir da sessão persistida.

16 16

17Este guia mostra como detectar cada tipo de solicitação e responder apropriadamente.17Este guia mostra como detectar cada tipo de solicitação e responder apropriadamente.

18 18

232 232

233* **Aprovar**: deixe a ferramenta executar conforme Claude solicitou233* **Aprovar**: deixe a ferramenta executar conforme Claude solicitou

234* **Aprovar com alterações**: modifique a entrada antes da execução (por exemplo, sanitize caminhos, adicione restrições)234* **Aprovar com alterações**: modifique a entrada antes da execução (por exemplo, sanitize caminhos, adicione restrições)

235* **Aprovar e lembrar**: repita uma regra de permissão sugerida para que chamadas correspondentes ignorem o prompt na próxima vez

235* **Rejeitar**: bloqueie a ferramenta e diga ao Claude por quê236* **Rejeitar**: bloqueie a ferramenta e diga ao Claude por quê

236* **Sugerir alternativa**: bloqueie mas guie Claude para o que o usuário quer em vez disso237* **Sugerir alternativa**: bloqueie mas guie Claude para o que o usuário quer em vez disso

237* **Redirecionar completamente**: use [entrada de streaming](/pt/agent-sdk/streaming-vs-single-mode) para enviar ao Claude uma instrução completamente nova238* **Redirecionar completamente**: use [entrada de streaming](/pt/agent-sdk/streaming-vs-single-mode) para enviar ao Claude uma instrução completamente nova

297 </CodeGroup>298 </CodeGroup>

298 </Tab>299 </Tab>

299 300

301 <Tab title="Aprovar e lembrar">

302 O usuário aprova e não quer ser perguntado novamente para este tipo de chamada. O terceiro argumento de callback carrega `suggestions`, uma matriz de entradas [`PermissionUpdate`](/pt/agent-sdk/typescript#permissionupdate) prontas. Repita uma de volta em `updatedPermissions` para aplicá-la. Uma sugestão com o destino `localSettings` escreve a regra em `.claude/settings.local.json` para que futuras sessões ignorem o prompt para chamadas correspondentes.

303

304 O exemplo Python requer `claude-agent-sdk` 0.1.80 ou posterior.

305

306 <CodeGroup>

307 ```python Python theme={null}

308 async def can_use_tool(tool_name, input_data, context):

309 choice = await ask_user(f"Allow {tool_name}?", ["once", "always", "no"])

310

311 if choice == "always":

312 persist = [

313 s for s in context.suggestions if s.destination == "localSettings"

314 ]

315 return PermissionResultAllow(

316 updated_input=input_data, updated_permissions=persist

317 )

318 if choice == "once":

319 return PermissionResultAllow(updated_input=input_data)

320 return PermissionResultDeny(message="User declined")

321 ```

322

323 ```typescript TypeScript theme={null}

324 canUseTool: async (toolName, input, { suggestions = [] }) => {

325 const choice = await askUser(`Allow ${toolName}?`, ["once", "always", "no"]);

326

327 if (choice === "always") {

328 const persist = suggestions.filter(

329 (s) => s.destination === "localSettings"

330 );

331 return {

332 behavior: "allow",

333 updatedInput: input,

334 updatedPermissions: persist

335 };

336 }

337 if (choice === "once") {

338 return { behavior: "allow", updatedInput: input };

339 }

340 return { behavior: "deny", message: "User declined" };

341 };

342 ```

343 </CodeGroup>

344 </Tab>

345

300 <Tab title="Rejeitar">346 <Tab title="Rejeitar">

301 O usuário não quer que esta ação aconteça. Bloqueie a ferramenta e forneça uma mensagem explicando por quê. Claude vê esta mensagem e pode tentar uma abordagem diferente.347 O usuário não quer que esta ação aconteça. Bloqueie a ferramenta e forneça uma mensagem explicando por quê. Claude vê esta mensagem e pode tentar uma abordagem diferente.

302 348

agent-teams.md +2 −0

Details

129Use Sonnet for each teammate.129Use Sonnet for each teammate.

130```130```

131 131

132Os companheiros de equipe não herdam a seleção `/model` do líder por padrão. Para alterar o modelo usado quando o prompt não especifica um, defina **Default teammate model** em `/config`. Escolha **Default (leader's model)** para que os companheiros de equipe sigam o modelo atual do líder.

133

132### Exigir aprovação de plano para companheiros de equipe134### Exigir aprovação de plano para companheiros de equipe

133 135

134Para tarefas complexas ou arriscadas, você pode exigir que os companheiros de equipe planejem antes de implementar. O companheiro de equipe trabalha em modo de plano somente leitura até que o líder aprove sua abordagem:136Para tarefas complexas ou arriscadas, você pode exigir que os companheiros de equipe planejem antes de implementar. O companheiro de equipe trabalha em modo de plano somente leitura até que o líder aprove sua abordagem:

agent-view.md +38 −19

Details

24* [Gerenciar sessões do shell](#manage-sessions-from-the-shell)24* [Gerenciar sessões do shell](#manage-sessions-from-the-shell)

25* [Como as sessões em background são hospedadas](#how-background-sessions-are-hosted) pelo processo supervisor25* [Como as sessões em background são hospedadas](#how-background-sessions-are-hosted) pelo processo supervisor

26 26

~~27## Quick start~~27## Início rápido

28 28

29Este passo a passo abre agent view, despacha uma sessão, responde do painel de espiada e anexa para a conversa completa.29Este passo a passo abre agent view, despacha uma sessão, responde do painel de espiada e anexa para a conversa completa.

30 30

40 </Step>40 </Step>

41 41

42 <Step title="Despache uma sessão">42 <Step title="Despache uma sessão">

43 Digite um prompt na entrada e pressione `Enter`. Uma nova sessão é iniciada e aparece como uma linha mostrando se está funcionando, aguardando você ou concluída. Repita para executar quantas sessões em paralelo desejar.43 Digite um prompt na entrada e pressione `Enter`. Uma nova sessão é iniciada e aparece como uma linha mostrando se está funcionando, aguardando você ou concluída. Repita para executar várias sessões em paralelo. Cada uma usa sua cota de assinatura independentemente, portanto, consulte [Limitações](#limitations) antes de despachar muitas de uma vez.

44 </Step>44 </Step>

45 45

46 <Step title="Espiada e resposta">46 <Step title="Espiada e resposta">

56 56

57Você pode usar `claude agents` como seu ponto de entrada principal em vez de `claude`: despache cada tarefa de agent view, anexe quando quiser a conversa completa e pressione `←` para retornar à tabela.57Você pode usar `claude agents` como seu ponto de entrada principal em vez de `claude`: despache cada tarefa de agent view, anexe quando quiser a conversa completa e pressione `←` para retornar à tabela.

58 58

~~59## Monitor sessions with agent view~~59## Monitorar sessões com agent view

60 60

61Execute `claude agents` para abrir agent view. Ele assume o terminal completo e lista cada sessão agrupada por estado, com sessões fixadas e as que precisam de você no topo. Cada linha mostra o nome da sessão, atividade atual e há quanto tempo foi alterada pela última vez.61Execute `claude agents` para abrir agent view. Ele assume o terminal completo e lista cada sessão agrupada por estado, com sessões fixadas e as que precisam de você no topo. Cada linha mostra o nome da sessão, atividade atual e há quanto tempo foi alterada pela última vez.

62 62

63A lista é global para sua máquina e inclui cada sessão em background independentemente de qual projeto ou worktree está trabalhando. Sessões interativas que você tem abertas em outros terminais não aparecem até que você as [coloque em background](#from-inside-a-session), e [subagents](/pt/sub-agents) em execução dentro de uma sessão não são listados como linhas separadas.63A lista abrange cada sessão em background sob seu [diretório de configuração](#how-background-sessions-are-hosted), independentemente de qual projeto ou worktree está trabalhando, então uma sessão iniciada em um repositório e outra iniciada em um worktree diferente aparecem juntas. Sessões interativas que você tem abertas em outros terminais não aparecem até que você as [coloque em background](#from-inside-a-session), e [subagents](/pt/sub-agents) em execução dentro de uma sessão não são listados como linhas separadas.

64 64

65```text theme={null}65```text theme={null}

66Pinned66Pinned

67 ✽ clawd walk cycle Write assets/sprites/clawd-walk.png 3m67 ✽ clawd walk cycle Write assets/sprites/clawd-walk.png 3m

68 68

69Ready for review69Ready for review

~~70 ∙ jump physics github.com/anthropics/example/pull/2048 2h~~70 ∙ jump physics github.com/anthropics/example/pull/2048 ● 2h

71 71

72Needs input72Needs input

73 ✻ power-up design needs input: double jump or wall climb? 1m73 ✻ power-up design needs input: double jump or wall climb? 1m

82 … 6 more82 … 6 more

83```83```

84 84

~~85O ícone informa o estado da sessão:~~85O ícone de cada linha carrega dois sinais. O indicador informa o estado da sessão, e a forma do ícone informa se o processo subjacente ainda está em execução. Os estados são:

86 86

88| :-------- | :---------- | :-------------------------------------------------------------------------------------- |88| :-------- | :---------- | :-------------------------------------------------------------------------------------- |

99 99

100As sessões persistem no disco: fechar seu terminal ou uma atualização automática não as perde, e reabrir `claude agents` as mostra todas. Se sua máquina dormir ou desligar, as sessões em execução param; reinicie-as com `claude respawn --all`.100As sessões persistem no disco: fechar seu terminal ou uma atualização automática não as perde, e reabrir `claude agents` as mostra todas. Se sua máquina dormir ou desligar, as sessões em execução param; reinicie-as com `claude respawn --all`.

101 101

102O resumo de uma linha em cada linha é gerado pelo seu [modelo Haiku-class](/pt/model-config) configurado, para que a linha possa informar o que a sessão está fazendo, o que precisa ou o que produziu sem abrir o transcript. Cada resumo é uma solicitação curta de Haiku-class através de seu provedor normal, cobrada e tratada sob os mesmos [termos de uso de dados](/pt/data-usage) que a sessão em si.102O resumo de uma linha em cada linha é gerado pelo seu [modelo Haiku-class](/pt/model-config) configurado, para que a linha possa informar o que a sessão está fazendo, o que precisa ou o que produziu sem abrir o transcript. Enquanto uma sessão está ativamente funcionando, o resumo é atualizado no máximo uma vez a cada 15 segundos, mais uma vez quando cada turno termina. Cada atualização é uma solicitação curta de Haiku-class através de seu provedor normal, cobrada e tratada sob os mesmos [termos de uso de dados](/pt/data-usage) que a sessão em si.

103 103

104Quando uma sessão abre um pull request, a linha mostra o link do PR e um indicador de status para suas verificações de CI. Para a maioria das tarefas, esta linha é como você coleta o trabalho: revise e mescle o pull request quando suas verificações passarem.104Quando uma sessão abre um pull request, um ponto de status aparece na borda direita da linha, vinculado ao pull request em terminais que suportam hiperlinks. Quando a sessão abriu mais de um pull request, a contagem aparece antes do ponto e a cor reflete qual deles mais precisa de atenção.

105

106| Cor do ponto | Status do pull request |

107| :----------- | :----------------------------------------------------------- |

108| Amarelo | Aguardando verificações ou revisão, ou verificações falharam |

109| Verde | Verificações passaram e nenhuma revisão está bloqueando |

110| Roxo | Mesclado |

111| Cinza | Rascunho ou fechado |

112

113Para a maioria das tarefas, esta linha é onde você coleta o resultado: revise e mescle o pull request quando o ponto ficar verde.

105 114

106### Peek and reply115### Peek and reply

107 116

121 130

122Desanexar nunca interrompe uma sessão em background: `←`, `Ctrl+C`, `Ctrl+D`, `Ctrl+Z` e `/exit` a deixam em execução. Para encerrar uma sessão de dentro dela, execute `/stop`.131Desanexar nunca interrompe uma sessão em background: `←`, `Ctrl+C`, `Ctrl+D`, `Ctrl+Z` e `/exit` a deixam em execução. Para encerrar uma sessão de dentro dela, execute `/stop`.

123 132

124Depois de usar agent view, pressionar `←` em um prompt vazio funciona de qualquer sessão Claude Code, não apenas as que você anexou. Abre agent view com sua sessão atual pré-selecionada, para que você possa alternar sessões sem sair do terminal.133Depois de ter despachado ou colocado uma sessão em background, pressionar `←` em um prompt vazio funciona de qualquer sessão Claude Code, não apenas as que você anexou a partir de agent view. Coloca a sessão atual em background e abre agent view com essa sessão pré-selecionada, para que você possa alternar sessões sem sair do terminal. Você pode desativar este atalho em `/config`.

125 134

126### Organize the list135### Organize the list

127 136

163| `?` | Mostrar todos os atalhos |172| `?` | Mostrar todos os atalhos |

164 173

165## Dispatch new agents174## Despachar novos agentes

166 175

167Você pode despachar novas sessões em background a partir de agent view, enviar uma sessão interativa existente para o background ou iniciar uma diretamente do shell.176Você pode despachar novas sessões em background a partir de agent view, enviar uma sessão interativa existente para o background ou iniciar uma diretamente do shell.

168 177

183 192

184Digite `/` para despachar uma [skill](/pt/skills). Empacotar uma tarefa recorrente como uma skill permite que você inicie o mesmo fluxo de trabalho muitas vezes a partir de agent view sem redigitar o prompt. Pressione `Tab` em uma entrada vazia para procurar cada subagent despachável, ou para aplicar a sugestão destacada quando as sugestões estão sendo exibidas.193Digite `/` para despachar uma [skill](/pt/skills). Empacotar uma tarefa recorrente como uma skill permite que você inicie o mesmo fluxo de trabalho muitas vezes a partir de agent view sem redigitar o prompt. Pressione `Tab` em uma entrada vazia para procurar cada subagent despachável, ou para aplicar a sugestão destacada quando as sugestões estão sendo exibidas.

185 194

195Quando o mesmo `@name` corresponde tanto a um subagent quanto a um repositório irmão, o subagent tem precedência. A forma de primeira palavra sem `@` também se aplica a qualquer nome de subagent, portanto um prompt que começa com uma palavra correspondente a um de seus nomes de subagent despacha esse subagent. Use a forma `@` quando quiser ser explícito.

196

186#### Dispatch to a specific directory197#### Dispatch to a specific directory

187 198

188Uma nova sessão é executada no diretório em que você abriu agent view. Para direcionar um diretório diferente:199Uma nova sessão é executada no diretório em que você abriu agent view. Para direcionar um diretório diferente:

193 204

194Quando agent view é agrupado por diretório, o diretório da linha destacada se torna o alvo de despacho, para que você possa rolar para um grupo e despachar nele sem redigitar o caminho.205Quando agent view é agrupado por diretório, o diretório da linha destacada se torna o alvo de despacho, para que você possa rolar para um grupo e despachar nele sem redigitar o caminho.

195 206

196#### Isolate file edits in a worktree

~~197~~

198Sessões despachadas a partir de agent view compartilham seu diretório de trabalho por padrão, então dois agentes editando os mesmos arquivos podem entrar em conflito. Para evitar isso, Claude Code bloqueia uma sessão despachada a partir de agent view de escrever arquivos até que se mova para um [git worktree](/pt/worktrees) isolado. Claude lida com isso automaticamente quando precisa editar arquivos. O worktree é criado sob `.claude/worktrees/` dentro do diretório do projeto e removido quando você deleta a sessão. Deletar uma sessão também deleta seu worktree, então mescle ou envie as alterações que você quer manter antes de deletar.

~~199~~

200Para fazer um subagent sempre executar em seu próprio worktree independentemente de como foi iniciado, defina [`isolation: worktree`](/pt/sub-agents#supported-frontmatter-fields) em seu frontmatter.

~~201~~

202### From inside a session207### From inside a session

203 208

204Execute `/background` ou seu alias `/bg` para desanexar a conversa atual e mantê-la em execução. Passe um prompt como `/bg run the test suite and fix any failures` para enviar uma instrução adicional antes de desanexar.209Execute `/background` ou seu alias `/bg` para desanexar a conversa atual e mantê-la em execução. Passe um prompt como `/bg run the test suite and fix any failures` para enviar uma instrução adicional antes de desanexar.

227 claude stop 7c5dcf5d stop this session232 claude stop 7c5dcf5d stop this session

228```233```

229 234

235### How file edits are isolated

236

237Toda sessão em background, seja iniciada a partir de agent view, `/bg` ou `claude --bg`, inicia no seu diretório de trabalho, mas é bloqueada de escrever arquivos lá. Quando a sessão precisa editar arquivos, Claude a move para um [git worktree](/pt/worktrees) isolado sob `.claude/worktrees/` automaticamente, para que sessões paralelas possam ler o mesmo checkout, mas cada uma escreve no seu próprio. O bloqueio não se aplica quando a sessão já está dentro de um worktree, quando o diretório de trabalho não é um repositório git, ou para escritas fora do diretório de trabalho.

238

239O worktree é removido quando você deleta a sessão, portanto mescle ou envie as alterações que você quer manter antes de deletar. Para encontrar o caminho do worktree de uma sessão, espreite a sessão ou anexe e verifique seu diretório de trabalho.

240

241Para fazer um subagent sempre executar em seu próprio worktree independentemente de como foi iniciado, defina [`isolation: worktree`](/pt/sub-agents#supported-frontmatter-fields) em seu frontmatter.

242

243### Permission mode and settings

244

245Uma sessão despachada lê suas [settings](/pt/settings) e [permission mode](/pt/permissions) do diretório em que é executada, da mesma forma que se você tivesse iniciado `claude` lá. Despachar a partir da entrada de agent view não passa um permission mode, portanto a sessão usa o `defaultMode` das settings daquele diretório ou o `permissionMode` do [frontmatter do subagent](/pt/sub-agents#supported-frontmatter-fields) despachado.

246

247Para definir o modo a partir do shell, passe `--permission-mode` com `claude --bg`. Usar `bypassPermissions` ou `auto` desta forma é recusado até que você tenha aceitado esse modo executando `claude` com ele uma vez interativamente, já que esses modos permitem que uma sessão que você não está observando aja sem aprovação.

248

230## Manage sessions from the shell249## Manage sessions from the shell

231 250

232Cada sessão em background tem um ID curto que você pode usar do shell. Esses comandos são úteis para scripts ou quando você não quer abrir agent view.251Cada sessão em background tem um ID curto que você pode usar do shell. Esses comandos são úteis para scripts ou quando você não quer abrir agent view.

277 296

278Worktrees são removidos quando você deleta a sessão que as criou. Se uma sessão terminou sem limpar, liste entradas restantes com `git worktree list` no diretório do projeto e remova cada uma com `git worktree remove <path>`. Veja [Clean up worktrees](/pt/worktrees#clean-up-worktrees).297Worktrees são removidos quando você deleta a sessão que as criou. Se uma sessão terminou sem limpar, liste entradas restantes com `git worktree list` no diretório do projeto e remova cada uma com `git worktree remove <path>`. Veja [Clean up worktrees](/pt/worktrees#clean-up-worktrees).

279 298

280## Limitations299## Limitações

281 300

282Agent view é uma visualização de pesquisa. Limitações atuais a serem observadas:301Agent view é uma visualização de pesquisa. Limitações atuais a serem observadas:

283 302

284* **Limites de taxa se aplicam**: sessões em background reduzem seu uso de assinatura da mesma forma que sessões interativas, então executar dez agentes em paralelo usa cota dez vezes mais rápido.303* **Limites de taxa se aplicam**: sessões em background consomem o uso de sua assinatura da mesma forma que sessões interativas, então executar dez agentes em paralelo usa cota aproximadamente dez vezes mais rápido do que executar um.

285* **Sessões são locais**: sessões em background são executadas em sua máquina e param se ela dormir ou desligar.304* **Sessões são locais**: sessões em background são executadas em sua máquina e param se ela dormir ou desligar.

286* **Worktrees são deletados com a sessão**: mescle ou envie alterações antes de deletar uma sessão que editou arquivos em seu próprio worktree.305* **Worktrees são deletados com a sessão**: mescle ou envie alterações antes de deletar uma sessão que editou arquivos em seu próprio worktree.

287 306

claude-directory.md +6 −3

Details

1465Clique em um nome de arquivo para abrir esse nó no explorador acima.1465Clique em um nome de arquivo para abrir esse nó no explorador acima.

1466 1466

1468| --------------------------------------------------- | ---------------- | --------- | ------------------------------------------------------------------ | -------------------------------------------------------------------- |1468| --------------------------------------------------- | ---------------- | --------- | ------------------------------------------------------------------ | ----------------------------------------------------------------- |

1470| [`rules/*.md`](#ce-rules) | Projeto e global | ✓ | Instruções com escopo de tópico, opcionalmente com gate de caminho | [Rules](/pt/memory#organize-rules-with-claude/rules/) |1470| [`rules/*.md`](#ce-rules) | Projeto e global | ✓ | Instruções com escopo de tópico, opcionalmente com gate de caminho | [Rules](/pt/memory#organize-rules-with-claude/rules/) |

1476| [`commands/*.md`](#ce-commands) | Projeto e global | ✓ | Prompts de arquivo único; mesmo mecanismo que skills | [Skills](/pt/skills) |1476| [`commands/*.md`](#ce-commands) | Projeto e global | ✓ | Prompts de arquivo único; mesmo mecanismo que skills | [Skills](/pt/skills) |

1477| [`output-styles/*.md`](#ce-output-styles) | Projeto e global | ✓ | Seções de prompt do sistema personalizadas | [Output styles](/pt/output-styles) |1477| [`output-styles/*.md`](#ce-output-styles) | Projeto e global | ✓ | Seções de prompt do sistema personalizadas | [Output styles](/pt/output-styles) |

1498| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |1498| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |

1499| `projects/<project>/<session>.jsonl` | Transcrição de conversa completa: cada mensagem, chamada de ferramenta e resultado de ferramenta |1499| `projects/<project>/<session>.jsonl` | Transcrição de conversa completa: cada mensagem, chamada de ferramenta e resultado de ferramenta |

1500| `projects/<project>/<session>/subagents/` | Transcrições de conversa de [subagent](/pt/sub-agents), removidas com a transcrição de sessão pai quando envelhecem |

1501| `file-history/<session>/` | Snapshots pré-edição de arquivos que Claude alterou, usados para [restauração de checkpoint](/pt/checkpointing) |1502| `file-history/<session>/` | Snapshots pré-edição de arquivos que Claude alterou, usados para [restauração de checkpoint](/pt/checkpointing) |

1502| `plans/` | Arquivos de plano escritos durante [plan mode](/pt/permission-modes#analyze-before-you-edit-with-plan-mode) |1503| `plans/` | Arquivos de plano escritos durante [plan mode](/pt/permission-modes#analyze-before-you-edit-with-plan-mode) |

1512Os caminhos a seguir não são cobertos pela limpeza automática e persistem indefinidamente.1513Os caminhos a seguir não são cobertos pela limpeza automática e persistem indefinidamente.

1513 1514

1515| ------------------------ | ------------------------------------------------------------------------------------------------------ |1516| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

1516| `history.jsonl` | Cada prompt que você digitou, com timestamp e caminho do projeto. Usado para recall de seta para cima. |1517| `history.jsonl` | Cada prompt que você digitou, com timestamp e caminho do projeto. Usado para recall de seta para cima. |

1519| `remote-settings.json` | Cópia em cache de [configurações gerenciadas pelo servidor](/pt/server-managed-settings) para sua organização. Presente apenas quando sua organização as configurou. Atualizado em cada inicialização. |

1519 1521

1520Outros arquivos pequenos de cache e lock aparecem dependendo de quais recursos você usa e são seguros para deletar.1522Outros arquivos pequenos de cache e lock aparecem dependendo de quais recursos você usa e são seguros para deletar.

1575| `~/.claude/remote-settings.json` | Nada. Re-buscado na próxima inicialização. |

1573| `~/.claude/debug/`, `~/.claude/plans/`, `~/.claude/paste-cache/`, `~/.claude/image-cache/`, `~/.claude/session-env/`, `~/.claude/tasks/`, `~/.claude/shell-snapshots/`, `~/.claude/backups/` | Nada voltado para o usuário |1576| `~/.claude/debug/`, `~/.claude/plans/`, `~/.claude/paste-cache/`, `~/.claude/image-cache/`, `~/.claude/session-env/`, `~/.claude/tasks/`, `~/.claude/shell-snapshots/`, `~/.claude/backups/` | Nada voltado para o usuário |

1575 1578

cli-reference.md +3 −1

Details

124 124

125`--system-prompt` e `--system-prompt-file` são mutuamente exclusivos. Os sinalizadores de anexação podem ser combinados com qualquer sinalizador de substituição.125`--system-prompt` e `--system-prompt-file` são mutuamente exclusivos. Os sinalizadores de anexação podem ser combinados com qualquer sinalizador de substituição.

126 126

127Para a maioria dos casos de uso, use um sinalizador de anexação. Anexar preserva os recursos integrados do Claude Code enquanto adiciona seus requisitos. Use um sinalizador de substituição apenas quando você precisar de controle completo sobre o prompt do sistema.127Escolha com base em se a identidade padrão do Claude Code ainda se adequa à sua tarefa. Use um sinalizador de anexação quando Claude deve permanecer um assistente de codificação que também segue suas regras extras: instruções por invocação, formatação de saída ou contexto de domínio para um script `-p`. Anexar preserva a orientação de ferramentas padrão, instruções de segurança e convenções de codificação, portanto você fornece apenas o que difere. Use um sinalizador de substituição quando a superfície, identidade ou modelo de permissão diferir do Claude Code, como um agente não codificador em um pipeline que nenhum humano observa. Substituir descarta todo o prompt padrão, incluindo orientação de ferramentas e instruções de segurança, portanto você assume a responsabilidade por tudo o que sua tarefa ainda precisa.

128

129Esses sinalizadores se aplicam apenas à invocação atual. Para personas persistentes que você pode alternar e compartilhar em um projeto, use [estilos de saída](/pt/output-styles). Para convenções de projeto que Claude deve sempre seguir, use [CLAUDE.md](/pt/memory). O [guia do Agent SDK sobre prompts do sistema](/pt/agent-sdk/modifying-system-prompts#decide-on-a-starting-point) cobre a mesma decisão com mais profundidade.

128 130

129## Veja também131## Veja também

130 132

data-usage.md +4 −4

Details

13**Usuários consumidores (planos Free, Pro e Max)**:13**Usuários consumidores (planos Free, Pro e Max)**:

14Oferecemos a você a opção de permitir que seus dados sejam usados para melhorar futuros modelos Claude. Treinaremos novos modelos usando dados de contas Free, Pro e Max quando essa configuração estiver ativada (inclusive quando você usa Claude Code dessas contas).14Oferecemos a você a opção de permitir que seus dados sejam usados para melhorar futuros modelos Claude. Treinaremos novos modelos usando dados de contas Free, Pro e Max quando essa configuração estiver ativada (inclusive quando você usa Claude Code dessas contas).

15 15

16**Usuários comerciais**: (planos Team e Enterprise, API, plataformas de terceiros e Claude Gov) mantêm as políticas existentes: a Anthropic não treina modelos generativos usando código ou prompts enviados para Claude Code sob termos comerciais, a menos que o cliente tenha optado por fornecer seus dados para melhorias de modelo (por exemplo, o [Development Partner Program](https://support.claude.com/en/articles/11174108-about-the-development-partner-program)).16**Usuários comerciais**: (planos Team e Enterprise, API, plataformas de terceiros e Claude Gov) mantêm as políticas existentes: a Anthropic não treina modelos generativos usando código ou prompts enviados para Claude Code sob termos comerciais, a menos que o cliente tenha optado por fornecer seus dados para melhorias de modelo (por exemplo, o [Development Partner Program](https://support.claude.com/pt/articles/11174108-about-the-development-partner-program)).

17 17

18### Development Partner Program18### Development Partner Program

19 19

20Se você optar explicitamente por métodos para nos fornecer materiais para treinar, como através do [Development Partner Program](https://support.claude.com/en/articles/11174108-about-the-development-partner-program), podemos usar esses materiais fornecidos para treinar nossos modelos. Um administrador da organização pode optar explicitamente pelo Development Partner Program para sua organização. Observe que este programa está disponível apenas para API de primeira parte da Anthropic, e não para usuários de Bedrock ou Vertex.20Se você optar explicitamente por métodos para nos fornecer materiais para treinar, como através do [Development Partner Program](https://support.claude.com/pt/articles/11174108-about-the-development-partner-program), podemos usar esses materiais fornecidos para treinar nossos modelos. Um administrador da organização pode optar explicitamente pelo Development Partner Program para sua organização. Observe que este programa está disponível apenas para API de primeira parte da Anthropic, e não para usuários de Bedrock ou Vertex.

21 21

22### Feedback usando o comando `/feedback`22### Feedback usando o comando `/feedback`

23 23

33* **No** (Não): recusa sem enviar nada33* **No** (Não): recusa sem enviar nada

34* **Don't ask again** (Não perguntar novamente): recusa e impede que este acompanhamento apareça em futuras sessões34* **Don't ask again** (Não perguntar novamente): recusa e impede que este acompanhamento apareça em futuras sessões

35 35

36Nada é carregado a menos que você selecione explicitamente **Yes**. Organizações com [zero data retention](/pt/zero-data-retention), ou onde o feedback de produto é desabilitado pela política da organização, nunca veem este acompanhamento. Suas respostas a esta pesquisa, inclusive transcrições de sessão enviadas após a pesquisa de classificação, não afetam suas preferências de treinamento de dados e não podem ser usadas para treinar nossos modelos de IA.36Nada é carregado a menos que você selecione explicitamente **Yes**. Organizações com [zero data retention](/pt/zero-data-retention), ou onde o feedback de produto é desabilitado pela política da organização, ou onde `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` está definido, nunca veem este acompanhamento. Suas respostas a esta pesquisa, inclusive transcrições de sessão enviadas após a pesquisa de classificação, não afetam suas preferências de treinamento de dados e não podem ser usadas para treinar nossos modelos de IA.

37 37

38Para desabilitar essas pesquisas, defina `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1`. A pesquisa também é desabilitada quando `DISABLE_TELEMETRY` ou `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` está definido. Para controlar a frequência em vez de desabilitar, defina [`feedbackSurveyRate`](/pt/settings#available-settings) em seu arquivo de configurações para uma probabilidade entre `0` e `1`.38Para desabilitar essas pesquisas, defina `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1`. A pesquisa também é desabilitada quando `DISABLE_TELEMETRY`, `DO_NOT_TRACK`, ou `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` está definido. Organizações que bloqueiam tráfego não essencial, mas capturam respostas de pesquisa através de seu próprio [coletor OpenTelemetry](/pt/monitoring-usage) podem optar pela pesquisa novamente definindo `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL=1`. A pesquisa então registra classificações apenas no coletor configurado. O acompanhamento de compartilhamento de transcrição e todo o outro tráfego de feedback vinculado à Anthropic permanecem desabilitados. Para controlar a frequência em vez de desabilitar, defina [`feedbackSurveyRate`](/pt/settings#available-settings) em seu arquivo de configurações para uma probabilidade entre `0` e `1`.

39 39

40### Retenção de dados40### Retenção de dados

41 41

env-vars.md +5 −2

Details

81| `CLAUDE_CODE_DISABLE_CRON` | Defina como `1` para desabilitar [tarefas agendadas](/pt/scheduled-tasks). A skill `/loop` e ferramentas cron ficam indisponíveis e qualquer tarefa já agendada para de disparar, incluindo tarefas que já estão em execução no meio da sessão |81| `CLAUDE_CODE_DISABLE_CRON` | Defina como `1` para desabilitar [tarefas agendadas](/pt/scheduled-tasks). A skill `/loop` e ferramentas cron ficam indisponíveis e qualquer tarefa já agendada para de disparar, incluindo tarefas que já estão em execução no meio da sessão |

82| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | Defina como `1` para remover cabeçalhos de solicitação `anthropic-beta` específicos do Anthropic e campos de esquema de ferramenta beta (como `defer_loading` e `eager_input_streaming`) de solicitações de API. Use isso quando um gateway proxy rejeita solicitações com erros como "Unexpected value(s) for the `anthropic-beta` header" ou "Extra inputs are not permitted". Campos padrão (`name`, `description`, `input_schema`, `cache_control`) são preservados. |82| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | Defina como `1` para remover cabeçalhos de solicitação `anthropic-beta` específicos do Anthropic e campos de esquema de ferramenta beta (como `defer_loading` e `eager_input_streaming`) de solicitações de API. Use isso quando um gateway proxy rejeita solicitações com erros como "Unexpected value(s) for the `anthropic-beta` header" ou "Extra inputs are not permitted". Campos padrão (`name`, `description`, `input_schema`, `cache_control`) são preservados. |

84| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | Defina como `1` para desabilitar as pesquisas de qualidade de sessão "Como Claude está se saindo?". Pesquisas também são desabilitadas quando `DISABLE_TELEMETRY` ou `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` está definido. Para definir uma taxa de amostra em vez de desabilitar completamente, use a configuração [`feedbackSurveyRate`](/pt/settings#available-settings). Veja [Pesquisas de qualidade de sessão](/pt/data-usage#session-quality-surveys) |84| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | Defina como `1` para desabilitar as pesquisas de qualidade de sessão "Como Claude está se saindo?". Pesquisas também são desabilitadas quando `DISABLE_TELEMETRY`, `DO_NOT_TRACK` ou `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` está definido, a menos que `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` opte por participar novamente. Para definir uma taxa de amostra em vez de desabilitar completamente, use a configuração [`feedbackSurveyRate`](/pt/settings#available-settings). Veja [Pesquisas de qualidade de sessão](/pt/data-usage#session-quality-surveys) |

85| `CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING` | Defina como `1` para desabilitar [checkpointing](/pt/checkpointing) de arquivo. O comando `/rewind` não será capaz de restaurar alterações de código |85| `CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING` | Defina como `1` para desabilitar [checkpointing](/pt/checkpointing) de arquivo. O comando `/rewind` não será capaz de restaurar alterações de código |

86| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | Defina como `1` para remover instruções de fluxo de trabalho de commit e PR integradas e o snapshot de status git do prompt do sistema do Claude. Útil ao usar suas próprias skills de fluxo de trabalho git. Tem precedência sobre a configuração [`includeGitInstructions`](/pt/settings#available-settings) quando definido |86| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | Defina como `1` para remover instruções de fluxo de trabalho de commit e PR integradas e o snapshot de status git do prompt do sistema do Claude. Útil ao usar suas próprias skills de fluxo de trabalho git. Tem precedência sobre a configuração [`includeGitInstructions`](/pt/settings#available-settings) quando definido |

87| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | Defina como `1` para evitar remapeamento automático de Opus 4.0 e 4.1 para a versão Opus atual na API Anthropic. Use quando você deseja intencionalmente fixar um modelo mais antigo. O remapeamento não é executado em Bedrock, Vertex ou Foundry |87| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | Defina como `1` para evitar remapeamento automático de Opus 4.0 e 4.1 para a versão Opus atual na API Anthropic. Use quando você deseja intencionalmente fixar um modelo mais antigo. O remapeamento não é executado em Bedrock, Vertex ou Foundry |

96| `CLAUDE_CODE_EFFORT_LEVEL` | Defina o nível de esforço para modelos suportados. Valores: `low`, `medium`, `high`, `xhigh`, `max` ou `auto` para usar o padrão do modelo. Os níveis disponíveis dependem do modelo. Tem precedência sobre `/effort` e a configuração `effortLevel`. Veja [Ajustar nível de esforço](/pt/model-config#adjust-effort-level) |96| `CLAUDE_CODE_EFFORT_LEVEL` | Defina o nível de esforço para modelos suportados. Valores: `low`, `medium`, `high`, `xhigh`, `max` ou `auto` para usar o padrão do modelo. Os níveis disponíveis dependem do modelo. Tem precedência sobre `/effort` e a configuração `effortLevel`. Veja [Ajustar nível de esforço](/pt/model-config#adjust-effort-level) |

97| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | Substitua a disponibilidade de [recapitulação de sessão](/pt/interactive-mode#session-recap). Defina como `0` para forçar recapitulações desativadas independentemente do toggle `/config`. Defina como `1` para forçar recapitulações ativadas quando [`awaySummaryEnabled`](/pt/settings#available-settings) é `false`. Tem precedência sobre a configuração e toggle `/config` |97| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | Substitua a disponibilidade de [recapitulação de sessão](/pt/interactive-mode#session-recap). Defina como `0` para forçar recapitulações desativadas independentemente do toggle `/config`. Defina como `1` para forçar recapitulações ativadas quando [`awaySummaryEnabled`](/pt/settings#available-settings) é `false`. Tem precedência sobre a configuração e toggle `/config` |

98| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | Defina como `1` para atualizar o estado do plugin em limites de turno em [modo não interativo](/pt/headless) após a conclusão de uma instalação em segundo plano. Desativado por padrão porque a atualização altera o prompt do sistema no meio da sessão, o que invalida [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) para esse turno |98| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | Defina como `1` para atualizar o estado do plugin em limites de turno em [modo não interativo](/pt/headless) após a conclusão de uma instalação em segundo plano. Desativado por padrão porque a atualização altera o prompt do sistema no meio da sessão, o que invalida [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) para esse turno |

99| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | Defina como `1` para rotear a pesquisa de qualidade de sessão "Como Claude está se saindo?" para seu próprio [coletor OpenTelemetry](/pt/monitoring-usage) quando o tráfego não essencial vinculado ao Anthropic está bloqueado. As classificações de pesquisa são emitidas apenas como eventos OTEL para seu coletor configurado. Nenhum dado de pesquisa é enviado ao Anthropic neste modo. Aplica-se quando `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`, `DISABLE_TELEMETRY` ou `DO_NOT_TRACK` está definido, e não tem efeito caso contrário. `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` e a política de feedback do produto da organização têm precedência |

99| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | Controla se as entradas de chamada de ferramenta são transmitidas da API conforme Claude as gera. Com isso desativado, uma entrada de ferramenta grande, como uma escrita de arquivo longa, chega apenas após Claude terminar de gerá-la, o que pode parecer que está travando. Habilitado por padrão na API Anthropic. Em Bedrock e Vertex, habilitado por modelo onde o contêiner implantado suporta. Defina como `0` para optar por não participar. Defina como `1` para forçar a habilitação ao rotear através de um proxy via `ANTHROPIC_BASE_URL`, `ANTHROPIC_VERTEX_BASE_URL` ou `ANTHROPIC_BEDROCK_BASE_URL`. Desativado por padrão em Foundry e conexões [gateway](/pt/llm-gateway) |100| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | Controla se as entradas de chamada de ferramenta são transmitidas da API conforme Claude as gera. Com isso desativado, uma entrada de ferramenta grande, como uma escrita de arquivo longa, chega apenas após Claude terminar de gerá-la, o que pode parecer que está travando. Habilitado por padrão na API Anthropic. Em Bedrock e Vertex, habilitado por modelo onde o contêiner implantado suporta. Defina como `0` para optar por não participar. Defina como `1` para forçar a habilitação ao rotear através de um proxy via `ANTHROPIC_BASE_URL`, `ANTHROPIC_VERTEX_BASE_URL` ou `ANTHROPIC_BEDROCK_BASE_URL`. Desativado por padrão em Foundry e conexões [gateway](/pt/llm-gateway) |

100| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | Defina como `1` para popular o seletor `/model` a partir do endpoint `/v1/models` do seu gateway quando `ANTHROPIC_BASE_URL` aponta para um gateway compatível com Anthropic, como LiteLLM, Kong ou um proxy interno. Desativado por padrão porque gateways apoiados por uma chave de API compartilhada mostrariam de outra forma cada usuário cada modelo que a chave pode acessar. Modelos descobertos ainda são filtrados pela lista de permissões [`availableModels`](/pt/settings#available-settings) |101| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | Defina como `1` para popular o seletor `/model` a partir do endpoint `/v1/models` do seu gateway quando `ANTHROPIC_BASE_URL` aponta para um gateway compatível com Anthropic, como LiteLLM, Kong ou um proxy interno. Desativado por padrão porque gateways apoiados por uma chave de API compartilhada mostrariam de outra forma cada usuário cada modelo que a chave pode acessar. Modelos descobertos ainda são filtrados pela lista de permissões [`availableModels`](/pt/settings#available-settings) |

102| `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE` | Defina como `1` para executar [modo rápido](/pt/fast-mode) em Claude Opus 4.7 em vez de Opus 4.6. Com a variável definida, `/fast` muda para Opus 4.7; sem ela, `/fast` continua a usar Opus 4.6 |

101| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | Defina como `false` para desabilitar sugestões de prompt (o toggle "Prompt suggestions" em `/config`). Estas são as previsões acinzentadas que aparecem na sua entrada de prompt após Claude responder. Veja [Sugestões de prompt](/pt/interactive-mode#prompt-suggestions) |103| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | Defina como `false` para desabilitar sugestões de prompt (o toggle "Prompt suggestions" em `/config`). Estas são as previsões acinzentadas que aparecem na sua entrada de prompt após Claude responder. Veja [Sugestões de prompt](/pt/interactive-mode#prompt-suggestions) |

102| `CLAUDE_CODE_ENABLE_TASKS` | Defina como `1` para habilitar o sistema de rastreamento de tarefas em modo não interativo (a flag `-p`). As tarefas estão ativadas por padrão em modo interativo. Veja [Lista de tarefas](/pt/interactive-mode#task-list) |104| `CLAUDE_CODE_ENABLE_TASKS` | Defina como `1` para habilitar o sistema de rastreamento de tarefas em modo não interativo (a flag `-p`). As tarefas estão ativadas por padrão em modo interativo. Veja [Lista de tarefas](/pt/interactive-mode#task-list) |

103| `CLAUDE_CODE_ENABLE_TELEMETRY` | Defina como `1` para habilitar coleta de dados OpenTelemetry para métricas e logging. Obrigatório antes de configurar exportadores OTel. Veja [Monitoramento](/pt/monitoring-usage) |105| `CLAUDE_CODE_ENABLE_TELEMETRY` | Defina como `1` para habilitar coleta de dados OpenTelemetry para métricas e logging. Obrigatório antes de configurar exportadores OTel. Veja [Monitoramento](/pt/monitoring-usage) |

119| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | Defina o número máximo de tokens de saída para a maioria das solicitações. Padrões e limites variam por modelo; veja [max output tokens](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison). Aumentar este valor reduz a janela de contexto efetiva disponível antes que [auto-compactação](/pt/costs#reduce-token-usage) seja acionada. |121| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | Defina o número máximo de tokens de saída para a maioria das solicitações. Padrões e limites variam por modelo; veja [max output tokens](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison). Aumentar este valor reduz a janela de contexto efetiva disponível antes que [auto-compactação](/pt/costs#reduce-token-usage) seja acionada. |

120| `CLAUDE_CODE_MAX_RETRIES` | Substitua o número de vezes para tentar novamente solicitações de API falhadas (padrão: 10) |122| `CLAUDE_CODE_MAX_RETRIES` | Substitua o número de vezes para tentar novamente solicitações de API falhadas (padrão: 10) |

121| `CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY` | Número máximo de ferramentas somente leitura e subagentes que podem executar em paralelo (padrão: 10). Valores mais altos aumentam o paralelismo mas consomem mais recursos |123| `CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY` | Número máximo de ferramentas somente leitura e subagentes que podem executar em paralelo (padrão: 10). Valores mais altos aumentam o paralelismo mas consomem mais recursos |

124| `CLAUDE_CODE_MAX_TURNS` | Limite o número de voltas agentes quando nenhum limite explícito é passado. Equivalente a passar [`--max-turns`](/pt/cli-reference#cli-flags), que tem precedência quando ambos estão definidos. Um valor que não é um inteiro positivo é rejeitado na inicialização com um erro em vez de ser tratado como sem limite |

122| `CLAUDE_CODE_MCP_ALLOWLIST_ENV` | Defina como `1` para gerar servidores MCP stdio com apenas um ambiente de linha de base segura mais o `env` configurado do servidor, em vez de herdar seu ambiente de shell |125| `CLAUDE_CODE_MCP_ALLOWLIST_ENV` | Defina como `1` para gerar servidores MCP stdio com apenas um ambiente de linha de base segura mais o `env` configurado do servidor, em vez de herdar seu ambiente de shell |

123| `CLAUDE_CODE_NATIVE_CURSOR` | Defina como `1` para mostrar o cursor próprio do terminal no cursor de entrada em vez de um bloco desenhado. O cursor respeita as configurações de piscar, forma e foco do terminal |126| `CLAUDE_CODE_NATIVE_CURSOR` | Defina como `1` para mostrar o cursor próprio do terminal no cursor de entrada em vez de um bloco desenhado. O cursor respeita as configurações de piscar, forma e foco do terminal |

124| `CLAUDE_CODE_NEW_INIT` | Defina como `1` para fazer `/init` executar um fluxo de configuração interativo. O fluxo pergunta quais arquivos gerar, incluindo CLAUDE.md, skills e hooks, antes de explorar a base de código e escrevê-los. Sem essa variável, `/init` gera um CLAUDE.md automaticamente sem solicitar. |127| `CLAUDE_CODE_NEW_INIT` | Defina como `1` para fazer `/init` executar um fluxo de configuração interativo. O fluxo pergunta quais arquivos gerar, incluindo CLAUDE.md, skills e hooks, antes de explorar a base de código e escrevê-los. Sem essa variável, `/init` gera um CLAUDE.md automaticamente sem solicitar. |

202| `ENABLE_CLAUDEAI_MCP_SERVERS` | Defina como `false` para desabilitar [servidores MCP claude.ai](/pt/mcp#use-mcp-servers-from-claude-ai) no Claude Code. Habilitado por padrão para usuários conectados |205| `ENABLE_CLAUDEAI_MCP_SERVERS` | Defina como `false` para desabilitar [servidores MCP claude.ai](/pt/mcp#use-mcp-servers-from-claude-ai) no Claude Code. Habilitado por padrão para usuários conectados |

203| `ENABLE_PROMPT_CACHING_1H` | Defina como `1` para solicitar um TTL de cache de prompt de 1 hora em vez do padrão de 5 minutos. Destinado para usuários de chave de API, [Bedrock](/pt/amazon-bedrock), [Vertex](/pt/google-vertex-ai), [Foundry](/pt/microsoft-foundry) e [Claude Platform on AWS](/pt/claude-platform-on-aws). Usuários de assinatura recebem TTL de 1 hora automaticamente. Escritas de cache de 1 hora são cobradas a uma taxa mais alta |206| `ENABLE_PROMPT_CACHING_1H` | Defina como `1` para solicitar um TTL de cache de prompt de 1 hora em vez do padrão de 5 minutos. Destinado para usuários de chave de API, [Bedrock](/pt/amazon-bedrock), [Vertex](/pt/google-vertex-ai), [Foundry](/pt/microsoft-foundry) e [Claude Platform on AWS](/pt/claude-platform-on-aws). Usuários de assinatura recebem TTL de 1 hora automaticamente. Escritas de cache de 1 hora são cobradas a uma taxa mais alta |

205| `ENABLE_TOOL_SEARCH` | Controla [busca de ferramentas MCP](/pt/mcp#scale-with-mcp-tool-search). Não definido: todas as ferramentas MCP adiadas por padrão, mas carregadas antecipadamente em Vertex AI ou quando `ANTHROPIC_BASE_URL` aponta para um host que não é de primeira parte. Valores: `true` (sempre adia incluindo proxies e Vertex AI), `auto` (modo de limite: carrega antecipadamente se as ferramentas se encaixarem em 10% do contexto), `auto:N` (limite personalizado, por exemplo, `auto:5` para 5%), `false` (carrega tudo antecipadamente) |208| `ENABLE_TOOL_SEARCH` | Controla [busca de ferramentas MCP](/pt/mcp#scale-with-mcp-tool-search). Não definido: todas as ferramentas MCP adiadas por padrão, mas carregadas antecipadamente em Vertex AI ou quando `ANTHROPIC_BASE_URL` aponta para um host que não é de primeira parte. Valores: `true` (sempre adia e envia o cabeçalho beta, solicitações falham em Vertex AI ou proxies que não suportam `tool_reference`), `auto` (modo de limite: carrega antecipadamente se as ferramentas se encaixarem em 10% do contexto), `auto:N` (limite personalizado, por exemplo, `auto:5` para 5%), `false` (carrega tudo antecipadamente) |

206| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | Defina como qualquer valor não vazio para acionador fallback para [`--fallback-model`](/pt/cli-reference#cli-flags) após erros de sobrecarga repetidos em qualquer modelo primário. Por padrão, apenas modelos Opus acionam o fallback |209| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | Defina como qualquer valor não vazio para acionador fallback para [`--fallback-model`](/pt/cli-reference#cli-flags) após erros de sobrecarga repetidos em qualquer modelo primário. Por padrão, apenas modelos Opus acionam o fallback |

207| `FORCE_AUTOUPDATE_PLUGINS` | Defina como `1` para forçar auto-atualizações de plugins mesmo quando o auto-atualizador principal está desabilitado via `DISABLE_AUTOUPDATER` |210| `FORCE_AUTOUPDATE_PLUGINS` | Defina como `1` para forçar auto-atualizações de plugins mesmo quando o auto-atualizador principal está desabilitado via `DISABLE_AUTOUPDATER` |

208| `FORCE_PROMPT_CACHING_5M` | Defina como `1` para forçar o TTL de cache de prompt de 5 minutos mesmo quando o TTL de 1 hora se aplicaria de outra forma. Substitui `ENABLE_PROMPT_CACHING_1H` |211| `FORCE_PROMPT_CACHING_5M` | Defina como `1` para forçar o TTL de cache de prompt de 5 minutos mesmo quando o TTL de 1 hora se aplicaria de outra forma. Substitui `ENABLE_PROMPT_CACHING_1H` |

fast-mode.md +47 −14

Details

4 4

5# Acelere respostas com modo rápido5# Acelere respostas com modo rápido

6 6

~~7> Obtenha respostas mais rápidas do Opus 4.6 no Claude Code alternando o modo rápido.~~7> Obtenha respostas mais rápidas do Opus no Claude Code alternando o modo rápido.

8 8

9<Note>9<Note>

10 O modo rápido está em [visualização de pesquisa](#research-preview). O recurso, preços e disponibilidade podem mudar com base no feedback.10 O modo rápido está em [visualização de pesquisa](#research-preview). O recurso, preços e disponibilidade podem mudar com base no feedback.

11</Note>11</Note>

12 12

13O modo rápido é uma configuração de alta velocidade para Claude Opus 4.6, tornando o modelo 2,5x mais rápido a um custo maior por token. Ative-o com `/fast` quando você precisar de velocidade para trabalho interativo como iteração rápida ou depuração ao vivo, e desative-o quando o custo importa mais do que a latência.13O modo rápido é uma configuração de alta velocidade para Claude Opus, tornando o modelo 2,5x mais rápido a um custo maior por token. Ative-o com `/fast` quando você precisar de velocidade para trabalho interativo como iteração rápida ou depuração ao vivo, e desative-o quando o custo importa mais do que a latência.

14 14

15O modo rápido não é um modelo diferente. Ele usa o mesmo Opus 4.6 com uma configuração de API diferente que prioriza a velocidade sobre a eficiência de custo. Você obtém qualidade e capacidades idênticas, apenas respostas mais rápidas.15O modo rápido não é um modelo diferente. Ele usa Claude Opus com uma configuração de API diferente que prioriza a velocidade sobre a eficiência de custo. Você obtém qualidade e capacidades idênticas, apenas respostas mais rápidas. O modo rápido é suportado no Opus 4.6 e Opus 4.7. Não está disponível no Sonnet, Haiku ou outros modelos.

16 16

17<Note>17<Note>

18 O modo rápido requer Claude Code v2.1.36 ou posterior. Verifique sua versão com `claude --version`.18 O modo rápido requer Claude Code v2.1.36 ou posterior. Verifique sua versão com `claude --version`.

21O que você precisa saber:21O que você precisa saber:

22 22

23* Use `/fast` para alternar o modo rápido no CLI do Claude Code. Também disponível via `/fast` na Extensão Claude Code VS Code.23* Use `/fast` para alternar o modo rápido no CLI do Claude Code. Também disponível via `/fast` na Extensão Claude Code VS Code.

~~24* O preço do modo rápido para Opus 4.6 começa em \$30/150 MTok. O modo rápido está disponível com desconto de 50% para todos os planos até 23:59 PT em 16 de fevereiro.~~24* Por padrão, `/fast` é executado no Opus 4.6. Para executar o modo rápido no Opus 4.7, defina a variável de ambiente [`CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE`](#use-fast-mode-on-opus-4-7).

25* O preço do modo rápido é \$30/150 MTok tanto no Opus 4.6 quanto no Opus 4.7.

25* Disponível para todos os usuários do Claude Code em planos de assinatura (Pro/Max/Team/Enterprise) e Claude Console.26* Disponível para todos os usuários do Claude Code em planos de assinatura (Pro/Max/Team/Enterprise) e Claude Console.

26* Para usuários do Claude Code em planos de assinatura (Pro/Max/Team/Enterprise), o modo rápido está disponível apenas via uso extra e não está incluído nos limites de taxa de assinatura.27* Para usuários do Claude Code em planos de assinatura (Pro/Max/Team/Enterprise), o modo rápido está disponível apenas via uso extra e não está incluído nos limites de taxa de assinatura.

27 28

28Esta página cobre como [alternar o modo rápido](#toggle-fast-mode), seu [tradeoff de custo](#understand-the-cost-tradeoff), [quando usá-lo](#decide-when-to-use-fast-mode), [requisitos](#requirements), [opt-in por sessão](#require-per-session-opt-in) e [comportamento de limite de taxa](#handle-rate-limits).29Esta página cobre como [alternar o modo rápido](#toggle-fast-mode), [usar o modo rápido no Opus 4.7](#use-fast-mode-on-opus-4-7), o [tradeoff de custo](#understand-the-cost-tradeoff), [quando usá-lo](#decide-when-to-use-fast-mode), [requisitos](#requirements), [opt-in por sessão](#require-per-session-opt-in) e [comportamento de limite de taxa](#handle-rate-limits).

29 30

30## Alternar modo rápido31## Alternar modo rápido

31 32

40 41

41Quando você ativa o modo rápido:42Quando você ativa o modo rápido:

42 43

~~43* Se você estiver em um modelo diferente, o Claude Code alterna automaticamente para Opus 4.6~~44* Se você estiver em um modelo diferente, o Claude Code alterna automaticamente para o modelo de modo rápido: Opus 4.6 por padrão, ou Opus 4.7 quando [`CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE`](#use-fast-mode-on-opus-4-7) está definido.

44* Você verá uma mensagem de confirmação: "Fast mode ON"45* Você verá uma mensagem de confirmação: "Fast mode ON"

45* Um pequeno ícone `↯` aparece ao lado do prompt enquanto o modo rápido está ativo46* Um pequeno ícone `↯` aparece ao lado do prompt enquanto o modo rápido está ativo

46* Execute `/fast` novamente a qualquer momento para verificar se o modo rápido está ativado ou desativado47* Execute `/fast` novamente a qualquer momento para verificar se o modo rápido está ativado ou desativado

47 48

~~48Quando você desativa o modo rápido com `/fast` novamente, você permanece no Opus 4.6. O modelo não reverte para seu modelo anterior. Para alternar para um modelo diferente, use `/model`.~~49Quando você desativa o modo rápido com `/fast` novamente, você permanece na mesma versão do Opus que o modo rápido estava executando. O modelo não reverte para seu modelo anterior. Para alternar para um modelo diferente, use `/model`.

51## Usar modo rápido no Opus 4.7

53<Note>

54 O modo rápido no Opus 4.7 requer Claude Code v2.1.139 ou posterior.

55</Note>

57O modo rápido para Claude Opus 4.7 está em visualização de pesquisa. Ele é executado na mesma velocidade 2,5x e no mesmo preço que o modo rápido para Opus 4.6, sem outras mudanças de comportamento.

59<Note>

60 Em 14 de maio de 2026, o Opus 4.7 se torna o modelo de modo rápido padrão. Até então, opte por participar definindo `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE=1`.

61</Note>

63Para optar por participar, defina `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE=1` antes de iniciar o Claude Code. Com a variável definida, `/fast` é executado no Opus 4.7. Sem ela, `/fast` continua a ser executado no Opus 4.6.

65Você pode definir a variável como uma exportação de shell:

67```bash theme={null}

68export CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE=1

69```

71Ou em qualquer [arquivo de configurações](/pt/settings#settings-files) do Claude Code, incluindo configurações de usuário, projeto e gerenciadas, para definir o escopo da participação:

73```json theme={null}

74{

75 "env": {

76 "CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE": "1"

77 }

78}

79```

81O modo rápido para Opus 4.6 permanece disponível ao lado do Opus 4.7. Os dois compartilham o mesmo pool de limite de taxa do modo rápido: o uso em qualquer modelo é extraído dos mesmos limites.

49 82

50## Entender o tradeoff de custo83## Entender o tradeoff de custo

51 84

~~52O modo rápido tem preços por token mais altos do que o Opus 4.6 padrão:~~85O modo rápido tem preços por token mais altos do que o Opus padrão:

53 86

~~55| -------------------------------- | -------------- | ------------ |~~88| ----------------------- | -------------- | ------------ |

~~56| Modo rápido no Opus 4.6 (\<200K) | \$30 | \$150 |~~89| Modo rápido no Opus 4.6 | \$30 | \$150 |

~~57| Modo rápido no Opus 4.6 (>200K) | \$60 | \$225 |~~90| Modo rápido no Opus 4.7 | \$30 | \$150 |

58 91

~~59O modo rápido é compatível com a janela de contexto estendida de 1M token.~~92O preço do modo rápido é fixo em toda a janela de contexto de 1M token.

60 93

61Quando você alterna para o modo rápido no meio de uma conversa, você paga o preço total do token de entrada não armazenado em cache do modo rápido para todo o contexto da conversa. Isso custa mais do que se você tivesse ativado o modo rápido desde o início.94Quando você alterna para o modo rápido no meio de uma conversa, você paga o preço total do token de entrada não armazenado em cache do modo rápido para todo o contexto da conversa. Isso custa mais do que se você tivesse ativado o modo rápido desde o início.

62 95

125 158

126## Lidar com limites de taxa159## Lidar com limites de taxa

127 160

128O modo rápido tem limites de taxa separados do Opus 4.6 padrão. Quando você atinge o limite de taxa do modo rápido ou fica sem créditos de uso extra:161O modo rápido tem limites de taxa separados do Opus padrão. O modo rápido para Opus 4.6 e Opus 4.7 compartilham o mesmo pool de limite de taxa: o uso em qualquer modelo é extraído dos mesmos limites. Quando você atinge o limite de taxa do modo rápido ou fica sem uso extra:

129 162

1301. O modo rápido automaticamente volta para Opus 4.6 padrão1631. O modo rápido automaticamente volta para velocidade padrão na mesma versão do Opus

1312. O ícone `↯` fica cinza para indicar cooldown1642. O ícone `↯` fica cinza para indicar cooldown

1323. Você continua trabalhando com velocidade e preços padrão1653. Você continua trabalhando com velocidade e preços padrão

1334. Quando o cooldown expira, o modo rápido é automaticamente reativado1664. Quando o cooldown expira, o modo rápido é automaticamente reativado

fullscreen.md +2 −0

Details

93 93

94Um valor de `3` corresponde ao padrão em `vim` e aplicativos semelhantes. A configuração aceita valores de 1 a 20.94Um valor de `3` corresponde ao padrão em `vim` e aplicativos semelhantes. A configuração aceita valores de 1 a 20.

95 95

96Para ajustar a velocidade de rolagem interativamente, execute `/scroll-speed`. O diálogo mostra uma régua que você pode rolar enquanto está aberto para que você possa sentir a mudança imediatamente. Pressione `←` e `→` para ajustar, `r` para redefinir para o padrão detectado automaticamente e `Enter` para salvar. O comando escreve o mesmo valor que a variável de ambiente `CLAUDE_CODE_SCROLL_SPEED` define, persistido em `~/.claude/settings.json`. O comando não está disponível no terminal do IDE JetBrains.

96### Rolagem no terminal do IDE JetBrains98### Rolagem no terminal do IDE JetBrains

97 99

98No terminal do IDE JetBrains, Claude Code aplica sua própria manipulação de rolagem e ignora `CLAUDE_CODE_SCROLL_SPEED`. O terminal envia eventos de rolagem em uma taxa muito mais alta do que outros emuladores, portanto um multiplicador ajustado em outro lugar ultrapassa aqui.100No terminal do IDE JetBrains, Claude Code aplica sua própria manipulação de rolagem e ignora `CLAUDE_CODE_SCROLL_SPEED`. O terminal envia eventos de rolagem em uma taxa muito mais alta do que outros emuladores, portanto um multiplicador ajustado em outro lugar ultrapassa aqui.

glossary.md +1 −1

Details

174 174

175### Output style175### Output style

176 176

177Uma configuração que modifica o prompt do sistema de Claude para alterar comportamento de resposta, tom ou formato. Output styles desligam as partes específicas de engenharia de software do prompt do sistema padrão, diferentemente de [CLAUDE.md](#claude-md) que é entregue como uma mensagem de usuário seguindo o prompt do sistema. Estilos built-in incluem Default, Explanatory e Learning.177Uma configuração que modifica o prompt do sistema de Claude para alterar comportamento de resposta, tom ou formato. Output styles desligam as partes específicas de engenharia de software do prompt do sistema padrão, diferentemente de [CLAUDE.md](#claude-md) que é entregue como uma mensagem de usuário seguindo o prompt do sistema. Estilos built-in incluem Default, Proactive, Explanatory e Learning.

178 178

179Saiba mais: [Output styles](/pt/output-styles)179Saiba mais: [Output styles](/pt/output-styles)

180 180

hooks.md +87 −24

Details

18 18

19<div style={{maxWidth: "500px", margin: "0 auto"}}>19<div style={{maxWidth: "500px", margin: "0 auto"}}>

20 <Frame>20 <Frame>

21 <img src="https://mintcdn.com/claude-code/ZIW26Z9pnpsXLhbS/images/hooks-lifecycle.svg?fit=max&auto=format&n=ZIW26Z9pnpsXLhbS&q=85&s=ee23691324deb6501df09bfdae560b64" alt="Diagrama do ciclo de vida do hook mostrando Setup opcional alimentando SessionStart, depois um loop por turno contendo UserPromptSubmit, UserPromptExpansion para slash commands, o loop agentic aninhado (PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, PostToolBatch, SubagentStart/Stop, TaskCreated, TaskCompleted) e Stop ou StopFailure, seguido por TeammateIdle, PreCompact, PostCompact e SessionEnd, com Elicitation e ElicitationResult aninhados dentro da execução de ferramenta MCP, PermissionDenied como um ramo lateral de PermissionRequest para negações em modo automático, e WorktreeCreate, WorktreeRemove, Notification, ConfigChange, InstructionsLoaded, CwdChanged e FileChanged como eventos assíncronos independentes" width="520" height="1228" data-path="images/hooks-lifecycle.svg" />21 <img src="https://mintcdn.com/claude-code/ZIW26Z9pnpsXLhbS/images/hooks-lifecycle.svg?fit=max&auto=format&n=ZIW26Z9pnpsXLhbS&q=85&s=ee23691324deb6501df09bfdae560b64" alt="Diagrama do ciclo de vida do hook mostrando Setup opcional alimentando SessionStart, depois um loop por turno contendo UserPromptSubmit, UserPromptExpansion para slash commands, o loop agentic aninhado (PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, PostToolBatch, SubagentStart/Stop, TaskCreated, TaskCompleted), e Stop ou StopFailure, seguido por TeammateIdle, PreCompact, PostCompact e SessionEnd, com Elicitation e ElicitationResult aninhados dentro da execução de ferramenta MCP, PermissionDenied como um ramo lateral de PermissionRequest para negações em modo automático, e WorktreeCreate, WorktreeRemove, Notification, ConfigChange, InstructionsLoaded, CwdChanged e FileChanged como eventos assíncronos independentes" width="520" height="1228" data-path="images/hooks-lifecycle.svg" />

22 </Frame>22 </Frame>

23</div>23</div>

24 24

70 {70 {

71 "type": "command",71 "type": "command",

72 "if": "Bash(rm *)",72 "if": "Bash(rm *)",

~~73 "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm.sh"~~73 "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh",

74 "args": []

74 }75 }

75 ]76 ]

76 }77 }

307Além dos [campos comuns](#common-fields), hooks de comando aceitam esses campos:308Além dos [campos comuns](#common-fields), hooks de comando aceitam esses campos:

308 309

310| :------------ | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |311| :------------ | :---------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

311| `command` | sim | Comando shell a executar |312| `command` | sim | Comando shell a executar. Com `args`, o executável a gerar diretamente. Consulte [Forma exec e forma shell](#exec-form-and-shell-form) |

313| `args` | não | Lista de argumentos. Quando presente, `command` é resolvido como um executável e gerado diretamente com `args` como o vetor de argumentos, sem shell envolvido. Consulte [Forma exec e forma shell](#exec-form-and-shell-form) |

312| `async` | não | Se `true`, executa em background sem bloquear. Consulte [Executar hooks em background](#run-hooks-in-the-background) |314| `async` | não | Se `true`, executa em background sem bloquear. Consulte [Executar hooks em background](#run-hooks-in-the-background) |

313| `asyncRewake` | não | Se `true`, executa em background e acorda Claude na saída do código 2. Implica `async`. O stderr do hook, ou stdout se stderr estiver vazio, é mostrado ao Claude como um lembrete do sistema para que possa reagir a uma falha de background de longa duração |315| `asyncRewake` | não | Se `true`, executa em background e acorda Claude na saída do código 2. Implica `async`. O stderr do hook, ou stdout se stderr estiver vazio, é mostrado ao Claude como um lembrete do sistema para que possa reagir a uma falha de background de longa duração |

314| `shell` | não | Shell a usar para este hook. Aceita `"bash"` (padrão) ou `"powershell"`. Definir `"powershell"` executa o comando via PowerShell no Windows. Não requer `CLAUDE_CODE_USE_POWERSHELL_TOOL` já que hooks geram PowerShell diretamente |316| `shell` | não | Shell a usar para este hook. Aceita `"bash"` (padrão) ou `"powershell"`. Definir `"powershell"` executa o comando via PowerShell no Windows. Não requer `CLAUDE_CODE_USE_POWERSHELL_TOOL` já que hooks geram PowerShell diretamente. Ignorado quando `args` é definido |

317

318<a id="exec-form-and-shell-form" />

319

320##### Forma exec e forma shell

321

322Um hook de comando executa como forma exec quando `args` é definido, e forma shell quando `args` é omitido. Defina `args` sempre que o hook referenciar um [placeholder de caminho](#reference-scripts-by-path), já que cada elemento é passado como um argumento sem aspas. Omita `args` quando você precisar de recursos de shell como pipes ou `&&`, ou quando nenhuma preocupação se aplica.

323

324**Forma exec** executa quando `args` está presente. Claude Code resolve `command` como um executável em `PATH` e o gera diretamente com `args` como o vetor de argumentos. Não há shell, então cada elemento `args` é um argumento exatamente como escrito, e placeholders de caminho como `${CLAUDE_PLUGIN_ROOT}` são substituídos em `command` e em cada elemento `args` como strings simples. Caracteres especiais como apóstrofos, `$` e backticks passam verbatim porque não há shell para interpretá-los. Nenhuma tokenização de shell acontece em nenhuma plataforma.

325

326**Forma shell** executa quando `args` está ausente. A string `command` é passada para um shell: `sh -c` em macOS e Linux, Git Bash no Windows, ou PowerShell quando Git Bash não está instalado. Defina o campo `shell` para escolher explicitamente. O shell tokeniza a string, expande variáveis e interpreta pipes, `&&`, redirecionamentos e globs.

327

328<Note>

329 No Windows, a forma exec requer que `command` seja resolvido para um executável real como `.exe`. Os shims `.cmd` e `.bat` que npm, npx, eslint e outras ferramentas instalam em `node_modules/.bin` não são executáveis e não podem ser gerados sem um shell. Para executá-los em forma exec, invoque o script subjacente com `node` diretamente, por exemplo `"command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/node_modules/eslint/bin/eslint.js"]`. O padrão `node` mais caminho-de-script funciona em todas as plataformas porque `node.exe` é um binário real. Para executar um shim `.cmd` ou `.bat` por nome, use forma shell.

330</Note>

331

332Este exemplo executa um script Node agrupado com um plugin. A forma exec passa o caminho do script resolvido como um argumento sem aspas:

333

334```json theme={null}

335{

336 "type": "command",

337 "command": "node",

338 "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/format.js", "--fix"]

339}

340```

341

342A forma shell equivalente precisa de aspas para lidar com caminhos com espaços ou caracteres especiais:

343

344```json theme={null}

345{

346 "type": "command",

347 "command": "node \"${CLAUDE_PLUGIN_ROOT}\"/scripts/format.js --fix"

348}

349```

350

351Ambas as formas suportam os mesmos [placeholders de caminho](#reference-scripts-by-path), e ambas os exportam como as variáveis de ambiente `CLAUDE_PROJECT_DIR`, `CLAUDE_PLUGIN_ROOT` e `CLAUDE_PLUGIN_DATA` no processo gerado, então um script pode ler `process.env.CLAUDE_PLUGIN_ROOT` independentemente de como foi lançado. Hooks de plugin adicionalmente substituem valores `${user_config.*}`; consulte [Configuração de usuário](/pt/plugins-reference#user-configuration).

352

353<Note>

354 Em forma exec, `command` é apenas o nome ou caminho do executável. Se `command` é um nome simples sem separador de caminho e contém espaço em branco junto com `args`, Claude Code registra um aviso porque o spawn falhará: não há executável nomeado `node script.js`. Mova os tokens extras para `args`. Caminhos absolutos com espaços, como `C:\Program Files\nodejs\node.exe`, são um executável válido único e não disparam o aviso.

355</Note>

315 356

316#### Campos de hook HTTP357#### Campos de hook HTTP

317 358

397| `prompt` | sim | Texto do prompt a enviar para o modelo. Use `$ARGUMENTS` como placeholder para a entrada JSON do hook |438| `prompt` | sim | Texto do prompt a enviar para o modelo. Use `$ARGUMENTS` como placeholder para a entrada JSON do hook |

398| `model` | não | Modelo a usar para avaliação. Padrão para um modelo rápido |439| `model` | não | Modelo a usar para avaliação. Padrão para um modelo rápido |

399 440

400Todos os hooks correspondentes executam em paralelo, e manipuladores idênticos são automaticamente desduplicados. Hooks de comando são desduplicados por string de comando, e hooks HTTP são desduplicados por URL. Manipuladores executam no diretório atual com o ambiente do Claude Code. A variável de ambiente `$CLAUDE_CODE_REMOTE` é definida como `"true"` em ambientes web remotos e não é definida na CLI local.441Todos os hooks correspondentes executam em paralelo, e manipuladores idênticos são automaticamente desduplicados. Hooks de comando são desduplicados por string de comando e `args`, e hooks HTTP são desduplicados por URL. Manipuladores executam no diretório atual com o ambiente do Claude Code. A variável de ambiente `$CLAUDE_CODE_REMOTE` é definida como `"true"` em ambientes web remotos e não é definida na CLI local.

401 442

402### Referenciar scripts por caminho443### Referenciar scripts por caminho

403 444

404Use variáveis de ambiente para referenciar scripts de hook relativos à raiz do projeto ou plugin, independentemente do diretório de trabalho quando o hook executa:445Use esses placeholders para referenciar scripts de hook relativos à raiz do projeto ou plugin, independentemente do diretório de trabalho quando o hook executa:

405 446

406* `$CLAUDE_PROJECT_DIR`: a raiz do projeto. Envolva em aspas para lidar com caminhos com espaços.447* `${CLAUDE_PROJECT_DIR}`: a raiz do projeto.

407* `${CLAUDE_PLUGIN_ROOT}`: o diretório raiz do plugin, para scripts agrupados com um [plugin](/pt/plugins). Muda em cada atualização de plugin.448* `${CLAUDE_PLUGIN_ROOT}`: o diretório de instalação do plugin, para scripts agrupados com um [plugin](/pt/plugins). Muda em cada atualização de plugin.

408* `${CLAUDE_PLUGIN_DATA}`: o [diretório de dados persistentes](/pt/plugins-reference#persistent-data-directory) do plugin, para dependências e estado que devem sobreviver a atualizações de plugin.449* `${CLAUDE_PLUGIN_DATA}`: o [diretório de dados persistentes](/pt/plugins-reference#persistent-data-directory) do plugin, para dependências e estado que devem sobreviver a atualizações de plugin.

409 450

451Prefira [forma exec](#exec-form-and-shell-form) para qualquer hook que referencie um placeholder de caminho. A forma exec passa cada elemento `args` como um argumento sem tokenização de shell, então caminhos com espaços ou caracteres especiais não precisam de aspas. Em forma shell, envolva cada placeholder em aspas duplas.

452

410<Tabs>453<Tabs>

411 <Tab title="Scripts de projeto">454 <Tab title="Scripts de projeto">

412 Este exemplo usa `$CLAUDE_PROJECT_DIR` para executar um verificador de estilo do diretório `.claude/hooks/` do projeto após qualquer chamada de ferramenta `Write` ou `Edit`:455 Este exemplo usa `${CLAUDE_PROJECT_DIR}` para executar um verificador de estilo do diretório `.claude/hooks/` do projeto após qualquer chamada de ferramenta `Write` ou `Edit`:

413 456

414 ```json theme={null}457 ```json theme={null}

415 {458 {

420 "hooks": [463 "hooks": [

421 {464 {

422 "type": "command",465 "type": "command",

423 "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-style.sh"466 "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/check-style.sh",

467 "args": []

424 }468 }

425 ]469 ]

426 }470 }

446 {490 {

447 "type": "command",491 "type": "command",

448 "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh",492 "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh",

493 "args": [],

449 "timeout": 30494 "timeout": 30

450 }495 }

451 ]496 ]

529Ao executar com `--agent` ou dentro de um subagente, dois campos adicionais são incluídos:574Ao executar com `--agent` ou dentro de um subagente, dois campos adicionais são incluídos:

530 575

531| Campo | Descrição |576| Campo | Descrição |

532| :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |577| :----------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

533| `agent_id` | Identificador único para o subagente. Presente apenas quando o hook dispara dentro de uma chamada de subagente. Use isso para distinguir chamadas de hook de subagente de chamadas de thread principal. |578| `agent_id` | Identificador único para o subagente. Presente apenas quando o hook dispara dentro de uma chamada de subagente. Use isso para distinguir chamadas de hook de subagente de chamadas de thread principal. |

534| `agent_type` | Nome do agente (por exemplo, `"Explore"` ou `"security-reviewer"`). Presente quando a sessão usa `--agent` ou o hook dispara dentro de um subagente. Para subagentes, o tipo do subagente tem precedência sobre o valor `--agent` da sessão. |579| `agent_type` | Nome do agente (por exemplo, `"Explore"` ou `"security-reviewer"`). Presente quando a sessão usa `--agent` ou o hook dispara dentro de um subagente. Para subagentes, o tipo do subagente tem precedência sobre o valor `--agent` da sessão. Para [subagentes personalizados](/pt/sub-agents), este é o campo `name` do frontmatter do agente, não o nome do arquivo. |

580

581Apenas hooks [`SessionStart`](#sessionstart) recebem um campo `model`. Não há variável de ambiente `$CLAUDE_MODEL`. Um processo de hook herda o ambiente pai, então pode ler `$ANTHROPIC_MODEL` se você defini-lo em seu shell, mas esse valor não muda quando você alterna modelos com `/model` durante uma sessão.

535 582

536Por exemplo, um hook `PreToolUse` para um comando Bash recebe isso em stdin:583Por exemplo, um hook `PreToolUse` para um comando Bash recebe isso em stdin:

537 584

1153| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React"}], "multiSelect": false}]` | Perguntas a apresentar, cada uma com uma string `question`, `header` curto, array `options` e flag `multiSelect` opcional |1200| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React"}], "multiSelect": false}]` | Perguntas a apresentar, cada uma com uma string `question`, `header` curto, array `options` e flag `multiSelect` opcional |

1154| `answers` | object | `{"Which framework?": "React"}` | Opcional. Mapeia texto de pergunta para rótulo de opção selecionada. Respostas multi-select juntam rótulos com vírgulas. Claude não define este campo; forneça-o via `updatedInput` para responder programaticamente |1201| `answers` | object | `{"Which framework?": "React"}` | Opcional. Mapeia texto de pergunta para rótulo de opção selecionada. Respostas multi-select juntam rótulos com vírgulas. Claude não define este campo; forneça-o via `updatedInput` para responder programaticamente |

1155 1202

1203##### ExitPlanMode

1204

1205Apresenta um plano e pede ao usuário para aprová-lo antes do Claude sair do [modo de plano](/pt/permission-modes#analyze-before-you-edit-with-plan-mode). Claude escreve o plano em um arquivo no disco antes de chamar a ferramenta, então o `tool_input` literal do modelo apenas carrega `allowedPrompts`. Claude Code injeta o conteúdo do plano e o caminho do arquivo antes de passar a entrada para hooks.

1206

1208| :--------------- | :----- | :------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1211| `allowedPrompts` | array | `[{"tool": "Bash", "prompt": "run tests"}]` | Opcional. Permissões baseadas em prompt que Claude está solicitando para implementar o plano, cada uma com um nome `tool` e um `prompt` descrevendo a categoria de ação |

1212

1213Em `PostToolUse`, `tool_response` é um objeto com campos `plan` e `filePath` contendo o plano aprovado, mais flags de status interno. Leia `tool_response.plan` para o conteúdo do plano em vez de re-ler o arquivo do disco.

1214

1156#### Controle de decisão de PreToolUse1215#### Controle de decisão de PreToolUse

1157 1216

1158Hooks `PreToolUse` podem controlar se uma chamada de ferramenta prossegue. Diferentemente de outros hooks que usam um campo `decision` de nível superior, PreToolUse retorna sua decisão dentro de um objeto `hookSpecificOutput`. Isso oferece controle mais rico: quatro resultados (permitir, negar, pedir ou adiar) além da capacidade de modificar entrada de ferramenta antes da execução.1217Hooks `PreToolUse` podem controlar se uma chamada de ferramenta prossegue. Diferentemente de outros hooks que usam um campo `decision` de nível superior, PreToolUse retorna sua decisão dentro de um objeto `hookSpecificOutput`. Isso oferece controle mais rico: quatro resultados (permitir, negar, pedir ou adiar) além da capacidade de modificar entrada de ferramenta antes da execução.

1596 1655

1597### SubagentStart1656### SubagentStart

1598 1657

1599Executa quando um subagente do Claude Code é gerado via ferramenta Agent. Suporta matchers para filtrar por nome de tipo de agente (agentes integrados como `general-purpose`, `Explore`, `Plan` ou nomes de agentes personalizados de `.claude/agents/`).1658Executa quando um subagente do Claude Code é gerado via ferramenta Agent. Suporta matchers para filtrar por nome de tipo de agente. Para agentes integrados, este é o nome do agente como `general-purpose`, `Explore` ou `Plan`. Para [subagentes personalizados](/pt/sub-agents), este é o campo `name` do frontmatter do agente, não o nome do arquivo.

1600 1659

1601#### Entrada de SubagentStart1660#### Entrada de SubagentStart

1602 1661

1651}1710}

1652```1711```

1653 1712

1654Hooks SubagentStop usam o mesmo formato de controle de decisão que [hooks Stop](#stop-decision-control).1713Hooks SubagentStop usam o mesmo formato de controle de decisão que [hooks Stop](#stop-decision-control). Eles não suportam `additionalContext`. Retornar `decision: "block"` com uma `reason` mantém o subagente em execução e entrega `reason` ao subagente como sua próxima instrução. Para injetar contexto na sessão pai após um subagente retornar, use um hook [`PostToolUse`](#posttooluse) na ferramenta `Agent` em vez disso.

1655 1714

1656### TaskCreated1715### TaskCreated

1657 1716

1905 "hooks": [1964 "hooks": [

1906 {1965 {

1907 "type": "command",1966 "type": "command",

1908 "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/audit-config-change.sh"1967 "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/audit-config-change.sh",

1968 "args": []

1909 }1969 }

1910 ]1970 ]

1911 }1971 }

2394```2454```

2395 2455

2397| :-------- | :---------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |2457| :---------------- | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

2398| `type` | sim | Deve ser `"prompt"` |2458| `type` | sim | Deve ser `"prompt"` |

2399| `prompt` | sim | O texto do prompt a enviar para o LLM. Use `$ARGUMENTS` como placeholder para a entrada JSON do hook. Se `$ARGUMENTS` não estiver presente, entrada JSON é anexada ao prompt |2459| `prompt` | sim | O texto do prompt a enviar para o LLM. Use `$ARGUMENTS` como placeholder para a entrada JSON do hook. Se `$ARGUMENTS` não estiver presente, entrada JSON é anexada ao prompt |

2400| `model` | não | Modelo a usar para avaliação. Padrão para um modelo rápido |2460| `model` | não | Modelo a usar para avaliação. Padrão para um modelo rápido |

2401| `timeout` | não | Timeout em segundos. Padrão: 30 |2461| `timeout` | não | Timeout em segundos. Padrão: 30 |

2462| `continueOnBlock` | não | Quando o prompt retorna `ok: false`, alimenta a razão de volta para Claude e continua o turno em vez de parar. Padrão: `false`. Implementado como `continue: true` na `decision: "block"` resultante. Veja [Esquema de resposta](#response-schema) para comportamento por evento |

2402 2463

2403### Esquema de resposta2464### Esquema de resposta

2404 2465

2412```2473```

2413 2474

2414| Campo | Descrição |2475| Campo | Descrição |

2415| :------- | :-------------------------------------------------------------------------------- |2476| :------- | :--------------------------------------------------------------------------------------------------- |

2416| `ok` | `true` permite a ação, `false` a bloqueia. Veja o comportamento por evento abaixo |2477| `ok` | `true` para permitir. `false` produz uma `decision: "block"`. Veja o comportamento por evento abaixo |

2418 2479

2419O que acontece em `ok: false` depende do evento:2480O que acontece em `ok: false` depende do evento:

2420 2481

2421* `Stop` e `SubagentStop`: a razão é retornada a Claude como sua próxima instrução e o turno continua2482* `Stop` e `SubagentStop`: a razão é alimentada de volta para Claude como sua próxima instrução e o turno continua

2422* `PreToolUse`: a chamada de ferramenta é negada e a razão é retornada a Claude como o erro da ferramenta, equivalente a um hook de comando com `permissionDecision: "deny"`2483* `PreToolUse`: a chamada de ferramenta é negada e a razão é retornada a Claude como o erro da ferramenta, equivalente a um hook de comando com `permissionDecision: "deny"`

2423* `PostToolUse`, `PostToolBatch`, `UserPromptSubmit` e `UserPromptExpansion`: o turno termina e a razão aparece no chat como uma linha de aviso, equivalente a retornar `"continue": false` de um hook de comando2484* `PostToolUse`: por padrão o turno termina e a razão aparece no chat como uma linha de aviso. Defina `continueOnBlock: true` para alimentar a razão de volta para Claude e continuar o turno em vez disso

2485* `PostToolBatch`, `UserPromptSubmit` e `UserPromptExpansion`: o turno termina e a razão aparece como uma linha de aviso. Esses eventos terminam o turno em `decision: "block"` independentemente de `continue`

2424* `PostToolUseFailure`, `TaskCreated` e `TaskCompleted`: a razão é retornada a Claude como um erro de ferramenta, similar a `PreToolUse`2486* `PostToolUseFailure`, `TaskCreated` e `TaskCompleted`: a razão é retornada a Claude como um erro de ferramenta, similar a `PreToolUse`

2425* `PermissionRequest`: `ok: false` não tem efeito. Para negar uma aprovação de um hook, use um [hook de comando](#command-hook-fields) retornando `hookSpecificOutput.decision.behavior: "deny"`2487* `PermissionRequest`: `ok: false` não tem efeito. Para negar uma aprovação de um hook, use um [hook de comando](#command-hook-fields) retornando `hookSpecificOutput.decision.behavior: "deny"`

2426 2488

2579 "hooks": [2641 "hooks": [

2580 {2642 {

2581 "type": "command",2643 "type": "command",

2582 "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/run-tests-async.sh",2644 "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/run-tests-async.sh",

2645 "args": [],

2583 "async": true,2646 "async": true,

2584 "timeout": 3002647 "timeout": 300

2585 }2648 }

2616* **Valide e sanitize entradas**: nunca confie em dados de entrada cegamente2679* **Valide e sanitize entradas**: nunca confie em dados de entrada cegamente

2617* **Sempre cite variáveis shell**: use `"$VAR"` não `$VAR`2680* **Sempre cite variáveis shell**: use `"$VAR"` não `$VAR`

2618* **Bloqueie traversal de caminho**: verifique `..` em caminhos de arquivo2681* **Bloqueie traversal de caminho**: verifique `..` em caminhos de arquivo

2619* **Use caminhos absolutos**: especifique caminhos completos para scripts, usando `"$CLAUDE_PROJECT_DIR"` para a raiz do projeto2682* **Use caminhos absolutos**: especifique caminhos completos para scripts. Na forma exec, use `${CLAUDE_PROJECT_DIR}` e o caminho não precisa de aspas. Na forma shell, envolva-o em aspas duplas

2620* **Pule arquivos sensíveis**: evite `.env`, `.git/`, chaves, etc.2683* **Pule arquivos sensíveis**: evite `.env`, `.git/`, chaves, etc.

2621 2684

2622## Ferramenta Windows PowerShell2685## Ferramenta Windows PowerShell

hooks-guide.md +2 −2

Details

895 echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh895 echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh

896 echo $? # Verifique o código de saída896 echo $? # Verifique o código de saída

897 ```897 ```

898* Se você vir "command not found", use caminhos absolutos ou `$CLAUDE_PROJECT_DIR` para referenciar scripts898* Se você vir "command not found", use caminhos absolutos ou `${CLAUDE_PROJECT_DIR}` para referenciar scripts. Para evitar quoting de shell completamente, adicione `"args": []` para mudar para [forma exec](/pt/hooks#exec-form-and-shell-form), que gera o script diretamente sem um shell

899* Se você vir "jq: command not found", instale `jq` ou use Python/Node.js para análise JSON899* Se você vir "jq: command not found", instale `jq` ou use Python/Node.js para análise JSON

900* Se o script não está executando em tudo, torne-o executável: `chmod +x ./my-hook.sh`900* Se o script não está executando em tudo, torne-o executável: `chmod +x ./my-hook.sh`

901 901

926 926

927Claude Code mostra um erro de análise JSON mesmo que seu script de hook produza JSON válido.927Claude Code mostra um erro de análise JSON mesmo que seu script de hook produza JSON válido.

928 928

929Quando Claude Code executa um hook, ele gera um shell que fornece seu perfil (`~/.zshrc` ou `~/.bashrc`). Se seu perfil contiver instruções `echo` incondicionais, essa saída é adicionada ao seu JSON do hook:929Quando Claude Code executa um hook de comando em forma de shell (um sem `args`), ele gera `sh -c` no macOS e Linux ou Git Bash no Windows por padrão. Este shell é não-interativo, mas Git Bash e algumas configurações (como `BASH_ENV` apontando para `~/.bashrc`) ainda fornecem seu perfil. Se esse perfil contiver instruções `echo` incondicionais, a saída é adicionada ao seu JSON do hook:

930 930

931```text theme={null}931```text theme={null}

932Shell ready on arm64932Shell ready on arm64

interactive-mode.md +6 −3

Details

9## Atalhos de teclado9## Atalhos de teclado

10 10

11<Note>11<Note>

~~12 Os atalhos de teclado podem variar por plataforma e terminal. Pressione `?` para ver os atalhos disponíveis para seu ambiente.~~12 Os atalhos de teclado podem variar por plataforma e terminal. Em [renderização em tela cheia](/pt/fullscreen), pressione `?` no visualizador de transcrição para ver os atalhos disponíveis lá.

13 13

14 **Usuários de macOS**: Os atalhos da tecla Option/Alt (`Alt+B`, `Alt+F`, `Alt+Y`, `Alt+M`, `Alt+P`) exigem configurar Option como Meta no seu terminal:14 **Usuários de macOS**: Os atalhos da tecla Option/Alt (`Alt+B`, `Alt+F`, `Alt+Y`, `Alt+M`, `Alt+P`) exigem configurar Option como Meta no seu terminal:

15 15

38| `Up/Down arrows` ou `Ctrl+P`/`Ctrl+N` | Mover cursor ou navegar histórico de comandos | Em entrada multilinha, primeiro move o cursor dentro do prompt. Uma vez que o cursor já está na borda superior ou inferior, pressionar novamente navega pelo histórico de comandos |38| `Up/Down arrows` ou `Ctrl+P`/`Ctrl+N` | Mover cursor ou navegar histórico de comandos | Em entrada multilinha, primeiro move o cursor dentro do prompt. Uma vez que o cursor já está na borda superior ou inferior, pressionar novamente navega pelo histórico de comandos |

39| `Esc` | Interromper Claude | Pare a resposta atual ou chamada de ferramenta no meio da vez para que você possa redirecionar. Claude mantém o trabalho realizado até agora |

40| `Shift+Tab` ou `Alt+M` (algumas configurações) | Alternar modos de permissão | Alternar entre `default`, `acceptEdits`, `plan` e qualquer modo que você tenha ativado, como `auto` ou `bypassPermissions`. Veja [modos de permissão](/pt/permission-modes). |41| `Shift+Tab` ou `Alt+M` (algumas configurações) | Alternar modos de permissão | Alternar entre `default`, `acceptEdits`, `plan` e qualquer modo que você tenha ativado, como `auto` ou `bypassPermissions`. Veja [modos de permissão](/pt/permission-modes). |

42| `Option+T` (macOS) ou `Alt+T` (Windows/Linux) | Alternar pensamento estendido | Ativar ou desativar modo de pensamento estendido. A partir da v2.1.132, este atalho funciona no macOS sem configurar Option como Meta |43| `Option+T` (macOS) ou `Alt+T` (Windows/Linux) | Alternar pensamento estendido | Ativar ou desativar modo de pensamento estendido. {/* min-version: 2.1.132 */}A partir da v2.1.132, este atalho funciona no macOS sem configurar Option como Meta |

44 45

45### Edição de texto46### Edição de texto

86 87

87### Visualizador de transcrição88### Visualizador de transcrição

88 89

~~89Quando o visualizador de transcrição está aberto (alternado com `Ctrl+O`), estes atalhos estão disponíveis. `Ctrl+E` pode ser reatribuído via [`transcript:toggleShowAll`](/pt/keybindings).~~90Quando o visualizador de transcrição está aberto (alternado com `Ctrl+O`), estes atalhos estão disponíveis. Em [renderização em tela cheia](/pt/fullscreen), pressione `?` para mostrar o painel de referência de atalho de teclado completo dentro do visualizador. `Ctrl+E` pode ser reatribuído via [`transcript:toggleShowAll`](/pt/keybindings).

90 91

91| Atalho | Descrição |92| Atalho | Descrição |

92| :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |93| :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

94| `?` | Alternar o painel de ajuda de atalho de teclado. Requer [renderização em tela cheia](/pt/fullscreen) |

95| `{` / `}` | Pular para o prompt do usuário anterior ou próximo, como movimento de parágrafo vim. Requer [renderização em tela cheia](/pt/fullscreen) |

94| `[` | Escrever a conversa completa no scrollback nativo do seu terminal para que `Cmd+F`, modo de cópia do tmux e outras ferramentas nativas possam pesquisá-lo. Requer [renderização em tela cheia](/pt/fullscreen#search-and-review-the-conversation) |97| `[` | Escrever a conversa completa no scrollback nativo do seu terminal para que `Cmd+F`, modo de cópia do tmux e outras ferramentas nativas possam pesquisá-lo. Requer [renderização em tela cheia](/pt/fullscreen#search-and-review-the-conversation) |

95| `v` | Escrever a conversa em um arquivo temporário e abri-lo em `$VISUAL` ou `$EDITOR`. Requer [renderização em tela cheia](/pt/fullscreen) |98| `v` | Escrever a conversa em um arquivo temporário e abri-lo em `$VISUAL` ou `$EDITOR`. Requer [renderização em tela cheia](/pt/fullscreen) |

llm-gateway.md +6 −2

Details

39 39

40**Cabeçalhos de solicitação**40**Cabeçalhos de solicitação**

41 41

~~42Claude Code inclui os seguintes cabeçalhos em cada solicitação de API:~~42Claude Code inclui os seguintes cabeçalhos em solicitações de API:

43 43

44| Cabeçalho | Descrição |44| Cabeçalho | Descrição |

45| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |45| :------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

46| `X-Claude-Code-Session-Id` | Um identificador único para a sessão atual do Claude Code. Proxies podem usar isso para agregar todas as solicitações de API de uma única sessão sem analisar o corpo da solicitação. |46| `X-Claude-Code-Session-Id` | Um identificador único para a sessão atual do Claude Code. Proxies podem usar isso para agregar todas as solicitações de API de uma única sessão sem analisar o corpo da solicitação. |

47| `X-Claude-Code-Agent-Id` | Identificador do subagente ou colega de trabalho que emitiu a solicitação. Seu proxy pode usar isso para atribuir o custo da API a subagentes paralelos individuais dentro de uma sessão, sem analisar o corpo da solicitação. Presente apenas para solicitações feitas por um subagente ou colega de trabalho em processo. |

48| `X-Claude-Code-Parent-Agent-Id` | Identificador do agente que gerou o agente que faz a solicitação. Use isso com `X-Claude-Code-Agent-Id` para atribuir custos de API entre agentes aninhados em seu proxy. Presente apenas quando o agente solicitante foi ele próprio gerado por outro agente. |

50Ambos os cabeçalhos de ID de agente são identificadores efêmeros por geração, não IDs de usuário ou dispositivo persistentes.

47 51

48Claude Code também adiciona um bloco de atribuição curto ao prompt do sistema contendo a versão do cliente e uma impressão digital derivada da conversa. A API Anthropic remove este bloco antes do processamento, portanto não afeta o cache de prompt de primeira parte. Se seu gateway implementa seu próprio cache de prompt com chave no corpo completo da solicitação, defina [`CLAUDE_CODE_ATTRIBUTION_HEADER=0`](/pt/env-vars) para omiti-lo.52Claude Code também adiciona um bloco de atribuição curto ao prompt do sistema contendo a versão do cliente e uma impressão digital derivada da conversa. A API Anthropic remove este bloco antes do processamento, portanto não afeta o cache de prompt de primeira parte. Se seu gateway implementa seu próprio cache de prompt com chave no corpo completo da solicitação, defina [`CLAUDE_CODE_ATTRIBUTION_HEADER=0`](/pt/env-vars) para omiti-lo.

49 53

mcp.md +35 −221

Details

6 6

7> Aprenda como conectar Claude Code às suas ferramentas com o Model Context Protocol.7> Aprenda como conectar Claude Code às suas ferramentas com o Model Context Protocol.

8 8

~~9export const MCPServersTable = ({platform = "all"}) => {~~

~~10 const ifYouAreAnAiAgentReadingThisYouShouldInsteadFetch = 'https://api.anthropic.com/mcp-registry/docs';~~

~~11 const [servers, setServers] = useState([]);~~

~~12 const [loading, setLoading] = useState(true);~~

~~13 const [error, setError] = useState(null);~~

~~14 useEffect(() => {~~

~~15 const fetchServers = async () => {~~

~~16 try {~~

~~17 setLoading(true);~~

~~18 const allServers = [];~~

~~19 let cursor = null;~~

~~20 do {~~

~~21 const url = new URL('https://api.anthropic.com/mcp-registry/v0/servers');~~

~~22 url.searchParams.set('version', 'latest');~~

~~23 url.searchParams.set('visibility', 'commercial');~~

~~24 url.searchParams.set('limit', '100');~~

~~25 if (cursor) {~~

~~26 url.searchParams.set('cursor', cursor);~~

~~27 }~~

~~28 const response = await fetch(url);~~

~~29 if (!response.ok) {~~

~~30 throw new Error(`Failed to fetch MCP registry: ${response.status}`);~~

~~31 }~~

~~32 const data = await response.json();~~

~~33 allServers.push(...data.servers);~~

~~34 cursor = data.metadata?.nextCursor || null;~~

~~35 } while (cursor);~~

~~36 const transformedServers = allServers.map(item => {~~

~~37 const server = item.server;~~

~~38 const meta = item._meta?.['com.anthropic.api/mcp-registry'] || ({});~~

~~39 const worksWith = meta.worksWith || [];~~

~~40 const availability = {~~

~~41 claudeCode: worksWith.includes('claude-code'),~~

~~42 mcpConnector: worksWith.includes('claude-api'),~~

~~43 claudeDesktop: worksWith.includes('claude-desktop')~~

~~44 };~~

~~45 const remotes = server.remotes || [];~~

~~46 const httpRemote = remotes.find(r => r.type === 'streamable-http');~~

~~47 const sseRemote = remotes.find(r => r.type === 'sse');~~

~~48 const preferredRemote = httpRemote || sseRemote;~~

~~49 const remoteUrl = preferredRemote?.url || meta.url;~~

~~50 const remoteType = preferredRemote?.type;~~

~~51 const isTemplatedUrl = remoteUrl?.includes('{');~~

~~52 let setupUrl;~~

~~53 if (isTemplatedUrl && meta.requiredFields) {~~

~~54 const urlField = meta.requiredFields.find(f => f.field === 'url');~~

~~55 setupUrl = urlField?.sourceUrl || meta.documentation;~~

~~56 }~~

~~57 const urls = {};~~

~~58 if (!isTemplatedUrl) {~~

~~59 if (remoteType === 'streamable-http') {~~

~~60 urls.http = remoteUrl;~~

~~61 } else if (remoteType === 'sse') {~~

~~62 urls.sse = remoteUrl;~~

~~63 }~~

~~64 }~~

~~65 let envVars = [];~~

~~66 if (server.packages && server.packages.length > 0) {~~

~~67 const npmPackage = server.packages.find(p => p.registryType === 'npm');~~

~~68 if (npmPackage) {~~

~~69 urls.stdio = `npx -y ${npmPackage.identifier}`;~~

~~70 if (npmPackage.environmentVariables) {~~

~~71 envVars = npmPackage.environmentVariables;~~

~~72 }~~

~~73 }~~

~~74 }~~

~~75 return {~~

~~76 name: meta.displayName || server.title || server.name,~~

~~77 description: meta.oneLiner || server.description,~~

~~78 documentation: meta.documentation,~~

~~79 urls: urls,~~

~~80 envVars: envVars,~~

~~81 availability: availability,~~

~~82 customCommands: meta.claudeCodeCopyText ? {~~

~~83 claudeCode: meta.claudeCodeCopyText~~

~~84 } : undefined,~~

~~85 setupUrl: setupUrl~~

~~86 };~~

~~87 });~~

~~88 setServers(transformedServers);~~

~~89 setError(null);~~

~~90 } catch (err) {~~

~~91 setError(err.message);~~

~~92 console.error('Error fetching MCP registry:', err);~~

~~93 } finally {~~

~~94 setLoading(false);~~

~~95 }~~

~~96 };~~

~~97 fetchServers();~~

~~98 }, []);~~

~~99 const generateClaudeCodeCommand = server => {~~

100 if (server.customCommands && server.customCommands.claudeCode) {

101 return server.customCommands.claudeCode.replace('--transport streamable-http', '--transport http');

102 }

103 const serverSlug = server.name.toLowerCase().replace(/[^a-z0-9]/g, '-');

104 if (server.urls.http) {

105 return `claude mcp add ${serverSlug} --transport http ${server.urls.http}`;

106 }

107 if (server.urls.sse) {

108 return `claude mcp add ${serverSlug} --transport sse ${server.urls.sse}`;

109 }

110 if (server.urls.stdio) {

111 const envFlags = server.envVars && server.envVars.length > 0 ? server.envVars.map(v => `--env ${v.name}=YOUR_${v.name}`).join(' ') : '';

112 const baseCommand = `claude mcp add ${serverSlug} --transport stdio`;

113 return envFlags ? `${baseCommand} ${envFlags} -- ${server.urls.stdio}` : `${baseCommand} -- ${server.urls.stdio}`;

114 }

115 return null;

116 };

117 if (loading) {

118 return <div>Loading MCP servers...</div>;

119 }

120 if (error) {

121 return <div>Error loading MCP servers: {error}</div>;

122 }

123 const filteredServers = servers.filter(server => {

124 if (platform === "claudeCode") {

125 return server.availability.claudeCode;

126 } else if (platform === "mcpConnector") {

127 return server.availability.mcpConnector;

128 } else if (platform === "claudeDesktop") {

129 return server.availability.claudeDesktop;

130 } else if (platform === "all") {

131 return true;

132 } else {

133 throw new Error(`Unknown platform: ${platform}`);

134 }

135 });

136 return <>

137 <style jsx>{`

138 .cards-container {

139 display: grid;

140 gap: 1rem;

141 margin-bottom: 2rem;

142 }

143 .server-card {

144 border: 1px solid var(--border-color, #e5e7eb);

145 border-radius: 6px;

146 padding: 1rem;

147 }

148 .command-row {

149 display: flex;

150 align-items: center;

151 gap: 0.25rem;

152 }

153 .command-row code {

154 font-size: 0.75rem;

155 overflow-x: auto;

156 }

157 `}</style>

~~158~~

159 <div className="cards-container">

160 {filteredServers.map(server => {

161 const claudeCodeCommand = generateClaudeCodeCommand(server);

162 const mcpUrl = server.urls.http || server.urls.sse;

163 const commandToShow = platform === "claudeCode" ? claudeCodeCommand : mcpUrl;

164 return <div key={server.name} className="server-card">

165 <div>

166 {server.documentation ? <a href={server.documentation}>

167 <strong>{server.name}</strong>

168 </a> : <strong>{server.name}</strong>}

169 </div>

~~170~~

171 <p style={{

172 margin: '0.5rem 0',

173 fontSize: '0.9rem'

174 }}>

175 {server.description}

176 </p>

~~177~~

178 {server.setupUrl && <p style={{

179 margin: '0.25rem 0',

180 fontSize: '0.8rem',

181 fontStyle: 'italic',

182 opacity: 0.7

183 }}>

184 Requires user-specific URL.{' '}

185 <a href={server.setupUrl} style={{

186 textDecoration: 'underline'

187 }}>

188 Get your URL here

189 </a>.

190 </p>}

~~191~~

192 {commandToShow && !server.setupUrl && <>

193 <p style={{

194 display: 'block',

195 fontSize: '0.75rem',

196 fontWeight: 500,

197 minWidth: 'fit-content',

198 marginTop: '0.5rem',

199 marginBottom: 0

200 }}>

201 {platform === "claudeCode" ? "Command" : "URL"}

202 </p>

203 <div className="command-row">

204 <code>

205 {commandToShow}

206 </code>

207 </div>

208 </>}

209 </div>;

210 })}

211 </div>

212 </>;

213};

~~214~~

215Claude Code pode se conectar a centenas de ferramentas e fontes de dados externas através do [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction), um padrão de código aberto para integrações de IA com ferramentas. Os servidores MCP dão ao Claude Code acesso às suas ferramentas, bancos de dados e APIs.9Claude Code pode se conectar a centenas de ferramentas e fontes de dados externas através do [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction), um padrão de código aberto para integrações de IA com ferramentas. Os servidores MCP dão ao Claude Code acesso às suas ferramentas, bancos de dados e APIs.

216 10

217Conecte um servidor quando você se encontrar copiando dados para o chat de outra ferramenta, como um rastreador de problemas ou um painel de monitoramento. Uma vez conectado, Claude pode ler e agir nesse sistema diretamente em vez de trabalhar com o que você cola.11Conecte um servidor quando você se encontrar copiando dados para o chat de outra ferramenta, como um rastreador de problemas ou um painel de monitoramento. Uma vez conectado, Claude pode ler e agir nesse sistema diretamente em vez de trabalhar com o que você cola.

227* **Automatizar fluxos de trabalho**: "Crie rascunhos do Gmail convidando esses 10 usuários para uma sessão de feedback sobre o novo recurso."21* **Automatizar fluxos de trabalho**: "Crie rascunhos do Gmail convidando esses 10 usuários para uma sessão de feedback sobre o novo recurso."

228* **Reagir a eventos externos**: Um servidor MCP também pode atuar como um [canal](/pt/channels) que envia mensagens para sua sessão, para que Claude reaja a mensagens do Telegram, chats do Discord ou eventos de webhook enquanto você está ausente.22* **Reagir a eventos externos**: Um servidor MCP também pode atuar como um [canal](/pt/channels) que envia mensagens para sua sessão, para que Claude reaja a mensagens do Telegram, chats do Discord ou eventos de webhook enquanto você está ausente.

229 23

230## Servidores MCP populares24## Encontre e crie servidores MCP

231 25

232Aqui estão alguns servidores MCP comumente usados que você pode conectar ao Claude Code:26Navegue por conectores revisados no [Diretório Anthropic](https://claude.ai/directory). Os conectores do Diretório usam a mesma infraestrutura MCP que Claude Code, então você pode adicionar qualquer servidor remoto listado lá com `claude mcp add`.

233 27

234<Warning>28<Warning>

235 Use servidores MCP de terceiros por sua conta e risco - Anthropic não verificou29 Verifique se você confia em cada servidor antes de conectá-lo. Servidores que buscam conteúdo externo podem expô-lo ao [risco de injeção de prompt](/pt/security#protect-against-prompt-injection).

236 a correção ou segurança de todos esses servidores.

237 Certifique-se de confiar nos servidores MCP que está instalando.

238 Tenha especial cuidado ao usar servidores MCP que possam buscar conteúdo não confiável,

239 pois estes podem expô-lo ao risco de injeção de prompt.

240</Warning>30</Warning>

241 31

242<MCPServersTable platform="claudeCode" />32Para criar seu próprio servidor, consulte o [guia do servidor MCP](https://modelcontextprotocol.io/docs/develop/build-server) para os fundamentos do protocolo e a [documentação de construção de conectores Claude](https://claude.com/docs/connectors/building) para autenticação, testes e envio ao Diretório.

243 33

244<Note>34Você também pode fazer com que Claude crie um servidor para você com o plugin oficial [`mcp-server-dev`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/mcp-server-dev).

245 **Precisa de uma integração específica?** [Encontre centenas de servidores MCP no GitHub](https://github.com/modelcontextprotocol/servers), ou crie o seu próprio usando o [MCP SDK](https://modelcontextprotocol.io/quickstart/server).35

246</Note>36<Steps>

37 <Step title="Instale o plugin">

38 Em uma sessão Claude Code, execute:

40 ```

41 /plugin install mcp-server-dev@claude-plugins-official

42 ```

44 Em seguida, execute `/reload-plugins` para ativá-lo na sessão atual.

45 </Step>

47 <Step title="Execute a skill de construção">

48 ```

49 /mcp-server-dev:build-mcp-server

50 ```

52 Claude pergunta sobre seu caso de uso e cria um servidor HTTP remoto ou servidor stdio local.

53 </Step>

54</Steps>

247 55

248## Instalando servidores MCP56## Instalando servidores MCP

249 57

289 97

290Servidores Stdio são executados como processos locais em sua máquina. Eles são ideais para ferramentas que precisam de acesso direto ao sistema ou scripts personalizados.98Servidores Stdio são executados como processos locais em sua máquina. Eles são ideais para ferramentas que precisam de acesso direto ao sistema ou scripts personalizados.

291 99

100Claude Code define `CLAUDE_PROJECT_DIR` no ambiente do servidor gerado para a raiz do projeto, para que seu servidor possa resolver caminhos relativos ao projeto sem depender do diretório de trabalho. Este é o mesmo diretório que hooks recebem em sua variável `CLAUDE_PROJECT_DIR`. Leia-o de dentro do seu processo de servidor, por exemplo `process.env.CLAUDE_PROJECT_DIR` em Node ou `os.environ["CLAUDE_PROJECT_DIR"]` em Python. Seu servidor também pode chamar a solicitação MCP `roots/list`, que retorna o diretório do qual Claude Code foi iniciado.

101

102Esta variável é definida no ambiente do servidor, não no ambiente do próprio Claude Code, portanto referenciá-la via expansão `${VAR}` em um `.mcp.json` com escopo de projeto ou usuário `command` ou `args` requer um padrão como `${CLAUDE_PROJECT_DIR:-.}`. As configurações MCP fornecidas por plugins substituem `${CLAUDE_PROJECT_DIR}` diretamente e não precisam do padrão.

103

292```bash theme={null}104```bash theme={null}

293# Sintaxe básica105# Sintaxe básica

294claude mcp add [options] <name> -- <command> [args...]106claude mcp add [options] <name> -- <command> [args...]

406**Recursos de MCP de plugin**:218**Recursos de MCP de plugin**:

407 219

408* **Ciclo de vida automático**: Na inicialização da sessão, os servidores para plugins habilitados se conectam automaticamente. Se você habilitar ou desabilitar um plugin durante uma sessão, execute `/reload-plugins` para conectar ou desconectar seus servidores MCP220* **Ciclo de vida automático**: Na inicialização da sessão, os servidores para plugins habilitados se conectam automaticamente. Se você habilitar ou desabilitar um plugin durante uma sessão, execute `/reload-plugins` para conectar ou desconectar seus servidores MCP

409* **Variáveis de ambiente**: Use `${CLAUDE_PLUGIN_ROOT}` para arquivos agrupados do plugin e `${CLAUDE_PLUGIN_DATA}` para [estado persistente](/pt/plugins-reference#persistent-data-directory) que sobrevive a atualizações de plugins221* **Variáveis de ambiente**: Use `${CLAUDE_PLUGIN_ROOT}` para arquivos agrupados do plugin, `${CLAUDE_PLUGIN_DATA}` para [estado persistente](/pt/plugins-reference#persistent-data-directory) que sobrevive a atualizações de plugins, e `${CLAUDE_PROJECT_DIR}` para a raiz do projeto estável

410* **Acesso a variáveis de ambiente do usuário**: Acesso às mesmas variáveis de ambiente que servidores configurados manualmente222* **Acesso a variáveis de ambiente do usuário**: Acesso às mesmas variáveis de ambiente que servidores configurados manualmente

411* **Múltiplos tipos de transporte**: Suporte para transportes stdio, SSE e HTTP (o suporte de transporte pode variar por servidor)223* **Múltiplos tipos de transporte**: Suporte para transportes stdio, SSE e HTTP (o suporte de transporte pode variar por servidor)

412 224

646 458

647Muitos servidores MCP baseados em nuvem exigem autenticação. Claude Code suporta OAuth 2.0 para conexões seguras.459Muitos servidores MCP baseados em nuvem exigem autenticação. Claude Code suporta OAuth 2.0 para conexões seguras.

648 460

461Claude Code marca um servidor remoto como necessitando autenticação quando o servidor responde com `401 Unauthorized` e um cabeçalho `WWW-Authenticate` apontando para seu servidor de autorização. Qualquer servidor personalizado que retorna essa resposta obtém o mesmo fluxo de autenticação `/mcp` que qualquer outro servidor remoto.

462

649<Steps>463<Steps>

650 <Step title="Adicione o servidor que requer autenticação">464 <Step title="Adicione o servidor que requer autenticação">

651 Por exemplo:465 Por exemplo:

1139 953

1140### Configurar pesquisa de ferramentas954### Configurar pesquisa de ferramentas

1141 955

1142Tool Search é ativado por padrão: as ferramentas MCP são adiadas e descobertas sob demanda. Está desabilitado por padrão no Vertex AI, que não aceita o cabeçalho beta de pesquisa de ferramentas, e quando `ANTHROPIC_BASE_URL` aponta para um host que não é de primeira parte, já que a maioria dos proxies não encaminha blocos `tool_reference`. Defina `ENABLE_TOOL_SEARCH` explicitamente para ativar. Este recurso requer modelos que suportam blocos `tool_reference`: Sonnet 4 e posterior, ou Opus 4 e posterior. Os modelos Haiku não suportam pesquisa de ferramentas.956Tool Search é ativado por padrão: as ferramentas MCP são adiadas e descobertas sob demanda. Está desabilitado por padrão no Vertex AI, que não aceita o cabeçalho beta de pesquisa de ferramentas, e quando `ANTHROPIC_BASE_URL` aponta para um host que não é de primeira parte, já que a maioria dos proxies não encaminha blocos `tool_reference`. Se seu proxy encaminha blocos `tool_reference`, defina `ENABLE_TOOL_SEARCH` explicitamente para substituir o fallback. Este recurso requer modelos que suportam blocos `tool_reference`: Sonnet 4 e posterior, ou Opus 4 e posterior. Os modelos Haiku não suportam pesquisa de ferramentas.

1143 957

1144Controle o comportamento da pesquisa de ferramentas com a variável de ambiente `ENABLE_TOOL_SEARCH`:958Controle o comportamento da pesquisa de ferramentas com a variável de ambiente `ENABLE_TOOL_SEARCH`:

1145 959

1146| Valor | Comportamento |960| Valor | Comportamento |

1147| :------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |961| :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

1148| (não definido) | Todas as ferramentas MCP adiadas e carregadas sob demanda. Volta a carregar antecipadamente no Vertex AI ou quando `ANTHROPIC_BASE_URL` é um host que não é de primeira parte |962| (não definido) | Todas as ferramentas MCP adiadas e carregadas sob demanda. Volta a carregar antecipadamente no Vertex AI ou quando `ANTHROPIC_BASE_URL` é um host que não é de primeira parte |

1149| `true` | Todas as ferramentas MCP adiadas, incluindo no Vertex AI e para `ANTHROPIC_BASE_URL` que não é de primeira parte |963| `true` | Todas as ferramentas MCP adiadas. Claude Code envia o cabeçalho beta mesmo no Vertex AI e através de proxies. As solicitações falham se o backend não suporta blocos `tool_reference` |

1150| `auto` | Modo de limite: ferramentas carregam antecipadamente se se encaixarem em 10% da janela de contexto, adiadas caso contrário |964| `auto` | Modo de limite: ferramentas carregam antecipadamente se se encaixarem em 10% da janela de contexto, adiadas caso contrário |

memory.md +17 −1

Details

26| :--------------- | :----------------------------------------------------------------- | :------------------------------------------------------------------------------ |26| :--------------- | :----------------------------------------------------------------- | :------------------------------------------------------------------------------ |

32 32

272 </Step>272 </Step>

273</Steps>273</Steps>

274 274

275A chave `claudeMd` permite que você coloque conteúdo CLAUDE.md gerenciado diretamente dentro de `managed-settings.json` em vez de implantar um arquivo separado.

276

277**Escopo**: cada sessão de Claude Code na máquina, em cada repositório. Para orientação específica do repositório, confirme um CLAUDE.md de projeto em vez disso.

278

279**Precedência**: igual a um arquivo CLAUDE.md gerenciado. Carrega antes de CLAUDE.md de usuário e projeto.

280

281**Onde é honrado**: apenas configurações gerenciadas e de política. Definir `claudeMd` em configurações de usuário, projeto ou local não tem efeito.

282

283O exemplo abaixo adiciona instruções comportamentais diretamente em um arquivo de configurações gerenciadas:

284

285```json theme={null}

286{

287 "claudeMd": "Always run `make lint` before committing.\nNever push directly to main."

288}

289```

290

275Um CLAUDE.md gerenciado e [configurações gerenciadas](/pt/settings#settings-files) servem a propósitos diferentes. Use configurações para imposição técnica e CLAUDE.md para orientação comportamental:291Um CLAUDE.md gerenciado e [configurações gerenciadas](/pt/settings#settings-files) servem a propósitos diferentes. Use configurações para imposição técnica e CLAUDE.md para orientação comportamental:

276 292

277| Preocupação | Configure em |293| Preocupação | Configure em |

monitoring-usage.md +139 −9

Details

166**`claude_code.llm_request`**166**`claude_code.llm_request`**

167 167

169| -------------------------------- | ----------------------------------------------------------------------------------------------------------------- | -------------- |169| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------- |

174| `agent_id` | Identificador do subagente ou colega que emitiu a solicitação. Ausente na sessão principal | |

175| `parent_agent_id` | Identificador do agente que gerou este. Ausente para a sessão principal e para agentes gerados diretamente a partir dela | |

209**`claude_code.tool.blocked_on_user`**211**`claude_code.tool.blocked_on_user`**

210 212

212| ------------- | -------------------------------------------------------------------------------------------------------------- | -------------- |214| ------------- | ------------------------------------------------------------------------------------------------------- | -------------- |

216 218

217**`claude_code.tool.execution`**219**`claude_code.tool.execution`**

218 220

446* `query_source`: Categoria do subsistema que emitiu a solicitação. Um de `"main"`, `"subagent"` ou `"auxiliary"`448* `query_source`: Categoria do subsistema que emitiu a solicitação. Um de `"main"`, `"subagent"` ou `"auxiliary"`

447* `speed`: `"fast"` quando a solicitação usou modo rápido. Ausente caso contrário449* `speed`: `"fast"` quando a solicitação usou modo rápido. Ausente caso contrário

448* `effort`: [Nível de esforço](/pt/model-config#adjust-effort-level) aplicado à solicitação: `"low"`, `"medium"`, `"high"`, `"xhigh"` ou `"max"`. Ausente quando o modelo não suporta esforço.450* `effort`: [Nível de esforço](/pt/model-config#adjust-effort-level) aplicado à solicitação: `"low"`, `"medium"`, `"high"`, `"xhigh"` ou `"max"`. Ausente quando o modelo não suporta esforço.

451* `agent.name`: Tipo de subagente que emitiu a solicitação. Nomes de agente integrados e agentes de plugins do marketplace oficial aparecem verbatim. Outros nomes de agente definidos pelo usuário são substituídos por `"custom"`. Ausente quando a solicitação não foi emitida por um tipo de subagente nomeado.

452* `skill.name`: Skill ativa para a solicitação, definida pela ferramenta Skill, um comando `/` ou herdada por um subagente gerado. Nomes de skill integrados, agrupados, definidos pelo usuário e de plugins do marketplace oficial aparecem verbatim. Nomes de skill de plugin de terceiros são substituídos por `"third-party"`. Ausente quando nenhuma skill está ativa.

453* `plugin.name`: Plugin proprietário quando a skill ativa ou subagente é fornecido por um plugin. Nomes de plugin do marketplace oficial aparecem verbatim. Nomes de plugin de terceiros são substituídos por `"third-party"`. Ausente quando nem a skill nem o subagente têm um plugin proprietário.

454* `marketplace.name`: Marketplace do qual o plugin proprietário foi instalado. Emitido apenas para plugins do marketplace oficial. Ausente caso contrário.

449 455

450#### Contador de token456#### Contador de token

451 457

459* `query_source`: Categoria do subsistema que emitiu a solicitação. Um de `"main"`, `"subagent"` ou `"auxiliary"`465* `query_source`: Categoria do subsistema que emitiu a solicitação. Um de `"main"`, `"subagent"` ou `"auxiliary"`

460* `speed`: `"fast"` quando a solicitação usou modo rápido. Ausente caso contrário466* `speed`: `"fast"` quando a solicitação usou modo rápido. Ausente caso contrário

461* `effort`: [Nível de esforço](/pt/model-config#adjust-effort-level) aplicado à solicitação. Veja [Contador de custo](#contador-de-custo) para detalhes.467* `effort`: [Nível de esforço](/pt/model-config#adjust-effort-level) aplicado à solicitação. Veja [Contador de custo](#contador-de-custo) para detalhes.

468* `agent.name`, `skill.name`, `plugin.name`, `marketplace.name`: Atribuição de skill, plugin e agente para a solicitação. Veja [Contador de custo](#contador-de-custo) para definições e comportamento de redação.

462 469

463#### Contador de decisão da ferramenta de edição de código470#### Contador de decisão da ferramenta de edição de código

464 471

647* `tool_use_id`: Identificador único para esta invocação de ferramenta. Corresponde ao `tool_use_id` passado para hooks, permitindo correlação entre eventos OTel e dados capturados por hook.654* `tool_use_id`: Identificador único para esta invocação de ferramenta. Corresponde ao `tool_use_id` passado para hooks, permitindo correlação entre eventos OTel e dados capturados por hook.

648* `decision`: Ou `"accept"` ou `"reject"`655* `decision`: Ou `"accept"` ou `"reject"`

649* `source`: Onde a decisão veio:656* `source`: Onde a decisão veio:

650 * `"config"`: Decidido automaticamente sem avisar, baseado em configurações de projeto, política gerenciada corporativa, sinalizadores `--allowedTools` ou `--disallowedTools`, o modo de permissão ativo ou porque a ferramenta é inerentemente segura.657 * `"config"`: Decidido automaticamente sem avisar, baseado em configurações de projeto, regras de permissão nas configurações pessoais do usuário, política gerenciada corporativa, sinalizadores `--allowedTools` ou `--disallowedTools`, o modo de permissão ativo, uma concessão com escopo de sessão de um prompt anterior na mesma sessão CLI interativa, ou porque a ferramenta é inerentemente segura. O evento não indica qual dessas fontes correspondeu.

651 * `"hook"`: Um hook `PreToolUse` ou `PermissionRequest` retornou a decisão.658 * `"hook"`: Um hook `PreToolUse` ou `PermissionRequest` retornou a decisão.

652 * `"user_permanent"`: Emitido quando o usuário escolheu "Sempre permitir" quando solicitado, salvando uma regra em suas configurações pessoais. Também emitido para chamadas posteriores que correspondem a essa regra salva. Tratado como uma aceitação.659 * `"user_permanent"`: Emitido quando o usuário escolheu "Sim, e não pergunte novamente para ..." em um aviso de permissão, que salva uma regra de permissão em suas configurações pessoais. Na CLI interativa isso é emitido apenas para essa escolha em si; chamadas posteriores que correspondem à regra salva emitem `"config"` em vez disso. No Agent SDK ou sessões não-interativas `-p`, tanto a escolha inicial quanto correspondências de regra posteriores emitem `"user_permanent"`. Tratado como uma aceitação.

653 * `"user_temporary"`: Emitido quando o usuário escolheu "Sim" ou "Sim, para esta sessão" quando solicitado, sem salvar uma regra. Também emitido para chamadas posteriores na mesma sessão que correspondem a essa permissão com escopo de sessão. Tratado como uma aceitação.660 * `"user_temporary"`: Emitido quando o usuário escolheu "Sim" em um aviso de permissão para uma aprovação única, ou escolheu uma das opções "... durante esta sessão" em um aviso de edição ou leitura de arquivo. Na CLI interativa isso é emitido apenas para a escolha em si; chamadas posteriores permitidas por essa concessão com escopo de sessão emitem `"config"` em vez disso. No Agent SDK ou sessões não-interativas `-p`, tanto a escolha quanto correspondências posteriores emitem `"user_temporary"`. Tratado como uma aceitação.

654 * `"user_abort"`: Emitido quando o usuário descartou o aviso de permissão sem responder. Tratado como uma rejeição.661 * `"user_abort"`: Emitido quando o usuário descartou o aviso de permissão sem responder. Tratado como uma rejeição.

655 * `"user_reject"`: Emitido quando o usuário escolheu "Não" quando solicitado, ou uma chamada correspondeu a uma regra de negação em suas configurações pessoais. Tratado como uma rejeição.662 * `"user_reject"`: Emitido quando o usuário escolheu "Não" quando solicitado, ou uma chamada correspondeu a uma regra de negação em suas configurações pessoais. Tratado como uma rejeição.

656 663

657#### Evento de modo de permissão alterado664#### Evento de modo de permissão alterado

658 665

659Registrado quando o modo de permissão muda, por exemplo de ciclagem Shift+Tab, saída do modo plano ou verificação de gate de modo automático.666Registrado quando o modo de permissão muda, por exemplo de ciclagem Shift+Tab, saída do Plan Mode ou verificação de gate de modo automático.

660 667

661**Nome do Evento**: `claude_code.permission_mode_changed`668**Nome do Evento**: `claude_code.permission_mode_changed`

662 669

741* `plugin.version`: Versão do plugin quando declarada na entrada do marketplace. Para marketplaces de terceiros isso é incluído apenas quando `OTEL_LOG_TOOL_DETAILS=1`748* `plugin.version`: Versão do plugin quando declarada na entrada do marketplace. Para marketplaces de terceiros isso é incluído apenas quando `OTEL_LOG_TOOL_DETAILS=1`

742* `marketplace.name`: Marketplace do qual o plugin foi instalado. Para marketplaces de terceiros isso é incluído apenas quando `OTEL_LOG_TOOL_DETAILS=1`749* `marketplace.name`: Marketplace do qual o plugin foi instalado. Para marketplaces de terceiros isso é incluído apenas quando `OTEL_LOG_TOOL_DETAILS=1`

743 750

751#### Evento de plugin carregado

752

753Registrado uma vez por plugin ativado no início da sessão. Use este evento para inventariar quais plugins estão ativos em toda a sua frota, como complemento ao `plugin_installed` que registra a ação de instalação em si.

754

755**Nome do Evento**: `claude_code.plugin_loaded`

756

757**Atributos**:

758

759* Todos os [atributos padrão](#atributos-padrão)

760* `event.name`: `"plugin_loaded"`

761* `event.timestamp`: Timestamp ISO 8601

762* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão

763* `plugin.name`: nome do plugin. Para plugins fora do marketplace oficial e pacote integrado o valor é `"third-party"` a menos que `OTEL_LOG_TOOL_DETAILS=1`

764* `marketplace.name`: marketplace do qual o plugin foi instalado, quando conhecido. Reduzido para `"third-party"` sob a mesma condição que `plugin.name`

765* `plugin.version`: versão do manifesto do plugin. Incluído apenas quando o nome não é reduzido e o manifesto declara uma versão

766* `plugin.scope`: categoria de proveniência para o plugin: `"official"`, `"org"`, `"user-local"` ou `"default-bundle"`

767* `enabled_via`: como o plugin veio a ser ativado: `"default-enable"`, `"org-policy"`, `"seed-mount"` ou `"user-install"`

768* `plugin_id_hash`: hash determinístico do nome do plugin e marketplace, enviado apenas para seu exportador configurado. Permite contar quantos plugins de terceiros distintos são carregados em toda a sua frota sem registrar seus nomes

769* `has_hooks`: se o plugin contribui hooks

770* `has_mcp`: se o plugin contribui servidores MCP

771* `skill_path_count`: número de diretórios de skill que o plugin declara

772* `command_path_count`: número de diretórios de comando que o plugin declara

773* `agent_path_count`: número de diretórios de agente que o plugin declara

774

744#### Evento de skill ativado775#### Evento de skill ativado

745 776

746Registrado quando uma skill é invocada, seja Claude a chama através da ferramenta Skill ou você a executa como um comando `/`.777Registrado quando uma skill é invocada, seja Claude a chama através da ferramenta Skill ou você a executa como um comando `/`.

793* `total_retry_duration_ms`: Tempo total de parede em todas as tentativas824* `total_retry_duration_ms`: Tempo total de parede em todas as tentativas

794* `speed`: `"fast"` ou `"normal"`825* `speed`: `"fast"` ou `"normal"`

795 826

827#### Evento de hook registrado

828

829Registrado uma vez por hook configurado no início da sessão. Use este evento para inventariar quais hooks estão ativos em toda a sua frota, como complemento aos eventos `hook_execution_start` e `hook_execution_complete` por execução.

830

831**Nome do Evento**: `claude_code.hook_registered`

832

833**Atributos**:

834

835* Todos os [atributos padrão](#atributos-padrão)

836* `event.name`: `"hook_registered"`

837* `event.timestamp`: Timestamp ISO 8601

838* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão

839* `hook_event`: tipo de evento de hook, como `"PreToolUse"` ou `"PostToolUse"`

840* `hook_type`: tipo de implementação de hook: `"command"`, `"prompt"`, `"mcp_tool"`, `"http"` ou `"agent"`

841* `hook_source`: onde o hook é definido: `"userSettings"`, `"projectSettings"`, `"localSettings"`, `"flagSettings"`, `"policySettings"` ou `"pluginHook"`

842* `hook_matcher` (quando `OTEL_LOG_TOOL_DETAILS=1`): a string matcher da configuração do hook, quando uma está definida

843* `plugin.name` (quando `hook_source` é `"pluginHook"`): nome do plugin contribuidor. Para plugins fora do marketplace oficial e pacote integrado o valor é `"third-party"` a menos que `OTEL_LOG_TOOL_DETAILS=1`

844* `plugin_id_hash` (quando `hook_source` é `"pluginHook"`): hash determinístico do nome do plugin e marketplace, enviado apenas para seu exportador configurado. Permite contar plugins contribuidores distintos sem registrar seus nomes

845

796#### Evento de início de execução de hook846#### Evento de início de execução de hook

797 847

798Registrado quando um ou mais hooks começam a executar para um evento de hook.848Registrado quando um ou mais hooks começam a executar para um evento de hook.

855* `post_tokens`: Contagem aproximada de tokens após compactação905* `post_tokens`: Contagem aproximada de tokens após compactação

856* `error`: Mensagem de erro quando a compactação falhou906* `error`: Mensagem de erro quando a compactação falhou

857 907

908#### Evento de pesquisa de feedback

909

910Registrado quando uma pesquisa de qualidade de sessão é mostrada ou respondida. Veja [Pesquisas de qualidade de sessão](/pt/data-usage#session-quality-surveys) para o que as pesquisas coletam e como controlá-las.

911

912**Nome do Evento**: `claude_code.feedback_survey`

913

914**Atributos**:

915

916* Todos os [atributos padrão](#atributos-padrão)

917* `event.name`: `"feedback_survey"`

918* `event.timestamp`: Timestamp ISO 8601

919* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão

920* `event_type`: Evento do ciclo de vida da pesquisa, por exemplo `"appeared"`, `"responded"` ou `"transcript_prompt_appeared"`

921* `appearance_id`: ID único vinculando os eventos emitidos para uma instância de pesquisa

922* `survey_type`: Qual pesquisa produziu o evento. `"session"` é o prompt de classificação "Como Claude está se saindo?"

923* `response`: A seleção do usuário em eventos `responded`

924* `enabled_via_override`: `true` quando [`CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL`](/pt/env-vars) está definido. Emitido como um booleano, não uma string. Presente em eventos de pesquisa `session`. Filtre neste atributo para confirmar que a substituição é aplicada em toda a frota

925

858## Interpretar dados de métricas e eventos926## Interpretar dados de métricas e eventos

859 927

860As métricas e eventos exportados suportam uma gama de análises:928As métricas e eventos exportados suportam uma gama de análises:

862### Monitoramento de uso930### Monitoramento de uso

863 931

864| Métrica | Oportunidade de Análise |932| Métrica | Oportunidade de Análise |

865| ------------------------------------------------------------- | ------------------------------------------------------------- |933| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |

869| `claude_code.commit.count` & `claude_code.pull_request.count` | Entender o impacto nos fluxos de trabalho de desenvolvimento |937| `claude_code.commit.count` & `claude_code.pull_request.count` | Entender o impacto nos fluxos de trabalho de desenvolvimento |

874 942

875* Rastreamento de tendências de uso entre equipes ou indivíduos943* Rastreamento de tendências de uso entre equipes ou indivíduos

876* Identificação de sessões de alto uso para otimização944* Identificação de sessões de alto uso para otimização

945* Atribuição de gastos a skills, plugins ou tipos de subagente específicos via atributos `skill.name`, `plugin.name` e `agent.name`

877 946

878<Note>947<Note>

879 As métricas de custo são aproximações. Para dados de faturamento oficiais, consulte seu provedor de API (Claude Console, Amazon Bedrock ou Google Cloud Vertex).948 As métricas de custo são aproximações. Para dados de faturamento oficiais, consulte seu provedor de API (Claude Console, Amazon Bedrock ou Google Cloud Vertex).

910 979

911**Monitoramento de Desempenho**: rastreie durações de solicitações de API e tempos de execução de ferramentas para identificar gargalos de desempenho.980**Monitoramento de Desempenho**: rastreie durações de solicitações de API e tempos de execução de ferramentas para identificar gargalos de desempenho.

912 981

982## Eventos de auditoria de segurança

983

984Os eventos OpenTelemetry são a fonte de dados de auditoria para atividade do Claude Code. Cada evento carrega atributos de identidade que vinculam chamadas de ferramenta, atividade MCP e decisões de permissão de volta ao usuário que as acionou, e o exportador de logs OTLP pode entregar esses eventos a qualquer plataforma Security Information and Event Management (SIEM) com um receptor OTLP ou a um OpenTelemetry Collector que encaminha para seu SIEM.

985

986### Atribuir ações a usuários

987

988Os [atributos padrão](#atributos-padrão) em cada evento incluem a identidade do usuário autenticado: `user.email`, `user.account_uuid`, `user.account_id` e `organization.id` quando conectado com uma conta Claude, mais o `user.id` com escopo de instalação e o `session.id` por sessão.

989

990Chamadas de ferramenta MCP, comandos Bash e edições de arquivo são, portanto, atribuídas ao desenvolvedor que iniciou a sessão. Claude Code não atua sob uma conta de serviço separada; a identidade registrada em cada evento é a própria conta Claude do desenvolvedor.

991

992Quando Claude Code autentica com uma chave de API direta, ou contra Bedrock, Vertex AI ou Microsoft Foundry, não há conta Claude na sessão e apenas `user.id` e `session.id` são preenchidos. Nessas implantações, anexe identidade do usuário você mesmo com `OTEL_RESOURCE_ATTRIBUTES`, definido por usuário através do arquivo de [configurações gerenciadas](#configuração-do-administrador) ou um wrapper de inicialização:

993

994```bash theme={null}

995export OTEL_RESOURCE_ATTRIBUTES="enduser.id=jdoe@example.com,enduser.directory_id=S-1-5-21-..."

996```

997

998### Auditoria de atividade MCP

999

1000Para capturar atividade do servidor MCP com detalhe completo de chamada, ative o exportador de logs e defina `OTEL_LOG_TOOL_DETAILS=1`. Cada operação MCP então produz eventos estruturados que carregam o nome do servidor, nome da ferramenta e argumentos de chamada junto com os atributos de identidade padrão:

1001

1002| Evento | O que registra para MCP |

1003| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1004| `mcp_server_connection` | Conexão do servidor, desconexão e falha de conexão com `server_name`, `transport_type`, `server_scope` e detalhe de erro |

1005| `tool_result` | Cada chamada de ferramenta MCP com `tool_name` e `mcp_server_scope`, uma carga útil `tool_parameters` contendo `mcp_server_name` e `mcp_tool_name`, e uma carga útil `tool_input` contendo os argumentos de chamada |

1006| `tool_decision` | Se a chamada foi permitida ou negada, e se a decisão veio de config, um hook ou o usuário |

1007

1008Sem `OTEL_LOG_TOOL_DETAILS`, eventos `tool_result` ainda carregam `tool_name` e `mcp_server_scope` mas omitem a divisão `mcp_server_name`/`mcp_tool_name` e os argumentos, e eventos `mcp_server_connection` omitem `server_name` e a mensagem de erro.

1009

1010### Mapear questões de segurança para eventos

1011

1012Ao construir regras de detecção, procure o sinal que você deseja monitorar e consulte seu backend para o evento correspondente e atributos:

1013

1014| Sinal | Evento | Atributos-chave |

1015| ---------------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------ |

1016| Chamada de ferramenta permitida ou negada, e por quê | `tool_decision` | `decision`, `source`, `tool_name` |

1017| Escalação de modo de permissão | `permission_mode_changed` | `from_mode`, `to_mode`, `trigger` |

1018| Hook de política bloqueou uma ação | `hook_execution_complete` | `hook_event`, `num_blocking` |

1019| Login, logout e falha de autenticação | `auth` | `action`, `success`, `error_category` |

1020| Conexão do servidor MCP ou falha | `mcp_server_connection` | `status`, `server_name`, `error_code` |

1021| Plugin instalado e sua origem | `plugin_installed` | `plugin.name`, `marketplace.name`, `marketplace.is_official` |

1022| Comandos executados e arquivos tocados | `tool_result` com `OTEL_LOG_TOOL_DETAILS=1` | `tool_parameters`, `tool_input` |

1023

1024Claude Code emite apenas o fluxo de eventos bruto. Detecção de anomalias, linha de base, correlação entre sessões e alertas são responsabilidade do seu SIEM ou backend de observabilidade.

1025

1026### Enviar eventos para um SIEM

1027

1028Aponte `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` para o receptor OTLP do seu SIEM, ou para um OpenTelemetry Collector que encaminha para a API de ingestão nativa do seu SIEM. O seguinte exemplo de configurações gerenciadas exporta apenas eventos, com detalhe completo de ferramenta ativado para auditoria MCP e Bash:

1029

1030```json theme={null}

1031{

1032 "env": {

1033 "CLAUDE_CODE_ENABLE_TELEMETRY": "1",

1034 "OTEL_LOGS_EXPORTER": "otlp",

1035 "OTEL_LOG_TOOL_DETAILS": "1",

1036 "OTEL_EXPORTER_OTLP_LOGS_PROTOCOL": "http/protobuf",

1037 "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT": "https://siem.example.com:4318/v1/logs",

1038 "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer your-siem-token"

1039 }

1040}

1041```

1042

913## Considerações de backend1043## Considerações de backend

914 1044

915Sua escolha de backends de métricas, logs e rastreamentos determina os tipos de análises que você pode realizar:1045Sua escolha de backends de métricas, logs e rastreamentos determina os tipos de análises que você pode realizar:

output-styles.md +7 −3

Details

14 14

15O estilo de saída **Default** do Claude Code é o prompt do sistema existente, projetado para ajudá-lo a completar tarefas de engenharia de software com eficiência.15O estilo de saída **Default** do Claude Code é o prompt do sistema existente, projetado para ajudá-lo a completar tarefas de engenharia de software com eficiência.

16 16

~~17Existem dois estilos de saída integrados adicionais focados em ensiná-lo sobre a base de código e como Claude opera:~~17Existem três estilos de saída integrados adicionais:

19* **Proactive**: Claude executa imediatamente, faz suposições razoáveis em vez de pausar para decisões rotineiras e prefere ação ao planejamento. Isso aplica a mesma orientação que [modo automático](/pt/permission-modes#eliminate-prompts-with-auto-mode) sem alterar seu modo de permissão, portanto você ainda vê prompts de permissão antes das ferramentas serem executadas.

18 20

19* **Explanatory**: Fornece "Insights" educacionais entre ajudá-lo a completar tarefas de engenharia de software. Ajuda você a entender as escolhas de implementação e padrões da base de código.21* **Explanatory**: Fornece "Insights" educacionais entre ajudá-lo a completar tarefas de engenharia de software. Ajuda você a entender as escolhas de implementação e padrões da base de código.

20 22

88 90

89### Output Styles vs. CLAUDE.md vs. --append-system-prompt91### Output Styles vs. CLAUDE.md vs. --append-system-prompt

90 92

91Os estilos de saída "desligam" completamente as partes do prompt do sistema padrão do Claude Code específicas para engenharia de software. Nem CLAUDE.md nem `--append-system-prompt` editam o prompt do sistema padrão do Claude Code. CLAUDE.md adiciona o conteúdo como uma mensagem do usuário *seguindo* o prompt do sistema padrão do Claude Code. `--append-system-prompt` anexa o conteúdo ao prompt do sistema.93Escolha com base em se Claude deve parar de agir como um assistente de codificação ou manter seu papel padrão e aprender mais. Os estilos de saída substituem as partes de engenharia de software do prompt do sistema do Claude Code pela sua própria função e voz, então use um quando Claude deve adotar uma identidade diferente, como um editor de redação ou um assistente de análise de dados. CLAUDE.md e `--append-system-prompt` mantêm a identidade padrão do Claude Code e adicionam a ela, então use-os quando Claude deve permanecer um assistente de codificação que também segue suas convenções de projeto ou instruções extras.

95Os mecanismos também diferem. Os estilos de saída editam o prompt do sistema diretamente. CLAUDE.md adiciona seu conteúdo como uma mensagem do usuário após o prompt do sistema. `--append-system-prompt` anexa conteúdo ao final do prompt do sistema sem remover nada.

92 96

93### Output Styles vs. [Agents](/pt/sub-agents)97### Output Styles vs. [Agents](/pt/sub-agents)

94 98

95Os estilos de saída afetam diretamente o loop do agente principal e apenas afetam o prompt do sistema. Os agentes são invocados para lidar com tarefas específicas e podem incluir configurações adicionais como o modelo a usar, as ferramentas disponíveis e algum contexto sobre quando usar o agente.99Use um estilo de saída para alterar como a conversa principal responde em cada sessão. Use um [subagente](/pt/sub-agents) quando você quiser um auxiliar com escopo separado para o qual a conversa principal delega. Os estilos de saída afetam apenas o prompt do sistema do loop do agente principal. Os agentes lidam com tarefas específicas e podem ter seu próprio modelo, ferramentas e contexto sobre quando invocá-los.

96 100

97### Output Styles vs. [Skills](/pt/skills)101### Output Styles vs. [Skills](/pt/skills)

98 102

permission-modes.md +31 −3

Details

116claude --permission-mode acceptEdits116claude --permission-mode acceptEdits

117```117```

118 118

119## Analyze before you edit with plan mode119## Analise antes de editar com plan mode

120 120

121Plan mode diz a Claude para pesquisar e propor alterações sem fazê-las. Claude lê arquivos, executa comandos shell para explorar e escreve um plano, mas não edita seu código-fonte. Prompts de permissão ainda se aplicam da mesma forma que o modo padrão.121Plan mode diz a Claude para pesquisar e propor alterações sem fazê-las. Claude lê arquivos, executa comandos shell para explorar e escreve um plano, mas não edita seu código-fonte. Prompts de permissão ainda se aplicam da mesma forma que o modo padrão.

122 122

128 128

129Pressione `Shift+Tab` novamente para sair do plan mode sem aprovar um plano.129Pressione `Shift+Tab` novamente para sair do plan mode sem aprovar um plano.

130 130

131### Revise e aprove um plano

132

131Quando o plano está pronto, Claude o apresenta e pergunta como proceder. A partir desse prompt você pode:133Quando o plano está pronto, Claude o apresenta e pergunta como proceder. A partir desse prompt você pode:

132 134

133* Aprovar e iniciar em auto mode135* Aprovar e iniciar em auto mode

136* Continuar planejando com feedback138* Continuar planejando com feedback

137* Refinar com [Ultraplan](/pt/ultraplan) para revisão baseada em navegador139* Refinar com [Ultraplan](/pt/ultraplan) para revisão baseada em navegador

138 140

139Cada opção de aprovação também oferece limpar o contexto de planejamento primeiro.141Aprovando um plano sai do plan mode e muda a sessão para o modo de permissão que cada opção de aprovação descreve, então Claude começa a editar. Para planejar novamente, volte ao plan mode com `Shift+Tab`, ou prefixe seu próximo prompt com `/plan`.

142

143Pressione `Ctrl+G` para abrir o plano proposto no seu editor de texto padrão e editá-lo diretamente antes de Claude prosseguir. Quando [`showClearContextOnPlanAccept`](/pt/settings#available-settings) está ativado, cada opção de aprovação também oferece limpar o contexto de planejamento primeiro.

144

145Aceitar um plano também nomeia a sessão a partir do conteúdo do plano automaticamente, a menos que você já tenha definido um nome com `--name` ou `/rename`.

146

147### Defina plan mode como o padrão

148

149Para fazer do plan mode o padrão para um projeto, defina `defaultMode` em `.claude/settings.json`:

150

151```json theme={null}

152{

153 "permissions": {

154 "defaultMode": "plan"

155 }

156}

157```

140 158

141## Elimine prompts com auto mode159## Elimine prompts com auto mode

142 160

146 164

147Auto mode permite que Claude execute sem prompts de permissão. Um modelo classificador separado revisa ações antes de serem executadas, bloqueando qualquer coisa que escale além de sua solicitação, direcione infraestrutura não reconhecida ou pareça impulsionada por conteúdo hostil que Claude leu.165Auto mode permite que Claude execute sem prompts de permissão. Um modelo classificador separado revisa ações antes de serem executadas, bloqueando qualquer coisa que escale além de sua solicitação, direcione infraestrutura não reconhecida ou pareça impulsionada por conteúdo hostil que Claude leu.

148 166

167Auto mode também instrui Claude a executar imediatamente e minimizar perguntas de esclarecimento. Para obter esse comportamento mantendo prompts de permissão, defina o [estilo de saída proativo](/pt/output-styles) em vez disso.

168

149<Warning>169<Warning>

150 Auto mode é uma visualização de pesquisa. Reduz prompts mas não garante segurança. Use-o para tarefas onde você confia na direção geral, não como substituto para revisão em operações sensíveis.170 Auto mode é uma visualização de pesquisa. Reduz prompts mas não garante segurança. Use-o para tarefas onde você confia na direção geral, não como substituto para revisão em operações sensíveis.

151</Warning>171</Warning>

246 266

247## Pule todas as verificações com o modo bypassPermissions267## Pule todas as verificações com o modo bypassPermissions

248 268

249O modo `bypassPermissions` desabilita prompts de permissão e verificações de segurança para que chamadas de ferramenta sejam executadas imediatamente. A partir da v2.1.126, isso inclui escritas em [caminhos protegidos](#protected-paths), que versões anteriores ainda solicitavam. Remoções direcionadas à raiz do sistema de arquivos ou diretório home, como `rm -rf /` e `rm -rf ~`, ainda solicitam como um disjuntor contra erro do modelo. Use este modo apenas em ambientes isolados como contêineres, VMs ou devcontainers sem acesso à internet, onde Claude Code não pode danificar seu sistema host.269O modo `bypassPermissions` desabilita prompts de permissão e verificações de segurança para que chamadas de ferramenta sejam executadas imediatamente. A partir da v2.1.126, isso inclui escritas em [caminhos protegidos](#protected-paths), que versões anteriores ainda solicitavam. Remoções direcionadas à raiz do sistema de arquivos ou diretório home, como `rm -rf /` e `rm -rf ~`, ainda solicitam como um disjuntor contra erro do modelo. Use este modo apenas em ambientes isolados como contêineres, VMs ou dev containers sem acesso à internet, onde Claude Code não pode danificar seu sistema host.

250 270

251Você não pode entrar em `bypassPermissions` a partir de uma sessão que foi iniciada sem uma das flags de habilitação; reinicie com uma para habilitá-lo:271Você não pode entrar em `bypassPermissions` a partir de uma sessão que foi iniciada sem uma das flags de habilitação; reinicie com uma para habilitá-lo:

252 272

256 276

257A flag `--dangerously-skip-permissions` é equivalente.277A flag `--dangerously-skip-permissions` é equivalente.

258 278

279No Linux e macOS, Claude Code recusa iniciar neste modo quando executado como root ou sob `sudo`:

280

281```text theme={null}

282--dangerously-skip-permissions cannot be used with root/sudo privileges for security reasons

283```

284

285A verificação é ignorada automaticamente dentro de uma sandbox reconhecida. Para executar autonomamente em um contêiner, use a configuração [dev container](/pt/devcontainer), que executa Claude Code como um usuário não-root.

286

259<Warning>287<Warning>

260 `bypassPermissions` não oferece proteção contra injeção de prompt ou ações não intencionais. Para verificações de segurança de fundo sem prompts, use [auto mode](#eliminate-prompts-with-auto-mode) em vez disso. Administradores podem bloquear este modo definindo `permissions.disableBypassPermissionsMode` para `"disable"` em [configurações gerenciadas](/pt/permissions#managed-settings).288 `bypassPermissions` não oferece proteção contra injeção de prompt ou ações não intencionais. Para verificações de segurança de fundo sem prompts, use [auto mode](#eliminate-prompts-with-auto-mode) em vez disso. Administradores podem bloquear este modo definindo `permissions.disableBypassPermissionsMode` para `"disable"` em [configurações gerenciadas](/pt/permissions#managed-settings).

261</Warning>289</Warning>

permissions.md +5 −1

Details

28 28

29As regras são avaliadas em ordem: **deny -> ask -> allow**. A primeira regra correspondente vence, portanto as regras deny sempre têm precedência.29As regras são avaliadas em ordem: **deny -> ask -> allow**. A primeira regra correspondente vence, portanto as regras deny sempre têm precedência.

30 30

31<Note>

32 As regras de permissão são aplicadas pelo Claude Code, não pelo modelo. As instruções em seu prompt ou `CLAUDE.md` moldam o que Claude tenta fazer, mas não alteram o que Claude Code permite. Para conceder ou revogar acesso, use `/permissions`, as regras descritas aqui, um [modo de permissão](/pt/permission-modes), ou um [hook PreToolUse](#extend-permissions-with-hooks).

33</Note>

31## Modos de permissão35## Modos de permissão

32 36

33Claude Code suporta vários modos de permissão que controlam como as ferramentas são aprovadas. Veja [Permission modes](/pt/permission-modes) para quando usar cada um. Defina o `defaultMode` em seus [arquivos de configuração](/pt/settings#settings-files):37Claude Code suporta vários modos de permissão que controlam como as ferramentas são aprovadas. Veja [Permission modes](/pt/permission-modes) para quando usar cada um. Defina o `defaultMode` em seus [arquivos de configuração](/pt/settings#settings-files):

153 157

154 * **Restringir ferramentas de rede Bash**: use regras deny para bloquear `curl`, `wget` e comandos similares, depois use a ferramenta WebFetch com permissão `WebFetch(domain:github.com)` para domínios permitidos158 * **Restringir ferramentas de rede Bash**: use regras deny para bloquear `curl`, `wget` e comandos similares, depois use a ferramenta WebFetch com permissão `WebFetch(domain:github.com)` para domínios permitidos

155 * **Use hooks PreToolUse**: implemente um hook que valida URLs em comandos Bash e bloqueia domínios não permitidos159 * **Use hooks PreToolUse**: implemente um hook que valida URLs em comandos Bash e bloqueia domínios não permitidos

156 * Instruir Claude Code sobre seus padrões curl permitidos via CLAUDE.md160 * **Adicione orientação CLAUDE.md**: descreva seus padrões curl permitidos em `CLAUDE.md`. Isso molda o que Claude tenta mas não impõe um limite, portanto combine com uma das opções acima

157 161

158 Observe que usar WebFetch sozinho não impede acesso à rede. Se Bash for permitido, Claude ainda pode usar `curl`, `wget` ou outras ferramentas para alcançar qualquer URL.162 Observe que usar WebFetch sozinho não impede acesso à rede. Se Bash for permitido, Claude ainda pode usar `curl`, `wget` ou outras ferramentas para alcançar qualquer URL.

159</Warning>163</Warning>

plugins.md +6 −0

Details

299claude --plugin-dir ./my-plugin299claude --plugin-dir ./my-plugin

300```300```

301 301

302A flag também aceita um arquivo `.zip` do diretório do plugin, que requer Claude Code v2.1.128 ou posterior.

303

304```bash theme={null}

305claude --plugin-dir ./my-plugin.zip

306```

307

302Quando um plugin `--plugin-dir` tem o mesmo nome que um plugin marketplace instalado, a cópia local tem precedência para essa sessão. Isso permite que você teste mudanças em um plugin que você já tem instalado sem desinstalá-lo primeiro. Plugins marketplace forçadamente habilitados por configurações gerenciadas são a única exceção e não podem ser substituídos.308Quando um plugin `--plugin-dir` tem o mesmo nome que um plugin marketplace instalado, a cópia local tem precedência para essa sessão. Isso permite que você teste mudanças em um plugin que você já tem instalado sem desinstalá-lo primeiro. Plugins marketplace forçadamente habilitados por configurações gerenciadas são a única exceção e não podem ser substituídos.

303 309

304Conforme você faz mudanças no seu plugin, execute `/reload-plugins` para pegar as atualizações sem reiniciar. Isso recarrega plugins, skills, agents, hooks, MCP servers do plugin e LSP servers do plugin. Teste seus componentes de plugin:310Conforme você faz mudanças no seu plugin, execute `/reload-plugins` para pegar as atualizações sem reiniciar. Isso recarrega plugins, skills, agents, hooks, MCP servers do plugin e LSP servers do plugin. Teste seus componentes de plugin:

plugins-reference.md +70 −10

Details

97 "hooks": [97 "hooks": [

98 {98 {

99 "type": "command",99 "type": "command",

100 "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format-code.sh"100 "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/format-code.sh"

101 }101 }

102 ]102 ]

103 }103 }

289[289[

290 {290 {

291 "name": "deploy-status",291 "name": "deploy-status",

292 "command": "${CLAUDE_PLUGIN_ROOT}/scripts/poll-deploy.sh ${user_config.api_endpoint}",292 "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh ${user_config.api_endpoint}",

293 "description": "Mudanças de status de implantação"293 "description": "Mudanças de status de implantação"

294 },294 },

295 {295 {

317| :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |317| :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

318| `when` | Controla quando o monitor inicia. `"always"` o inicia no início da sessão e no recarregamento do plugin, e é o padrão. `"on-skill-invoke:<skill-name>"` o inicia na primeira vez que a skill nomeada neste plugin é despachada |318| `when` | Controla quando o monitor inicia. `"always"` o inicia no início da sessão e no recarregamento do plugin, e é o padrão. `"on-skill-invoke:<skill-name>"` o inicia na primeira vez que a skill nomeada neste plugin é despachada |

319 319

320O valor `command` suporta as mesmas [substituições de variáveis](#environment-variables) que configurações de servidor MCP e LSP: `${CLAUDE_PLUGIN_ROOT}`, `${CLAUDE_PLUGIN_DATA}`, `${user_config.*}` e qualquer `${ENV_VAR}` do ambiente. Prefixe o comando com `cd "${CLAUDE_PLUGIN_ROOT}" && ` se o script precisa ser executado do próprio diretório do plugin.320O valor `command` suporta as mesmas [substituições de variáveis](#environment-variables) que configurações de servidor MCP e LSP: `${CLAUDE_PLUGIN_ROOT}`, `${CLAUDE_PLUGIN_DATA}`, `${CLAUDE_PROJECT_DIR}`, `${user_config.*}` e qualquer `${ENV_VAR}` do ambiente. Prefixe o comando com `cd "${CLAUDE_PLUGIN_ROOT}" && ` se o script precisa ser executado do próprio diretório do plugin.

321 321

322Desabilitar um plugin no meio da sessão não para monitors que já estão em execução. Eles param quando a sessão termina.322Desabilitar um plugin no meio da sessão não para monitors que já estão em execução. Eles param quando a sessão termina.

323 323

540 540

541### Variáveis de ambiente541### Variáveis de ambiente

542 542

543Claude Code fornece duas variáveis para referenciar caminhos de plugin. Ambas são substituídas inline em qualquer lugar que apareçam em conteúdo de skill, conteúdo de agent, comandos de hook, comandos de monitor e configurações de servidor MCP ou LSP. Ambas também são exportadas como variáveis de ambiente para processos de hook e subprocessos de servidor MCP ou LSP.543Claude Code fornece três variáveis para referenciar caminhos. Todas são substituídas inline em qualquer lugar que apareçam em conteúdo de skill, conteúdo de agent, comandos de hook, comandos de monitor e configurações de servidor MCP ou LSP. Todas também são exportadas como variáveis de ambiente para processos de hook e subprocessos de servidor MCP ou LSP.

544 544

545**`${CLAUDE_PLUGIN_ROOT}`**: o caminho absoluto para o diretório de instalação do seu plugin. Use isso para referenciar scripts, binários e arquivos de configuração agrupados com o plugin. Este caminho muda quando o plugin é atualizado. O diretório da versão anterior permanece no disco por aproximadamente sete dias após uma atualização antes da limpeza, mas trate-o como efêmero e não escreva estado aqui.545**`${CLAUDE_PLUGIN_ROOT}`**: o caminho absoluto para o diretório de instalação do seu plugin. Use isso para referenciar scripts, binários e arquivos de configuração agrupados com o plugin. Em comandos de hook, use [forma exec](/pt/hooks#exec-form-and-shell-form) com `args` para que o caminho seja passado como um argumento com nenhuma citação. Em hooks de forma shell e comandos de monitor, envolva-o em aspas duplas, como em `"${CLAUDE_PLUGIN_ROOT}"`. Este caminho muda quando o plugin é atualizado. O diretório da versão anterior permanece no disco por aproximadamente sete dias após uma atualização antes da limpeza, mas trate-o como efêmero e não escreva estado aqui.

546 546

547Quando um plugin é atualizado no meio de uma sessão, comandos de hook, monitors, servidores MCP e servidores LSP continuam usando o caminho da versão anterior. Execute `/reload-plugins` para alternar hooks, servidores MCP e servidores LSP para o novo caminho; monitors requerem uma reinicialização de sessão.547Quando um plugin é atualizado no meio de uma sessão, comandos de hook, monitors, servidores MCP e servidores LSP continuam usando o caminho da versão anterior. Execute `/reload-plugins` para alternar hooks, servidores MCP e servidores LSP para o novo caminho; monitors requerem uma reinicialização de sessão.

548 548

549**`${CLAUDE_PLUGIN_DATA}`**: um diretório persistente para estado do plugin que sobrevive a atualizações. Use isso para dependências instaladas como `node_modules` ou ambientes virtuais Python, código gerado, caches e quaisquer outros arquivos que devem persistir entre versões de plugin. O diretório é criado automaticamente na primeira vez que esta variável é referenciada.549**`${CLAUDE_PLUGIN_DATA}`**: um diretório persistente para estado do plugin que sobrevive a atualizações. Use isso para dependências instaladas como `node_modules` ou ambientes virtuais Python, código gerado, caches e quaisquer outros arquivos que devem persistir entre versões de plugin. O diretório é criado automaticamente na primeira vez que esta variável é referenciada.

550 550

551**`${CLAUDE_PROJECT_DIR}`**: a raiz do projeto. Este é o mesmo diretório que hooks recebem em sua variável `CLAUDE_PROJECT_DIR`. Use isso para referenciar scripts ou arquivos de configuração locais do projeto. Envolva em aspas para lidar com caminhos com espaços, por exemplo `"${CLAUDE_PROJECT_DIR}/scripts/server.sh"`. Servidores MCP também podem chamar a solicitação MCP `roots/list`, que retorna o diretório do qual Claude Code foi iniciado.

552

551```json theme={null}553```json theme={null}

552{554{

553 "hooks": {555 "hooks": {

556 "hooks": [558 "hooks": [

557 {559 {

558 "type": "command",560 "type": "command",

559 "command": "${CLAUDE_PLUGIN_ROOT}/scripts/process.sh"561 "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/process.sh"

560 }562 }

561 ]563 ]

562 }564 }

629 631

630Plugins instalados não podem referenciar arquivos fora de seu diretório. Caminhos que atravessam fora da raiz do plugin (como `../shared-utils`) não funcionarão após a instalação porque esses arquivos externos não são copiados para o cache.632Plugins instalados não podem referenciar arquivos fora de seu diretório. Caminhos que atravessam fora da raiz do plugin (como `../shared-utils`) não funcionarão após a instalação porque esses arquivos externos não são copiados para o cache.

631 633

632### Trabalhando com dependências externas634### Compartilhar arquivos dentro de um marketplace com symlinks

635

636Se seu plugin precisa compartilhar arquivos com outras partes do mesmo marketplace, você pode criar links simbólicos dentro de seu diretório de plugin. Como um symlink é tratado quando o plugin é copiado para o cache depende de onde seu alvo é resolvido:

637

638* **Dentro do próprio diretório do plugin:** o symlink é preservado como um symlink relativo no cache, então ele continua resolvendo para o alvo copiado em tempo de execução.

639* **Em outro lugar dentro do mesmo marketplace:** o symlink é desreferenciado. O conteúdo do alvo é copiado para o cache em seu lugar. Isso permite que o diretório `skills/` de um meta-plugin seja vinculado a skills definidas por outros plugins no marketplace.

640* **Fora do marketplace:** o symlink é ignorado por segurança. Isso impede que plugins puxem arquivos arbitrários do host, como caminhos do sistema, para o cache.

633 641

634Se seu plugin precisa acessar arquivos fora de seu diretório, você pode criar links simbólicos para arquivos externos dentro de seu diretório de plugin. Links simbólicos são preservados no cache em vez de desreferenciados, e eles resolvem para seu alvo em tempo de execução. O seguinte comando cria um link de dentro de seu diretório de plugin para um local de utilitários compartilhados:642Para plugins instalados com `--plugin-dir` ou de um caminho local, apenas symlinks que são resolvidos dentro do próprio diretório do plugin são preservados. Todos os outros são ignorados.

643

644O seguinte comando cria um link de dentro de um plugin do marketplace para uma skill compartilhada definida por um plugin irmão. No Windows, use `mklink /D` de um Prompt de Comando elevado ou ative o Modo de Desenvolvedor:

635 645

636```bash theme={null}646```bash theme={null}

637ln -s /path/to/shared-utils ./shared-utils647ln -s ../../shared-plugin/skills/foo ./skills/foo

638```648```

639 649

640Isso fornece flexibilidade enquanto mantém os benefícios de segurança do sistema de cache.650Isso fornece flexibilidade enquanto mantém os benefícios de segurança do sistema de cache.

877 887

888### plugin details

889

890Mostre o inventário de componentes de um plugin e o custo de token projetado. A saída lista todos os componentes que o plugin contribui, agrupados como Skills (skills e comandos), Agents, Hooks e servidores MCP, juntamente com uma estimativa de quantos tokens ele adiciona a cada sessão.

891

892```bash theme={null}

893claude plugin details <name>

894```

895

896**Argumentos:**

897

898* `<name>`: Nome do plugin ou `plugin-name@marketplace-name`

899

900**Opções:**

901

902| Opção | Descrição | Padrão |

903| :----------- | :------------------------ | :----- |

904| `-h, --help` | Exibir ajuda para comando | |

905

906A saída mostra dois valores de custo para cada componente:

907

908* **Always-on:** tokens adicionados a cada sessão pelo texto de listagem do plugin, como descrições de skill, descrições de agent e nomes de comando, independentemente de qualquer componente disparar.

909* **On-invoke:** tokens que um componente custa quando dispara. Mostrado por componente, não como total do plugin, porque uma sessão típica invoca apenas um subconjunto de componentes.

910

911Este exemplo mostra como a saída se parece para um plugin com duas skills:

912

913```

914security-guidance 1.2.0

915 Real-time security analysis for Claude Code sessions

916 Source: security-guidance@claude-code-marketplace

917

918Component inventory

919 Skills (2) scan-dependencies, review-changes

920 Agents (0)

921 Hooks (1) (harness-only — no model context cost)

922 MCP servers (0)

923

924Projected token cost

925 Always-on: ~180 tok added to every session

926

927Per-component (rounded)

928 component always-on on-invoke

929 scan-dependencies ~100 ~2400

930 review-changes ~80 ~1800

931

932 On-invoke cost is paid each time a skill or agent fires.

933 Token counts are estimates and may differ from actual usage.

934```

935

936O total always-on é calculado via API `count_tokens` para seu modelo ativo. Os números por componente são dimensionados proporcionalmente a partir desse total. Se a API estiver inacessível, o comando volta para uma estimativa baseada em caracteres.

937

878### plugin tag938### plugin tag

879 939

880Crie uma tag git de lançamento para o plugin no diretório atual. Execute de dentro da pasta do plugin. Veja [Tag plugin releases](/pt/plugin-dependencies#tag-plugin-releases-for-version-resolution).940Crie uma tag git de lançamento para o plugin no diretório atual. Execute de dentro da pasta do plugin. Veja [Tag plugin releases](/pt/plugin-dependencies#tag-plugin-releases-for-version-resolution).

938 998

9391. Verificar se o script é executável: `chmod +x ./scripts/your-script.sh`9991. Verificar se o script é executável: `chmod +x ./scripts/your-script.sh`

9402. Verificar a linha shebang: Primeira linha deve ser `#!/bin/bash` ou `#!/usr/bin/env bash`10002. Verificar a linha shebang: Primeira linha deve ser `#!/bin/bash` ou `#!/usr/bin/env bash`

9413. Verificar se o caminho usa `${CLAUDE_PLUGIN_ROOT}`: `"command": "${CLAUDE_PLUGIN_ROOT}/scripts/your-script.sh"`10013. Verificar se o caminho usa `${CLAUDE_PLUGIN_ROOT}`: `"command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/your-script.sh"`

9424. Testar o script manualmente: `./scripts/your-script.sh`10024. Testar o script manualmente: `./scripts/your-script.sh`

943 1003

944**Hook não disparando em eventos esperados**:1004**Hook não disparando em eventos esperados**:

quickstart.md +9 −9

Details

279 279

280<AccordionGroup>280<AccordionGroup>

281 <Accordion title="Seja específico com seus pedidos">281 <Accordion title="Seja específico com seus pedidos">

282 Em vez de: "fix the bug"282 Em vez de: "corrigir o bug"

283 283

284 Tente: "fix the login bug where users see a blank screen after entering wrong credentials"284 Tente: "corrigir o bug de login onde os usuários veem uma tela em branco após inserir credenciais incorretas"

285 </Accordion>285 </Accordion>

286 286

287 <Accordion title="Use instruções passo a passo">287 <Accordion title="Use instruções passo a passo">

288 Divida tarefas complexas em etapas:288 Divida tarefas complexas em etapas:

289 289

290 ```text theme={null}290 ```text theme={null}

291 1. create a new database table for user profiles291 1. criar uma nova tabela de banco de dados para perfis de usuário

292 2. create an API endpoint to get and update user profiles292 2. criar um endpoint de API para obter e atualizar perfis de usuário

293 3. build a webpage that allows users to see and edit their information293 3. construir uma página da web que permite aos usuários ver e editar suas informações

294 ```294 ```

295 </Accordion>295 </Accordion>

296 296

298 Antes de fazer alterações, deixe Claude entender seu código:298 Antes de fazer alterações, deixe Claude entender seu código:

299 299

300 ```text theme={null}300 ```text theme={null}

301 analyze the database schema301 analisar o esquema do banco de dados

302 ```302 ```

303 303

304 ```text theme={null}304 ```text theme={null}

305 build a dashboard showing products that are most frequently returned by our UK customers305 construir um painel mostrando produtos que são devolvidos com mais frequência por nossos clientes do Reino Unido

306 ```306 ```

307 </Accordion>307 </Accordion>

308 308

309 <Accordion title="Economize tempo com atalhos">309 <Accordion title="Economize tempo com atalhos">

310 * Pressione `?` para ver todos os atalhos de teclado disponíveis310 * Digite `/` para ver todos os comandos e skills

311 * Use Tab para conclusão de comando311 * Use Tab para conclusão de comando

312 * Pressione ↑ para histórico de comando312 * Pressione ↑ para histórico de comando

313 * Digite `/` para ver todos os comandos e skills313 * Pressione `Shift+Tab` para alternar modos de permissão

314 </Accordion>314 </Accordion>

315</AccordionGroup>315</AccordionGroup>

316 316

routines.md +2 −0

Details

318 318

319As rotinas podem usar seus conectores MCP conectados para ler e escrever em serviços externos durante cada execução. Por exemplo, uma rotina que faz triagem de solicitações de suporte pode ler de um canal do Slack e criar problemas no Linear.319As rotinas podem usar seus conectores MCP conectados para ler e escrever em serviços externos durante cada execução. Por exemplo, uma rotina que faz triagem de solicitações de suporte pode ler de um canal do Slack e criar problemas no Linear.

320 320

321Conectores são as [integrações do claude.ai](/pt/mcp#use-mcp-servers-from-claude-ai) em sua conta. Servidores MCP que você adicionou localmente na CLI com `claude mcp add` são armazenados em sua máquina em vez de sua conta claude.ai, portanto não aparecem na lista de conectores. Para usar um desses servidores em uma rotina, adicione-o como um conector em [claude.ai/customize/connectors](https://claude.ai/customize/connectors), ou declare-o em um [`.mcp.json`](/pt/mcp#project-scope) confirmado para que faça parte do repositório clonado.

322

321Quando você cria uma rotina, todos os seus conectores atualmente conectados são incluídos por padrão. Remova qualquer um que não seja necessário para limitar quais ferramentas Claude tem acesso durante a execução. Você também pode adicionar conectores diretamente do formulário de rotina.323Quando você cria uma rotina, todos os seus conectores atualmente conectados são incluídos por padrão. Remova qualquer um que não seja necessário para limitar quais ferramentas Claude tem acesso durante a execução. Você também pode adicionar conectores diretamente do formulário de rotina.

322 324

323Para gerenciar ou adicionar conectores fora do formulário de rotina, visite **Configurações > Conectores** em claude.ai ou use `/schedule update` na CLI.325Para gerenciar ou adicionar conectores fora do formulário de rotina, visite **Configurações > Conectores** em claude.ai ou use `/schedule update` na CLI.

security.md +2 −2

Details

85 85

86## Segurança do MCP86## Segurança do MCP

87 87

88Claude Code permite que os usuários configurem servidores Model Context Protocol (MCP). A lista de MCP servers permitidos é configurada no seu código-fonte, como parte das configurações do Claude Code que os engenheiros verificam no controle de versão.88Claude Code permite que os usuários configurem servidores Model Context Protocol (MCP). A lista de servidores MCP permitidos é configurada no seu código-fonte, como parte das configurações do Claude Code que os engenheiros verificam no controle de versão.

89 89

90Encorajamos escrever seus próprios MCP servers ou usar MCP servers de provedores em que você confia. Você é capaz de configurar permissões do Claude Code para MCP servers. Anthropic não gerencia ou audita nenhum MCP server.90Encorajamos escrever seus próprios servidores MCP ou usar servidores MCP de provedores em que você confia. Você é capaz de configurar permissões do Claude Code para servidores MCP. Anthropic analisa conectores em relação aos seus [critérios de listagem](https://claude.com/docs/connectors/building/review-criteria) antes de adicioná-los ao [Diretório Anthropic](https://claude.ai/directory), mas não realiza auditoria de segurança ou gerencia nenhum servidor MCP.

91 91

92## Segurança do IDE92## Segurança do IDE

93 93

settings.md +3 −1

Details

178| `awsCredentialExport` | Script personalizado que produz JSON com credenciais AWS (veja [configuração avançada de credenciais](/pt/amazon-bedrock#advanced-credential-configuration)) | `/bin/generate_aws_grant.sh` |178| `awsCredentialExport` | Script personalizado que produz JSON com credenciais AWS (veja [configuração avançada de credenciais](/pt/amazon-bedrock#advanced-credential-configuration)) | `/bin/generate_aws_grant.sh` |

179| `blockedMarketplaces` | (Apenas configurações gerenciadas) Lista de negação de fontes de marketplace. Aplicado em adição de marketplace e em instalação, atualização, atualização e auto-atualização de plugin, então um marketplace adicionado antes da política ser definida não pode ser usado para buscar plugins. Fontes bloqueadas são verificadas antes do download, então nunca tocam o sistema de arquivos. Veja [Restrições de marketplace gerenciado](/pt/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "untrusted/plugins" }]` |179| `blockedMarketplaces` | (Apenas configurações gerenciadas) Lista de negação de fontes de marketplace. Aplicado em adição de marketplace e em instalação, atualização, atualização e auto-atualização de plugin, então um marketplace adicionado antes da política ser definida não pode ser usado para buscar plugins. Fontes bloqueadas são verificadas antes do download, então nunca tocam o sistema de arquivos. Veja [Restrições de marketplace gerenciado](/pt/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "untrusted/plugins" }]` |

180| `channelsEnabled` | (Apenas configurações gerenciadas) Permitir [channels](/pt/channels) para a organização. Em planos Claude.ai Team e Enterprise, channels são bloqueados quando isto está indefinido ou `false`. Para contas [Anthropic Console](/pt/authentication#claude-console-authentication) usando autenticação de chave de API, channels são permitidos por padrão a menos que sua organização implante configurações gerenciadas, nesse caso esta chave deve ser definida como `true` | `true` |180| `channelsEnabled` | (Apenas configurações gerenciadas) Permitir [channels](/pt/channels) para a organização. Em planos Claude.ai Team e Enterprise, channels são bloqueados quando isto está indefinido ou `false`. Para contas [Anthropic Console](/pt/authentication#claude-console-authentication) usando autenticação de chave de API, channels são permitidos por padrão a menos que sua organização implante configurações gerenciadas, nesse caso esta chave deve ser definida como `true` | `true` |

181| `claudeMd` | (Apenas configurações gerenciadas) Instruções no estilo CLAUDE.md injetadas como memória gerenciada pela organização. Apenas honrado quando definido em configurações gerenciadas ou de política e ignorado em configurações de usuário, projeto e local. Veja [CLAUDE.md em toda a organização](/pt/memory#deploy-organization-wide-claude-md) | `"Always run make lint before committing."` |

181| `claudeMdExcludes` | Padrões Glob ou caminhos absolutos de arquivos `CLAUDE.md` para pular ao carregar [memória](/pt/memory). Padrões correspondem contra caminhos de arquivo absolutos. Aplica-se apenas a memória de usuário, projeto e local; arquivos de política gerenciada não podem ser excluídos | `["**/vendor/**/CLAUDE.md"]` |182| `claudeMdExcludes` | Padrões Glob ou caminhos absolutos de arquivos `CLAUDE.md` para pular ao carregar [memória](/pt/memory). Padrões correspondem contra caminhos de arquivo absolutos. Aplica-se apenas a memória de usuário, projeto e local; arquivos de política gerenciada não podem ser excluídos | `["**/vendor/**/CLAUDE.md"]` |

182| `cleanupPeriodDays` | Arquivos de sessão mais antigos que este período são deletados na inicialização (padrão: 30 dias, mínimo 1). Definir como `0` é rejeitado com um erro de validação. Também controla o corte de idade para remoção automática de [worktrees de subagent órfãos](/pt/worktrees#clean-up-worktrees) na inicialização. Para desabilitar escritas de transcrição completamente, defina a variável de ambiente [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/pt/env-vars), ou em modo não interativo (`-p`) use a flag `--no-session-persistence` ou a opção SDK `persistSession: false`. | `20` |183| `cleanupPeriodDays` | Arquivos de sessão mais antigos que este período são deletados na inicialização (padrão: 30 dias, mínimo 1). Definir como `0` é rejeitado com um erro de validação. Também controla o corte de idade para remoção automática de [worktrees de subagent órfãos](/pt/worktrees#clean-up-worktrees) na inicialização. Para desabilitar escritas de transcrição completamente, defina a variável de ambiente [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/pt/env-vars), ou em modo não interativo (`-p`) use a flag `--no-session-persistence` ou a opção SDK `persistSession: false`. | `20` |

183| `companyAnnouncements` | Anúncio a ser exibido aos usuários na inicialização. Se múltiplos anúncios forem fornecidos, eles serão alternados aleatoriamente. | `["Welcome to Acme Corp! Review our code guidelines at docs.acme.com"]` |184| `companyAnnouncements` | Anúncio a ser exibido aos usuários na inicialização. Se múltiplos anúncios forem fornecidos, eles serão alternados aleatoriamente. | `["Welcome to Acme Corp! Review our code guidelines at docs.acme.com"]` |

253</Note>254</Note>

254 255

256| :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------ |257| :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------- |

257| `autoConnectIde` | Conectar automaticamente a um IDE em execução quando Claude Code inicia de um terminal externo. Padrão: `false`. Aparece em `/config` como **Auto-connect to IDE (external terminal)** ao executar fora de um terminal VS Code ou JetBrains. A variável de ambiente [`CLAUDE_CODE_AUTO_CONNECT_IDE`](/pt/env-vars) substitui isto quando definida | `true` |258| `autoConnectIde` | Conectar automaticamente a um IDE em execução quando Claude Code inicia de um terminal externo. Padrão: `false`. Aparece em `/config` como **Auto-connect to IDE (external terminal)** ao executar fora de um terminal VS Code ou JetBrains. A variável de ambiente [`CLAUDE_CODE_AUTO_CONNECT_IDE`](/pt/env-vars) substitui isto quando definida | `true` |

258| `autoInstallIdeExtension` | Instalar automaticamente a extensão IDE do Claude Code ao executar de um terminal VS Code. Padrão: `true`. Aparece em `/config` como **Auto-install IDE extension** ao executar dentro de um terminal VS Code ou JetBrains. Você também pode definir a variável de ambiente [`CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL`](/pt/env-vars) | `false` |259| `autoInstallIdeExtension` | Instalar automaticamente a extensão IDE do Claude Code ao executar de um terminal VS Code. Padrão: `true`. Aparece em `/config` como **Auto-install IDE extension** ao executar dentro de um terminal VS Code ou JetBrains. Você também pode definir a variável de ambiente [`CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL`](/pt/env-vars) | `false` |

259| `externalEditorContext` | Prepend a resposta anterior do Claude como contexto comentado com `#` quando você abre o editor externo com `Ctrl+G`. Padrão: `false`. Aparece em `/config` como **Show last response in external editor** | `true` |260| `externalEditorContext` | Prepend a resposta anterior do Claude como contexto comentado com `#` quando você abre o editor externo com `Ctrl+G`. Padrão: `false`. Aparece em `/config` como **Show last response in external editor** | `true` |

261| `teammateDefaultModel` | Modelo padrão para [colegas de equipe de agente](/pt/agent-teams) quando o prompt de spawn não especifica um. Defina como um alias de modelo como `"sonnet"`, ou `null` para herdar a seleção `/model` atual do líder. Aparece em `/config` como **Default teammate model** | `"sonnet"` |

260 262

261### Configurações de worktrees263### Configurações de worktrees

262 264

vs-code.md +4 −2

Details

233</Note>233</Note>

234 234

236| -------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |236| -------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

238| Open in Side Bar | - | Abra Claude na barra lateral esquerda |238| Open in Side Bar | - | Abra Claude na barra lateral esquerda |

239| Open in Terminal | - | Abra Claude em modo terminal |239| Open in Terminal | - | Abra Claude em modo terminal |

241| Open in New Window | - | Abra uma nova conversa em uma janela separada |241| Open in New Window | - | Abra uma nova conversa em uma janela separada |

242| New Conversation | `Cmd+N` (Mac) / `Ctrl+N` (Windows/Linux) | Inicie uma nova conversa. Requer que Claude esteja focado e `enableNewConversationShortcut` definido como `true` |242| New Conversation | `Cmd+N` (Mac) / `Ctrl+N` (Windows/Linux) | Inicie uma nova conversa. Requer que Claude esteja focado e `enableNewConversationShortcut` definido como `true` |

243| Reopen Closed Session | `Cmd+Shift+T` (Mac) / `Ctrl+Shift+T` (Windows/Linux) | Reabra a aba de sessão Claude fechada mais recentemente. Volta para a reabertura normal de editor fechado do VS Code quando a última aba fechada não era uma sessão Claude. Desabilite com `enableReopenClosedSessionShortcut` |

244| Show Logs | - | Visualize logs de depuração da extensão |245| Show Logs | - | Visualize logs de depuração da extensão |

245| Logout | - | Saia de sua conta Anthropic |246| Logout | - | Saia de sua conta Anthropic |

307### Extension settings308### Extension settings

308 309

310| --------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |311| ----------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

312| `initialPermissionMode` | `default` | Controla prompts de aprovação para novas conversas: `default`, `plan`, `acceptEdits` ou `bypassPermissions`. Consulte [permission modes](/pt/permission-modes). |313| `initialPermissionMode` | `default` | Controla prompts de aprovação para novas conversas: `default`, `plan`, `acceptEdits` ou `bypassPermissions`. Consulte [permission modes](/pt/permission-modes). |

318| `enableReopenClosedSessionShortcut` | `true` | Use Cmd/Ctrl+Shift+T para reabrir a aba de sessão Claude fechada mais recentemente. Quando a última aba fechada não era uma sessão Claude, o atalho executa o comando normal de reabrir editor fechado do VS Code. |

Documentation 2026-05-11 23:00 UTC to 2026-05-12 22:57 UTC