Documentation — Spybara

agent-sdk/claude-code-features.md +12 −10

Details

12 12

13Para uma visão geral conceitual do que cada recurso faz e quando usá-lo, veja [Extend Claude Code](/pt/features-overview).13Para uma visão geral conceitual do que cada recurso faz e quando usá-lo, veja [Extend Claude Code](/pt/features-overview).

14 14

~~15## Control filesystem settings with settingSources~~15## Controlar configurações do sistema de arquivos com settingSources

16 16

17A opção de fontes de configuração ([`setting_sources`](/pt/agent-sdk/python#claude-agent-options) em Python, [`settingSources`](/pt/agent-sdk/typescript#setting-source) em TypeScript) controla quais configurações baseadas em sistema de arquivos o SDK carrega. Passe uma lista explícita para optar por fontes específicas, ou passe um array vazio para desabilitar configurações de usuário, projeto e local.17A opção de fontes de configuração ([`setting_sources`](/pt/agent-sdk/python#claudeagentoptions) em Python, [`settingSources`](/pt/agent-sdk/typescript#settingsource) em TypeScript) controla quais configurações baseadas em sistema de arquivos o SDK carrega. Passe uma lista explícita para optar por fontes específicas, ou passe um array vazio para desabilitar configurações de usuário, projeto e local.

18 18

19Este exemplo carrega configurações de nível de usuário e nível de projeto definindo `settingSources` para `["user", "project"]`:19Este exemplo carrega configurações de nível de usuário e nível de projeto definindo `settingSources` para `["user", "project"]`:

20 20

65 ```65 ```

66</CodeGroup>66</CodeGroup>

67 67

68Cada fonte carrega configurações de um local específico, onde `<cwd>` é o diretório de trabalho que você passa via opção `cwd` (ou o diretório atual do processo se não definido). Para a definição de tipo completa, veja [`SettingSource`](/pt/agent-sdk/typescript#setting-source) (TypeScript) ou [`SettingSource`](/pt/agent-sdk/python#setting-source) (Python).68Cada fonte carrega configurações de um local específico, onde `<cwd>` é o diretório de trabalho que você passa via opção `cwd`, ou o diretório atual do processo se não definido. Para a definição de tipo completa, veja [`SettingSource`](/pt/agent-sdk/typescript#settingsource) (TypeScript) ou [`SettingSource`](/pt/agent-sdk/python#settingsource) (Python).

69 69

71| :---------- | :---------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- |71| :---------- | :---------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- |

77 77

78A opção `cwd` determina onde o SDK procura por configurações de projeto. Se nem `cwd` nem nenhum de seus diretórios pai contiver uma pasta `.claude/`, os recursos de nível de projeto não serão carregados.78A opção `cwd` determina onde o SDK procura por configurações de projeto. Se nem `cwd` nem nenhum de seus diretórios pai contiver uma pasta `.claude/`, os recursos de nível de projeto não serão carregados.

79 79

~~80### What settingSources does not control~~80### O que settingSources não controla

81 81

82`settingSources` cobre configurações de usuário, projeto e local. Algumas entradas são lidas independentemente de seu valor:82`settingSources` cobre configurações de usuário, projeto e local. Algumas entradas são lidas independentemente de seu valor:

83 83

119 119

120Skills são arquivos markdown que dão ao seu agente conhecimento especializado e fluxos de trabalho invocáveis. Diferentemente de `CLAUDE.md` (que carrega a cada sessão), skills carregam sob demanda. O agente recebe descrições de skills na inicialização e carrega o conteúdo completo quando relevante.120Skills são arquivos markdown que dão ao seu agente conhecimento especializado e fluxos de trabalho invocáveis. Diferentemente de `CLAUDE.md` (que carrega a cada sessão), skills carregam sob demanda. O agente recebe descrições de skills na inicialização e carrega o conteúdo completo quando relevante.

121 121

122Skills são descobertos do sistema de arquivos através de `settingSources`. Com opções padrão, skills de usuário e projeto carregam automaticamente. A ferramenta `Skill` é habilitada por padrão quando você não especifica `allowedTools`. Se você está usando uma lista de permissão `allowedTools`, inclua `"Skill"` explicitamente.122Skills são descobertos do sistema de arquivos através de `settingSources`. Quando a opção `skills` em `query()` é omitida, skills de usuário e projeto descobertos são habilitados e a ferramenta Skill fica disponível, correspondendo ao comportamento da CLI. Para controlar quais skills são habilitados, passe `skills` como `"all"`, uma lista de nomes de skills, ou `[]` para desabilitar todos. O SDK habilita a ferramenta Skill automaticamente quando `skills` é definido, portanto você não precisa adicioná-la a `allowedTools`.

123 123

124<CodeGroup>124<CodeGroup>

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

131 prompt="Review this PR using our code review checklist",131 prompt="Review this PR using our code review checklist",

132 options=ClaudeAgentOptions(132 options=ClaudeAgentOptions(

133 setting_sources=["user", "project"],133 setting_sources=["user", "project"],

134 allowed_tools=["Skill", "Read", "Grep", "Glob"],134 skills="all",

135 allowed_tools=["Read", "Grep", "Glob"],

135 ),136 ),

136 ):137 ):

137 if isinstance(message, ResultMessage) and message.subtype == "success":138 if isinstance(message, ResultMessage) and message.subtype == "success":

147 prompt: "Review this PR using our code review checklist",148 prompt: "Review this PR using our code review checklist",

148 options: {149 options: {

149 settingSources: ["user", "project"],150 settingSources: ["user", "project"],

150 allowedTools: ["Skill", "Read", "Grep", "Glob"]151 skills: "all",

152 allowedTools: ["Read", "Grep", "Glob"]

151 }153 }

152 })) {154 })) {

153 if (message.type === "result" && message.subtype === "success") {155 if (message.type === "result" && message.subtype === "success") {

253 255

254Para detalhes completos sobre hooks programáticos, veja [Control execution with hooks](/pt/agent-sdk/hooks). Para sintaxe de hook do sistema de arquivos, veja [Hooks](/pt/hooks).256Para detalhes completos sobre hooks programáticos, veja [Control execution with hooks](/pt/agent-sdk/hooks). Para sintaxe de hook do sistema de arquivos, veja [Hooks](/pt/hooks).

255 257

256## Choose the right feature258## Escolha o recurso certo

257 259

258O Agent SDK oferece acesso a várias maneiras de estender o comportamento do seu agente. Se você não tem certeza qual usar, esta tabela mapeia objetivos comuns para a abordagem correta.260O Agent SDK oferece acesso a várias maneiras de estender o comportamento do seu agente. Se você não tem certeza qual usar, esta tabela mapeia objetivos comuns para a abordagem correta.

259 261

260| Você quer... | Use | Superfície SDK |262| Você quer... | Use | Superfície SDK |

261| :------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |263| :------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

266| Coordenar múltiplas instâncias de Claude Code com listas de tarefas compartilhadas e mensagens diretas entre agentes | [Agent teams](/pt/agent-teams) | Não configurado diretamente via opções SDK. Agent teams são um recurso CLI onde uma sessão atua como o líder da equipe, coordenando trabalho entre colegas independentes |268| Coordenar múltiplas instâncias de Claude Code com listas de tarefas compartilhadas e mensagens diretas entre agentes | [Agent teams](/pt/agent-teams) | Não configurado diretamente via opções SDK. Agent teams são um recurso CLI onde uma sessão atua como o líder da equipe, coordenando trabalho entre colegas independentes |

267| Executar lógica determinística em chamadas de ferramenta (audit, block, transform) | [Hooks](/pt/agent-sdk/hooks) | parâmetro `hooks` com callbacks, ou scripts shell carregados via `settingSources` |269| Executar lógica determinística em chamadas de ferramenta (audit, block, transform) | [Hooks](/pt/agent-sdk/hooks) | parâmetro `hooks` com callbacks, ou scripts shell carregados via `settingSources` |

agent-sdk/mcp.md +772 −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# Conectar a ferramentas externas com MCP

7> Configure servidores MCP para estender seu agente com ferramentas externas. Abrange tipos de transporte, busca de ferramentas para grandes conjuntos de ferramentas, autenticação e tratamento de erros.

9O [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro) é um padrão aberto para conectar agentes de IA a ferramentas e fontes de dados externas. Com MCP, seu agente pode consultar bancos de dados, integrar com APIs como Slack e GitHub, e conectar a outros serviços sem escrever implementações de ferramentas personalizadas.

11Os servidores MCP podem ser executados como processos locais, conectar via HTTP ou executar diretamente dentro de sua aplicação SDK.

13<Note>

14 Esta página abrange a configuração de MCP para o Agent SDK. Para adicionar servidores MCP ao Claude Code CLI para que sejam carregados em cada projeto, consulte [escopos de instalação de MCP](/pt/mcp#mcp-installation-scopes).

15</Note>

17## Início rápido

19Este exemplo conecta ao servidor MCP de [documentação do Claude Code](https://code.claude.com/docs) usando [transporte HTTP](#httpsse-servers) e usa [`allowedTools`](#allow-mcp-tools) com um curinga para permitir todas as ferramentas do servidor.

21<CodeGroup>

22 ```typescript TypeScript theme={null}

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

25 for await (const message of query({

26 prompt: "Use the docs MCP server to explain what hooks are in Claude Code",

27 options: {

28 mcpServers: {

29 "claude-code-docs": {

30 type: "http",

31 url: "https://code.claude.com/docs/mcp"

32 }

33 },

34 allowedTools: ["mcp__claude-code-docs__*"]

35 }

36 })) {

37 if (message.type === "result" && message.subtype === "success") {

38 console.log(message.result);

39 }

40 }

41 ```

43 ```python Python theme={null}

44 import asyncio

45 from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

48 async def main():

49 options = ClaudeAgentOptions(

50 mcp_servers={

51 "claude-code-docs": {

52 "type": "http",

53 "url": "https://code.claude.com/docs/mcp",

54 }

55 },

56 allowed_tools=["mcp__claude-code-docs__*"],

57 )

59 async for message in query(

60 prompt="Use the docs MCP server to explain what hooks are in Claude Code",

61 options=options,

62 ):

63 if isinstance(message, ResultMessage) and message.subtype == "success":

64 print(message.result)

67 asyncio.run(main())

68 ```

69</CodeGroup>

71O agente conecta ao servidor de documentação, busca informações sobre hooks e retorna os resultados.

73## Adicionar um servidor MCP

75Você pode configurar servidores MCP em código ao chamar `query()`, ou em um arquivo `.mcp.json` carregado via [`settingSources`](#from-a-config-file).

77### Em código

79Passe servidores MCP diretamente na opção `mcpServers`:

81<CodeGroup>

82 ```typescript TypeScript theme={null}

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

85 for await (const message of query({

86 prompt: "List files in my project",

87 options: {

88 mcpServers: {

89 filesystem: {

90 command: "npx",

91 args: ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]

92 }

93 },

94 allowedTools: ["mcp__filesystem__*"]

95 }

96 })) {

97 if (message.type === "result" && message.subtype === "success") {

98 console.log(message.result);

99 }

100 }

101 ```

102

103 ```python Python theme={null}

104 import asyncio

105 from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

106

107

108 async def main():

109 options = ClaudeAgentOptions(

110 mcp_servers={

111 "filesystem": {

112 "command": "npx",

113 "args": [

114 "-y",

115 "@modelcontextprotocol/server-filesystem",

116 "/Users/me/projects",

117 ],

118 }

119 },

120 allowed_tools=["mcp__filesystem__*"],

121 )

122

123 async for message in query(prompt="List files in my project", options=options):

124 if isinstance(message, ResultMessage) and message.subtype == "success":

125 print(message.result)

126

127

128 asyncio.run(main())

129 ```

130</CodeGroup>

131

132### De um arquivo de configuração

133

134Crie um arquivo `.mcp.json` na raiz do seu projeto. O arquivo é detectado quando a fonte de configuração `project` está habilitada, o que é padrão para as opções `query()`. Se você definir `settingSources` explicitamente, inclua `"project"` para que este arquivo seja carregado:

135

136```json theme={null}

137{

138 "mcpServers": {

139 "filesystem": {

140 "command": "npx",

141 "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]

142 }

143 }

144}

145```

146

147## Permitir ferramentas MCP

148

149As ferramentas MCP requerem permissão explícita antes que Claude possa usá-las. Sem permissão, Claude verá que as ferramentas estão disponíveis, mas não poderá chamá-las.

150

151### Convenção de nomenclatura de ferramentas

152

153As ferramentas MCP seguem o padrão de nomenclatura `mcp__<server-name>__<tool-name>`. Por exemplo, um servidor GitHub nomeado `"github"` com uma ferramenta `list_issues` se torna `mcp__github__list_issues`.

154

155### Conceder acesso com allowedTools

156

157Use `allowedTools` para especificar quais ferramentas MCP Claude pode usar:

158

159```typescript hidelines={1,-1} theme={null}

160const _ = {

161 options: {

162 mcpServers: {

163 // your servers

164 },

165 allowedTools: [

166 "mcp__github__*", // All tools from the github server

167 "mcp__db__query", // Only the query tool from db server

168 "mcp__slack__send_message" // Only send_message from slack server

169 ]

170 }

171};

172```

173

174Curingas (`*`) permitem que você autorize todas as ferramentas de um servidor sem listar cada uma individualmente.

175

176<Note>

177 **Prefira `allowedTools` em vez de modos de permissão para acesso MCP.** `permissionMode: "acceptEdits"` não aprova automaticamente ferramentas MCP (apenas edições de arquivo e comandos Bash do sistema de arquivos). `permissionMode: "bypassPermissions"` aprova automaticamente ferramentas MCP, mas também desabilita todos os outros prompts de segurança, o que é mais amplo do que necessário. Um curinga em `allowedTools` concede exatamente o servidor MCP que você deseja e nada mais. Consulte [Modos de permissão](/pt/agent-sdk/permissions#permission-modes) para uma comparação completa.

178</Note>

179

180### Descobrir ferramentas disponíveis

181

182Para ver quais ferramentas um servidor MCP fornece, verifique a documentação do servidor ou conecte ao servidor e inspecione a mensagem de inicialização `system`:

183

184```typescript theme={null}

185for await (const message of query({ prompt: "...", options })) {

186 if (message.type === "system" && message.subtype === "init") {

187 console.log("Available MCP tools:", message.mcp_servers);

188 }

189}

190```

191

192## Tipos de transporte

193

194Os servidores MCP se comunicam com seu agente usando diferentes protocolos de transporte. Verifique a documentação do servidor para ver qual transporte ele suporta:

195

196* Se a documentação fornecer um **comando para executar** (como `npx @modelcontextprotocol/server-github`), use stdio

197* Se a documentação fornecer uma **URL**, use HTTP ou SSE

198* Se você estiver construindo suas próprias ferramentas em código, use um servidor MCP SDK

199

200### Servidores stdio

201

202Processos locais que se comunicam via stdin/stdout. Use isso para servidores MCP que você executa na mesma máquina:

203

204<Tabs>

205 <Tab title="Em código">

206 <CodeGroup>

207 ```typescript TypeScript hidelines={1,-1} theme={null}

208 const _ = {

209 options: {

210 mcpServers: {

211 github: {

212 command: "npx",

213 args: ["-y", "@modelcontextprotocol/server-github"],

214 env: {

215 GITHUB_TOKEN: process.env.GITHUB_TOKEN

216 }

217 }

218 },

219 allowedTools: ["mcp__github__list_issues", "mcp__github__search_issues"]

220 }

221 };

222 ```

223

224 ```python Python theme={null}

225 options = ClaudeAgentOptions(

226 mcp_servers={

227 "github": {

228 "command": "npx",

229 "args": ["-y", "@modelcontextprotocol/server-github"],

230 "env": {"GITHUB_TOKEN": os.environ["GITHUB_TOKEN"]},

231 }

232 },

233 allowed_tools=["mcp__github__list_issues", "mcp__github__search_issues"],

234 )

235 ```

236 </CodeGroup>

237 </Tab>

238

239 <Tab title=".mcp.json">

240 ```json theme={null}

241 {

242 "mcpServers": {

243 "github": {

244 "command": "npx",

245 "args": ["-y", "@modelcontextprotocol/server-github"],

246 "env": {

247 "GITHUB_TOKEN": "${GITHUB_TOKEN}"

248 }

249 }

250 }

251 }

252 ```

253 </Tab>

254</Tabs>

255

256### Servidores HTTP/SSE

257

258Use HTTP ou SSE para servidores MCP hospedados em nuvem e APIs remotas:

259

260<Tabs>

261 <Tab title="Em código">

262 <CodeGroup>

263 ```typescript TypeScript hidelines={1,-1} theme={null}

264 const _ = {

265 options: {

266 mcpServers: {

267 "remote-api": {

268 type: "sse",

269 url: "https://api.example.com/mcp/sse",

270 headers: {

271 Authorization: `Bearer ${process.env.API_TOKEN}`

272 }

273 }

274 },

275 allowedTools: ["mcp__remote-api__*"]

276 }

277 };

278 ```

279

280 ```python Python theme={null}

281 options = ClaudeAgentOptions(

282 mcp_servers={

283 "remote-api": {

284 "type": "sse",

285 "url": "https://api.example.com/mcp/sse",

286 "headers": {"Authorization": f"Bearer {os.environ['API_TOKEN']}"},

287 }

288 },

289 allowed_tools=["mcp__remote-api__*"],

290 )

291 ```

292 </CodeGroup>

293 </Tab>

294

295 <Tab title=".mcp.json">

296 ```json theme={null}

297 {

298 "mcpServers": {

299 "remote-api": {

300 "type": "sse",

301 "url": "https://api.example.com/mcp/sse",

302 "headers": {

303 "Authorization": "Bearer ${API_TOKEN}"

304 }

305 }

306 }

307 }

308 ```

309 </Tab>

310</Tabs>

311

312Para HTTP (não-streaming), use `"type": "http"` em vez disso.

313

314### Servidores MCP SDK

315

316Defina ferramentas personalizadas diretamente no código da sua aplicação em vez de executar um processo de servidor separado. Consulte o [guia de ferramentas personalizadas](/pt/agent-sdk/custom-tools) para detalhes de implementação.

317

318## Busca de ferramentas MCP

319

320Quando você tem muitas ferramentas MCP configuradas, as definições de ferramentas podem consumir uma porção significativa de sua janela de contexto. A busca de ferramentas resolve isso retendo as definições de ferramentas do contexto e carregando apenas as que Claude precisa para cada turno.

321

322A busca de ferramentas está habilitada por padrão. Consulte [Busca de ferramentas](/pt/agent-sdk/tool-search) para opções de configuração e detalhes.

323

324Para mais detalhes, incluindo melhores práticas e uso de busca de ferramentas com ferramentas SDK personalizadas, consulte o [guia de busca de ferramentas](/pt/agent-sdk/tool-search).

325

326## Autenticação

327

328A maioria dos servidores MCP requer autenticação para acessar serviços externos. Passe credenciais através de variáveis de ambiente na configuração do servidor.

329

330### Passar credenciais via variáveis de ambiente

331

332Use o campo `env` para passar chaves de API, tokens e outras credenciais para o servidor MCP:

333

334<Tabs>

335 <Tab title="Em código">

336 <CodeGroup>

337 ```typescript TypeScript hidelines={1,-1} theme={null}

338 const _ = {

339 options: {

340 mcpServers: {

341 github: {

342 command: "npx",

343 args: ["-y", "@modelcontextprotocol/server-github"],

344 env: {

345 GITHUB_TOKEN: process.env.GITHUB_TOKEN

346 }

347 }

348 },

349 allowedTools: ["mcp__github__list_issues"]

350 }

351 };

352 ```

353

354 ```python Python theme={null}

355 options = ClaudeAgentOptions(

356 mcp_servers={

357 "github": {

358 "command": "npx",

359 "args": ["-y", "@modelcontextprotocol/server-github"],

360 "env": {"GITHUB_TOKEN": os.environ["GITHUB_TOKEN"]},

361 }

362 },

363 allowed_tools=["mcp__github__list_issues"],

364 )

365 ```

366 </CodeGroup>

367 </Tab>

368

369 <Tab title=".mcp.json">

370 ```json theme={null}

371 {

372 "mcpServers": {

373 "github": {

374 "command": "npx",

375 "args": ["-y", "@modelcontextprotocol/server-github"],

376 "env": {

377 "GITHUB_TOKEN": "${GITHUB_TOKEN}"

378 }

379 }

380 }

381 }

382 ```

383

384 A sintaxe `${GITHUB_TOKEN}` expande variáveis de ambiente em tempo de execução.

385 </Tab>

386</Tabs>

387

388Consulte [Listar problemas de um repositório](#list-issues-from-a-repository) para um exemplo completo e funcional com registro de depuração.

389

390### Cabeçalhos HTTP para servidores remotos

391

392Para servidores HTTP e SSE, passe cabeçalhos de autenticação diretamente na configuração do servidor:

393

394<Tabs>

395 <Tab title="Em código">

396 <CodeGroup>

397 ```typescript TypeScript hidelines={1,-1} theme={null}

398 const _ = {

399 options: {

400 mcpServers: {

401 "secure-api": {

402 type: "http",

403 url: "https://api.example.com/mcp",

404 headers: {

405 Authorization: `Bearer ${process.env.API_TOKEN}`

406 }

407 }

408 },

409 allowedTools: ["mcp__secure-api__*"]

410 }

411 };

412 ```

413

414 ```python Python theme={null}

415 options = ClaudeAgentOptions(

416 mcp_servers={

417 "secure-api": {

418 "type": "http",

419 "url": "https://api.example.com/mcp",

420 "headers": {"Authorization": f"Bearer {os.environ['API_TOKEN']}"},

421 }

422 },

423 allowed_tools=["mcp__secure-api__*"],

424 )

425 ```

426 </CodeGroup>

427 </Tab>

428

429 <Tab title=".mcp.json">

430 ```json theme={null}

431 {

432 "mcpServers": {

433 "secure-api": {

434 "type": "http",

435 "url": "https://api.example.com/mcp",

436 "headers": {

437 "Authorization": "Bearer ${API_TOKEN}"

438 }

439 }

440 }

441 }

442 ```

443

444 A sintaxe `${API_TOKEN}` expande variáveis de ambiente em tempo de execução.

445 </Tab>

446</Tabs>

447

448### Autenticação OAuth2

449

450A [especificação MCP suporta OAuth 2.1](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization) para autorização. O SDK não trata fluxos OAuth automaticamente, mas você pode passar tokens de acesso via cabeçalhos após completar o fluxo OAuth em sua aplicação:

451

452<CodeGroup>

453 ```typescript TypeScript theme={null}

454 // After completing OAuth flow in your app

455 const accessToken = await getAccessTokenFromOAuthFlow();

456

457 const options = {

458 mcpServers: {

459 "oauth-api": {

460 type: "http",

461 url: "https://api.example.com/mcp",

462 headers: {

463 Authorization: `Bearer ${accessToken}`

464 }

465 }

466 },

467 allowedTools: ["mcp__oauth-api__*"]

468 };

469 ```

470

471 ```python Python theme={null}

472 # After completing OAuth flow in your app

473 access_token = await get_access_token_from_oauth_flow()

474

475 options = ClaudeAgentOptions(

476 mcp_servers={

477 "oauth-api": {

478 "type": "http",

479 "url": "https://api.example.com/mcp",

480 "headers": {"Authorization": f"Bearer {access_token}"},

481 }

482 },

483 allowed_tools=["mcp__oauth-api__*"],

484 )

485 ```

486</CodeGroup>

487

488## Exemplos

489

490### Listar problemas de um repositório

491

492Este exemplo conecta ao [servidor GitHub MCP](https://github.com/modelcontextprotocol/servers/tree/main/src/github) para listar problemas recentes. O exemplo inclui registro de depuração para verificar a conexão MCP e chamadas de ferramentas.

493

494Antes de executar, crie um [token de acesso pessoal do GitHub](https://github.com/settings/tokens) com escopo `repo` e defina-o como uma variável de ambiente:

495

496```bash theme={null}

497export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

498```

499

500<CodeGroup>

501 ```typescript TypeScript theme={null}

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

503

504 for await (const message of query({

505 prompt: "List the 3 most recent issues in anthropics/claude-code",

506 options: {

507 mcpServers: {

508 github: {

509 command: "npx",

510 args: ["-y", "@modelcontextprotocol/server-github"],

511 env: {

512 GITHUB_TOKEN: process.env.GITHUB_TOKEN

513 }

514 }

515 },

516 allowedTools: ["mcp__github__list_issues"]

517 }

518 })) {

519 // Verify MCP server connected successfully

520 if (message.type === "system" && message.subtype === "init") {

521 console.log("MCP servers:", message.mcp_servers);

522 }

523

524 // Log when Claude calls an MCP tool

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

526 for (const block of message.message.content) {

527 if (block.type === "tool_use" && block.name.startsWith("mcp__")) {

528 console.log("MCP tool called:", block.name);

529 }

530 }

531 }

532

533 // Print the final result

534 if (message.type === "result" && message.subtype === "success") {

535 console.log(message.result);

536 }

537 }

538 ```

539

540 ```python Python theme={null}

541 import asyncio

542 import os

543 from claude_agent_sdk import (

544 query,

545 ClaudeAgentOptions,

546 ResultMessage,

547 SystemMessage,

548 AssistantMessage,

549 )

550

551

552 async def main():

553 options = ClaudeAgentOptions(

554 mcp_servers={

555 "github": {

556 "command": "npx",

557 "args": ["-y", "@modelcontextprotocol/server-github"],

558 "env": {"GITHUB_TOKEN": os.environ["GITHUB_TOKEN"]},

559 }

560 },

561 allowed_tools=["mcp__github__list_issues"],

562 )

563

564 async for message in query(

565 prompt="List the 3 most recent issues in anthropics/claude-code",

566 options=options,

567 ):

568 # Verify MCP server connected successfully

569 if isinstance(message, SystemMessage) and message.subtype == "init":

570 print("MCP servers:", message.data.get("mcp_servers"))

571

572 # Log when Claude calls an MCP tool

573 if isinstance(message, AssistantMessage):

574 for block in message.content:

575 if hasattr(block, "name") and block.name.startswith("mcp__"):

576 print("MCP tool called:", block.name)

577

578 # Print the final result

579 if isinstance(message, ResultMessage) and message.subtype == "success":

580 print(message.result)

581

582

583 asyncio.run(main())

584 ```

585</CodeGroup>

586

587### Consultar um banco de dados

588

589Este exemplo usa o [servidor Postgres MCP](https://github.com/modelcontextprotocol/servers/tree/main/src/postgres) para consultar um banco de dados. A string de conexão é passada como um argumento para o servidor. O agente descobre automaticamente o esquema do banco de dados, escreve a consulta SQL e retorna os resultados:

590

591<CodeGroup>

592 ```typescript TypeScript theme={null}

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

594

595 // Connection string from environment variable

596 const connectionString = process.env.DATABASE_URL;

597

598 for await (const message of query({

599 // Natural language query - Claude writes the SQL

600 prompt: "How many users signed up last week? Break it down by day.",

601 options: {

602 mcpServers: {

603 postgres: {

604 command: "npx",

605 // Pass connection string as argument to the server

606 args: ["-y", "@modelcontextprotocol/server-postgres", connectionString]

607 }

608 },

609 // Allow only read queries, not writes

610 allowedTools: ["mcp__postgres__query"]

611 }

612 })) {

613 if (message.type === "result" && message.subtype === "success") {

614 console.log(message.result);

615 }

616 }

617 ```

618

619 ```python Python theme={null}

620 import asyncio

621 import os

622 from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

623

624

625 async def main():

626 # Connection string from environment variable

627 connection_string = os.environ["DATABASE_URL"]

628

629 options = ClaudeAgentOptions(

630 mcp_servers={

631 "postgres": {

632 "command": "npx",

633 # Pass connection string as argument to the server

634 "args": [

635 "-y",

636 "@modelcontextprotocol/server-postgres",

637 connection_string,

638 ],

639 }

640 },

641 # Allow only read queries, not writes

642 allowed_tools=["mcp__postgres__query"],

643 )

644

645 # Natural language query - Claude writes the SQL

646 async for message in query(

647 prompt="How many users signed up last week? Break it down by day.",

648 options=options,

649 ):

650 if isinstance(message, ResultMessage) and message.subtype == "success":

651 print(message.result)

652

653

654 asyncio.run(main())

655 ```

656</CodeGroup>

657

658## Tratamento de erros

659

660Os servidores MCP podem falhar ao conectar por vários motivos: o processo do servidor pode não estar instalado, as credenciais podem ser inválidas ou um servidor remoto pode estar inacessível.

661

662O SDK emite uma mensagem `system` com subtipo `init` no início de cada consulta. Esta mensagem inclui o status de conexão para cada servidor MCP. Verifique o campo `status` para detectar falhas de conexão antes que o agente comece a trabalhar:

663

664<CodeGroup>

665 ```typescript TypeScript theme={null}

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

667

668 for await (const message of query({

669 prompt: "Process data",

670 options: {

671 mcpServers: {

672 "data-processor": dataServer

673 }

674 }

675 })) {

676 if (message.type === "system" && message.subtype === "init") {

677 const failedServers = message.mcp_servers.filter((s) => s.status !== "connected");

678

679 if (failedServers.length > 0) {

680 console.warn("Failed to connect:", failedServers);

681 }

682 }

683

684 if (message.type === "result" && message.subtype === "error_during_execution") {

685 console.error("Execution failed");

686 }

687 }

688 ```

689

690 ```python Python theme={null}

691 import asyncio

692 from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage, ResultMessage

693

694

695 async def main():

696 options = ClaudeAgentOptions(mcp_servers={"data-processor": data_server})

697

698 async for message in query(prompt="Process data", options=options):

699 if isinstance(message, SystemMessage) and message.subtype == "init":

700 failed_servers = [

701 s

702 for s in message.data.get("mcp_servers", [])

703 if s.get("status") != "connected"

704 ]

705

706 if failed_servers:

707 print(f"Failed to connect: {failed_servers}")

708

709 if (

710 isinstance(message, ResultMessage)

711 and message.subtype == "error_during_execution"

712 ):

713 print("Execution failed")

714

715

716 asyncio.run(main())

717 ```

718</CodeGroup>

719

720## Solução de problemas

721

722### Servidor mostra status "failed"

723

724Verifique a mensagem `init` para ver quais servidores falharam ao conectar:

725

726```typescript theme={null}

727if (message.type === "system" && message.subtype === "init") {

728 for (const server of message.mcp_servers) {

729 if (server.status === "failed") {

730 console.error(`Server ${server.name} failed to connect`);

731 }

732 }

733}

734```

735

736Causas comuns:

737

738* **Variáveis de ambiente ausentes**: Certifique-se de que tokens e credenciais necessários estão definidos. Para servidores stdio, verifique se o campo `env` corresponde ao que o servidor espera.

739* **Servidor não instalado**: Para comandos `npx`, verifique se o pacote existe e se Node.js está em seu PATH.

740* **String de conexão inválida**: Para servidores de banco de dados, verifique o formato da string de conexão e se o banco de dados está acessível.

741* **Problemas de rede**: Para servidores HTTP/SSE remotos, verifique se a URL está acessível e se algum firewall permite a conexão.

742

743### Ferramentas não sendo chamadas

744

745Se Claude vê ferramentas mas não as usa, verifique se você concedeu permissão com `allowedTools`:

746

747```typescript hidelines={1,-1} theme={null}

748const _ = {

749 options: {

750 mcpServers: {

751 // your servers

752 },

753 allowedTools: ["mcp__servername__*"] // Required for Claude to use the tools

754 }

755};

756```

757

758### Tempos limite de conexão

759

760O SDK MCP tem um tempo limite padrão de 60 segundos para conexões de servidor. Se seu servidor levar mais tempo para iniciar, a conexão falhará. Para servidores que precisam de mais tempo de inicialização, considere:

761

762* Usar um servidor mais leve se disponível

763* Pré-aquecer o servidor antes de iniciar seu agente

764* Verificar logs do servidor para causas de inicialização lenta

765

766## Recursos relacionados

767

768* **[Guia de ferramentas personalizadas](/pt/agent-sdk/custom-tools)**: Construa seu próprio servidor MCP que é executado em processo com sua aplicação SDK

769* **[Permissões](/pt/agent-sdk/permissions)**: Controle quais ferramentas MCP seu agente pode usar com `allowedTools` e `disallowedTools`

770* **[Referência do SDK TypeScript](/pt/agent-sdk/typescript)**: Referência completa da API incluindo opções de configuração de MCP

771* **[Referência do SDK Python](/pt/agent-sdk/python)**: Referência completa da API incluindo opções de configuração de MCP

772* **[Diretório de servidores MCP](https://github.com/modelcontextprotocol/servers)**: Procure servidores MCP disponíveis para bancos de dados, APIs e muito mais

agent-sdk/python.md +2 −1

Details

836| `setting_sources` | `list[SettingSource] \| None` | `None` (CLI defaults: all sources) | Controle quais configurações do sistema de arquivos carregar. Passe `[]` para desabilitar configurações de usuário, projeto e local. Configurações de política gerenciada carregam independentemente. Veja [Use Claude Code features](/pt/agent-sdk/claude-code-features#what-settingsources-does-not-control) |836| `setting_sources` | `list[SettingSource] \| None` | `None` (CLI defaults: all sources) | Controle quais configurações do sistema de arquivos carregar. Passe `[]` para desabilitar configurações de usuário, projeto e local. Configurações de política gerenciada carregam independentemente. Veja [Use Claude Code features](/pt/agent-sdk/claude-code-features#what-settingsources-does-not-control) |

837| `skills` | `list[str] \| Literal["all"] \| None` | `None` | Skills disponíveis para a sessão. Passe `"all"` para ativar cada skill descoberto, ou uma lista de nomes de skills. Quando definido, o SDK ativa a ferramenta Skill automaticamente sem listá-la em `allowed_tools`. Veja [Skills](/pt/agent-sdk/skills) |

1049| `tools` | Não | Array de nomes de ferramentas permitidas. Se omitido, herda todas as ferramentas |1050| `tools` | Não | Array de nomes de ferramentas permitidas. Se omitido, herda todas as ferramentas |

1050| `disallowedTools` | Não | Array de nomes de ferramentas a remover do conjunto de ferramentas do agente |1051| `disallowedTools` | Não | Array de nomes de ferramentas a remover do conjunto de ferramentas do agente |

1051| `model` | Não | Substituição de modelo para este agente. Aceita um alias como `"sonnet"`, `"opus"`, `"haiku"`, ou `"inherit"`, ou um ID de modelo completo. Se omitido, usa o modelo principal |1052| `model` | Não | Substituição de modelo para este agente. Aceita um alias como `"sonnet"`, `"opus"`, `"haiku"`, ou `"inherit"`, ou um ID de modelo completo. Se omitido, usa o modelo principal |

1052| `skills` | Não | Lista de nomes de skills disponíveis para este agente |1053| `skills` | Não | Lista de nomes de skills a pré-carregar no contexto do agente na inicialização. Skills não listados permanecem invocáveis através da ferramenta Skill |

1053| `memory` | Não | Fonte de memória para este agente: `"user"`, `"project"`, ou `"local"` |1054| `memory` | Não | Fonte de memória para este agente: `"user"`, `"project"`, ou `"local"` |

1054| `mcpServers` | Não | Servidores MCP disponíveis para este agente. Cada entrada é um nome de servidor ou um dict `{name: config}` inline |1055| `mcpServers` | Não | Servidores MCP disponíveis para este agente. Cada entrada é um nome de servidor ou um dict `{name: config}` inline |

1055| `initialPrompt` | Não | Auto-enviado como o primeiro turno de usuário quando este agente é executado como o agente de thread principal |1056| `initialPrompt` | Não | Auto-enviado como o primeiro turno de usuário quando este agente é executado como o agente de thread principal |

agent-sdk/sessions.md +324 −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# Trabalhar com sessões

7> Como as sessões persistem o histórico de conversas do agente e quando usar continue, resume e fork para retornar a uma execução anterior.

9Uma sessão é o histórico de conversas que o SDK acumula enquanto seu agente trabalha. Ela contém seu prompt, cada chamada de ferramenta que o agente fez, cada resultado de ferramenta e cada resposta. O SDK a escreve em disco automaticamente para que você possa retornar a ela mais tarde.

11Retornar a uma sessão significa que o agente tem contexto completo de antes: arquivos que já leu, análises que já realizou, decisões que já tomou. Você pode fazer uma pergunta de acompanhamento, se recuperar de uma interrupção ou ramificar para tentar uma abordagem diferente.

13<Note>

14 As sessões persistem a **conversa**, não o sistema de arquivos. Para capturar e reverter alterações de arquivo que o agente fez, use [file checkpointing](/pt/agent-sdk/file-checkpointing).

15</Note>

17Este guia cobre como escolher a abordagem certa para seu aplicativo, as interfaces do SDK que rastreiam sessões automaticamente, como capturar IDs de sessão e usar `resume` e `fork` manualmente, e o que você precisa saber sobre retomar sessões entre hosts.

19## Escolha uma abordagem

21Quanto gerenciamento de sessão você precisa depende da forma do seu aplicativo. O gerenciamento de sessão entra em jogo quando você envia múltiplos prompts que devem compartilhar contexto. Dentro de uma única chamada `query()`, o agente já faz quantas voltas precisar, e prompts de permissão e `AskUserQuestion` são [tratados em loop](/pt/agent-sdk/user-input) (eles não encerram a chamada).

23| O que você está construindo | O que usar |

24| :-------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |

25| Tarefa única: prompt único, sem acompanhamento | Nada extra. Uma chamada `query()` resolve. |

26| Chat multi-turno em um processo | [`ClaudeSDKClient` (Python) ou `continue: true` (TypeScript)](#automatic-session-management). O SDK rastreia a sessão para você sem nenhum tratamento de ID. |

27| Retomar de onde parou após reinicialização do processo | `continue_conversation=True` (Python) / `continue: true` (TypeScript). Retoma a sessão mais recente no diretório, sem necessidade de ID. |

28| Retomar uma sessão passada específica (não a mais recente) | Capture o ID da sessão e passe para `resume`. |

29| Tentar uma abordagem alternativa sem perder a original | Faça fork da sessão. |

30| Tarefa sem estado, não quer nada escrito em disco (apenas TypeScript) | Defina [`persistSession: false`](/pt/agent-sdk/typescript#options). A sessão existe apenas na memória durante a chamada. Python sempre persiste em disco. |

32### Continue, resume e fork

34Continue, resume e fork são campos de opção que você define em `query()` ([`ClaudeAgentOptions`](/pt/agent-sdk/python#claudeagentoptions) em Python, [`Options`](/pt/agent-sdk/typescript#options) em TypeScript).

36**Continue** e **resume** ambos retomam uma sessão existente e adicionam a ela. A diferença é como eles encontram essa sessão:

38* **Continue** encontra a sessão mais recente no diretório atual. Você não rastreia nada. Funciona bem quando seu aplicativo executa uma conversa por vez.

39* **Resume** recebe um ID de sessão específico. Você rastreia o ID. Necessário quando você tem múltiplas sessões (por exemplo, uma por usuário em um aplicativo multi-usuário) ou quer retornar a uma que não é a mais recente.

41**Fork** é diferente: cria uma nova sessão que começa com uma cópia do histórico da original. A original permanece inalterada. Use fork para tentar uma direção diferente enquanto mantém a opção de voltar.

43## Gerenciamento automático de sessão

45Ambos os SDKs oferecem uma interface que rastreia o estado da sessão para você entre chamadas, para que você não passe IDs manualmente. Use-os para conversas multi-turno dentro de um único processo.

47### Python: `ClaudeSDKClient`

49[`ClaudeSDKClient`](/pt/agent-sdk/python#claudesdkclient) trata IDs de sessão internamente. Cada chamada para `client.query()` continua automaticamente a mesma sessão. Chame [`client.receive_response()`](/pt/agent-sdk/python#claudesdkclient) para iterar sobre as mensagens da consulta atual. O cliente deve ser usado como um gerenciador de contexto assíncrono.

51Este exemplo executa duas consultas contra o mesmo `client`. A primeira pede ao agente para analisar um módulo; a segunda pede para refatorar esse módulo. Como ambas as chamadas passam pela mesma instância do cliente, a segunda consulta tem contexto completo da primeira sem nenhum `resume` ou ID de sessão explícito:

53```python Python theme={null}

54import asyncio

55from claude_agent_sdk import (

56 ClaudeSDKClient,

57 ClaudeAgentOptions,

58 AssistantMessage,

59 ResultMessage,

60 TextBlock,

61)

64def print_response(message):

65 """Print only the human-readable parts of a message."""

66 if isinstance(message, AssistantMessage):

67 for block in message.content:

68 if isinstance(block, TextBlock):

69 print(block.text)

70 elif isinstance(message, ResultMessage):

71 cost = (

72 f"${message.total_cost_usd:.4f}"

73 if message.total_cost_usd is not None

74 else "N/A"

75 )

76 print(f"[done: {message.subtype}, cost: {cost}]")

79async def main():

80 options = ClaudeAgentOptions(

81 allowed_tools=["Read", "Edit", "Glob", "Grep"],

82 )

84 async with ClaudeSDKClient(options=options) as client:

85 # First query: client captures the session ID internally

86 await client.query("Analyze the auth module")

87 async for message in client.receive_response():

88 print_response(message)

90 # Second query: automatically continues the same session

91 await client.query("Now refactor it to use JWT")

92 async for message in client.receive_response():

93 print_response(message)

96asyncio.run(main())

97```

99Veja a [referência do SDK Python](/pt/agent-sdk/python#choosing-between-query-and-claudesdkclient) para detalhes sobre quando usar `ClaudeSDKClient` versus a função `query()` independente.

100

101### TypeScript: `continue: true`

102

103O SDK TypeScript estável (a função `query()` usada em toda esta documentação, às vezes chamada de V1) não tem um objeto cliente que mantém sessão como o `ClaudeSDKClient` do Python. Em vez disso, passe `continue: true` em cada chamada `query()` subsequente e o SDK retoma a sessão mais recente no diretório atual. Nenhum rastreamento de ID necessário.

104

105Este exemplo faz duas chamadas `query()` separadas. A primeira cria uma sessão nova; a segunda define `continue: true`, que diz ao SDK para encontrar e retomar a sessão mais recente em disco. O agente tem contexto completo da primeira chamada:

106

107```typescript TypeScript theme={null}

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

109

110// First query: creates a new session

111for await (const message of query({

112 prompt: "Analyze the auth module",

113 options: { allowedTools: ["Read", "Glob", "Grep"] }

114})) {

115 if (message.type === "result" && message.subtype === "success") {

116 console.log(message.result);

117 }

118}

119

120// Second query: continue: true resumes the most recent session

121for await (const message of query({

122 prompt: "Now refactor it to use JWT",

123 options: {

124 continue: true,

125 allowedTools: ["Read", "Edit", "Write", "Glob", "Grep"]

126 }

127})) {

128 if (message.type === "result" && message.subtype === "success") {

129 console.log(message.result);

130 }

131}

132```

133

134<Note>

135 A [API de sessão V2](/pt/agent-sdk/typescript-v2-preview) experimental, que fornecia `createSession()` com um padrão `send` / `stream`, está descontinuada. Use a função V1 `query()` e as opções de sessão descritas nesta página.

136</Note>

137

138## Use opções de sessão com `query()`

139

140### Capture o ID da sessão

141

142Resume e fork requerem um ID de sessão. Leia-o do campo `session_id` na mensagem de resultado ([`ResultMessage`](/pt/agent-sdk/python#resultmessage) em Python, [`SDKResultMessage`](/pt/agent-sdk/typescript#sdkresultmessage) em TypeScript), que está presente em cada resultado independentemente de sucesso ou erro. Em TypeScript, o ID também está disponível mais cedo como um campo direto na `SystemMessage` de inicialização; em Python, está aninhado dentro de `SystemMessage.data`.

143

144<CodeGroup>

145 ```python Python theme={null}

146 import asyncio

147 from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

148

149

150 async def main():

151 session_id = None

152

153 async for message in query(

154 prompt="Analyze the auth module and suggest improvements",

155 options=ClaudeAgentOptions(

156 allowed_tools=["Read", "Glob", "Grep"],

157 ),

158 ):

159 if isinstance(message, ResultMessage):

160 session_id = message.session_id

161 if message.subtype == "success":

162 print(message.result)

163

164 print(f"Session ID: {session_id}")

165 return session_id

166

167

168 session_id = asyncio.run(main())

169 ```

170

171 ```typescript TypeScript theme={null}

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

173

174 let sessionId: string | undefined;

175

176 for await (const message of query({

177 prompt: "Analyze the auth module and suggest improvements",

178 options: { allowedTools: ["Read", "Glob", "Grep"] }

179 })) {

180 if (message.type === "result") {

181 sessionId = message.session_id;

182 if (message.subtype === "success") {

183 console.log(message.result);

184 }

185 }

186 }

187

188 console.log(`Session ID: ${sessionId}`);

189 ```

190</CodeGroup>

191

192### Retomar por ID

193

194Passe um ID de sessão para `resume` para retornar a essa sessão específica. O agente retoma com contexto completo de onde a sessão parou. Razões comuns para retomar:

195

196* **Acompanhamento de uma tarefa concluída.** O agente já analisou algo; agora você quer que ele aja com base nessa análise sem reler arquivos.

197* **Recuperação de um limite.** A primeira execução terminou com `error_max_turns` ou `error_max_budget_usd` (veja [Handle the result](/pt/agent-sdk/agent-loop#handle-the-result)); retome com um limite mais alto.

198* **Reiniciar seu processo.** Você capturou o ID antes do desligamento e quer restaurar a conversa.

199

200Este exemplo retoma a sessão de [Capture o ID da sessão](#capture-the-session-id) com um prompt de acompanhamento. Como você está retomando, o agente já tem a análise anterior em contexto:

201

202<CodeGroup>

203 ```python Python theme={null}

204 # Earlier session analyzed the code; now build on that analysis

205 async for message in query(

206 prompt="Now implement the refactoring you suggested",

207 options=ClaudeAgentOptions(

208 resume=session_id,

209 allowed_tools=["Read", "Edit", "Write", "Glob", "Grep"],

210 ),

211 ):

212 if isinstance(message, ResultMessage) and message.subtype == "success":

213 print(message.result)

214 ```

215

216 ```typescript TypeScript theme={null}

217 // Earlier session analyzed the code; now build on that analysis

218 for await (const message of query({

219 prompt: "Now implement the refactoring you suggested",

220 options: {

221 resume: sessionId,

222 allowedTools: ["Read", "Edit", "Write", "Glob", "Grep"]

223 }

224 })) {

225 if (message.type === "result" && message.subtype === "success") {

226 console.log(message.result);

227 }

228 }

229 ```

230</CodeGroup>

231

232<Tip>

233 Se uma chamada `resume` retornar uma sessão nova em vez do histórico esperado, a causa mais comum é um `cwd` incompatível. As sessões são armazenadas em `~/.claude/projects/<encoded-cwd>/*.jsonl`, onde `<encoded-cwd>` é o diretório de trabalho absoluto com cada caractere não alfanumérico substituído por `-` (então `/Users/me/proj` se torna `-Users-me-proj`). Se sua chamada resume for executada de um diretório diferente, o SDK procura no lugar errado. O arquivo de sessão também precisa existir na máquina atual.

234</Tip>

235

236Para retomar sessões entre máquinas ou em ambientes sem servidor, espelhe transcrições para armazenamento compartilhado com um adaptador [`SessionStore`](/pt/agent-sdk/session-storage).

237

238### Fork para explorar alternativas

239

240Forking cria uma nova sessão que começa com uma cópia do histórico da original, mas diverge a partir desse ponto. O fork recebe seu próprio ID de sessão; o ID e histórico da original permanecem inalterados. Você acaba com duas sessões independentes que pode retomar separadamente.

241

242<Note>

243 Forking ramifica o histórico de conversas, não o sistema de arquivos. Se um agente com fork editar arquivos, essas alterações são reais e visíveis para qualquer sessão trabalhando no mesmo diretório. Para ramificar e reverter alterações de arquivo, use [file checkpointing](/pt/agent-sdk/file-checkpointing).

244</Note>

245

246Este exemplo se baseia em [Capture o ID da sessão](#capture-the-session-id): você já analisou um módulo de autenticação em `session_id` e quer explorar OAuth2 sem perder o thread focado em JWT. O primeiro bloco faz fork da sessão e captura o ID do fork (`forked_id`); o segundo bloco retoma o `session_id` original para continuar pelo caminho JWT. Você agora tem dois IDs de sessão apontando para dois históricos separados:

247

248<CodeGroup>

249 ```python Python theme={null}

250 # Fork: branch from session_id into a new session

251 forked_id = None

252 async for message in query(

253 prompt="Instead of JWT, implement OAuth2 for the auth module",

254 options=ClaudeAgentOptions(

255 resume=session_id,

256 fork_session=True,

257 ),

258 ):

259 if isinstance(message, ResultMessage):

260 forked_id = message.session_id # The fork's ID, distinct from session_id

261 if message.subtype == "success":

262 print(message.result)

263

264 print(f"Forked session: {forked_id}")

265

266 # Original session is untouched; resuming it continues the JWT thread

267 async for message in query(

268 prompt="Continue with the JWT approach",

269 options=ClaudeAgentOptions(resume=session_id),

270 ):

271 if isinstance(message, ResultMessage) and message.subtype == "success":

272 print(message.result)

273 ```

274

275 ```typescript TypeScript theme={null}

276 // Fork: branch from sessionId into a new session

277 let forkedId: string | undefined;

278

279 for await (const message of query({

280 prompt: "Instead of JWT, implement OAuth2 for the auth module",

281 options: {

282 resume: sessionId,

283 forkSession: true

284 }

285 })) {

286 if (message.type === "system" && message.subtype === "init") {

287 forkedId = message.session_id; // The fork's ID, distinct from sessionId

288 }

289 if (message.type === "result" && message.subtype === "success") {

290 console.log(message.result);

291 }

292 }

293

294 console.log(`Forked session: ${forkedId}`);

295

296 // Original session is untouched; resuming it continues the JWT thread

297 for await (const message of query({

298 prompt: "Continue with the JWT approach",

299 options: { resume: sessionId }

300 })) {

301 if (message.type === "result" && message.subtype === "success") {

302 console.log(message.result);

303 }

304 }

305 ```

306</CodeGroup>

307

308## Retomar entre hosts

309

310Os arquivos de sessão são locais para a máquina que os criou. Para retomar uma sessão em um host diferente (workers de CI, contêineres efêmeros, sem servidor), você tem duas opções:

311

312* **Mover o arquivo de sessão.** Persista `~/.claude/projects/<encoded-cwd>/<session-id>.jsonl` da primeira execução e restaure-o para o mesmo caminho no novo host antes de chamar `resume`. O `cwd` deve corresponder.

313* **Não confie em retomada de sessão.** Capture os resultados que você precisa (saída de análise, decisões, diffs de arquivo) como estado do aplicativo e passe-os para o prompt de uma sessão nova. Isso geralmente é mais robusto do que enviar arquivos de transcrição.

314

315Ambos os SDKs expõem funções para enumerar sessões em disco e ler suas mensagens: [`listSessions()`](/pt/agent-sdk/typescript#listsessions) e [`getSessionMessages()`](/pt/agent-sdk/typescript#getsessionmessages) em TypeScript, [`list_sessions()`](/pt/agent-sdk/python#list_sessions) e [`get_session_messages()`](/pt/agent-sdk/python#get_session_messages) em Python. Use-os para construir seletores de sessão personalizados, lógica de limpeza ou visualizadores de transcrição.

316

317Ambos os SDKs também expõem funções para procurar e mutar sessões individuais: [`get_session_info()`](/pt/agent-sdk/python#get_session_info), [`rename_session()`](/pt/agent-sdk/python#rename_session) e [`tag_session()`](/pt/agent-sdk/python#tag_session) em Python, e [`getSessionInfo()`](/pt/agent-sdk/typescript#getsessioninfo), [`renameSession()`](/pt/agent-sdk/typescript#renamesession) e [`tagSession()`](/pt/agent-sdk/typescript#tagsession) em TypeScript. Use-os para organizar sessões por tag ou dar-lhes títulos legíveis por humanos.

318

319## Recursos relacionados

320

321* [How the agent loop works](/pt/agent-sdk/agent-loop): Entenda voltas, mensagens e acumulação de contexto dentro de uma sessão

322* [File checkpointing](/pt/agent-sdk/file-checkpointing): Rastreie e reverta alterações de arquivo entre sessões

323* [Python `ClaudeAgentOptions`](/pt/agent-sdk/python#claudeagentoptions): Referência completa de opções de sessão para Python

324* [TypeScript `Options`](/pt/agent-sdk/typescript#options): Referência completa de opções de sessão para TypeScript

agent-sdk/skills.md +314 −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# Agent Skills no SDK

7> Estenda Claude com capacidades especializadas usando Agent Skills no Claude Agent SDK

9## Visão Geral

11Agent Skills estendem Claude com capacidades especializadas que Claude invoca autonomamente quando relevante. Skills são empacotadas como arquivos `SKILL.md` contendo instruções, descrições e recursos de suporte opcionais.

13Para informações abrangentes sobre Skills, incluindo benefícios, arquitetura e diretrizes de autoria, consulte a [visão geral de Agent Skills](https://platform.claude.com/docs/pt/agents-and-tools/agent-skills/overview).

15## Como Skills Funcionam com o SDK

17Ao usar o Claude Agent SDK, Skills são:

191. **Definidas como artefatos do sistema de arquivos**: Criadas como arquivos `SKILL.md` em diretórios específicos (`.claude/skills/`)

202. **Carregadas do sistema de arquivos**: Skills são carregadas de locais do sistema de arquivos governados por `settingSources` (TypeScript) ou `setting_sources` (Python)

213. **Descobertas automaticamente**: Uma vez que as configurações do sistema de arquivos são carregadas, os metadados de Skill são descobertos na inicialização a partir de diretórios de usuário e projeto; conteúdo completo carregado quando acionado

224. **Invocadas pelo modelo**: Claude escolhe autonomamente quando usá-las com base no contexto

235. **Filtradas via opção `skills`**: Skills descobertas são habilitadas por padrão. Passe uma lista de nomes de skills, `"all"`, ou `[]` para controlar quais estão disponíveis na sessão

25Diferentemente de subagentes (que podem ser definidos programaticamente), Skills devem ser criadas como artefatos do sistema de arquivos. O SDK não fornece uma API programática para registrar Skills.

27<Note>

28 Skills são descobertas através das fontes de configuração do sistema de arquivos. Com opções padrão de `query()`, o SDK carrega fontes de usuário e projeto, portanto skills em `~/.claude/skills/` e `<cwd>/.claude/skills/` estão disponíveis. Se você definir `settingSources` explicitamente, inclua `'user'` ou `'project'` para manter a descoberta de skills, ou use a [opção `plugins`](/pt/agent-sdk/plugins) para carregar skills de um caminho específico.

29</Note>

31## Usando Skills com o SDK

33Defina a opção `skills` em `query()` para controlar quais Skills estão disponíveis para a sessão. Quando omitida, Skills descobertas são habilitadas e a ferramenta Skill está disponível, correspondendo ao comportamento da CLI. Passe `"all"` para habilitar cada Skill descoberta, uma lista de nomes de Skill para habilitar apenas aquelas, ou `[]` para desabilitar todas. Quando você define `skills`, o SDK habilita a ferramenta Skill automaticamente, portanto você não precisa listá-la em `allowedTools`.

35Uma vez configurado, Claude descobre automaticamente Skills do sistema de arquivos e as invoca quando relevante para a solicitação do usuário.

37<CodeGroup>

38 ```python Python theme={null}

39 import asyncio

40 from claude_agent_sdk import query, ClaudeAgentOptions

43 async def main():

44 options = ClaudeAgentOptions(

45 cwd="/path/to/project", # Project with .claude/skills/

46 setting_sources=["user", "project"], # Load Skills from filesystem

47 skills="all", # Enable every discovered Skill

48 allowed_tools=["Read", "Write", "Bash"],

49 )

51 async for message in query(

52 prompt="Help me process this PDF document", options=options

53 ):

54 print(message)

57 asyncio.run(main())

58 ```

60 ```typescript TypeScript theme={null}

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

63 for await (const message of query({

64 prompt: "Help me process this PDF document",

65 options: {

66 cwd: "/path/to/project", // Project with .claude/skills/

67 settingSources: ["user", "project"], // Load Skills from filesystem

68 skills: "all", // Enable every discovered Skill

69 allowedTools: ["Read", "Write", "Bash"]

70 }

71 })) {

72 console.log(message);

73 }

74 ```

75</CodeGroup>

77Para habilitar apenas Skills específicas, passe seus nomes. Os nomes correspondem ao campo `name` em `SKILL.md` ou ao nome do diretório da Skill. Use `plugin:skill` para Skills fornecidas por plugin.

79<CodeGroup>

80 ```python Python theme={null}

81 options = ClaudeAgentOptions(skills=["pdf", "docx"])

82 ```

84 ```typescript TypeScript theme={null}

85 const options = { skills: ["pdf", "docx"] };

86 ```

87</CodeGroup>

89A opção `skills` é um filtro de contexto, não uma sandbox. Skills não listadas são ocultadas do modelo e rejeitadas pela ferramenta Skill, mas seus arquivos permanecem no disco e são acessíveis através de Read e Bash.

91## Locais de Skill

93Skills são carregadas de diretórios do sistema de arquivos com base na sua configuração `settingSources`/`setting_sources`:

95* **Project Skills** (`.claude/skills/`): Compartilhadas com sua equipe via git - carregadas quando `setting_sources` inclui `"project"`

96* **User Skills** (`~/.claude/skills/`): Skills pessoais em todos os projetos - carregadas quando `setting_sources` inclui `"user"`

97* **Plugin Skills**: Agrupadas com plugins Claude Code instalados

99## Criando Skills

100

101Skills são definidas como diretórios contendo um arquivo `SKILL.md` com frontmatter YAML e conteúdo Markdown. O campo `description` determina quando Claude invoca sua Skill.

102

103**Exemplo de estrutura de diretório**:

104

105```bash theme={null}

106.claude/skills/processing-pdfs/

107└── SKILL.md

108```

109

110Para orientação completa sobre criação de Skills, incluindo estrutura SKILL.md, Skills multi-arquivo e exemplos, consulte:

111

112* [Agent Skills no Claude Code](/pt/skills): Guia completo com exemplos

113* [Agent Skills Best Practices](https://platform.claude.com/docs/pt/agents-and-tools/agent-skills/best-practices): Diretrizes de autoria e convenções de nomenclatura

114

115## Restrições de Ferramenta

116

117<Note>

118 O campo frontmatter `allowed-tools` em SKILL.md é suportado apenas ao usar Claude Code CLI diretamente. **Ele não se aplica ao usar Skills através do SDK**.

119

120 Ao usar o SDK, controle o acesso à ferramenta através da opção principal `allowedTools` na sua configuração de query.

121</Note>

122

123Para controlar o acesso à ferramenta para Skills em aplicações SDK, use `allowedTools` para pré-aprovar ferramentas específicas. Sem um callback `canUseTool`, qualquer coisa não na lista é negada:

124

125<Note>

126 As instruções de importação do primeiro exemplo são assumidas nos seguintes trechos de código.

127</Note>

128

129<CodeGroup>

130 ```python Python theme={null}

131 options = ClaudeAgentOptions(

132 setting_sources=["user", "project"], # Load Skills from filesystem

133 skills="all",

134 allowed_tools=["Read", "Grep", "Glob"],

135 )

136

137 async for message in query(prompt="Analyze the codebase structure", options=options):

138 print(message)

139 ```

140

141 ```typescript TypeScript theme={null}

142 for await (const message of query({

143 prompt: "Analyze the codebase structure",

144 options: {

145 settingSources: ["user", "project"], // Load Skills from filesystem

146 skills: "all",

147 allowedTools: ["Read", "Grep", "Glob"],

148 permissionMode: "dontAsk" // Deny anything not in allowedTools

149 }

150 })) {

151 console.log(message);

152 }

153 ```

154</CodeGroup>

155

156## Descobrindo Skills Disponíveis

157

158Para ver quais Skills estão disponíveis em sua aplicação SDK, simplesmente pergunte a Claude:

159

160<CodeGroup>

161 ```python Python theme={null}

162 options = ClaudeAgentOptions(

163 setting_sources=["user", "project"], # Load Skills from filesystem

164 skills="all",

165 )

166

167 async for message in query(prompt="What Skills are available?", options=options):

168 print(message)

169 ```

170

171 ```typescript TypeScript theme={null}

172 for await (const message of query({

173 prompt: "What Skills are available?",

174 options: {

175 settingSources: ["user", "project"], // Load Skills from filesystem

176 skills: "all"

177 }

178 })) {

179 console.log(message);

180 }

181 ```

182</CodeGroup>

183

184Claude listará as Skills disponíveis com base no seu diretório de trabalho atual e plugins instalados.

185

186## Testando Skills

187

188Teste Skills fazendo perguntas que correspondam às suas descrições:

189

190<CodeGroup>

191 ```python Python theme={null}

192 options = ClaudeAgentOptions(

193 cwd="/path/to/project",

194 setting_sources=["user", "project"], # Load Skills from filesystem

195 skills="all",

196 allowed_tools=["Read", "Bash"],

197 )

198

199 async for message in query(prompt="Extract text from invoice.pdf", options=options):

200 print(message)

201 ```

202

203 ```typescript TypeScript theme={null}

204 for await (const message of query({

205 prompt: "Extract text from invoice.pdf",

206 options: {

207 cwd: "/path/to/project",

208 settingSources: ["user", "project"], // Load Skills from filesystem

209 skills: "all",

210 allowedTools: ["Read", "Bash"]

211 }

212 })) {

213 console.log(message);

214 }

215 ```

216</CodeGroup>

217

218Claude invoca automaticamente a Skill relevante se a descrição corresponder à sua solicitação.

219

220## Solução de Problemas

221

222### Skills Não Encontradas

223

224**Verifique a configuração settingSources**: Skills são descobertas através das fontes de configuração `user` e `project`. Se você definir `settingSources`/`setting_sources` explicitamente e omitir essas fontes, skills não são carregadas:

225

226<CodeGroup>

227 ```python Python theme={null}

228 # Skills not loaded: setting_sources excludes user and project

229 options = ClaudeAgentOptions(setting_sources=[], skills="all")

230

231 # Skills loaded: user and project sources included

232 options = ClaudeAgentOptions(

233 setting_sources=["user", "project"],

234 skills="all",

235 )

236 ```

237

238 ```typescript TypeScript theme={null}

239 // Skills not loaded: settingSources excludes user and project

240 const options = {

241 settingSources: [],

242 skills: "all"

243 };

244

245 // Skills loaded: user and project sources included

246 const options = {

247 settingSources: ["user", "project"],

248 skills: "all"

249 };

250 ```

251</CodeGroup>

252

253Para mais detalhes sobre `settingSources`/`setting_sources`, consulte a [referência TypeScript SDK](/pt/agent-sdk/typescript#settingsource) ou [referência Python SDK](/pt/agent-sdk/python#settingsource).

254

255**Verifique o diretório de trabalho**: O SDK carrega Skills relativo à opção `cwd`. Certifique-se de que aponta para um diretório contendo `.claude/skills/`:

256

257<CodeGroup>

258 ```python Python theme={null}

259 # Ensure your cwd points to the directory containing .claude/skills/

260 options = ClaudeAgentOptions(

261 cwd="/path/to/project", # Must contain .claude/skills/

262 setting_sources=["user", "project"], # Loads skills from these sources

263 skills="all",

264 )

265 ```

266

267 ```typescript TypeScript theme={null}

268 // Ensure your cwd points to the directory containing .claude/skills/

269 const options = {

270 cwd: "/path/to/project", // Must contain .claude/skills/

271 settingSources: ["user", "project"], // Loads skills from these sources

272 skills: "all"

273 };

274 ```

275</CodeGroup>

276

277Consulte a seção "Usando Skills com o SDK" acima para o padrão completo.

278

279**Verifique o local do sistema de arquivos**:

280

281```bash theme={null}

282# Check project Skills

283ls .claude/skills/*/SKILL.md

284

285# Check personal Skills

286ls ~/.claude/skills/*/SKILL.md

287```

288

289### Skill Não Sendo Usada

290

291**Verifique a opção `skills`**: Se você passou uma lista `skills`, confirme que o nome da skill está incluído. Passar `[]` desabilita todas as skills.

292

293**Verifique a descrição**: Certifique-se de que é específica e inclui palavras-chave relevantes. Consulte [Agent Skills Best Practices](https://platform.claude.com/docs/pt/agents-and-tools/agent-skills/best-practices#writing-effective-descriptions) para orientação sobre como escrever descrições eficazes.

294

295### Solução de Problemas Adicional

296

297Para solução de problemas geral de Skills (sintaxe YAML, depuração, etc.), consulte a [seção de solução de problemas de Skills do Claude Code](/pt/skills#troubleshooting).

298

299## Documentação Relacionada

300

301### Guias de Skills

302

303* [Agent Skills no Claude Code](/pt/skills): Guia completo de Skills com criação, exemplos e solução de problemas

304* [Agent Skills Overview](https://platform.claude.com/docs/pt/agents-and-tools/agent-skills/overview): Visão geral conceitual, benefícios e arquitetura

305* [Agent Skills Best Practices](https://platform.claude.com/docs/pt/agents-and-tools/agent-skills/best-practices): Diretrizes de autoria para Skills eficazes

306* [Agent Skills Cookbook](https://platform.claude.com/cookbook/skills-notebooks-01-skills-introduction): Skills de exemplo e templates

307

308### Recursos SDK

309

310* [Subagents no SDK](/pt/agent-sdk/subagents): Agentes similares baseados em sistema de arquivos com opções programáticas

311* [Slash Commands no SDK](/pt/agent-sdk/slash-commands): Comandos invocados pelo usuário

312* [Visão Geral do SDK](/pt/agent-sdk/overview): Conceitos gerais do SDK

313* [Referência TypeScript SDK](/pt/agent-sdk/typescript): Documentação completa da API

314* [Referência Python SDK](/pt/agent-sdk/python): Documentação completa da API

agent-sdk/subagents.md +601 −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# Subagentes no SDK

7> Defina e invoque subagentes para isolar contexto, executar tarefas em paralelo e aplicar instruções especializadas em suas aplicações Claude Agent SDK.

9Subagentes são instâncias de agente separadas que seu agente principal pode gerar para lidar com subtarefas focadas.

10Use subagentes para isolar contexto para subtarefas focadas, executar múltiplas análises em paralelo e aplicar instruções especializadas sem sobrecarregar o prompt do agente principal.

12Este guia explica como definir e usar subagentes no SDK usando o parâmetro `agents`.

14## Visão geral

16Você pode criar subagentes de três maneiras:

18* **Programaticamente**: use o parâmetro `agents` em suas opções `query()` ([TypeScript](/pt/agent-sdk/typescript#agentdefinition), [Python](/pt/agent-sdk/python#agentdefinition))

19* **Baseado em sistema de arquivos**: defina agentes como arquivos markdown em diretórios `.claude/agents/` (veja [definindo subagentes como arquivos](/pt/sub-agents))

20* **Propósito geral integrado**: Claude pode invocar o subagente integrado `general-purpose` a qualquer momento via a ferramenta Agent sem você definir nada

22Este guia se concentra na abordagem programática, que é recomendada para aplicações SDK.

24Quando você define subagentes, Claude determina se deve invocá-los com base no campo `description` de cada subagente. Escreva descrições claras que expliquem quando o subagente deve ser usado, e Claude delegará automaticamente tarefas apropriadas. Você também pode solicitar explicitamente um subagente pelo nome em seu prompt (por exemplo, "Use o agente code-reviewer para...").

26## Benefícios de usar subagentes

28### Isolamento de contexto

30Cada subagente é executado em sua própria conversa nova. Chamadas de ferramentas intermediárias e resultados permanecem dentro do subagente; apenas sua mensagem final retorna ao pai. Veja [O que subagentes herdam](#what-subagents-inherit) para saber exatamente o que está no contexto do subagente.

32**Exemplo:** um subagente `research-assistant` pode explorar dezenas de arquivos sem que nenhum desse conteúdo se acumule na conversa principal. O pai recebe um resumo conciso, não cada arquivo que o subagente leu.

34### Paralelização

36Múltiplos subagentes podem ser executados simultaneamente, acelerando dramaticamente fluxos de trabalho complexos.

38**Exemplo:** durante uma revisão de código, você pode executar os subagentes `style-checker`, `security-scanner` e `test-coverage` simultaneamente, reduzindo o tempo de revisão de minutos para segundos.

40### Instruções e conhecimento especializados

42Cada subagente pode ter prompts de sistema personalizados com expertise específica, melhores práticas e restrições.

44**Exemplo:** um subagente `database-migration` pode ter conhecimento detalhado sobre melhores práticas SQL, estratégias de reversão e verificações de integridade de dados que seriam ruído desnecessário nas instruções do agente principal.

46### Restrições de ferramentas

48Subagentes podem ser limitados a ferramentas específicas, reduzindo o risco de ações não intencionais.

50**Exemplo:** um subagente `doc-reviewer` pode ter acesso apenas às ferramentas Read e Grep, garantindo que possa analisar mas nunca modifique acidentalmente seus arquivos de documentação.

52## Criando subagentes

54### Definição programática (recomendada)

56Defina subagentes diretamente em seu código usando o parâmetro `agents`. Este exemplo cria dois subagentes: um revisor de código com acesso somente leitura e um executor de testes que pode executar comandos. A ferramenta `Agent` deve ser incluída em `allowedTools` já que Claude invoca subagentes através da ferramenta Agent.

58<CodeGroup>

59 ```python Python theme={null}

60 import asyncio

61 from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

64 async def main():

65 async for message in query(

66 prompt="Review the authentication module for security issues",

67 options=ClaudeAgentOptions(

68 # Agent tool is required for subagent invocation

69 allowed_tools=["Read", "Grep", "Glob", "Agent"],

70 agents={

71 "code-reviewer": AgentDefinition(

72 # description tells Claude when to use this subagent

73 description="Expert code review specialist. Use for quality, security, and maintainability reviews.",

74 # prompt defines the subagent's behavior and expertise

75 prompt="""You are a code review specialist with expertise in security, performance, and best practices.

77 When reviewing code:

78 - Identify security vulnerabilities

79 - Check for performance issues

80 - Verify adherence to coding standards

81 - Suggest specific improvements

83 Be thorough but concise in your feedback.""",

84 # tools restricts what the subagent can do (read-only here)

85 tools=["Read", "Grep", "Glob"],

86 # model overrides the default model for this subagent

87 model="sonnet",

88 ),

89 "test-runner": AgentDefinition(

90 description="Runs and analyzes test suites. Use for test execution and coverage analysis.",

91 prompt="""You are a test execution specialist. Run tests and provide clear analysis of results.

93 Focus on:

94 - Running test commands

95 - Analyzing test output

96 - Identifying failing tests

97 - Suggesting fixes for failures""",

98 # Bash access lets this subagent run test commands

99 tools=["Bash", "Read", "Grep"],

100 ),

101 },

102 ),

103 ):

104 if hasattr(message, "result"):

105 print(message.result)

106

107

108 asyncio.run(main())

109 ```

110

111 ```typescript TypeScript theme={null}

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

113

114 for await (const message of query({

115 prompt: "Review the authentication module for security issues",

116 options: {

117 // Agent tool is required for subagent invocation

118 allowedTools: ["Read", "Grep", "Glob", "Agent"],

119 agents: {

120 "code-reviewer": {

121 // description tells Claude when to use this subagent

122 description:

123 "Expert code review specialist. Use for quality, security, and maintainability reviews.",

124 // prompt defines the subagent's behavior and expertise

125 prompt: `You are a code review specialist with expertise in security, performance, and best practices.

126

127 When reviewing code:

128 - Identify security vulnerabilities

129 - Check for performance issues

130 - Verify adherence to coding standards

131 - Suggest specific improvements

132

133 Be thorough but concise in your feedback.`,

134 // tools restricts what the subagent can do (read-only here)

135 tools: ["Read", "Grep", "Glob"],

136 // model overrides the default model for this subagent

137 model: "sonnet"

138 },

139 "test-runner": {

140 description:

141 "Runs and analyzes test suites. Use for test execution and coverage analysis.",

142 prompt: `You are a test execution specialist. Run tests and provide clear analysis of results.

143

144 Focus on:

145 - Running test commands

146 - Analyzing test output

147 - Identifying failing tests

148 - Suggesting fixes for failures`,

149 // Bash access lets this subagent run test commands

150 tools: ["Bash", "Read", "Grep"]

151 }

152 }

153 }

154 })) {

155 if ("result" in message) console.log(message.result);

156 }

157 ```

158</CodeGroup>

159

160### Configuração de AgentDefinition

161

163| :---------------- | :---------------------------------------------------------- | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

176

177No SDK Python, esses nomes de campo usam camelCase para corresponder ao formato de transmissão. Veja a referência [`AgentDefinition`](/pt/agent-sdk/python#agentdefinition) para detalhes.

178

179<Note>

180 Subagentes não podem gerar seus próprios subagentes. Não inclua `Agent` no array `tools` de um subagente.

181</Note>

182

183### Definição baseada em sistema de arquivos (alternativa)

184

185Você também pode definir subagentes como arquivos markdown em diretórios `.claude/agents/`. Veja a [documentação de subagentes Claude Code](/pt/sub-agents) para detalhes sobre essa abordagem. Agentes definidos programaticamente têm precedência sobre agentes baseados em sistema de arquivos com o mesmo nome.

186

187<Note>

188 Mesmo sem definir subagentes personalizados, Claude pode gerar o subagente integrado `general-purpose` quando `Agent` está em seu `allowedTools`. Isso é útil para delegar tarefas de pesquisa ou exploração sem criar agentes especializados.

189</Note>

190

191## O que subagentes herdam

192

193A janela de contexto de um subagente começa nova (sem conversa pai) mas não está vazia. O único canal do pai para o subagente é a string de prompt da ferramenta Agent, então inclua quaisquer caminhos de arquivo, mensagens de erro ou decisões que o subagente precise diretamente nesse prompt.

194

195| O subagente recebe | O subagente não recebe |

196| :-------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------- |

197| Seu próprio prompt do sistema (`AgentDefinition.prompt`) e o prompt da ferramenta Agent | O histórico de conversa do pai ou resultados de ferramentas |

198| CLAUDE.md do projeto (carregado via `settingSources`) | Conteúdo de skill pré-carregado, a menos que listado em `AgentDefinition.skills` |

199| Definições de ferramentas (herdadas do pai, ou o subconjunto em `tools`) | O prompt do sistema do pai |

200

201<Note>

202 O pai recebe a mensagem final do subagente verbatim como o resultado da ferramenta Agent, mas pode resumi-la em sua própria resposta. Para preservar a saída do subagente verbatim na resposta voltada para o usuário, inclua uma instrução para fazer isso no prompt ou opção `systemPrompt` que você passa para a chamada **principal** `query()`.

203</Note>

204

205## Invocando subagentes

206

207### Invocação automática

208

209Claude decide automaticamente quando invocar subagentes com base na tarefa e na `description` de cada subagente. Por exemplo, se você definir um subagente `performance-optimizer` com a descrição "Performance optimization specialist for query tuning", Claude o invocará quando seu prompt mencionar otimizar consultas.

210

211Escreva descrições claras e específicas para que Claude possa corresponder tarefas ao subagente certo.

212

213### Invocação explícita

214

215Para garantir que Claude use um subagente específico, mencione-o pelo nome em seu prompt:

216

217```text theme={null}

218"Use the code-reviewer agent to check the authentication module"

219```

220

221Isso ignora a correspondência automática e invoca diretamente o subagente nomeado.

222

223### Configuração dinâmica de agente

224

225Você pode criar definições de agente dinamicamente com base em condições de tempo de execução. Este exemplo cria um revisor de segurança com diferentes níveis de rigor, usando um modelo mais poderoso para revisões rigorosas.

226

227<CodeGroup>

228 ```python Python theme={null}

229 import asyncio

230 from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

231

232

233 # Factory function that returns an AgentDefinition

234 # This pattern lets you customize agents based on runtime conditions

235 def create_security_agent(security_level: str) -> AgentDefinition:

236 is_strict = security_level == "strict"

237 return AgentDefinition(

238 description="Security code reviewer",

239 # Customize the prompt based on strictness level

240 prompt=f"You are a {'strict' if is_strict else 'balanced'} security reviewer...",

241 tools=["Read", "Grep", "Glob"],

242 # Key insight: use a more capable model for high-stakes reviews

243 model="opus" if is_strict else "sonnet",

244 )

245

246

247 async def main():

248 # The agent is created at query time, so each request can use different settings

249 async for message in query(

250 prompt="Review this PR for security issues",

251 options=ClaudeAgentOptions(

252 allowed_tools=["Read", "Grep", "Glob", "Agent"],

253 agents={

254 # Call the factory with your desired configuration

255 "security-reviewer": create_security_agent("strict")

256 },

257 ),

258 ):

259 if hasattr(message, "result"):

260 print(message.result)

261

262

263 asyncio.run(main())

264 ```

265

266 ```typescript TypeScript theme={null}

267 import { query, type AgentDefinition } from "@anthropic-ai/claude-agent-sdk";

268

269 // Factory function that returns an AgentDefinition

270 // This pattern lets you customize agents based on runtime conditions

271 function createSecurityAgent(securityLevel: "basic" | "strict"): AgentDefinition {

272 const isStrict = securityLevel === "strict";

273 return {

274 description: "Security code reviewer",

275 // Customize the prompt based on strictness level

276 prompt: `You are a ${isStrict ? "strict" : "balanced"} security reviewer...`,

277 tools: ["Read", "Grep", "Glob"],

278 // Key insight: use a more capable model for high-stakes reviews

279 model: isStrict ? "opus" : "sonnet"

280 };

281 }

282

283 // The agent is created at query time, so each request can use different settings

284 for await (const message of query({

285 prompt: "Review this PR for security issues",

286 options: {

287 allowedTools: ["Read", "Grep", "Glob", "Agent"],

288 agents: {

289 // Call the factory with your desired configuration

290 "security-reviewer": createSecurityAgent("strict")

291 }

292 }

293 })) {

294 if ("result" in message) console.log(message.result);

295 }

296 ```

297</CodeGroup>

298

299## Detectando invocação de subagente

300

301Subagentes são invocados via a ferramenta Agent. Para detectar quando um subagente é invocado, verifique blocos `tool_use` onde `name` é `"Agent"`. Mensagens de dentro do contexto de um subagente incluem um campo `parent_tool_use_id`.

302

303<Note>

304 O nome da ferramenta foi renomeado de `"Task"` para `"Agent"` no Claude Code v2.1.63. Lançamentos atuais do SDK emitem `"Agent"` em blocos `tool_use` mas ainda usam `"Task"` na lista de ferramentas `system:init` e em `result.permission_denials[].tool_name`. Verificar ambos os valores em `block.name` garante compatibilidade entre versões do SDK.

305</Note>

306

307Este exemplo itera através de mensagens transmitidas, registrando quando um subagente é invocado e quando mensagens subsequentes originam-se de dentro do contexto de execução desse subagente.

308

309<Note>

310 A estrutura de mensagem difere entre SDKs. Em Python, blocos de conteúdo são acessados diretamente via `message.content`. Em TypeScript, `SDKAssistantMessage` envolve a mensagem da API Claude, então o conteúdo é acessado via `message.message.content`.

311</Note>

312

313<CodeGroup>

314 ```python Python theme={null}

315 import asyncio

316 from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

317

318

319 async def main():

320 async for message in query(

321 prompt="Use the code-reviewer agent to review this codebase",

322 options=ClaudeAgentOptions(

323 allowed_tools=["Read", "Glob", "Grep", "Agent"],

324 agents={

325 "code-reviewer": AgentDefinition(

326 description="Expert code reviewer.",

327 prompt="Analyze code quality and suggest improvements.",

328 tools=["Read", "Glob", "Grep"],

329 )

330 },

331 ),

332 ):

333 # Check for subagent invocation. Match both names: older SDK

334 # versions emitted "Task", current versions emit "Agent".

335 if hasattr(message, "content") and message.content:

336 for block in message.content:

337 if getattr(block, "type", None) == "tool_use" and block.name in (

338 "Task",

339 "Agent",

340 ):

341 print(f"Subagent invoked: {block.input.get('subagent_type')}")

342

343 # Check if this message is from within a subagent's context

344 if hasattr(message, "parent_tool_use_id") and message.parent_tool_use_id:

345 print(" (running inside subagent)")

346

347 if hasattr(message, "result"):

348 print(message.result)

349

350

351 asyncio.run(main())

352 ```

353

354 ```typescript TypeScript theme={null}

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

356

357 for await (const message of query({

358 prompt: "Use the code-reviewer agent to review this codebase",

359 options: {

360 allowedTools: ["Read", "Glob", "Grep", "Agent"],

361 agents: {

362 "code-reviewer": {

363 description: "Expert code reviewer.",

364 prompt: "Analyze code quality and suggest improvements.",

365 tools: ["Read", "Glob", "Grep"]

366 }

367 }

368 }

369 })) {

370 const msg = message as any;

371

372 // Check for subagent invocation. Match both names: older SDK versions

373 // emitted "Task", current versions emit "Agent".

374 for (const block of msg.message?.content ?? []) {

375 if (block.type === "tool_use" && (block.name === "Task" || block.name === "Agent")) {

376 console.log(`Subagent invoked: ${block.input.subagent_type}`);

377 }

378 }

379

380 // Check if this message is from within a subagent's context

381 if (msg.parent_tool_use_id) {

382 console.log(" (running inside subagent)");

383 }

384

385 if ("result" in message) {

386 console.log(message.result);

387 }

388 }

389 ```

390</CodeGroup>

391

392## Retomando subagentes

393

394Subagentes podem ser retomados para continuar de onde pararam. Subagentes retomados retêm seu histórico de conversa completo, incluindo todas as chamadas de ferramentas anteriores, resultados e raciocínio. O subagente continua exatamente de onde parou em vez de começar do zero.

395

396Quando um subagente é concluído, Claude recebe seu ID de agente no resultado da ferramenta Agent. Para retomar um subagente programaticamente:

397

3981. **Capture o ID da sessão**: Extraia `session_id` de mensagens durante a primeira query

3992. **Extraia o ID do agente**: Analise `agentId` do conteúdo da mensagem

4003. **Retome a sessão**: Passe `resume: sessionId` nas opções da segunda query e inclua o ID do agente em seu prompt

401

402<Note>

403 Você deve retomar a mesma sessão para acessar a transcrição do subagente. Cada chamada `query()` inicia uma nova sessão por padrão, então passe `resume: sessionId` para continuar na mesma sessão.

404

405 Se você estiver usando um agente personalizado (não um integrado), você também precisa passar a mesma definição de agente no parâmetro `agents` para ambas as queries.

406</Note>

407

408O exemplo abaixo demonstra esse fluxo: a primeira query executa um subagente e captura o ID da sessão e ID do agente, então a segunda query retoma a sessão para fazer uma pergunta de acompanhamento que requer contexto da primeira análise.

409

410<CodeGroup>

411 ```typescript TypeScript theme={null}

412 import { query, type SDKMessage } from "@anthropic-ai/claude-agent-sdk";

413

414 // Helper to extract agentId from message content

415 // Stringify to avoid traversing different block types (TextBlock, ToolResultBlock, etc.)

416 function extractAgentId(message: SDKMessage): string | undefined {

417 if (!("message" in message)) return undefined;

418 // Stringify the content so we can search it without traversing nested blocks

419 const content = JSON.stringify(message.message.content);

420 const match = content.match(/agentId:\s*([a-f0-9-]+)/);

421 return match?.[1];

422 }

423

424 let agentId: string | undefined;

425 let sessionId: string | undefined;

426

427 // First invocation - use the Explore agent to find API endpoints

428 for await (const message of query({

429 prompt: "Use the Explore agent to find all API endpoints in this codebase",

430 options: { allowedTools: ["Read", "Grep", "Glob", "Agent"] }

431 })) {

432 // Capture session_id from ResultMessage (needed to resume this session)

433 if ("session_id" in message) sessionId = message.session_id;

434 // Search message content for the agentId (appears in Agent tool results)

435 const extractedId = extractAgentId(message);

436 if (extractedId) agentId = extractedId;

437 // Print the final result

438 if ("result" in message) console.log(message.result);

439 }

440

441 // Second invocation - resume and ask follow-up

442 if (agentId && sessionId) {

443 for await (const message of query({

444 prompt: `Resume agent ${agentId} and list the top 3 most complex endpoints`,

445 options: { allowedTools: ["Read", "Grep", "Glob", "Agent"], resume: sessionId }

446 })) {

447 if ("result" in message) console.log(message.result);

448 }

449 }

450 ```

451

452 ```python Python theme={null}

453 import asyncio

454 import json

455 import re

456 from claude_agent_sdk import query, ClaudeAgentOptions

457

458

459 def extract_agent_id(text: str) -> str | None:

460 """Extract agentId from Agent tool result text."""

461 match = re.search(r"agentId:\s*([a-f0-9-]+)", text)

462 return match.group(1) if match else None

463

464

465 async def main():

466 agent_id = None

467 session_id = None

468

469 # First invocation - use the Explore agent to find API endpoints

470 async for message in query(

471 prompt="Use the Explore agent to find all API endpoints in this codebase",

472 options=ClaudeAgentOptions(allowed_tools=["Read", "Grep", "Glob", "Agent"]),

473 ):

474 # Capture session_id from ResultMessage (needed to resume this session)

475 if hasattr(message, "session_id"):

476 session_id = message.session_id

477 # Search message content for the agentId (appears in Agent tool results)

478 if hasattr(message, "content"):

479 # Stringify the content so we can search it without traversing nested blocks

480 content_str = json.dumps(message.content, default=str)

481 extracted = extract_agent_id(content_str)

482 if extracted:

483 agent_id = extracted

484 # Print the final result

485 if hasattr(message, "result"):

486 print(message.result)

487

488 # Second invocation - resume and ask follow-up

489 if agent_id and session_id:

490 async for message in query(

491 prompt=f"Resume agent {agent_id} and list the top 3 most complex endpoints",

492 options=ClaudeAgentOptions(

493 allowed_tools=["Read", "Grep", "Glob", "Agent"], resume=session_id

494 ),

495 ):

496 if hasattr(message, "result"):

497 print(message.result)

498

499

500 asyncio.run(main())

501 ```

502</CodeGroup>

503

504Transcrições de subagentes persistem independentemente da conversa principal:

505

506* **Compactação de conversa principal**: Quando a conversa principal se compacta, transcrições de subagentes não são afetadas. Elas são armazenadas em arquivos separados.

507* **Persistência de sessão**: Transcrições de subagentes persistem dentro de sua sessão. Você pode retomar um subagente após reiniciar Claude Code retomando a mesma sessão.

508* **Limpeza automática**: Transcrições são limpas com base na configuração `cleanupPeriodDays` (padrão: 30 dias).

509

510## Restrições de ferramentas

511

512Subagentes podem ter acesso restrito a ferramentas via o campo `tools`:

513

514* **Omita o campo**: agente herda todas as ferramentas disponíveis (padrão)

515* **Especifique ferramentas**: agente pode usar apenas ferramentas listadas

516

517Este exemplo cria um agente de análise somente leitura que pode examinar código mas não pode modificar arquivos ou executar comandos.

518

519<CodeGroup>

520 ```python Python theme={null}

521 import asyncio

522 from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

523

524

525 async def main():

526 async for message in query(

527 prompt="Analyze the architecture of this codebase",

528 options=ClaudeAgentOptions(

529 allowed_tools=["Read", "Grep", "Glob", "Agent"],

530 agents={

531 "code-analyzer": AgentDefinition(

532 description="Static code analysis and architecture review",

533 prompt="""You are a code architecture analyst. Analyze code structure,

534 identify patterns, and suggest improvements without making changes.""",

535 # Read-only tools: no Edit, Write, or Bash access

536 tools=["Read", "Grep", "Glob"],

537 )

538 },

539 ),

540 ):

541 if hasattr(message, "result"):

542 print(message.result)

543

544

545 asyncio.run(main())

546 ```

547

548 ```typescript TypeScript theme={null}

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

550

551 for await (const message of query({

552 prompt: "Analyze the architecture of this codebase",

553 options: {

554 allowedTools: ["Read", "Grep", "Glob", "Agent"],

555 agents: {

556 "code-analyzer": {

557 description: "Static code analysis and architecture review",

558 prompt: `You are a code architecture analyst. Analyze code structure,

559 identify patterns, and suggest improvements without making changes.`,

560 // Read-only tools: no Edit, Write, or Bash access

561 tools: ["Read", "Grep", "Glob"]

562 }

563 }

564 }

565 })) {

566 if ("result" in message) console.log(message.result);

567 }

568 ```

569</CodeGroup>

570

571### Combinações comuns de ferramentas

572

573| Caso de uso | Ferramentas | Descrição |

574| :---------------------- | :-------------------------------------- | :---------------------------------------------------------- |

575| Análise somente leitura | `Read`, `Grep`, `Glob` | Pode examinar código mas não modificar ou executar |

576| Execução de testes | `Bash`, `Read`, `Grep` | Pode executar comandos e analisar saída |

577| Modificação de código | `Read`, `Edit`, `Write`, `Grep`, `Glob` | Acesso completo de leitura/escrita sem execução de comandos |

578| Acesso completo | Todas as ferramentas | Herda todas as ferramentas do pai (omita o campo `tools`) |

579

580## Troubleshooting

581

582### Claude não delegando para subagentes

583

584Se Claude completa tarefas diretamente em vez de delegar para seu subagente:

585

5861. **Inclua a ferramenta Agent**: subagentes são invocados via a ferramenta Agent, então ela deve estar em `allowedTools`

5872. **Use prompting explícito**: mencione o subagente pelo nome em seu prompt (por exemplo, "Use o agente code-reviewer para...")

5883. **Escreva uma descrição clara**: explique exatamente quando o subagente deve ser usado para que Claude possa corresponder tarefas apropriadamente

589

590### Agentes baseados em sistema de arquivos não carregando

591

592Agentes definidos em `.claude/agents/` são carregados apenas na inicialização. Se você criar um novo arquivo de agente enquanto Claude Code está em execução, reinicie a sessão para carregá-lo.

593

594### Windows: falhas de prompt longo

595

596No Windows, subagentes com prompts muito longos podem falhar devido a limites de comprimento de linha de comando (8191 caracteres). Mantenha prompts concisos ou use agentes baseados em sistema de arquivos para instruções complexas.

597

598## Documentação relacionada

599

600* [Subagentes Claude Code](/pt/sub-agents): documentação abrangente de subagentes incluindo definições baseadas em sistema de arquivos

601* [Visão geral do SDK](/pt/agent-sdk/overview): começando com o Claude Agent SDK

agent-sdk/typescript.md +5 −3

Details

334| `env` | `Record<string, string \| undefined>` | `process.env` | Variáveis de ambiente. Veja [Variáveis de ambiente](/pt/env-vars) para variáveis que a CLI subjacente lê, e [Handle slow or stalled API responses](#handle-slow-or-stalled-api-responses) para variáveis relacionadas a timeout. Defina `CLAUDE_AGENT_SDK_CLIENT_APP` para identificar sua aplicação no cabeçalho User-Agent |334| `env` | `Record<string, string \| undefined>` | `process.env` | Variáveis de ambiente. Veja [Variáveis de ambiente](/pt/env-vars) para variáveis que a CLI subjacente lê, e [Lidar com respostas de API lentas ou travadas](#handle-slow-or-stalled-api-responses) para variáveis relacionadas a timeout. Defina `CLAUDE_AGENT_SDK_CLIENT_APP` para identificar sua aplicação no cabeçalho User-Agent |

337| `extraArgs` | `Record<string, string \| null>` | `{}` | Argumentos adicionais |337| `extraArgs` | `Record<string, string \| null>` | `{}` | Argumentos adicionais |

358| `sessionStore` | [`SessionStore`](/pt/agent-sdk/session-storage#the-sessionstore-interface) | `undefined` | Espelhar transcrições de sessão para um backend externo para que qualquer host possa retomá-las. Veja [Persist sessions to external storage](/pt/agent-sdk/session-storage) |358| `sessionStore` | [`SessionStore`](/pt/agent-sdk/session-storage#the-sessionstore-interface) | `undefined` | Espelhar transcrições de sessão para um backend externo para que qualquer host possa retomá-las. Veja [Persist sessions to external storage](/pt/agent-sdk/session-storage) |

359| `settings` | `string \| Settings` | `undefined` | Objeto de [configurações](/pt/settings) inline ou caminho para um arquivo de configurações. Popula a camada de configurações de flag na [ordem de precedência](/pt/settings#settings-precedence). Altere em tempo de execução com [`applyFlagSettings()`](#applyflagsettings) |359| `settings` | `string \| Settings` | `undefined` | Objeto de [configurações](/pt/settings) inline ou caminho para um arquivo de configurações. Popula a camada de configurações de flag na [ordem de precedência](/pt/settings#settings-precedence). Altere em tempo de execução com [`applyFlagSettings()`](#applyflagsettings) |

360| `settingSources` | [`SettingSource`](#settingsource)`[]` | Padrões da CLI (todas as fontes) | Controle quais configurações do sistema de arquivos carregar. Passe `[]` para desativar configurações de usuário, projeto e local. Configurações de política gerenciada carregam independentemente. Veja [Use Claude Code features](/pt/agent-sdk/claude-code-features#what-settingsources-does-not-control) |360| `settingSources` | [`SettingSource`](#settingsource)`[]` | Padrões da CLI (todas as fontes) | Controle quais configurações do sistema de arquivos carregar. Passe `[]` para desativar configurações de usuário, projeto e local. Configurações de política gerenciada carregam independentemente. Veja [Use Claude Code features](/pt/agent-sdk/claude-code-features#what-settingsources-does-not-control) |

361| `skills` | `string[] \| 'all'` | `undefined` | Skills disponíveis para a sessão. Passe `'all'` para ativar cada skill descoberta, ou uma lista de nomes de skills. Quando definido, o SDK ativa a ferramenta Skill automaticamente sem listá-la em `allowedTools`. Veja [Skills](/pt/agent-sdk/skills) |

361| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Função personalizada para gerar o processo Claude Code. Use para executar Claude Code em VMs, contêineres ou ambientes remotos |362| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Função personalizada para gerar o processo Claude Code. Use para executar Claude Code em VMs, contêineres ou ambientes remotos |

528```529```

529 530

531| :------------------------------------ | :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |532| :------------------------------------ | :---------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

532| `description` | Sim | Descrição em linguagem natural de quando usar este agente |533| `description` | Sim | Descrição em linguagem natural de quando usar este agente |

533| `tools` | Não | Array de nomes de ferramentas permitidas. Se omitido, herda todas as ferramentas do pai |534| `tools` | Não | Array de nomes de ferramentas permitidas. Se omitido, herda todas as ferramentas do pai. Para pré-carregar Skills no contexto do agente, use o campo `skills` em vez de listar `'Skill'` aqui |

534| `disallowedTools` | Não | Array de nomes de ferramentas para explicitamente desallocar para este agente |535| `disallowedTools` | Não | Array de nomes de ferramentas para explicitamente desallocar para este agente |

535| `prompt` | Sim | O prompt do sistema do agente |536| `prompt` | Sim | O prompt do sistema do agente |

536| `model` | Não | Substituição de modelo para este agente. Aceita um alias como `'sonnet'`, `'opus'`, `'haiku'`, `'inherit'`, ou um ID de modelo completo. Se omitido ou `'inherit'`, usa o modelo principal |537| `model` | Não | Substituição de modelo para este agente. Aceita um alias como `'sonnet'`, `'opus'`, `'haiku'`, `'inherit'`, ou um ID de modelo completo. Se omitido ou `'inherit'`, usa o modelo principal |

1176 transcript_path: string;1177 transcript_path: string;

1177 cwd: string;1178 cwd: string;

1178 permission_mode?: string;1179 permission_mode?: string;

1180 effort?: { level: string };

1179 agent_id?: string;1181 agent_id?: string;

1180 agent_type?: string;1182 agent_type?: string;

1181};1183};

agent-sdk/typescript-v2-preview.md +6 −10

Details

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt2> 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.3> Use this file to discover all available pages before exploring further.

4 4

~~5# Interface TypeScript SDK V2 (visualização)~~5# API de sessão TypeScript SDK V2 (descontinuada)

6 6

~~7> Visualização do SDK do Agent TypeScript V2 simplificado, com padrões de envio/stream baseados em sessão para conversas multi-turno.~~7> Referência para a API de sessão descontinuada V2 do SDK do Agent TypeScript, com padrões de envio/stream baseados em sessão para conversas multi-turno.

8 8

9<Warning>9<Warning>

10 A interface V2 é uma **visualização instável**. As APIs podem mudar com base em feedback antes de se tornarem estáveis. Alguns recursos como bifurcação de sessão estão disponíveis apenas no [SDK V1](/pt/agent-sdk/typescript).10 As funções da API de sessão V2 `unstable_v2_createSession`, `unstable_v2_resumeSession` e `unstable_v2_prompt` estão descontinuadas e serão removidas em uma versão futura. Use a [API V1 `query()`](/pt/agent-sdk/typescript) em seu lugar.

11</Warning>11</Warning>

12 12

13O SDK do Agent TypeScript Claude V2 remove a necessidade de geradores assíncronos e coordenação de yield. Isso torna as conversas multi-turno mais simples, em vez de gerenciar o estado do gerador entre turnos, cada turno é um ciclo `send()`/`stream()` separado. A superfície da API se reduz a três conceitos:13V2 era uma API de sessão experimental que removeu a necessidade de geradores assíncronos e coordenação de yield. Em vez de gerenciar o estado do gerador entre turnos, cada turno era um ciclo `send()`/`stream()` separado. A superfície da API se reduzia a três conceitos:

14 14

15* `createSession()` / `resumeSession()`: Iniciar ou continuar uma conversa15* `createSession()` / `resumeSession()`: Iniciar ou continuar uma conversa

16* `session.send()`: Enviar uma mensagem16* `session.send()`: Enviar uma mensagem

301 301

302### Limpeza302### Limpeza

303 303

304As sessões podem ser fechadas manualmente ou automaticamente usando [`await using`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html#using-declarations-and-explicit-resource-management), um recurso do TypeScript 5.2+ para limpeza automática de recursos. Se você estiver usando uma versão mais antiga do TypeScript ou encontrar problemas de compatibilidade, use limpeza manual.304As sessões podem ser fechadas manualmente ou automaticamente usando [`await using`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html#using-declarations-and-explicit-resource-management), um recurso do TypeScript 5.2+ para limpeza automática de recursos. Se você estiver usando uma versão mais antiga do TypeScript ou encontrar problemas de compatibilidade, use limpeza manual em seu lugar.

305 305

306**Limpeza automática (TypeScript 5.2+):**306**Limpeza automática (TypeScript 5.2+):**

307 307

380 380

381## Disponibilidade de recursos381## Disponibilidade de recursos

382 382

383Nem todos os recursos V1 estão disponíveis em V2 ainda. Os seguintes requerem o uso do [SDK V1](/pt/agent-sdk/typescript):383A API de sessão V2 não suporta todos os recursos V1. Os seguintes requerem o [SDK V1](/pt/agent-sdk/typescript):

384 384

385* Bifurcação de sessão (opção `forkSession`)385* Bifurcação de sessão (opção `forkSession`)

386* Alguns padrões avançados de entrada de streaming386* Alguns padrões avançados de entrada de streaming

387 387

388## Feedback

~~389~~

390Compartilhe seu feedback sobre a interface V2 antes que ela se torne estável. Relate problemas e sugestões através de [GitHub Issues](https://github.com/anthropics/claude-code/issues).

~~391~~

392## Veja também388## Veja também

393 389

394* [Referência do SDK TypeScript (V1)](/pt/agent-sdk/typescript) - Documentação completa do SDK V1390* [Referência do SDK TypeScript (V1)](/pt/agent-sdk/typescript) - Documentação completa do SDK V1

agent-teams.md +2 −2

Details

405* **Sem retomada de sessão com companheiros de equipe in-process**: `/resume` e `/rewind` não restauram companheiros de equipe in-process. Após retomar uma sessão, o líder pode tentar enviar mensagens para companheiros de equipe que não existem mais. Se isso acontecer, diga ao líder para gerar novos companheiros de equipe.405* **Sem retomada de sessão com companheiros de equipe in-process**: `/resume` e `/rewind` não restauram companheiros de equipe in-process. Após retomar uma sessão, o líder pode tentar enviar mensagens para companheiros de equipe que não existem mais. Se isso acontecer, diga ao líder para gerar novos companheiros de equipe.

406* **Status da tarefa pode ficar atrasado**: os companheiros de equipe às vezes falham em marcar tarefas como concluídas, o que bloqueia tarefas dependentes. Se uma tarefa parecer presa, verifique se o trabalho está realmente pronto e atualize o status da tarefa manualmente ou diga ao líder para dar um empurrão ao companheiro de equipe.406* **Status da tarefa pode ficar atrasado**: os companheiros de equipe às vezes falham em marcar tarefas como concluídas, o que bloqueia tarefas dependentes. Se uma tarefa parecer presa, verifique se o trabalho está realmente pronto e atualize o status da tarefa manualmente ou diga ao líder para dar um empurrão ao companheiro de equipe.

407* **Encerramento pode ser lento**: os companheiros de equipe terminam sua solicitação atual ou chamada de ferramenta antes de encerrar, o que pode levar tempo.407* **Encerramento pode ser lento**: os companheiros de equipe terminam sua solicitação atual ou chamada de ferramenta antes de encerrar, o que pode levar tempo.

408* **Uma equipe por sessão**: um líder pode gerenciar apenas uma equipe por vez. Limpe a equipe atual antes de iniciar uma nova.408* **Uma equipe por vez**: um líder pode gerenciar apenas uma equipe. Limpe a equipe atual antes de criar uma nova.

409* **Sem equipes aninhadas**: os companheiros de equipe não podem gerar suas próprias equipes ou companheiros de equipe. Apenas o líder pode gerenciar a equipe.409* **Sem equipes aninhadas**: os companheiros de equipe não podem gerar suas próprias equipes ou companheiros de equipe. Apenas o líder pode gerenciar a equipe.

410* **Líder é fixo**: a sessão que cria a equipe é o líder por sua vida útil. Você não pode promover um companheiro de equipe a líder ou transferir liderança.410* **Líder é fixo**: a sessão que cria a equipe é o líder por sua vida útil. Você não pode promover um companheiro de equipe a líder ou transferir liderança.

411* **Permissões definidas no tempo de geração**: todos os companheiros de equipe começam com o modo de permissão do líder. Você pode alterar modos de companheiros de equipe individuais após gerar, mas não pode definir modos por companheiro de equipe no tempo de geração.411* **Permissões definidas no tempo de geração**: todos os companheiros de equipe começam com o modo de permissão do líder. Você pode alterar modos de companheiros de equipe individuais após gerar, mas não pode definir modos por companheiro de equipe no tempo de geração.

420Explore abordagens relacionadas para trabalho paralelo e delegação:420Explore abordagens relacionadas para trabalho paralelo e delegação:

421 421

422* **Delegação leve**: [subagents](/pt/sub-agents) geram agentes auxiliares para pesquisa ou verificação dentro de sua sessão, melhor para tarefas que não precisam de coordenação entre agentes422* **Delegação leve**: [subagents](/pt/sub-agents) geram agentes auxiliares para pesquisa ou verificação dentro de sua sessão, melhor para tarefas que não precisam de coordenação entre agentes

423* **Sessões paralelas manuais**: [Git worktrees](/pt/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees) permitem que você execute múltiplas sessões Claude Code você mesmo sem coordenação de equipe automatizada423* **Sessões paralelas manuais**: [Git worktrees](/pt/worktrees) permitem que você execute múltiplas sessões Claude Code você mesmo sem coordenação de equipe automatizada

424* **Comparar abordagens**: veja a comparação [subagent vs agent team](/pt/features-overview#compare-similar-features) para um detalhamento lado a lado424* **Comparar abordagens**: veja a comparação [subagent vs agent team](/pt/features-overview#compare-similar-features) para um detalhamento lado a lado

amazon-bedrock.md +1 −111

Details

76 </div>;76 </div>;

77};77};

78 78

~~79export const Experiment = ({flag, treatment, children}) => {~~79<ContactSalesCard surface="bedrock" />

~~80 const VID_KEY = 'exp_vid';~~

81 const CONSENT_COUNTRIES = new Set(['AT', 'BE', 'BG', 'HR', 'CY', 'CZ', 'DK', 'EE', 'FI', 'FR', 'DE', 'GR', 'HU', 'IE', 'IT', 'LV', 'LT', 'LU', 'MT', 'NL', 'PL', 'PT', 'RO', 'SK', 'SI', 'ES', 'SE', 'RE', 'GP', 'MQ', 'GF', 'YT', 'BL', 'MF', 'PM', 'WF', 'PF', 'NC', 'AW', 'CW', 'SX', 'FO', 'GL', 'AX', 'GB', 'UK', 'AI', 'BM', 'IO', 'VG', 'KY', 'FK', 'GI', 'MS', 'PN', 'SH', 'TC', 'GG', 'JE', 'IM', 'CA', 'BR', 'IN']);

~~82 const fnv1a = s => {~~

~~83 let h = 0x811c9dc5;~~

~~84 for (let i = 0; i < s.length; i++) {~~

~~85 h ^= s.charCodeAt(i);~~

~~86 h += (h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24);~~

~~87 }~~

~~88 return h >>> 0;~~

~~89 };~~

~~90 const bucket = (seed, vid) => fnv1a(fnv1a(seed + vid) + '') % 10000 < 5000 ? 'control' : 'treatment';~~

~~91 const [decision] = useState(() => {~~

~~92 const params = new URLSearchParams(location.search);~~

~~93 const preBucketed = document.documentElement.dataset['gb_' + flag.replace(/-/g, '_')];~~

~~94 const force = params.get('gb-force');~~

~~95 if (force) {~~

~~96 for (const p of force.split(',')) {~~

~~97 const [k, v] = p.split(':');~~

~~98 if (k === flag) return {~~

~~99 variant: v || 'treatment',~~

100 track: false

101 };

102 }

103 }

104 if (navigator.globalPrivacyControl) {

105 return {

106 variant: 'control',

107 track: false

108 };

109 }

110 const prefsMatch = document.cookie.match(/(?:^|; )anthropic-consent-preferences=([^;]+)/);

111 if (prefsMatch) {

112 try {

113 if (JSON.parse(decodeURIComponent(prefsMatch[1])).analytics !== true) {

114 return {

115 variant: 'control',

116 track: false

117 };

118 }

119 } catch {

120 return {

121 variant: 'control',

122 track: false

123 };

124 }

125 } else {

126 const country = params.get('country')?.toUpperCase() || (document.cookie.match(/(?:^|; )cf_geo=([A-Z]{2})/) || [])[1];

127 if (!country || CONSENT_COUNTRIES.has(country)) {

128 return {

129 variant: 'control',

130 track: false

131 };

132 }

133 }

134 let vid;

135 try {

136 const ajsMatch = document.cookie.match(/(?:^|; )ajs_anonymous_id=([^;]+)/);

137 if (ajsMatch) {

138 vid = decodeURIComponent(ajsMatch[1]).replace(/^"|"$/g, '');

139 } else {

140 vid = localStorage.getItem(VID_KEY);

141 if (!vid) {

142 vid = crypto.randomUUID();

143 }

144 document.cookie = `ajs_anonymous_id=${vid}; domain=.claude.com; path=/; Secure; SameSite=Lax; max-age=31536000`;

145 }

146 try {

147 localStorage.setItem(VID_KEY, vid);

148 } catch {}

149 } catch {

150 return {

151 variant: 'control',

152 track: false

153 };

154 }

155 const variant = preBucketed === '1' ? 'treatment' : preBucketed === '0' ? 'control' : bucket(flag, vid);

156 return {

157 variant,

158 track: true,

159 vid

160 };

161 });

162 useEffect(() => {

163 if (!decision.track) return;

164 fetch('https://api.anthropic.com/api/event_logging/v2/batch', {

165 method: 'POST',

166 headers: {

167 'Content-Type': 'application/json',

168 'x-service-name': 'claude_code_docs'

169 },

170 body: JSON.stringify({

171 events: [{

172 event_type: 'GrowthbookExperimentEvent',

173 event_data: {

174 device_id: decision.vid,

175 anonymous_id: decision.vid,

176 timestamp: new Date().toISOString(),

177 experiment_id: flag,

178 variation_id: decision.variant === 'treatment' ? 1 : 0,

179 environment: 'production'

180 }

181 }]

182 }),

183 keepalive: true

184 }).catch(() => {});

185 }, []);

186 return decision.variant === 'treatment' ? treatment : children;

187};

~~188~~

189<Experiment flag="docs-contact-sales-cta" treatment={<ContactSalesCard surface="bedrock" />} />

190 80

191## Pré-requisitos81## Pré-requisitos

192 82

cli-reference.md +2 −2

Details

84| `--permission-mode` | Começar em um [modo de permissão](/pt/permission-modes) especificado. Aceita `default`, `acceptEdits`, `plan`, `auto`, `dontAsk` ou `bypassPermissions`. Substitui `defaultMode` dos arquivos de configuração | `claude --permission-mode plan` |84| `--permission-mode` | Começar em um [modo de permissão](/pt/permission-modes) especificado. Aceita `default`, `acceptEdits`, `plan`, `auto`, `dontAsk` ou `bypassPermissions`. Substitui `defaultMode` dos arquivos de configuração | `claude --permission-mode plan` |

85| `--permission-prompt-tool` | Especificar uma ferramenta MCP para lidar com prompts de permissão em modo não interativo | `claude -p --permission-prompt-tool mcp_auth_tool "query"` |85| `--permission-prompt-tool` | Especificar uma ferramenta MCP para lidar com prompts de permissão em modo não interativo | `claude -p --permission-prompt-tool mcp_auth_tool "query"` |

86| `--plugin-dir` | Carregar um plugin de um diretório ou arquivo `.zip` apenas para esta sessão. Cada sinalizador leva um caminho. Repita o sinalizador para vários plugins: `--plugin-dir A --plugin-dir B.zip` | `claude --plugin-dir ./my-plugin` |86| `--plugin-dir` | Carregar um plugin de um diretório ou arquivo `.zip` apenas para esta sessão. Cada sinalizador leva um caminho. Repita o sinalizador para vários plugins: `--plugin-dir A --plugin-dir B.zip` | `claude --plugin-dir ./my-plugin` |

87| `--plugin-url` | Buscar um arquivo `.zip` de plugin de uma URL apenas para esta sessão. Cada sinalizador leva uma URL. Repita o sinalizador para vários plugins | `claude --plugin-url https://example.com/plugin.zip` |87| `--plugin-url` | Buscar um arquivo `.zip` de plugin de uma URL apenas para esta sessão. Repita o sinalizador para vários plugins, ou passe URLs separadas por espaço em um único valor entre aspas | `claude --plugin-url https://example.com/plugin.zip` |

88| `--print`, `-p` | Imprimir resposta sem modo interativo (veja [documentação do Agent SDK](/pt/agent-sdk/overview) para detalhes de uso programático) | `claude -p "query"` |88| `--print`, `-p` | Imprimir resposta sem modo interativo (veja [documentação do Agent SDK](/pt/agent-sdk/overview) para detalhes de uso programático) | `claude -p "query"` |

90| `--remote-control`, `--rc` | Iniciar uma sessão interativa com [Remote Control](/pt/remote-control#start-a-remote-control-session) ativado para que você também possa controlá-la a partir de claude.ai ou do aplicativo Claude. Opcionalmente, passe um nome para a sessão | `claude --remote-control "My Project"` |90| `--remote-control`, `--rc` | Iniciar uma sessão interativa com [Remote Control](/pt/remote-control#start-a-remote-control-session) ativado para que você também possa controlá-la a partir de claude.ai ou do aplicativo Claude. Opcionalmente, passe um nome para a sessão | `claude --remote-control "My Project"` |

103| `--tools` | Restringir quais ferramentas integradas Claude pode usar. Use `""` para desativar todas, `"default"` para todas, ou nomes de ferramentas como `"Bash,Edit,Read"` | `claude --tools "Bash,Edit,Read"` |103| `--tools` | Restringir quais ferramentas integradas Claude pode usar. Use `""` para desativar todas, `"default"` para todas, ou nomes de ferramentas como `"Bash,Edit,Read"` | `claude --tools "Bash,Edit,Read"` |

104| `--verbose` | Ativar logging detalhado, mostra saída completa turno por turno. Substitui a configuração [`viewMode`](/pt/settings#available-settings) para esta sessão | `claude --verbose` |104| `--verbose` | Ativar logging detalhado, mostra saída completa turno por turno. Substitui a configuração [`viewMode`](/pt/settings#available-settings) para esta sessão | `claude --verbose` |

106| `--worktree`, `-w` | Iniciar Claude em um [git worktree](/pt/worktrees) isolado em `<repo>/.claude/worktrees/<name>`. Se nenhum nome for fornecido, um será gerado automaticamente | `claude -w feature-auth` |106| `--worktree`, `-w` | Iniciar Claude em um [git worktree](/pt/worktrees) isolado em `<repo>/.claude/worktrees/<name>`. Se nenhum nome for fornecido, um será gerado automaticamente. Passe `#<number>` ou uma URL de pull request do GitHub para buscar esse PR de `origin` e ramificar o worktree a partir dele | `claude -w feature-auth` |

107 107

108### Sinalizadores de prompt do sistema108### Sinalizadores de prompt do sistema

109 109

commands.md +21 −3

Details

12 12

13Um comando é reconhecido apenas no início da sua mensagem. O texto que segue o nome do comando é passado para ele como argumentos.13Um comando é reconhecido apenas no início da sua mensagem. O texto que segue o nome do comando é passado para ele como argumentos.

14 14

15A tabela abaixo lista todos os comandos incluídos no Claude Code. As entradas marcadas como **[Skill](/pt/skills#bundled-skills)** são skills agrupadas. Elas usam o mesmo mecanismo que as skills que você escreve: um prompt entregue ao Claude, que Claude também pode invocar automaticamente quando relevante. Tudo o mais é um comando integrado cujo comportamento é codificado na CLI. Para adicionar seus próprios comandos, consulte [skills](/pt/skills).15## Comandos em um fluxo de trabalho típico

17A maioria dos comandos é útil em um ponto específico de uma sessão, desde a configuração de um projeto até o envio de uma alteração.

19**Primeira sessão em um repositório.** Execute `/init` para gerar um `CLAUDE.md` inicial, depois `/memory` para refiná-lo. Use `/mcp` e `/agents` para configurar quaisquer servidores ou subagentes que o projeto necessite, e `/permissions` para definir as regras de aprovação que você deseja.

21**Durante uma tarefa.** `/plan` alterna para o Plan Mode antes de uma grande alteração. `/model` e `/effort` ajustam quanto raciocínio você está gastando. Quando a conversa fica longa, `/context` mostra para onde a janela está indo e `/compact` a resume; use `/btw` para uma observação rápida que não deve inchar o histórico.

23**Antes de você enviar.** `/diff` mostra o que mudou, `/simplify` revisa arquivos recentes e aplica correções de qualidade e eficiência, e `/review` ou `/security-review` fornecem uma passagem mais profunda somente leitura.

16 24

17Nem todo comando aparece para todos os usuários. A disponibilidade depende da sua plataforma, plano e ambiente. Por exemplo, `/desktop` aparece apenas no macOS e Windows, e `/upgrade` aparece apenas nos planos Pro e Max.25**Entre sessões.** `/clear` começa do zero em uma nova tarefa enquanto mantém a memória do projeto. `/resume` e `/branch` permitem que você retorne ou bifurque uma conversa anterior. `/teleport` puxa uma sessão web para este terminal, e `/remote-control` permite que você continue esta sessão local de outro dispositivo.

27**Quando algo está errado.** `/rewind` reverte o código e a conversa para um checkpoint. `/doctor` e `/debug` diagnosticam problemas de instalação e tempo de execução, e `/feedback` relata um bug com contexto de sessão anexado.

29## Todos os comandos

31A tabela abaixo lista todos os comandos incluídos no Claude Code. As entradas marcadas como **[Skill](/pt/skills#bundled-skills)** são skills agrupadas. Elas usam o mesmo mecanismo que as skills que você escreve: um prompt entregue ao Claude, que Claude também pode invocar automaticamente quando relevante. Tudo o mais é um comando integrado cujo comportamento é codificado na CLI. Para adicionar seus próprios comandos, consulte [skills](/pt/skills).

18 32

19Na tabela abaixo, `<arg>` indica um argumento obrigatório e `[arg]` indica um opcional.33Na tabela abaixo, `<arg>` indica um argumento obrigatório e `[arg]` indica um opcional.

20 34

35<Note>

36 Nem todo comando aparece para todos os usuários. A disponibilidade depende da sua plataforma, plano e ambiente. Por exemplo, `/desktop` aparece apenas no macOS e Windows, e `/upgrade` aparece apenas nos planos Pro e Max.

37</Note>

22| :---------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |40| :---------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

23| `/add-dir <path>` | Adicionar um diretório de trabalho para acesso a arquivos durante a sessão atual. A maioria da configuração `.claude/` [não é descoberta](/pt/permissions#additional-directories-grant-file-access-not-configuration) do diretório adicionado. Você pode retomar a sessão posteriormente do diretório adicionado com `--continue` ou `--resume` |41| `/add-dir <path>` | Adicionar um diretório de trabalho para acesso a arquivos durante a sessão atual. A maioria da configuração `.claude/` [não é descoberta](/pt/permissions#additional-directories-grant-file-access-not-configuration) do diretório adicionado. Você pode retomar a sessão posteriormente do diretório adicionado com `--continue` ou `--resume` |

80| `/review [PR]` | Revisar uma solicitação de pull localmente em sua sessão atual. Para uma revisão mais profunda baseada em nuvem, consulte [`/ultrareview`](/pt/ultrareview) |98| `/review [PR]` | Revisar uma solicitação de pull localmente em sua sessão atual. Para uma revisão mais profunda baseada em nuvem, consulte [`/ultrareview`](/pt/ultrareview) |

81| `/rewind` | Retroceder a conversa e/ou código para um ponto anterior, ou resumir a partir de uma mensagem selecionada. Consulte [checkpointing](/pt/checkpointing). Aliases: `/checkpoint`, `/undo` |99| `/rewind` | Retroceder a conversa e/ou código para um ponto anterior, ou resumir a partir de uma mensagem selecionada. Consulte [checkpointing](/pt/checkpointing). Aliases: `/checkpoint`, `/undo` |

83| `/schedule [description]` | Criar, atualizar, listar ou executar [rotinas](/pt/routines). Claude orienta você através da configuração conversacionalmente. Alias: `/routines` |101| `/schedule [description]` | Criar, atualizar, listar ou executar [rotinas](/pt/routines), que são executadas na infraestrutura em nuvem gerenciada pela Anthropic. Claude orienta você através da configuração conversacionalmente. Alias: `/routines` |

84| `/security-review` | Analisar alterações pendentes no branch atual para vulnerabilidades de segurança. Revisa o diff git e identifica riscos como injeção, problemas de autenticação e exposição de dados |102| `/security-review` | Analisar alterações pendentes no branch atual para vulnerabilidades de segurança. Revisa o diff git e identifica riscos como injeção, problemas de autenticação e exposição de dados |

85| `/setup-bedrock` | Configurar autenticação, região e fixações de modelo do [Amazon Bedrock](/pt/amazon-bedrock) através de um assistente interativo. Visível apenas quando `CLAUDE_CODE_USE_BEDROCK=1` está definido. Usuários do Bedrock pela primeira vez também podem acessar este assistente na tela de login |103| `/setup-bedrock` | Configurar autenticação, região e fixações de modelo do [Amazon Bedrock](/pt/amazon-bedrock) através de um assistente interativo. Visível apenas quando `CLAUDE_CODE_USE_BEDROCK=1` está definido. Usuários do Bedrock pela primeira vez também podem acessar este assistente na tela de login |

86| `/setup-vertex` | Configurar autenticação, projeto, região e fixações de modelo do [Google Vertex AI](/pt/google-vertex-ai) através de um assistente interativo. Visível apenas quando `CLAUDE_CODE_USE_VERTEX=1` está definido. Usuários do Vertex AI pela primeira vez também podem acessar este assistente na tela de login |104| `/setup-vertex` | Configurar autenticação, projeto, região e fixações de modelo do [Google Vertex AI](/pt/google-vertex-ai) através de um assistente interativo. Visível apenas quando `CLAUDE_CODE_USE_VERTEX=1` está definido. Usuários do Vertex AI pela primeira vez também podem acessar este assistente na tela de login |

desktop.md +23 −6

Details

564 564

565Cada entrada requer `id`, `name` e `sshHost`. Os campos `sshPort`, `sshIdentityFile` e `startDirectory` são opcionais. Os usuários também podem adicionar `sshConfigs` ao seu próprio `~/.claude/settings.json`, que é onde as conexões adicionadas através do diálogo são armazenadas.565Cada entrada requer `id`, `name` e `sshHost`. Os campos `sshPort`, `sshIdentityFile` e `startDirectory` são opcionais. Os usuários também podem adicionar `sshConfigs` ao seu próprio `~/.claude/settings.json`, que é onde as conexões adicionadas através do diálogo são armazenadas.

566 566

567#### Restringir quais hosts SSH os usuários podem se conectar

568

569Administradores podem limitar as sessões SSH do Desktop a um conjunto aprovado de hosts adicionando `sshHostAllowlist` a um arquivo de [configurações gerenciadas](/pt/settings#settings-precedence). Quando definido, os usuários podem se conectar apenas a hosts cujo nome de host resolvido corresponde a um dos padrões. Defina-o como um array vazio para desabilitar sessões SSH completamente.

570

571O exemplo a seguir permite conexões a qualquer host sob `devboxes.example.com` e a um único host bastion nomeado:

572

573```json theme={null}

574{

575 "sshHostAllowlist": ["*.devboxes.example.com", "bastion.example.com"]

576}

577```

578

579Padrões são insensíveis a maiúsculas e minúsculas. `*` corresponde a qualquer host, e `*.example.com` corresponde a `example.com` e qualquer subdomínio. Qualquer outra coisa é uma correspondência exata. A verificação é executada contra o nome de host após resolução `~/.ssh/config` via `ssh -G`, portanto entradas `Host` aliases e `ProxyCommand`/`ProxyJump` são permitidas desde que o `HostName` resolvido corresponda.

580

581`sshHostAllowlist` é lido apenas de configurações gerenciadas; valores em configurações de usuário ou projeto são ignorados. Apenas o aplicativo Claude Desktop honra esta configuração; a CLI Claude Code e extensões IDE não a leem, e não restringe comandos `ssh` executados através da ferramenta Bash. Governa quais hosts o aplicativo Desktop se conecta, não saída de rede, portanto combine-o com controles de rede ou zero-trust da sua organização se você precisar de um limite rígido.

582

567## Configuração corporativa583## Configuração corporativa

568 584

569Organizações em planos Team ou Enterprise podem gerenciar o comportamento do aplicativo desktop através de controles do console de administração, arquivos de configurações gerenciadas e políticas de gerenciamento de dispositivos.585Organizações em planos Team ou Enterprise podem gerenciar o comportamento do aplicativo desktop através de controles do console de administração, arquivos de configurações gerenciadas e políticas de gerenciamento de dispositivos.

570 586

571### Admin console controls587### Controles do console de administração

572 588

573Essas configurações são configuradas através do [console de configurações de administração](https://claude.ai/admin-settings/claude-code):589Essas configurações são configuradas através do [console de configurações de administração](https://claude.ai/admin-settings/claude-code):

574 590

582Configurações gerenciadas sobrescrevem configurações de projeto e usuário e se aplicam quando Desktop gera sessões CLI. Você pode definir essas chaves no arquivo de [configurações gerenciadas](/pt/settings#settings-precedence) de sua organização ou enviá-las remotamente através do console de administração.598Configurações gerenciadas sobrescrevem configurações de projeto e usuário e se aplicam quando Desktop gera sessões CLI. Você pode definir essas chaves no arquivo de [configurações gerenciadas](/pt/settings#settings-precedence) de sua organização ou enviá-las remotamente através do console de administração.

583 599

584| Chave | Descrição |600| Chave | Descrição |

585| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |601| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

586| `permissions.disableBypassPermissionsMode` | defina como `"disable"` para impedir usuários de ativar o modo Bypass permissions. |602| `permissions.disableBypassPermissionsMode` | defina como `"disable"` para impedir usuários de ativar o modo Bypass permissions. |

587| `disableAutoMode` | defina como `"disable"` para impedir usuários de ativar o modo [Auto](/pt/permission-modes#eliminate-prompts-with-auto-mode). Remove Auto do seletor de modo. Também aceito em `permissions`. |603| `disableAutoMode` | defina como `"disable"` para impedir usuários de ativar o modo [Auto](/pt/permission-modes#eliminate-prompts-with-auto-mode). Remove Auto do seletor de modo. Também aceito em `permissions`. |

588| `autoMode` | customize o que o classificador de modo auto confia e bloqueia em sua organização. Veja [Configurar o modo auto](/pt/auto-mode-config). |604| `autoMode` | customize o que o classificador de modo auto confia e bloqueia em sua organização. Veja [Configurar o modo auto](/pt/auto-mode-config). |

589| `sshConfigs` | pré-configure [conexões SSH](#pre-configure-ssh-connections-for-your-team) que aparecem no dropdown de ambiente. Usuários não podem editar ou excluir conexões gerenciadas. |605| `sshConfigs` | pré-configure [conexões SSH](#pre-configure-ssh-connections-for-your-team) que aparecem no dropdown de ambiente. Usuários não podem editar ou excluir conexões gerenciadas. |

606| `sshHostAllowlist` | restrinja [sessões SSH](#restrict-which-ssh-hosts-users-can-connect-to) a hosts cujo nome de host resolvido corresponde a um desses padrões. Uma matriz vazia desativa sessões SSH. Lido apenas de configurações gerenciadas. |

590 607

591Um arquivo de configurações gerenciadas implantado em disco em cada máquina se aplica a sessões Desktop. Configurações gerenciadas enviadas remotamente através do console de administração atualmente alcançam apenas sessões CLI e IDE, portanto, para implantações Desktop, distribua o arquivo via MDM ou use os [controles do console de administração](#admin-console-controls) acima.608Um arquivo de configurações gerenciadas implantado em disco em cada máquina se aplica a sessões Desktop. Configurações gerenciadas enviadas remotamente através do console de administração atualmente alcançam apenas sessões CLI e IDE, portanto, para implantações Desktop, distribua o arquivo via MDM ou use os [controles do console de administração](#admin-console-controls) acima.

592 609

593`permissions.disableBypassPermissionsMode` e `disableAutoMode` também funcionam em configurações de usuário e projeto, mas colocá-los em configurações gerenciadas impede que usuários os sobrescrevam. `autoMode` é lido de configurações de usuário, `.claude/settings.local.json` e configurações gerenciadas, mas não de `.claude/settings.json` verificado: um repo clonado não pode injetar suas próprias regras de classificador. Para a lista completa de configurações apenas gerenciadas incluindo `allowManagedPermissionRulesOnly` e `allowManagedHooksOnly`, veja [configurações apenas gerenciadas](/pt/permissions#managed-only-settings).610`permissions.disableBypassPermissionsMode` e `disableAutoMode` também funcionam em configurações de usuário e projeto, mas colocá-los em configurações gerenciadas impede que usuários os sobrescrevam. `autoMode` é lido de configurações de usuário, `.claude/settings.local.json` e configurações gerenciadas, mas não de `.claude/settings.json` verificado: um repo clonado não pode injetar suas próprias regras de classificador. Para a lista completa de configurações apenas gerenciadas incluindo `allowManagedPermissionRulesOnly` e `allowManagedHooksOnly`, veja [configurações apenas gerenciadas](/pt/permissions#managed-only-settings).

594 611

595### Device management policies612### Políticas de gerenciamento de dispositivos

596 613

597Equipes de TI podem gerenciar o aplicativo desktop através de MDM em macOS ou group policy no Windows. As políticas disponíveis incluem ativar ou desativar o recurso Claude Code, controlar atualizações automáticas e definir uma URL de implantação personalizada.614Equipes de TI podem gerenciar o aplicativo desktop através de MDM em macOS ou group policy no Windows. As políticas disponíveis incluem ativar ou desativar o recurso Claude Code, controlar atualizações automáticas e definir uma URL de implantação personalizada.

598 615

599* **macOS**: configure via domínio de preferência `com.anthropic.Claude` usando ferramentas como Jamf ou Kandji616* **macOS**: configure via domínio de preferência `com.anthropic.Claude` usando ferramentas como Jamf ou Kandji

600* **Windows**: configure via registro em `SOFTWARE\Policies\Claude`617* **Windows**: configure via registro em `SOFTWARE\Policies\Claude`

601 618

602### Authentication and SSO619### Autenticação e SSO

603 620

604Organizações corporativas podem exigir SSO para todos os usuários. Veja [autenticação](/pt/authentication) para detalhes de nível de plano e [Configurando SSO](https://support.claude.com/en/articles/13132885-setting-up-single-sign-on-sso) para configuração SAML e OIDC.621Organizações corporativas podem exigir SSO para todos os usuários. Veja [autenticação](/pt/authentication) para detalhes de nível de plano e [Configurando SSO](https://support.claude.com/en/articles/13132885-setting-up-single-sign-on-sso) para configuração SAML e OIDC.

605 622

606### Data handling623### Manipulação de dados

607 624

608Claude Code processa seu código localmente em sessões locais ou na infraestrutura em nuvem da Anthropic em sessões remotas. Conversas e contexto de código são enviados para a API da Anthropic para processamento. Veja [manipulação de dados](/pt/data-usage) para detalhes sobre retenção de dados, privacidade e conformidade.625Claude Code processa seu código localmente em sessões locais ou na infraestrutura em nuvem da Anthropic em sessões remotas. Conversas e contexto de código são enviados para a API da Anthropic para processamento. Veja [manipulação de dados](/pt/data-usage) para detalhes sobre retenção de dados, privacidade e conformidade.

609 626

610### Deployment627### Implantação

611 628

612Desktop pode ser distribuído através de ferramentas de implantação corporativa:629Desktop pode ser distribuído através de ferramentas de implantação corporativa:

613 630

env-vars.md +3 −1

Details

92| `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) |92| `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) |

93| `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` |93| `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` |

94| `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 |94| `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 |

95| `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 para conexões diretas da API Anthropic. Defina como `0` para optar por não participar. Defina como `1` para forçar a habilitação mesmo quando o padrão do lado do servidor está desativado. Não tem efeito em conexões Bedrock, Vertex, Foundry ou [gateway](/pt/llm-gateway) |95| `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) |

96| `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) |96| `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) |

97| `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) |97| `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) |

98| `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) |98| `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) |

164| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | Controla a ferramenta PowerShell. No Windows sem Git Bash, a ferramenta é habilitada automaticamente; defina como `0` para desabilitá-la. No Windows com Git Bash instalado, a ferramenta está sendo lançada progressivamente: defina como `1` para optar por participar ou `0` para optar por não participar. No Linux, macOS e WSL, defina como `1` para habilitá-la, o que requer `pwsh` no seu `PATH`. Quando habilitada no Windows, Claude pode executar comandos PowerShell nativamente em vez de rotear através do Git Bash. Veja [Ferramenta PowerShell](/pt/tools-reference#powershell-tool) |164| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | Controla a ferramenta PowerShell. No Windows sem Git Bash, a ferramenta é habilitada automaticamente; defina como `0` para desabilitá-la. No Windows com Git Bash instalado, a ferramenta está sendo lançada progressivamente: defina como `1` para optar por participar ou `0` para optar por não participar. No Linux, macOS e WSL, defina como `1` para habilitá-la, o que requer `pwsh` no seu `PATH`. Quando habilitada no Windows, Claude pode executar comandos PowerShell nativamente em vez de rotear através do Git Bash. Veja [Ferramenta PowerShell](/pt/tools-reference#powershell-tool) |

166| `CLAUDE_CONFIG_DIR` | Substitua o diretório de configuração (padrão: `~/.claude`). Todas as configurações, credenciais, histórico de sessão e plugins são armazenados sob este caminho. Útil para executar múltiplas contas lado a lado: por exemplo, `alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'` |166| `CLAUDE_CONFIG_DIR` | Substitua o diretório de configuração (padrão: `~/.claude`). Todas as configurações, credenciais, histórico de sessão e plugins são armazenados sob este caminho. Útil para executar múltiplas contas lado a lado: por exemplo, `alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'` |

167| `CLAUDE_EFFORT` | Definido automaticamente em subprocessos de ferramenta Bash e comandos hook para o [nível de esforço](/pt/model-config#adjust-effort-level) ativo para a volta: `low`, `medium`, `high`, `xhigh` ou `max`. Corresponde ao campo `effort.level` passado para [hooks](/pt/hooks). Apenas definido quando o modelo atual suporta o parâmetro de esforço |

167| `CLAUDE_ENABLE_BYTE_WATCHDOG` | Defina como `1` para forçar a habilitação do watchdog ocioso de nível de byte, ou defina como `0` para forçar a desabilitação. Quando não definido, o watchdog é habilitado por padrão para conexões da API Anthropic. O watchdog de byte aborta uma conexão quando nenhum byte chega no fio pela duração definida por `CLAUDE_STREAM_IDLE_TIMEOUT_MS`, com um mínimo de 5 minutos, independente do watchdog de nível de evento |168| `CLAUDE_ENABLE_BYTE_WATCHDOG` | Defina como `1` para forçar a habilitação do watchdog ocioso de nível de byte, ou defina como `0` para forçar a desabilitação. Quando não definido, o watchdog é habilitado por padrão para conexões da API Anthropic. O watchdog de byte aborta uma conexão quando nenhum byte chega no fio pela duração definida por `CLAUDE_STREAM_IDLE_TIMEOUT_MS`, com um mínimo de 5 minutos, independente do watchdog de nível de evento |

168| `CLAUDE_ENABLE_STREAM_WATCHDOG` | Defina como `1` para habilitar o watchdog ocioso de streaming de nível de evento. Desativado por padrão. Para Bedrock, Vertex e Foundry, este é o único watchdog ocioso disponível. Configure o tempo limite com `CLAUDE_STREAM_IDLE_TIMEOUT_MS` |169| `CLAUDE_ENABLE_STREAM_WATCHDOG` | Defina como `1` para habilitar o watchdog ocioso de streaming de nível de evento. Desativado por padrão. Para Bedrock, Vertex e Foundry, este é o único watchdog ocioso disponível. Configure o tempo limite com `CLAUDE_STREAM_IDLE_TIMEOUT_MS` |

169| `CLAUDE_ENV_FILE` | Caminho para um script de shell cujo conteúdo Claude Code executa antes de cada comando Bash no mesmo processo de shell, para que as exportações no arquivo sejam visíveis para o comando. Use para persistir ativação de virtualenv ou conda entre comandos. Também preenchido dinamicamente por hooks [SessionStart](/pt/hooks#persist-environment-variables), [Setup](/pt/hooks#setup), [CwdChanged](/pt/hooks#cwdchanged) e [FileChanged](/pt/hooks#filechanged) |170| `CLAUDE_ENV_FILE` | Caminho para um script de shell cujo conteúdo Claude Code executa antes de cada comando Bash no mesmo processo de shell, para que as exportações no arquivo sejam visíveis para o comando. Use para persistir ativação de virtualenv ou conda entre comandos. Também preenchido dinamicamente por hooks [SessionStart](/pt/hooks#persist-environment-variables), [Setup](/pt/hooks#setup), [CwdChanged](/pt/hooks#cwdchanged) e [FileChanged](/pt/hooks#filechanged) |

205| `MAX_THINKING_TOKENS` | Substitua o orçamento de token de [pensamento estendido](https://platform.claude.com/docs/en/build-with-claude/extended-thinking). O teto é o [max output tokens](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison) do modelo menos um. Defina como `0` para desabilitar pensamento inteiramente. Em modelos com [raciocínio adaptativo](/pt/model-config#adjust-effort-level), o orçamento é ignorado a menos que raciocínio adaptativo seja desabilitado via `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` |206| `MAX_THINKING_TOKENS` | Substitua o orçamento de token de [pensamento estendido](https://platform.claude.com/docs/en/build-with-claude/extended-thinking). O teto é o [max output tokens](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison) do modelo menos um. Defina como `0` para desabilitar pensamento inteiramente. Em modelos com [raciocínio adaptativo](/pt/model-config#adjust-effort-level), o orçamento é ignorado a menos que raciocínio adaptativo seja desabilitado via `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` |

206| `MCP_CLIENT_SECRET` | Segredo do cliente OAuth para servidores MCP que requerem [credenciais pré-configuradas](/pt/mcp#use-pre-configured-oauth-credentials). Evita o prompt interativo ao adicionar um servidor com `--client-secret` |207| `MCP_CLIENT_SECRET` | Segredo do cliente OAuth para servidores MCP que requerem [credenciais pré-configuradas](/pt/mcp#use-pre-configured-oauth-credentials). Evita o prompt interativo ao adicionar um servidor com `--client-secret` |

207| `MCP_CONNECTION_NONBLOCKING` | Defina como `true` em modo não interativo (`-p`) para pular a espera de conexão MCP inteiramente. Útil para pipelines com script onde ferramentas MCP não são necessárias. Sem essa variável, a primeira consulta aguarda até 5 segundos para conexões de servidor `--mcp-config`. Servidores configurados com [`alwaysLoad: true`](/pt/mcp#exempt-a-server-from-deferral) sempre bloqueiam a inicialização independentemente dessa variável, já que suas ferramentas devem estar presentes quando o primeiro prompt é construído |208| `MCP_CONNECTION_NONBLOCKING` | Defina como `true` em modo não interativo (`-p`) para pular a espera de conexão MCP inteiramente. Útil para pipelines com script onde ferramentas MCP não são necessárias. Sem essa variável, a primeira consulta aguarda até 5 segundos para conexões de servidor `--mcp-config`. Servidores configurados com [`alwaysLoad: true`](/pt/mcp#exempt-a-server-from-deferral) sempre bloqueiam a inicialização independentemente dessa variável, já que suas ferramentas devem estar presentes quando o primeiro prompt é construído |

209| `MCP_CONNECT_TIMEOUT_MS` | Quanto tempo a primeira consulta aguarda, em milissegundos, para o lote de conexão MCP antes de tirar um snapshot da lista de ferramentas (padrão: 5000). Servidores ainda pendentes no prazo continuam se conectando em segundo plano mas não aparecerão até a próxima consulta. Distinto de `MCP_TIMEOUT`, que limita a tentativa de conexão de um servidor individual. Mais relevante para sessões não interativas que emitem uma única consulta e precisam que servidores de conexão lenta sejam visíveis |

208| `MCP_OAUTH_CALLBACK_PORT` | Porta fixa para o callback de redirecionamento OAuth, como alternativa a `--callback-port` ao adicionar um servidor MCP com [credenciais pré-configuradas](/pt/mcp#use-pre-configured-oauth-credentials) |210| `MCP_OAUTH_CALLBACK_PORT` | Porta fixa para o callback de redirecionamento OAuth, como alternativa a `--callback-port` ao adicionar um servidor MCP com [credenciais pré-configuradas](/pt/mcp#use-pre-configured-oauth-credentials) |

209| `MCP_REMOTE_SERVER_CONNECTION_BATCH_SIZE` | Número máximo de servidores MCP remotos (HTTP/SSE) para conectar em paralelo durante a inicialização (padrão: 20) |211| `MCP_REMOTE_SERVER_CONNECTION_BATCH_SIZE` | Número máximo de servidores MCP remotos (HTTP/SSE) para conectar em paralelo durante a inicialização (padrão: 20) |

210| `MCP_SERVER_CONNECTION_BATCH_SIZE` | Número máximo de servidores MCP locais (stdio) para conectar em paralelo durante a inicialização (padrão: 3) |212| `MCP_SERVER_CONNECTION_BATCH_SIZE` | Número máximo de servidores MCP locais (stdio) para conectar em paralelo durante a inicialização (padrão: 3) |

features-overview.md +1 −1

Details

249 249

250 **Custo de contexto:** Baixo até ser usado. Skills apenas de usuário têm custo zero até invocação.250 **Custo de contexto:** Baixo até ser usado. Skills apenas de usuário têm custo zero até invocação.

251 251

252 **Em subagents:** Skills funcionam diferentemente em subagents. Em vez de carregamento sob demanda, skills passadas para um subagent são totalmente pré-carregadas em seu contexto no lançamento. Subagents não herdam skills da sessão principal; você deve especificá-las explicitamente.252 **Em subagents:** Skills funcionam diferentemente em subagents. Em vez de carregamento sob demanda, skills listadas no campo `skills:` do subagent são totalmente pré-carregadas em seu contexto no lançamento. Subagents ainda podem descobrir e invocar skills de projeto, usuário e plugin não listadas através da ferramenta Skill.

253 253

254 <Tip>Use `disable-model-invocation: true` para skills com efeitos colaterais. Isso economiza contexto e garante que apenas você as dispare.</Tip>254 <Tip>Use `disable-model-invocation: true` para skills com efeitos colaterais. Isso economiza contexto e garante que apenas você as dispare.</Tip>

255 </Tab>255 </Tab>

google-vertex-ai.md +1 −111

Details

76 </div>;76 </div>;

77};77};

78 78

~~79export const Experiment = ({flag, treatment, children}) => {~~79<ContactSalesCard surface="vertex" />

~~80 const VID_KEY = 'exp_vid';~~

~~82 const fnv1a = s => {~~

~~83 let h = 0x811c9dc5;~~

~~84 for (let i = 0; i < s.length; i++) {~~

~~85 h ^= s.charCodeAt(i);~~

~~86 h += (h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24);~~

~~87 }~~

~~88 return h >>> 0;~~

~~89 };~~

~~90 const bucket = (seed, vid) => fnv1a(fnv1a(seed + vid) + '') % 10000 < 5000 ? 'control' : 'treatment';~~

~~91 const [decision] = useState(() => {~~

~~92 const params = new URLSearchParams(location.search);~~

~~93 const preBucketed = document.documentElement.dataset['gb_' + flag.replace(/-/g, '_')];~~

~~94 const force = params.get('gb-force');~~

~~95 if (force) {~~

~~96 for (const p of force.split(',')) {~~

~~97 const [k, v] = p.split(':');~~

~~98 if (k === flag) return {~~

~~99 variant: v || 'treatment',~~

100 track: false

101 };

102 }

103 }

104 if (navigator.globalPrivacyControl) {

105 return {

106 variant: 'control',

107 track: false

108 };

109 }

110 const prefsMatch = document.cookie.match(/(?:^|; )anthropic-consent-preferences=([^;]+)/);

111 if (prefsMatch) {

112 try {

113 if (JSON.parse(decodeURIComponent(prefsMatch[1])).analytics !== true) {

114 return {

115 variant: 'control',

116 track: false

117 };

118 }

119 } catch {

120 return {

121 variant: 'control',

122 track: false

123 };

124 }

125 } else {

126 const country = params.get('country')?.toUpperCase() || (document.cookie.match(/(?:^|; )cf_geo=([A-Z]{2})/) || [])[1];

127 if (!country || CONSENT_COUNTRIES.has(country)) {

128 return {

129 variant: 'control',

130 track: false

131 };

132 }

133 }

134 let vid;

135 try {

136 const ajsMatch = document.cookie.match(/(?:^|; )ajs_anonymous_id=([^;]+)/);

137 if (ajsMatch) {

138 vid = decodeURIComponent(ajsMatch[1]).replace(/^"|"$/g, '');

139 } else {

140 vid = localStorage.getItem(VID_KEY);

141 if (!vid) {

142 vid = crypto.randomUUID();

143 }

144 document.cookie = `ajs_anonymous_id=${vid}; domain=.claude.com; path=/; Secure; SameSite=Lax; max-age=31536000`;

145 }

146 try {

147 localStorage.setItem(VID_KEY, vid);

148 } catch {}

149 } catch {

150 return {

151 variant: 'control',

152 track: false

153 };

154 }

155 const variant = preBucketed === '1' ? 'treatment' : preBucketed === '0' ? 'control' : bucket(flag, vid);

156 return {

157 variant,

158 track: true,

159 vid

160 };

161 });

162 useEffect(() => {

163 if (!decision.track) return;

164 fetch('https://api.anthropic.com/api/event_logging/v2/batch', {

165 method: 'POST',

166 headers: {

167 'Content-Type': 'application/json',

168 'x-service-name': 'claude_code_docs'

169 },

170 body: JSON.stringify({

171 events: [{

172 event_type: 'GrowthbookExperimentEvent',

173 event_data: {

174 device_id: decision.vid,

175 anonymous_id: decision.vid,

176 timestamp: new Date().toISOString(),

177 experiment_id: flag,

178 variation_id: decision.variant === 'treatment' ? 1 : 0,

179 environment: 'production'

180 }

181 }]

182 }),

183 keepalive: true

184 }).catch(() => {});

185 }, []);

186 return decision.variant === 'treatment' ? treatment : children;

187};

~~188~~

189<Experiment flag="docs-contact-sales-cta" treatment={<ContactSalesCard surface="vertex" />} />

190 80

191## Pré-requisitos81## Pré-requisitos

192 82

hooks.md +5 −4

Details

518Eventos de hook recebem esses campos como JSON, além de campos específicos do evento documentados em cada seção [evento de hook](#hook-events). Para hooks de comando, este JSON chega via stdin. Para hooks HTTP, chega como corpo da solicitação POST.518Eventos de hook recebem esses campos como JSON, além de campos específicos do evento documentados em cada seção [evento de hook](#hook-events). Para hooks de comando, este JSON chega via stdin. Para hooks HTTP, chega como corpo da solicitação POST.

519 519

521| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |521| :---------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

524| `cwd` | Diretório de trabalho atual quando o hook é invocado |524| `cwd` | Diretório de trabalho atual quando o hook é invocado |

525| `permission_mode` | [Modo de permissão](/pt/permissions#permission-modes) atual: `"default"`, `"plan"`, `"acceptEdits"`, `"auto"`, `"dontAsk"` ou `"bypassPermissions"`. Nem todos os eventos recebem este campo: consulte cada exemplo JSON de evento abaixo para verificar |525| `permission_mode` | [Modo de permissão](/pt/permissions#permission-modes) atual: `"default"`, `"plan"`, `"acceptEdits"`, `"auto"`, `"dontAsk"` ou `"bypassPermissions"`. Nem todos os eventos recebem este campo: consulte cada exemplo JSON de evento abaixo para verificar |

526| `effort` | Objeto com um campo `level` contendo o [nível de esforço](/pt/model-config#adjust-effort-level) ativo para a rodada: `"low"`, `"medium"`, `"high"`, `"xhigh"` ou `"max"`. Se o esforço solicitado exceder o que o modelo atual suporta, este é o nível reduzido que o modelo realmente usou, não o nível que você solicitou. O objeto corresponde ao campo `effort` da [linha de status](/pt/statusline#available-data). Presente para eventos que disparam dentro de um contexto de uso de ferramenta, como `PreToolUse`, `PostToolUse`, `Stop` e `SubagentStop`, quando o modelo atual suporta o parâmetro de esforço. O nível também está disponível para comandos de hook e a ferramenta Bash como a variável de ambiente `$CLAUDE_EFFORT`. |

527 528

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

1225 1226

1226Se a ferramenta adiada não estiver mais disponível quando você retomar, o processo sai com `stop_reason: "tool_deferred_unavailable"` e `is_error: true` antes do hook disparar. Isso acontece quando um servidor MCP que forneceu a ferramenta não está conectado para a sessão retomada. O payload `deferred_tool_use` ainda é incluído para que você possa identificar qual ferramenta desapareceu.1227Se a ferramenta adiada não estiver mais disponível quando você retomar, o processo sai com `stop_reason: "tool_deferred_unavailable"` e `is_error: true` antes do hook disparar. Isso acontece quando um servidor MCP que forneceu a ferramenta não está conectado para a sessão retomada. O payload `deferred_tool_use` ainda é incluído para que você possa identificar qual ferramenta desapareceu.

1227 1228

1228<Warning>1229<Note>

1229 `--resume` não restaura o modo de permissão da sessão anterior. Passe a mesma flag `--permission-mode` na retomada que estava ativa quando a ferramenta foi adiada. Claude Code registra um aviso se os modos diferem.1230 `--resume` restaura o modo de permissão que estava ativo quando a ferramenta foi adiada, então você não precisa passar `--permission-mode` novamente. As exceções são `plan` e `bypassPermissions`, que nunca são transportados. Passar `--permission-mode` explicitamente na retomada sobrescreve o valor restaurado.

1230</Warning>1231</Note>

1231 1232

1232### PermissionRequest1233### PermissionRequest

1233 1234

memory.md +11 −1

Details

132Use plan mode para alterações em `src/billing/`.132Use plan mode para alterações em `src/billing/`.

133```133```

134 134

135Um symlink também funciona se você não precisar adicionar conteúdo específico do Claude Code:

136

137```bash theme={null}

138ln -s AGENTS.md CLAUDE.md

139```

140

141No Windows, criar um symlink requer privilégios de Administrador ou Modo de Desenvolvedor, então use a importação `@AGENTS.md` em vez disso.

142

143Executar [`/init`](/pt/commands) em um repositório que já tem um `AGENTS.md` o lê e incorpora as partes relevantes no `CLAUDE.md` gerado. Ele também lê outras configurações de ferramentas como `.cursorrules` e `.windsurfrules`.

144

135### Como arquivos CLAUDE.md são carregados145### Como arquivos CLAUDE.md são carregados

136 146

137Claude Code lê arquivos CLAUDE.md caminhando para cima na árvore de diretórios a partir do seu diretório de trabalho atual, verificando cada diretório ao longo do caminho para arquivos `CLAUDE.md` e `CLAUDE.local.md`. Isso significa que se você executar Claude Code em `foo/bar/`, ele carrega instruções de `foo/bar/CLAUDE.md`, `foo/CLAUDE.md` e qualquer arquivo `CLAUDE.local.md` ao lado deles.147Claude Code lê arquivos CLAUDE.md caminhando para cima na árvore de diretórios a partir do seu diretório de trabalho atual, verificando cada diretório ao longo do caminho para arquivos `CLAUDE.md` e `CLAUDE.local.md`. Isso significa que se você executar Claude Code em `foo/bar/`, ele carrega instruções de `foo/bar/CLAUDE.md`, `foo/CLAUDE.md` e qualquer arquivo `CLAUDE.local.md` ao lado deles.

138 148

139Todos os arquivos descobertos são concatenados em contexto em vez de se sobreporem. Dentro de cada diretório, `CLAUDE.local.md` é anexado após `CLAUDE.md`, então quando as instruções entram em conflito, suas notas pessoais são a última coisa que Claude lê naquele nível.149Todos os arquivos descobertos são concatenados em contexto em vez de se sobreporem. Dentro da árvore de diretórios, o conteúdo é ordenado da raiz do sistema de arquivos até seu diretório de trabalho. Para o exemplo `foo/bar/`, `foo/CLAUDE.md` aparece em contexto antes de `foo/bar/CLAUDE.md`, então as instruções mais próximas de onde você lançou Claude são lidas por último. Dentro de cada diretório, `CLAUDE.local.md` é anexado após `CLAUDE.md`, então suas notas pessoais são a última coisa que Claude lê naquele nível.

140 150

141Claude também descobre arquivos `CLAUDE.md` e `CLAUDE.local.md` em subdiretórios sob seu diretório de trabalho atual. Em vez de carregá-los no lançamento, eles são incluídos quando Claude lê arquivos nesses subdiretórios.151Claude também descobre arquivos `CLAUDE.md` e `CLAUDE.local.md` em subdiretórios sob seu diretório de trabalho atual. Em vez de carregá-los no lançamento, eles são incluídos quando Claude lê arquivos nesses subdiretórios.

142 152

microsoft-foundry.md +1 −111

Details

76 </div>;76 </div>;

77};77};

78 78

~~79export const Experiment = ({flag, treatment, children}) => {~~79<ContactSalesCard surface="foundry" />

~~80 const VID_KEY = 'exp_vid';~~

~~82 const fnv1a = s => {~~

~~83 let h = 0x811c9dc5;~~

~~84 for (let i = 0; i < s.length; i++) {~~

~~85 h ^= s.charCodeAt(i);~~

~~86 h += (h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24);~~

~~87 }~~

~~88 return h >>> 0;~~

~~89 };~~

~~90 const bucket = (seed, vid) => fnv1a(fnv1a(seed + vid) + '') % 10000 < 5000 ? 'control' : 'treatment';~~

~~91 const [decision] = useState(() => {~~

~~92 const params = new URLSearchParams(location.search);~~

~~93 const preBucketed = document.documentElement.dataset['gb_' + flag.replace(/-/g, '_')];~~

~~94 const force = params.get('gb-force');~~

~~95 if (force) {~~

~~96 for (const p of force.split(',')) {~~

~~97 const [k, v] = p.split(':');~~

~~98 if (k === flag) return {~~

~~99 variant: v || 'treatment',~~

100 track: false

101 };

102 }

103 }

104 if (navigator.globalPrivacyControl) {

105 return {

106 variant: 'control',

107 track: false

108 };

109 }

110 const prefsMatch = document.cookie.match(/(?:^|; )anthropic-consent-preferences=([^;]+)/);

111 if (prefsMatch) {

112 try {

113 if (JSON.parse(decodeURIComponent(prefsMatch[1])).analytics !== true) {

114 return {

115 variant: 'control',

116 track: false

117 };

118 }

119 } catch {

120 return {

121 variant: 'control',

122 track: false

123 };

124 }

125 } else {

126 const country = params.get('country')?.toUpperCase() || (document.cookie.match(/(?:^|; )cf_geo=([A-Z]{2})/) || [])[1];

127 if (!country || CONSENT_COUNTRIES.has(country)) {

128 return {

129 variant: 'control',

130 track: false

131 };

132 }

133 }

134 let vid;

135 try {

136 const ajsMatch = document.cookie.match(/(?:^|; )ajs_anonymous_id=([^;]+)/);

137 if (ajsMatch) {

138 vid = decodeURIComponent(ajsMatch[1]).replace(/^"|"$/g, '');

139 } else {

140 vid = localStorage.getItem(VID_KEY);

141 if (!vid) {

142 vid = crypto.randomUUID();

143 }

144 document.cookie = `ajs_anonymous_id=${vid}; domain=.claude.com; path=/; Secure; SameSite=Lax; max-age=31536000`;

145 }

146 try {

147 localStorage.setItem(VID_KEY, vid);

148 } catch {}

149 } catch {

150 return {

151 variant: 'control',

152 track: false

153 };

154 }

155 const variant = preBucketed === '1' ? 'treatment' : preBucketed === '0' ? 'control' : bucket(flag, vid);

156 return {

157 variant,

158 track: true,

159 vid

160 };

161 });

162 useEffect(() => {

163 if (!decision.track) return;

164 fetch('https://api.anthropic.com/api/event_logging/v2/batch', {

165 method: 'POST',

166 headers: {

167 'Content-Type': 'application/json',

168 'x-service-name': 'claude_code_docs'

169 },

170 body: JSON.stringify({

171 events: [{

172 event_type: 'GrowthbookExperimentEvent',

173 event_data: {

174 device_id: decision.vid,

175 anonymous_id: decision.vid,

176 timestamp: new Date().toISOString(),

177 experiment_id: flag,

178 variation_id: decision.variant === 'treatment' ? 1 : 0,

179 environment: 'production'

180 }

181 }]

182 }),

183 keepalive: true

184 }).catch(() => {});

185 }, []);

186 return decision.variant === 'treatment' ? treatment : children;

187};

~~188~~

189<Experiment flag="docs-contact-sales-cta" treatment={<ContactSalesCard surface="foundry" />} />

190 80

191## Pré-requisitos81## Pré-requisitos

192 82

model-config.md +4 −0

Details

17 * Foundry: um nome de implantação17 * Foundry: um nome de implantação

18 * Vertex: um nome de versão18 * Vertex: um nome de versão

19 19

20<Note>

21 `ANTHROPIC_BASE_URL` altera para onde as solicitações são enviadas, não qual modelo as responde. Para rotear Claude através de um gateway LLM, consulte [configuração de gateway LLM](/pt/llm-gateway).

22</Note>

20### Aliases de modelo24### Aliases de modelo

21 25

22Os aliases de modelo fornecem uma maneira conveniente de selecionar configurações de modelo sem precisar lembrar dos números exatos da versão:26Os aliases de modelo fornecem uma maneira conveniente de selecionar configurações de modelo sem precisar lembrar dos números exatos da versão:

overview.md +1 −635

Details

6 6

7> Claude Code é uma ferramenta de codificação agentic que lê sua base de código, edita arquivos, executa comandos e se integra com suas ferramentas de desenvolvimento. Disponível em seu terminal, IDE, aplicativo de desktop e navegador.7> Claude Code é uma ferramenta de codificação agentic que lê sua base de código, edita arquivos, executa comandos e se integra com suas ferramentas de desenvolvimento. Disponível em seu terminal, IDE, aplicativo de desktop e navegador.

8 8

~~9export const InstallConfigurator = ({defaultSurface = 'terminal'}) => {~~

~~10 const TERM = {~~

~~11 mac: {~~

~~12 label: 'macOS / Linux',~~

~~13 cmd: 'curl -fsSL https://claude.ai/install.sh | bash'~~

~~14 },~~

~~15 win: {~~

~~16 label: 'Windows'~~

~~17 },~~

~~18 brew: {~~

~~19 label: 'Homebrew',~~

~~20 cmd: 'brew install --cask claude-code'~~

~~21 },~~

~~22 winget: {~~

~~23 label: 'WinGet',~~

~~24 cmd: 'winget install Anthropic.ClaudeCode'~~

~~25 }~~

~~26 };~~

~~27 const WIN_VARIANTS = {~~

~~28 ps: 'irm https://claude.ai/install.ps1 | iex',~~

~~29 cmd: 'curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd'~~

~~30 };~~

~~31 const TABS = [{~~

~~32 key: 'terminal',~~

~~33 label: 'Terminal'~~

~~34 }, {~~

~~35 key: 'desktop',~~

~~36 label: 'Desktop'~~

~~37 }, {~~

~~38 key: 'vscode',~~

~~39 label: 'VS Code'~~

~~40 }, {~~

~~41 key: 'jetbrains',~~

~~42 label: 'JetBrains'~~

~~43 }];~~

~~44 const ALT_TARGETS = {~~

~~45 desktop: {~~

~~46 name: 'Desktop',~~

~~47 tagline: 'The full agent in a native app for macOS and Windows.',~~

~~48 installLabel: 'Download the app',~~

~~49 installHref: 'https://claude.com/download?utm_source=claude_code&utm_medium=docs&utm_content=configurator_desktop_download',~~

~~50 guideHref: '/en/desktop-quickstart'~~

~~51 },~~

~~52 vscode: {~~

~~53 name: 'VS Code',~~

~~54 tagline: 'Review diffs, manage context, and chat without leaving your editor.',~~

~~55 installLabel: 'Install from Marketplace',~~

~~56 installHref: 'https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code',~~

~~57 altCmd: 'code --install-extension anthropic.claude-code',~~

~~58 guideHref: '/en/vs-code'~~

~~59 },~~

~~60 jetbrains: {~~

~~61 name: 'JetBrains',~~

~~62 tagline: 'Native plugin for IntelliJ, PyCharm, WebStorm, and other JetBrains IDEs.',~~

~~63 installLabel: 'Install from Marketplace',~~

~~64 installHref: 'https://plugins.jetbrains.com/plugin/27310-claude-code-beta-',~~

~~65 guideHref: '/en/jetbrains'~~

~~66 }~~

~~67 };~~

~~68 const PROVIDERS = [{~~

~~69 key: 'anthropic',~~

~~70 label: 'Anthropic'~~

~~71 }, {~~

~~72 key: 'bedrock',~~

~~73 label: 'Amazon Bedrock'~~

~~74 }, {~~

~~75 key: 'foundry',~~

~~76 label: 'Microsoft Foundry'~~

~~77 }, {~~

~~78 key: 'vertex',~~

~~79 label: 'Google Vertex AI'~~

~~80 }];~~

~~81 const PROVIDER_NOTICE = {~~

~~82 bedrock: <>~~

~~83 <strong>Configure your AWS account first.</strong> Running on Bedrock~~

~~84 requires model access enabled in the AWS console and IAM credentials.{' '}~~

~~85 <a href="/en/amazon-bedrock">Bedrock setup guide →</a>~~

~~86 </>,~~

~~87 vertex: <>~~

~~88 <strong>Configure your GCP project first.</strong> Running on Vertex AI~~

~~89 requires the Vertex API enabled and a service account with the right~~

~~90 permissions.{' '}~~

~~91 <a href="/en/google-vertex-ai">Vertex setup guide →</a>~~

~~92 </>,~~

~~93 foundry: <>~~

~~94 <strong>Configure your Azure resources first.</strong> Running on~~

~~95 Microsoft Foundry requires an Azure subscription with a Foundry resource~~

~~96 and model deployments provisioned.{' '}~~

~~97 <a href="/en/microsoft-foundry">Foundry setup guide →</a>~~

~~98 </>~~

~~99 };~~

100 const iconCheck = (size = 14) => <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="3" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">

101 <polyline points="20 6 9 17 4 12" />

102 </svg>;

103 const iconCopy = (size = 14) => <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">

104 <rect x="9" y="9" width="13" height="13" rx="2" />

105 <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" />

106 </svg>;

107 const iconArrowRight = (size = 13) => <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">

108 <line x1="5" y1="12" x2="19" y2="12" />

109 <polyline points="12 5 19 12 12 19" />

110 </svg>;

111 const iconArrowUpRight = (size = 14) => <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">

112 <line x1="7" y1="17" x2="17" y2="7" />

113 <polyline points="7 7 17 7 17 17" />

114 </svg>;

115 const iconInfo = (size = 16) => <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">

116 <circle cx="12" cy="12" r="10" />

117 <line x1="12" y1="16" x2="12" y2="12" />

118 <line x1="12" y1="8" x2="12.01" y2="8" />

119 </svg>;

120 const [target, setTarget] = useState(defaultSurface);

121 const [team, setTeam] = useState(false);

122 const [provider, setProvider] = useState('anthropic');

123 const [pkg, setPkg] = useState(() => (/Win/).test(navigator.userAgent) ? 'win' : 'mac');

124 const [winCmd, setWinCmd] = useState(false);

125 const [copied, setCopied] = useState(null);

126 const copyTimer = useRef(null);

127 const handleCopy = async (text, key) => {

128 try {

129 await navigator.clipboard.writeText(text);

130 } catch {

131 const ta = document.createElement('textarea');

132 ta.value = text;

133 document.body.appendChild(ta);

134 ta.select();

135 document.execCommand('copy');

136 document.body.removeChild(ta);

137 }

138 clearTimeout(copyTimer.current);

139 setCopied(key);

140 copyTimer.current = setTimeout(() => setCopied(null), 1800);

141 };

142 const cardBodyCmd = (cmd, prompt) => {

143 const on = copied === 'term';

144 return <div className="cc-ic-card-body">

145 <span className="cc-ic-prompt">{prompt || '$'}</span>

146 <div className="cc-ic-cmd">{cmd}</div>

147 <button type="button" className={'cc-ic-copy' + (on ? ' cc-ic-copied' : '')} onClick={() => handleCopy(cmd, 'term')}>

148 {on ? iconCheck(13) : iconCopy(13)}

149 <span>{on ? 'Copied' : 'Copy'}</span>

150 </button>

151 </div>;

152 };

153 const isWinInstaller = pkg === 'win';

154 const isWinPrompt = pkg === 'win' || pkg === 'winget';

155 const terminalCmd = isWinInstaller ? WIN_VARIANTS[winCmd ? 'cmd' : 'ps'] : TERM[pkg].cmd;

156 const alt = ALT_TARGETS[target];

157 const showNotice = team && provider !== 'anthropic';

158 const STYLES = `

159.cc-ic {

160 --ic-slate: #141413;

161 --ic-clay: #d97757;

162 --ic-clay-deep: #c6613f;

163 --ic-gray-000: #ffffff;

164 --ic-gray-150: #f0eee6;

165 --ic-gray-550: #73726c;

166 --ic-gray-700: #3d3d3a;

167 --ic-border-subtle: rgba(31, 30, 29, 0.08);

168 --ic-border-default: rgba(31, 30, 29, 0.15);

169 --ic-border-strong: rgba(31, 30, 29, 0.3);

170 --ic-font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, 'Courier New', monospace;

171 font-family: 'Anthropic Sans', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;

172 font-size: 14px; line-height: 1.5; color: var(--ic-slate);

173 margin: 8px 0 32px;

174}

175.dark .cc-ic {

176 --ic-slate: #f0eee6;

177 --ic-gray-000: #262624;

178 --ic-gray-150: #1f1e1d;

179 --ic-gray-550: #91908a;

180 --ic-gray-700: #bfbdb4;

181 --ic-border-subtle: rgba(240, 238, 230, 0.08);

182 --ic-border-default: rgba(240, 238, 230, 0.14);

183 --ic-border-strong: rgba(240, 238, 230, 0.28);

184}

185.dark .cc-ic-check { background: transparent; }

186.dark .cc-ic-card { border: 0.5px solid var(--ic-border-subtle); }

187.dark .cc-ic-p-pill.cc-ic-active { box-shadow: 0 1px 2px rgba(0, 0, 0, 0.3); }

188.cc-ic *, .cc-ic *::before, .cc-ic *::after { box-sizing: border-box; }

189.cc-ic a { text-decoration: none; }

190.cc-ic a:not([class]) { color: inherit; }

191.cc-ic button { font-family: inherit; cursor: pointer; }

~~192~~

193.cc-ic-tab-strip {

194 display: inline-flex; gap: 2px;

195 padding: 4px; background: var(--ic-gray-150);

196 border-radius: 10px; overflow-x: auto;

197 max-width: 100%;

198}

199.cc-ic-tab {

200 appearance: none; background: none; border: none;

201 padding: 10px 18px; font-size: 15px; font-weight: 430;

202 color: var(--ic-gray-550); border-radius: 7px;

203 white-space: nowrap;

204 transition: color 0.12s, background-color 0.12s;

205}

206.cc-ic-tab:hover { color: var(--ic-gray-700); }

207.cc-ic-tab.cc-ic-active {

208 color: var(--ic-slate); font-weight: 500;

209 background: var(--ic-gray-000);

210 box-shadow: 0 1px 3px rgba(0, 0, 0, 0.08);

211}

212.dark .cc-ic-tab.cc-ic-active { box-shadow: 0 1px 3px rgba(0, 0, 0, 0.4); }

~~213~~

214.cc-ic-team-wrap { padding: 16px 0 20px; }

215.cc-ic-team-toggle {

216 display: flex; align-items: center; gap: 12px; font-family: inherit;

217 padding: 12px 16px; font-size: 14px; font-weight: 430;

218 color: var(--ic-gray-700); cursor: pointer; user-select: none;

219 width: fit-content; background: var(--ic-gray-150);

220 border: 0.5px solid var(--ic-border-subtle); border-radius: 8px;

221 transition: border-color 0.15s;

222}

223.cc-ic-team-toggle:hover { border-color: var(--ic-border-default); }

224.cc-ic-team-toggle.cc-ic-checked {

225 background: rgba(217, 119, 87, 0.08);

226 border-color: rgba(217, 119, 87, 0.25);

227}

228.cc-ic-check {

229 width: 16px; height: 16px;

230 border: 1px solid var(--ic-border-strong); border-radius: 4px;

231 background: var(--ic-gray-000);

232 display: flex; align-items: center; justify-content: center;

233 flex-shrink: 0;

234}

235.cc-ic-check svg { color: #fff; display: none; }

236.cc-ic-team-toggle.cc-ic-checked .cc-ic-check { background: var(--ic-clay-deep); border-color: var(--ic-clay-deep); }

237.cc-ic-team-toggle.cc-ic-checked .cc-ic-check svg { display: block; }

~~238~~

239.cc-ic-team-reveal { display: flex; flex-direction: column; gap: 12px; margin-bottom: 16px; }

240.cc-ic-sales {

241 display: flex; align-items: center; justify-content: space-between;

242 gap: 16px; padding: 14px 16px;

243 background: var(--ic-gray-000); border: 0.5px solid var(--ic-border-default);

244 border-radius: 8px; flex-wrap: wrap;

245}

246.cc-ic-sales-text { font-size: 13px; color: var(--ic-gray-700); line-height: 1.5; flex: 1; min-width: 200px; }

247.cc-ic-sales-text strong { font-weight: 550; color: var(--ic-slate); }

248.cc-ic-sales-actions { display: flex; align-items: center; gap: 8px; flex-shrink: 0; }

249.cc-ic-btn-clay {

250 display: inline-flex; align-items: center; gap: 8px;

251 background: var(--ic-clay-deep); color: #fff; border: none;

252 border-radius: 8px; padding: 8px 14px;

253 font-size: 13px; font-weight: 500;

254 transition: background-color 0.15s; white-space: nowrap;

255}

256.cc-ic-btn-clay:hover { background: var(--ic-clay); }

257.cc-ic-btn-ghost {

258 display: inline-flex; align-items: center; gap: 8px;

259 background: transparent; color: var(--ic-gray-700);

260 border: 0.5px solid var(--ic-border-default);

261 border-radius: 8px; padding: 8px 14px;

262 font-size: 13px; font-weight: 500;

263}

264.cc-ic-btn-ghost:hover { background: rgba(0, 0, 0, 0.04); }

~~265~~

266.cc-ic-provider-bar {

267 display: flex; align-items: center; gap: 12px;

268 padding: 14px 16px; background: var(--ic-gray-150);

269 border-radius: 8px; font-size: 13px; flex-wrap: wrap;

270}

271.cc-ic-provider-bar .cc-ic-label { color: var(--ic-gray-550); flex-shrink: 0; }

272.cc-ic-provider-pills { display: flex; gap: 4px; flex-wrap: wrap; }

273.cc-ic-p-pill {

274 appearance: none; border: none; background: transparent;

275 padding: 6px 12px; border-radius: 6px;

276 font-size: 13px; font-weight: 430; color: var(--ic-gray-700);

277 white-space: nowrap;

278}

279.cc-ic-p-pill:hover { background: rgba(0, 0, 0, 0.04); }

280.cc-ic-p-pill.cc-ic-active {

281 background: var(--ic-gray-000); color: var(--ic-slate);

282 font-weight: 500; box-shadow: 0 1px 2px rgba(0, 0, 0, 0.05);

283}

284.cc-ic-provider-notice {

285 display: flex; padding: 16px 18px;

286 background: var(--ic-gray-000); border: 0.5px solid var(--ic-border-default);

287 border-radius: 8px; gap: 14px; align-items: flex-start;

288}

289.cc-ic-provider-notice > svg { color: var(--ic-gray-550); margin-top: 2px; flex-shrink: 0; }

290.cc-ic-provider-notice-body { font-size: 14px; line-height: 1.55; color: var(--ic-gray-700); }

291.cc-ic-provider-notice-body strong { font-weight: 550; color: var(--ic-slate); }

292.cc-ic-provider-notice-body a { color: var(--ic-clay-deep); font-weight: 500; }

293.cc-ic-provider-notice-body a:hover { text-decoration: underline; }

~~294~~

295.cc-ic-card { background: #141413; border-radius: 12px; overflow: hidden; }

296.cc-ic-subtabs {

297 display: flex; align-items: center;

298 background: #1a1918;

299 border-bottom: 0.5px solid rgba(255, 255, 255, 0.08);

300 padding: 0 8px; overflow-x: auto;

301}

302.cc-ic-subtab {

303 appearance: none; background: none; border: none;

304 padding: 12px 16px; font-size: 12px;

305 color: rgba(255, 255, 255, 0.5);

306 position: relative; white-space: nowrap;

307}

308.cc-ic-subtab:hover { color: rgba(255, 255, 255, 0.75); }

309.cc-ic-subtab.cc-ic-active { color: #fff; }

310.cc-ic-subtab.cc-ic-active::after {

311 content: ''; position: absolute;

312 left: 12px; right: 12px; bottom: -0.5px;

313 height: 2px; background: var(--ic-clay);

314}

315.cc-ic-shell-switch {

316 display: inline-flex; gap: 2px;

317 margin: 14px 26px 0; padding: 3px;

318 background: rgba(255, 255, 255, 0.06);

319 border: 0.5px solid rgba(255, 255, 255, 0.08);

320 border-radius: 8px;

321 font-family: inherit;

322}

323.cc-ic-shell-option {

324 font: inherit; font-size: 12px; font-weight: 500;

325 padding: 5px 12px; border-radius: 6px;

326 background: transparent; border: none;

327 color: rgba(255, 255, 255, 0.55);

328 cursor: pointer; user-select: none; white-space: nowrap;

329 transition: color 120ms ease, background-color 120ms ease;

330}

331.cc-ic-shell-option:hover { color: rgba(255, 255, 255, 0.85); }

332.cc-ic-shell-option.cc-ic-active {

333 background: rgba(255, 255, 255, 0.12);

334 color: #fff;

335 box-shadow: 0 1px 2px rgba(0, 0, 0, 0.25);

336}

~~337~~

338.cc-ic-card-body { padding: 24px 26px; display: flex; align-items: flex-start; gap: 14px; }

339.cc-ic-prompt {

340 color: var(--ic-clay); font-family: var(--ic-font-mono);

341 font-size: 17px; user-select: none; padding-top: 2px;

342}

343.cc-ic-cmd {

344 flex: 1; font-family: var(--ic-font-mono);

345 font-size: 17px; color: #f0eee6;

346 line-height: 1.55; white-space: pre-wrap; word-break: break-word;

347}

348.cc-ic-copy {

349 display: inline-flex; align-items: center; gap: 6px;

350 background: rgba(255, 255, 255, 0.08);

351 border: 0.5px solid rgba(255, 255, 255, 0.12);

352 color: rgba(255, 255, 255, 0.85);

353 padding: 7px 13px; border-radius: 8px;

354 font-size: 13px; font-weight: 500; flex-shrink: 0;

355}

356.cc-ic-copy:hover { background: rgba(255, 255, 255, 0.14); }

357.cc-ic-copy.cc-ic-copied { background: var(--ic-clay-deep); border-color: var(--ic-clay-deep); color: #fff; }

~~358~~

359.cc-ic-below {

360 margin-top: 12px; font-size: 13px; color: var(--ic-gray-550);

361 display: flex; gap: 16px; flex-wrap: wrap; align-items: baseline;

362}

363.cc-ic-below a { color: var(--ic-gray-700); border-bottom: 0.5px solid var(--ic-border-default); }

364.cc-ic-below a:hover { color: var(--ic-clay-deep); border-bottom-color: var(--ic-clay-deep); }

365.cc-ic-handoff {

366 padding: 22px 24px;

367 background: linear-gradient(180deg, #faf9f4 0%, #f3f1e9 100%);

368 border: 0.5px solid var(--ic-border-default);

369 border-radius: 12px;

370 box-shadow: 0 1px 2px rgba(31, 30, 29, 0.04), 0 6px 16px -4px rgba(31, 30, 29, 0.06);

371}

372.dark .cc-ic-handoff {

373 background: linear-gradient(180deg, #262624 0%, #1f1e1d 100%);

374 box-shadow: 0 1px 2px rgba(0, 0, 0, 0.3), 0 6px 16px -4px rgba(0, 0, 0, 0.4);

375}

376.cc-ic-handoff-title {

377 font-size: 16px; font-weight: 550; color: var(--ic-slate);

378 letter-spacing: -0.01em; margin-bottom: 4px;

379}

380.cc-ic-handoff-sub {

381 font-size: 14px; line-height: 1.5; color: var(--ic-gray-700);

382 margin-bottom: 18px;

383}

384.cc-ic-handoff-actions { display: flex; gap: 10px; flex-wrap: wrap; }

385.cc-ic-handoff-alt {

386 margin-top: 12px; font-size: 12px; color: var(--ic-gray-550);

387}

388.cc-ic-handoff-alt code {

389 font-family: var(--ic-font-mono); font-size: 11px;

390 background: var(--ic-gray-150); padding: 2px 6px;

391 border-radius: 4px; color: var(--ic-gray-700);

392}

393.cc-ic-copy-sm {

394 appearance: none; border: none;

395 display: inline-flex; align-items: center; justify-content: center;

396 width: 22px; height: 22px;

397 margin-left: 4px; vertical-align: middle;

398 background: var(--ic-gray-150); color: var(--ic-gray-550);

399 border-radius: 4px;

400 transition: color 0.1s, background-color 0.1s;

401}

402.cc-ic-copy-sm:hover { color: var(--ic-gray-700); background: var(--ic-border-default); }

403.cc-ic-copy-sm.cc-ic-copied { background: var(--ic-clay-deep); color: #fff; }

~~404~~

405@media (max-width: 720px) {

406 .cc-ic-tab { padding: 12px 14px; font-size: 14px; }

407 .cc-ic-sales-actions { width: 100%; }

408 .cc-ic-card-body { padding: 20px; }

409 .cc-ic-cmd { font-size: 15px; }

410}

411`;

412 return <div className="cc-ic not-prose">

413 <style>{STYLES}</style>

~~414~~

415 {}

416 <div className="cc-ic-tab-strip" role="tablist">

417 {TABS.map(t => <button key={t.key} type="button" role="tab" aria-selected={target === t.key} className={'cc-ic-tab' + (target === t.key ? ' cc-ic-active' : '')} onClick={() => setTarget(t.key)}>

418 {t.label}

419 </button>)}

420 </div>

~~421~~

422 {}

423 <div className="cc-ic-team-wrap">

424 <button type="button" role="switch" aria-checked={team} className={'cc-ic-team-toggle' + (team ? ' cc-ic-checked' : '')} onClick={() => setTeam(!team)}>

425 <span className="cc-ic-check">{iconCheck(11)}</span>

426 <span>

427 I’m buying for a team or company (SSO, AWS/Azure/GCP, central billing)

428 </span>

429 </button>

430 </div>

~~431~~

432 {}

433 {team && <div className="cc-ic-team-reveal">

434 <div className="cc-ic-sales">

435 <div className="cc-ic-sales-text">

436 <strong>Set up your team:</strong> self-serve or talk to sales.

437 </div>

438 <div className="cc-ic-sales-actions">

439 <a href="https://claude.ai/upgrade?initialPlanType=team&utm_source=claude_code&utm_medium=docs&utm_content=configurator_team_get_started" className="cc-ic-btn-ghost">

440 Get started

441 </a>

442 <a href="https://www.anthropic.com/contact-sales?utm_source=claude_code&utm_medium=docs&utm_content=configurator_team_contact_sales" className="cc-ic-btn-clay">

443 Contact sales {iconArrowRight()}

444 </a>

445 </div>

446 </div>

~~447~~

448 <div className="cc-ic-provider-bar">

449 <span className="cc-ic-label">Run on</span>

450 <div className="cc-ic-provider-pills" role="radiogroup" aria-label="Provider">

451 {PROVIDERS.map(p => <button key={p.key} type="button" role="radio" aria-checked={provider === p.key} className={'cc-ic-p-pill' + (provider === p.key ? ' cc-ic-active' : '')} onClick={() => setProvider(p.key)}>

452 {p.label}

453 </button>)}

454 </div>

455 </div>

~~456~~

457 {showNotice && <div className="cc-ic-provider-notice">

458 {iconInfo()}

459 <div className="cc-ic-provider-notice-body">

460 {PROVIDER_NOTICE[provider]}

461 </div>

462 </div>}

463 </div>}

~~464~~

465 {}

466 {target === 'terminal' && <div className="cc-ic-card">

467 <div className="cc-ic-subtabs" role="tablist" aria-label="Install method">

468 {Object.keys(TERM).map(k => <button key={k} type="button" role="tab" aria-selected={pkg === k} className={'cc-ic-subtab' + (pkg === k ? ' cc-ic-active' : '')} onClick={() => setPkg(k)}>

469 {TERM[k].label}

470 </button>)}

471 </div>

472 {isWinInstaller && <div className="cc-ic-shell-switch" role="tablist" aria-label="Shell">

473 {[{

474 k: 'ps',

475 label: 'PowerShell'

476 }, {

477 k: 'cmd',

478 label: 'CMD'

479 }].map(({k, label}) => {

480 const active = k === 'cmd' === winCmd;

481 return <button key={k} type="button" role="tab" aria-selected={active} className={'cc-ic-shell-option' + (active ? ' cc-ic-active' : '')} onClick={() => setWinCmd(k === 'cmd')}>

482 {label}

483 </button>;

484 })}

485 </div>}

486 {cardBodyCmd(terminalCmd, isWinPrompt ? '>' : '$')}

487 </div>}

~~488~~

489 {}

490 {target === 'terminal' && <div className="cc-ic-below">

491 {isWinInstaller && <span>

492 <a href="https://git-scm.com/downloads/win" target="_blank" rel="noopener">

493 Git for Windows

494 </a>{' '}

495 recommended. PowerShell is used if Git Bash is absent.

496 </span>}

497 {(pkg === 'brew' || pkg === 'winget') && <span>

498 Does not auto-update. Run{' '}

499 <code>{pkg === 'brew' ? 'brew upgrade claude-code' : 'winget upgrade Anthropic.ClaudeCode'}</code>{' '}

500 periodically.

501 </span>}

502 <a href="/en/troubleshoot-install">Installation troubleshooting</a>

503 </div>}

~~504~~

505 {alt && <div className="cc-ic-handoff">

506 <div className="cc-ic-handoff-title">Claude Code for {alt.name}</div>

507 <div className="cc-ic-handoff-sub">{alt.tagline}</div>

508 <div className="cc-ic-handoff-actions">

509 <a href={alt.installHref} className="cc-ic-btn-clay" {...alt.installHref.startsWith('http') ? {

510 target: '_blank',

511 rel: 'noopener'

512 } : {}}>

513 {alt.installLabel} {iconArrowUpRight(13)}

514 </a>

515 <a href={alt.guideHref} className="cc-ic-btn-ghost">

516 {alt.name} guide {iconArrowRight(12)}

517 </a>

518 </div>

519 {alt.altCmd && <div className="cc-ic-handoff-alt">

520 or run <code>{alt.altCmd}</code>

521 <button type="button" className={'cc-ic-copy-sm' + (copied === 'alt' ? ' cc-ic-copied' : '')} onClick={() => handleCopy(alt.altCmd, 'alt')} aria-label="Copy command">

522 {copied === 'alt' ? iconCheck(11) : iconCopy(11)}

523 </button>

524 </div>}

525 </div>}

526 </div>;

527};

~~528~~

529export const Experiment = ({flag, treatment, children}) => {

530 const VID_KEY = 'exp_vid';

531 const CONSENT_COUNTRIES = new Set(['AT', 'BE', 'BG', 'HR', 'CY', 'CZ', 'DK', 'EE', 'FI', 'FR', 'DE', 'GR', 'HU', 'IE', 'IT', 'LV', 'LT', 'LU', 'MT', 'NL', 'PL', 'PT', 'RO', 'SK', 'SI', 'ES', 'SE', 'RE', 'GP', 'MQ', 'GF', 'YT', 'BL', 'MF', 'PM', 'WF', 'PF', 'NC', 'AW', 'CW', 'SX', 'FO', 'GL', 'AX', 'GB', 'UK', 'AI', 'BM', 'IO', 'VG', 'KY', 'FK', 'GI', 'MS', 'PN', 'SH', 'TC', 'GG', 'JE', 'IM', 'CA', 'BR', 'IN']);

532 const fnv1a = s => {

533 let h = 0x811c9dc5;

534 for (let i = 0; i < s.length; i++) {

535 h ^= s.charCodeAt(i);

536 h += (h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24);

537 }

538 return h >>> 0;

539 };

540 const bucket = (seed, vid) => fnv1a(fnv1a(seed + vid) + '') % 10000 < 5000 ? 'control' : 'treatment';

541 const [decision] = useState(() => {

542 const params = new URLSearchParams(location.search);

543 const preBucketed = document.documentElement.dataset['gb_' + flag.replace(/-/g, '_')];

544 const force = params.get('gb-force');

545 if (force) {

546 for (const p of force.split(',')) {

547 const [k, v] = p.split(':');

548 if (k === flag) return {

549 variant: v || 'treatment',

550 track: false

551 };

552 }

553 }

554 if (navigator.globalPrivacyControl) {

555 return {

556 variant: 'control',

557 track: false

558 };

559 }

560 const prefsMatch = document.cookie.match(/(?:^|; )anthropic-consent-preferences=([^;]+)/);

561 if (prefsMatch) {

562 try {

563 if (JSON.parse(decodeURIComponent(prefsMatch[1])).analytics !== true) {

564 return {

565 variant: 'control',

566 track: false

567 };

568 }

569 } catch {

570 return {

571 variant: 'control',

572 track: false

573 };

574 }

575 } else {

576 const country = params.get('country')?.toUpperCase() || (document.cookie.match(/(?:^|; )cf_geo=([A-Z]{2})/) || [])[1];

577 if (!country || CONSENT_COUNTRIES.has(country)) {

578 return {

579 variant: 'control',

580 track: false

581 };

582 }

583 }

584 let vid;

585 try {

586 const ajsMatch = document.cookie.match(/(?:^|; )ajs_anonymous_id=([^;]+)/);

587 if (ajsMatch) {

588 vid = decodeURIComponent(ajsMatch[1]).replace(/^"|"$/g, '');

589 } else {

590 vid = localStorage.getItem(VID_KEY);

591 if (!vid) {

592 vid = crypto.randomUUID();

593 }

594 document.cookie = `ajs_anonymous_id=${vid}; domain=.claude.com; path=/; Secure; SameSite=Lax; max-age=31536000`;

595 }

596 try {

597 localStorage.setItem(VID_KEY, vid);

598 } catch {}

599 } catch {

600 return {

601 variant: 'control',

602 track: false

603 };

604 }

605 const variant = preBucketed === '1' ? 'treatment' : preBucketed === '0' ? 'control' : bucket(flag, vid);

606 return {

607 variant,

608 track: true,

609 vid

610 };

611 });

612 useEffect(() => {

613 if (!decision.track) return;

614 fetch('https://api.anthropic.com/api/event_logging/v2/batch', {

615 method: 'POST',

616 headers: {

617 'Content-Type': 'application/json',

618 'x-service-name': 'claude_code_docs'

619 },

620 body: JSON.stringify({

621 events: [{

622 event_type: 'GrowthbookExperimentEvent',

623 event_data: {

624 device_id: decision.vid,

625 anonymous_id: decision.vid,

626 timestamp: new Date().toISOString(),

627 experiment_id: flag,

628 variation_id: decision.variant === 'treatment' ? 1 : 0,

629 environment: 'production'

630 }

631 }]

632 }),

633 keepalive: true

634 }).catch(() => {});

635 }, []);

636 return decision.variant === 'treatment' ? treatment : children;

637};

~~638~~

639Claude Code é um assistente de codificação alimentado por IA que ajuda você a construir recursos, corrigir bugs e automatizar tarefas de desenvolvimento. Ele compreende toda a sua base de código e pode trabalhar em vários arquivos e ferramentas para realizar tarefas.9Claude Code é um assistente de codificação alimentado por IA que ajuda você a construir recursos, corrigir bugs e automatizar tarefas de desenvolvimento. Ele compreende toda a sua base de código e pode trabalhar em vários arquivos e ferramentas para realizar tarefas.

640 10

641<div data-gb-slot="overview-install-configurator">

642 <Experiment flag="overview-install-configurator" treatment={<InstallConfigurator />} />

643</div>

~~644~~

645## Comece agora11## Comece agora

646 12

647Escolha seu ambiente para começar. A maioria das superfícies requer uma [assinatura Claude](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=overview_pricing) ou uma conta do [Anthropic Console](https://console.anthropic.com/). O Terminal CLI e VS Code também suportam [provedores de terceiros](/pt/third-party-integrations).13Escolha seu ambiente para começar. A maioria das superfícies requer uma [assinatura Claude](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=overview_pricing) ou uma conta do [Anthropic Console](https://console.anthropic.com/). O Terminal CLI e VS Code também suportam [provedores de terceiros](/pt/third-party-integrations).

798 <Accordion title="Personalize com instruções, skills e hooks" icon="sliders">164 <Accordion title="Personalize com instruções, skills e hooks" icon="sliders">

799 [`CLAUDE.md`](/pt/memory) é um arquivo markdown que você adiciona à raiz do seu projeto que Claude Code lê no início de cada sessão. Use-o para definir padrões de codificação, decisões de arquitetura, bibliotecas preferidas e listas de verificação de revisão. Claude também constrói [memória automática](/pt/memory#auto-memory) conforme funciona, salvando aprendizados como comandos de compilação e insights de depuração em sessões sem você escrever nada.165 [`CLAUDE.md`](/pt/memory) é um arquivo markdown que você adiciona à raiz do seu projeto que Claude Code lê no início de cada sessão. Use-o para definir padrões de codificação, decisões de arquitetura, bibliotecas preferidas e listas de verificação de revisão. Claude também constrói [memória automática](/pt/memory#auto-memory) conforme funciona, salvando aprendizados como comandos de compilação e insights de depuração em sessões sem você escrever nada.

800 166

801 Crie [comandos personalizados](/pt/skills) para empacotar fluxos de trabalho repetíveis que sua equipe pode compartilhar, como `/review-pr` ou `/deploy-staging`.167 Crie [skills](/pt/skills) para empacotar fluxos de trabalho repetíveis que sua equipe pode compartilhar, como `/review-pr` ou `/deploy-staging`.

802 168

803 [Hooks](/pt/hooks) permitem que você execute comandos shell antes ou depois de ações do Claude Code, como formatação automática após cada edição de arquivo ou execução de lint antes de um commit.169 [Hooks](/pt/hooks) permitem que você execute comandos shell antes ou depois de ações do Claude Code, como formatação automática após cada edição de arquivo ou execução de lint antes de um commit.

804 </Accordion>170 </Accordion>

plugins.md +9 −1

Details

317 317

318Para testar um plugin que já está empacotado como um arquivo `.zip` e hospedado em uma URL, como um artefato de compilação de CI, use `--plugin-url` em vez disso. Claude Code busca o arquivo no início e o carrega apenas para essa sessão. Se a busca falhar ou o arquivo for inválido, Claude Code relata um erro de carregamento de plugin e inicia sem ele. As mesmas [considerações de confiança](/pt/discover-plugins#security) se aplicam como para qualquer fonte de plugin: apenas aponte esse flag para arquivos que você controla ou confia.318Para testar um plugin que já está empacotado como um arquivo `.zip` e hospedado em uma URL, como um artefato de compilação de CI, use `--plugin-url` em vez disso. Claude Code busca o arquivo no início e o carrega apenas para essa sessão. Se a busca falhar ou o arquivo for inválido, Claude Code relata um erro de carregamento de plugin e inicia sem ele. As mesmas [considerações de confiança](/pt/discover-plugins#security) se aplicam como para qualquer fonte de plugin: apenas aponte esse flag para arquivos que você controla ou confia.

319 319

320Para carregar múltiplos plugins, repita a flag para cada URL:

321

322```bash theme={null}

323claude --plugin-url https://example.com/my-plugin.zip --plugin-url https://example.com/other.zip

324```

325

326Ou passe URLs separadas por espaço como um argumento entre aspas:

327

320```bash theme={null}328```bash theme={null}

321claude --plugin-url https://example.com/my-plugin.zip329claude --plugin-url "https://example.com/my-plugin.zip https://example.com/other.zip"

322```330```

323 331

324### Depure problemas de plugin332### Depure problemas de plugin

quickstart.md +3 −636

Details

6 6

7> Bem-vindo ao Claude Code!7> Bem-vindo ao Claude Code!

8 8

~~9export const InstallConfigurator = ({defaultSurface = 'terminal'}) => {~~

~~10 const TERM = {~~

~~11 mac: {~~

~~12 label: 'macOS / Linux',~~

~~13 cmd: 'curl -fsSL https://claude.ai/install.sh | bash'~~

~~14 },~~

~~15 win: {~~

~~16 label: 'Windows'~~

~~17 },~~

~~18 brew: {~~

~~19 label: 'Homebrew',~~

~~20 cmd: 'brew install --cask claude-code'~~

~~21 },~~

~~22 winget: {~~

~~23 label: 'WinGet',~~

~~24 cmd: 'winget install Anthropic.ClaudeCode'~~

~~25 }~~

~~26 };~~

~~27 const WIN_VARIANTS = {~~

~~28 ps: 'irm https://claude.ai/install.ps1 | iex',~~

~~29 cmd: 'curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd'~~

~~30 };~~

~~31 const TABS = [{~~

~~32 key: 'terminal',~~

~~33 label: 'Terminal'~~

~~34 }, {~~

~~35 key: 'desktop',~~

~~36 label: 'Desktop'~~

~~37 }, {~~

~~38 key: 'vscode',~~

~~39 label: 'VS Code'~~

~~40 }, {~~

~~41 key: 'jetbrains',~~

~~42 label: 'JetBrains'~~

~~43 }];~~

~~44 const ALT_TARGETS = {~~

~~45 desktop: {~~

~~46 name: 'Desktop',~~

~~47 tagline: 'The full agent in a native app for macOS and Windows.',~~

~~48 installLabel: 'Download the app',~~

~~49 installHref: 'https://claude.com/download?utm_source=claude_code&utm_medium=docs&utm_content=configurator_desktop_download',~~

~~50 guideHref: '/en/desktop-quickstart'~~

~~51 },~~

~~52 vscode: {~~

~~53 name: 'VS Code',~~

~~54 tagline: 'Review diffs, manage context, and chat without leaving your editor.',~~

~~55 installLabel: 'Install from Marketplace',~~

~~56 installHref: 'https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code',~~

~~57 altCmd: 'code --install-extension anthropic.claude-code',~~

~~58 guideHref: '/en/vs-code'~~

~~59 },~~

~~60 jetbrains: {~~

~~61 name: 'JetBrains',~~

~~62 tagline: 'Native plugin for IntelliJ, PyCharm, WebStorm, and other JetBrains IDEs.',~~

~~63 installLabel: 'Install from Marketplace',~~

~~64 installHref: 'https://plugins.jetbrains.com/plugin/27310-claude-code-beta-',~~

~~65 guideHref: '/en/jetbrains'~~

~~66 }~~

~~67 };~~

~~68 const PROVIDERS = [{~~

~~69 key: 'anthropic',~~

~~70 label: 'Anthropic'~~

~~71 }, {~~

~~72 key: 'bedrock',~~

~~73 label: 'Amazon Bedrock'~~

~~74 }, {~~

~~75 key: 'foundry',~~

~~76 label: 'Microsoft Foundry'~~

~~77 }, {~~

~~78 key: 'vertex',~~

~~79 label: 'Google Vertex AI'~~

~~80 }];~~

~~81 const PROVIDER_NOTICE = {~~

~~82 bedrock: <>~~

~~83 <strong>Configure your AWS account first.</strong> Running on Bedrock~~

~~84 requires model access enabled in the AWS console and IAM credentials.{' '}~~

~~85 <a href="/en/amazon-bedrock">Bedrock setup guide →</a>~~

~~86 </>,~~

~~87 vertex: <>~~

~~88 <strong>Configure your GCP project first.</strong> Running on Vertex AI~~

~~89 requires the Vertex API enabled and a service account with the right~~

~~90 permissions.{' '}~~

~~91 <a href="/en/google-vertex-ai">Vertex setup guide →</a>~~

~~92 </>,~~

~~93 foundry: <>~~

~~94 <strong>Configure your Azure resources first.</strong> Running on~~

~~95 Microsoft Foundry requires an Azure subscription with a Foundry resource~~

~~96 and model deployments provisioned.{' '}~~

~~97 <a href="/en/microsoft-foundry">Foundry setup guide →</a>~~

~~98 </>~~

~~99 };~~

101 <polyline points="20 6 9 17 4 12" />

102 </svg>;

104 <rect x="9" y="9" width="13" height="13" rx="2" />

105 <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" />

106 </svg>;

108 <line x1="5" y1="12" x2="19" y2="12" />

109 <polyline points="12 5 19 12 12 19" />

110 </svg>;

112 <line x1="7" y1="17" x2="17" y2="7" />

113 <polyline points="7 7 17 7 17 17" />

114 </svg>;

116 <circle cx="12" cy="12" r="10" />

117 <line x1="12" y1="16" x2="12" y2="12" />

118 <line x1="12" y1="8" x2="12.01" y2="8" />

119 </svg>;

120 const [target, setTarget] = useState(defaultSurface);

121 const [team, setTeam] = useState(false);

122 const [provider, setProvider] = useState('anthropic');

123 const [pkg, setPkg] = useState(() => (/Win/).test(navigator.userAgent) ? 'win' : 'mac');

124 const [winCmd, setWinCmd] = useState(false);

125 const [copied, setCopied] = useState(null);

126 const copyTimer = useRef(null);

127 const handleCopy = async (text, key) => {

128 try {

129 await navigator.clipboard.writeText(text);

130 } catch {

131 const ta = document.createElement('textarea');

132 ta.value = text;

133 document.body.appendChild(ta);

134 ta.select();

135 document.execCommand('copy');

136 document.body.removeChild(ta);

137 }

138 clearTimeout(copyTimer.current);

139 setCopied(key);

140 copyTimer.current = setTimeout(() => setCopied(null), 1800);

141 };

142 const cardBodyCmd = (cmd, prompt) => {

143 const on = copied === 'term';

144 return <div className="cc-ic-card-body">

145 <span className="cc-ic-prompt">{prompt || '$'}</span>

146 <div className="cc-ic-cmd">{cmd}</div>

147 <button type="button" className={'cc-ic-copy' + (on ? ' cc-ic-copied' : '')} onClick={() => handleCopy(cmd, 'term')}>

148 {on ? iconCheck(13) : iconCopy(13)}

149 <span>{on ? 'Copied' : 'Copy'}</span>

150 </button>

151 </div>;

152 };

153 const isWinInstaller = pkg === 'win';

154 const isWinPrompt = pkg === 'win' || pkg === 'winget';

155 const terminalCmd = isWinInstaller ? WIN_VARIANTS[winCmd ? 'cmd' : 'ps'] : TERM[pkg].cmd;

156 const alt = ALT_TARGETS[target];

157 const showNotice = team && provider !== 'anthropic';

158 const STYLES = `

159.cc-ic {

160 --ic-slate: #141413;

161 --ic-clay: #d97757;

162 --ic-clay-deep: #c6613f;

163 --ic-gray-000: #ffffff;

164 --ic-gray-150: #f0eee6;

165 --ic-gray-550: #73726c;

166 --ic-gray-700: #3d3d3a;

167 --ic-border-subtle: rgba(31, 30, 29, 0.08);

168 --ic-border-default: rgba(31, 30, 29, 0.15);

169 --ic-border-strong: rgba(31, 30, 29, 0.3);

170 --ic-font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, 'Courier New', monospace;

171 font-family: 'Anthropic Sans', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;

172 font-size: 14px; line-height: 1.5; color: var(--ic-slate);

173 margin: 8px 0 32px;

174}

175.dark .cc-ic {

176 --ic-slate: #f0eee6;

177 --ic-gray-000: #262624;

178 --ic-gray-150: #1f1e1d;

179 --ic-gray-550: #91908a;

180 --ic-gray-700: #bfbdb4;

181 --ic-border-subtle: rgba(240, 238, 230, 0.08);

182 --ic-border-default: rgba(240, 238, 230, 0.14);

183 --ic-border-strong: rgba(240, 238, 230, 0.28);

184}

185.dark .cc-ic-check { background: transparent; }

186.dark .cc-ic-card { border: 0.5px solid var(--ic-border-subtle); }

187.dark .cc-ic-p-pill.cc-ic-active { box-shadow: 0 1px 2px rgba(0, 0, 0, 0.3); }

188.cc-ic *, .cc-ic *::before, .cc-ic *::after { box-sizing: border-box; }

189.cc-ic a { text-decoration: none; }

190.cc-ic a:not([class]) { color: inherit; }

191.cc-ic button { font-family: inherit; cursor: pointer; }

~~192~~

193.cc-ic-tab-strip {

194 display: inline-flex; gap: 2px;

195 padding: 4px; background: var(--ic-gray-150);

196 border-radius: 10px; overflow-x: auto;

197 max-width: 100%;

198}

199.cc-ic-tab {

200 appearance: none; background: none; border: none;

201 padding: 10px 18px; font-size: 15px; font-weight: 430;

202 color: var(--ic-gray-550); border-radius: 7px;

203 white-space: nowrap;

204 transition: color 0.12s, background-color 0.12s;

205}

206.cc-ic-tab:hover { color: var(--ic-gray-700); }

207.cc-ic-tab.cc-ic-active {

208 color: var(--ic-slate); font-weight: 500;

209 background: var(--ic-gray-000);

210 box-shadow: 0 1px 3px rgba(0, 0, 0, 0.08);

211}

212.dark .cc-ic-tab.cc-ic-active { box-shadow: 0 1px 3px rgba(0, 0, 0, 0.4); }

~~213~~

214.cc-ic-team-wrap { padding: 16px 0 20px; }

215.cc-ic-team-toggle {

216 display: flex; align-items: center; gap: 12px; font-family: inherit;

217 padding: 12px 16px; font-size: 14px; font-weight: 430;

218 color: var(--ic-gray-700); cursor: pointer; user-select: none;

219 width: fit-content; background: var(--ic-gray-150);

220 border: 0.5px solid var(--ic-border-subtle); border-radius: 8px;

221 transition: border-color 0.15s;

222}

223.cc-ic-team-toggle:hover { border-color: var(--ic-border-default); }

224.cc-ic-team-toggle.cc-ic-checked {

225 background: rgba(217, 119, 87, 0.08);

226 border-color: rgba(217, 119, 87, 0.25);

227}

228.cc-ic-check {

229 width: 16px; height: 16px;

230 border: 1px solid var(--ic-border-strong); border-radius: 4px;

231 background: var(--ic-gray-000);

232 display: flex; align-items: center; justify-content: center;

233 flex-shrink: 0;

234}

235.cc-ic-check svg { color: #fff; display: none; }

236.cc-ic-team-toggle.cc-ic-checked .cc-ic-check { background: var(--ic-clay-deep); border-color: var(--ic-clay-deep); }

237.cc-ic-team-toggle.cc-ic-checked .cc-ic-check svg { display: block; }

~~238~~

239.cc-ic-team-reveal { display: flex; flex-direction: column; gap: 12px; margin-bottom: 16px; }

240.cc-ic-sales {

241 display: flex; align-items: center; justify-content: space-between;

242 gap: 16px; padding: 14px 16px;

243 background: var(--ic-gray-000); border: 0.5px solid var(--ic-border-default);

244 border-radius: 8px; flex-wrap: wrap;

245}

246.cc-ic-sales-text { font-size: 13px; color: var(--ic-gray-700); line-height: 1.5; flex: 1; min-width: 200px; }

247.cc-ic-sales-text strong { font-weight: 550; color: var(--ic-slate); }

248.cc-ic-sales-actions { display: flex; align-items: center; gap: 8px; flex-shrink: 0; }

249.cc-ic-btn-clay {

250 display: inline-flex; align-items: center; gap: 8px;

251 background: var(--ic-clay-deep); color: #fff; border: none;

252 border-radius: 8px; padding: 8px 14px;

253 font-size: 13px; font-weight: 500;

254 transition: background-color 0.15s; white-space: nowrap;

255}

256.cc-ic-btn-clay:hover { background: var(--ic-clay); }

257.cc-ic-btn-ghost {

258 display: inline-flex; align-items: center; gap: 8px;

259 background: transparent; color: var(--ic-gray-700);

260 border: 0.5px solid var(--ic-border-default);

261 border-radius: 8px; padding: 8px 14px;

262 font-size: 13px; font-weight: 500;

263}

264.cc-ic-btn-ghost:hover { background: rgba(0, 0, 0, 0.04); }

~~265~~

266.cc-ic-provider-bar {

267 display: flex; align-items: center; gap: 12px;

268 padding: 14px 16px; background: var(--ic-gray-150);

269 border-radius: 8px; font-size: 13px; flex-wrap: wrap;

270}

271.cc-ic-provider-bar .cc-ic-label { color: var(--ic-gray-550); flex-shrink: 0; }

272.cc-ic-provider-pills { display: flex; gap: 4px; flex-wrap: wrap; }

273.cc-ic-p-pill {

274 appearance: none; border: none; background: transparent;

275 padding: 6px 12px; border-radius: 6px;

276 font-size: 13px; font-weight: 430; color: var(--ic-gray-700);

277 white-space: nowrap;

278}

279.cc-ic-p-pill:hover { background: rgba(0, 0, 0, 0.04); }

280.cc-ic-p-pill.cc-ic-active {

281 background: var(--ic-gray-000); color: var(--ic-slate);

282 font-weight: 500; box-shadow: 0 1px 2px rgba(0, 0, 0, 0.05);

283}

284.cc-ic-provider-notice {

285 display: flex; padding: 16px 18px;

286 background: var(--ic-gray-000); border: 0.5px solid var(--ic-border-default);

287 border-radius: 8px; gap: 14px; align-items: flex-start;

288}

289.cc-ic-provider-notice > svg { color: var(--ic-gray-550); margin-top: 2px; flex-shrink: 0; }

290.cc-ic-provider-notice-body { font-size: 14px; line-height: 1.55; color: var(--ic-gray-700); }

291.cc-ic-provider-notice-body strong { font-weight: 550; color: var(--ic-slate); }

292.cc-ic-provider-notice-body a { color: var(--ic-clay-deep); font-weight: 500; }

293.cc-ic-provider-notice-body a:hover { text-decoration: underline; }

~~294~~

295.cc-ic-card { background: #141413; border-radius: 12px; overflow: hidden; }

296.cc-ic-subtabs {

297 display: flex; align-items: center;

298 background: #1a1918;

299 border-bottom: 0.5px solid rgba(255, 255, 255, 0.08);

300 padding: 0 8px; overflow-x: auto;

301}

302.cc-ic-subtab {

303 appearance: none; background: none; border: none;

304 padding: 12px 16px; font-size: 12px;

305 color: rgba(255, 255, 255, 0.5);

306 position: relative; white-space: nowrap;

307}

308.cc-ic-subtab:hover { color: rgba(255, 255, 255, 0.75); }

309.cc-ic-subtab.cc-ic-active { color: #fff; }

310.cc-ic-subtab.cc-ic-active::after {

311 content: ''; position: absolute;

312 left: 12px; right: 12px; bottom: -0.5px;

313 height: 2px; background: var(--ic-clay);

314}

315.cc-ic-shell-switch {

316 display: inline-flex; gap: 2px;

317 margin: 14px 26px 0; padding: 3px;

318 background: rgba(255, 255, 255, 0.06);

319 border: 0.5px solid rgba(255, 255, 255, 0.08);

320 border-radius: 8px;

321 font-family: inherit;

322}

323.cc-ic-shell-option {

324 font: inherit; font-size: 12px; font-weight: 500;

325 padding: 5px 12px; border-radius: 6px;

326 background: transparent; border: none;

327 color: rgba(255, 255, 255, 0.55);

328 cursor: pointer; user-select: none; white-space: nowrap;

329 transition: color 120ms ease, background-color 120ms ease;

330}

331.cc-ic-shell-option:hover { color: rgba(255, 255, 255, 0.85); }

332.cc-ic-shell-option.cc-ic-active {

333 background: rgba(255, 255, 255, 0.12);

334 color: #fff;

335 box-shadow: 0 1px 2px rgba(0, 0, 0, 0.25);

336}

~~337~~

338.cc-ic-card-body { padding: 24px 26px; display: flex; align-items: flex-start; gap: 14px; }

339.cc-ic-prompt {

340 color: var(--ic-clay); font-family: var(--ic-font-mono);

341 font-size: 17px; user-select: none; padding-top: 2px;

342}

343.cc-ic-cmd {

344 flex: 1; font-family: var(--ic-font-mono);

345 font-size: 17px; color: #f0eee6;

346 line-height: 1.55; white-space: pre-wrap; word-break: break-word;

347}

348.cc-ic-copy {

349 display: inline-flex; align-items: center; gap: 6px;

350 background: rgba(255, 255, 255, 0.08);

351 border: 0.5px solid rgba(255, 255, 255, 0.12);

352 color: rgba(255, 255, 255, 0.85);

353 padding: 7px 13px; border-radius: 8px;

354 font-size: 13px; font-weight: 500; flex-shrink: 0;

355}

356.cc-ic-copy:hover { background: rgba(255, 255, 255, 0.14); }

357.cc-ic-copy.cc-ic-copied { background: var(--ic-clay-deep); border-color: var(--ic-clay-deep); color: #fff; }

~~358~~

359.cc-ic-below {

360 margin-top: 12px; font-size: 13px; color: var(--ic-gray-550);

361 display: flex; gap: 16px; flex-wrap: wrap; align-items: baseline;

362}

363.cc-ic-below a { color: var(--ic-gray-700); border-bottom: 0.5px solid var(--ic-border-default); }

364.cc-ic-below a:hover { color: var(--ic-clay-deep); border-bottom-color: var(--ic-clay-deep); }

365.cc-ic-handoff {

366 padding: 22px 24px;

367 background: linear-gradient(180deg, #faf9f4 0%, #f3f1e9 100%);

368 border: 0.5px solid var(--ic-border-default);

369 border-radius: 12px;

370 box-shadow: 0 1px 2px rgba(31, 30, 29, 0.04), 0 6px 16px -4px rgba(31, 30, 29, 0.06);

371}

372.dark .cc-ic-handoff {

373 background: linear-gradient(180deg, #262624 0%, #1f1e1d 100%);

374 box-shadow: 0 1px 2px rgba(0, 0, 0, 0.3), 0 6px 16px -4px rgba(0, 0, 0, 0.4);

375}

376.cc-ic-handoff-title {

377 font-size: 16px; font-weight: 550; color: var(--ic-slate);

378 letter-spacing: -0.01em; margin-bottom: 4px;

379}

380.cc-ic-handoff-sub {

381 font-size: 14px; line-height: 1.5; color: var(--ic-gray-700);

382 margin-bottom: 18px;

383}

384.cc-ic-handoff-actions { display: flex; gap: 10px; flex-wrap: wrap; }

385.cc-ic-handoff-alt {

386 margin-top: 12px; font-size: 12px; color: var(--ic-gray-550);

387}

388.cc-ic-handoff-alt code {

389 font-family: var(--ic-font-mono); font-size: 11px;

390 background: var(--ic-gray-150); padding: 2px 6px;

391 border-radius: 4px; color: var(--ic-gray-700);

392}

393.cc-ic-copy-sm {

394 appearance: none; border: none;

395 display: inline-flex; align-items: center; justify-content: center;

396 width: 22px; height: 22px;

397 margin-left: 4px; vertical-align: middle;

398 background: var(--ic-gray-150); color: var(--ic-gray-550);

399 border-radius: 4px;

400 transition: color 0.1s, background-color 0.1s;

401}

402.cc-ic-copy-sm:hover { color: var(--ic-gray-700); background: var(--ic-border-default); }

403.cc-ic-copy-sm.cc-ic-copied { background: var(--ic-clay-deep); color: #fff; }

~~404~~

405@media (max-width: 720px) {

406 .cc-ic-tab { padding: 12px 14px; font-size: 14px; }

407 .cc-ic-sales-actions { width: 100%; }

408 .cc-ic-card-body { padding: 20px; }

409 .cc-ic-cmd { font-size: 15px; }

410}

411`;

412 return <div className="cc-ic not-prose">

413 <style>{STYLES}</style>

~~414~~

415 {}

416 <div className="cc-ic-tab-strip" role="tablist">

418 {t.label}

419 </button>)}

420 </div>

~~421~~

422 {}

423 <div className="cc-ic-team-wrap">

424 <button type="button" role="switch" aria-checked={team} className={'cc-ic-team-toggle' + (team ? ' cc-ic-checked' : '')} onClick={() => setTeam(!team)}>

425 <span className="cc-ic-check">{iconCheck(11)}</span>

426 <span>

427 I’m buying for a team or company (SSO, AWS/Azure/GCP, central billing)

428 </span>

429 </button>

430 </div>

~~431~~

432 {}

433 {team && <div className="cc-ic-team-reveal">

434 <div className="cc-ic-sales">

435 <div className="cc-ic-sales-text">

436 <strong>Set up your team:</strong> self-serve or talk to sales.

437 </div>

438 <div className="cc-ic-sales-actions">

439 <a href="https://claude.ai/upgrade?initialPlanType=team&utm_source=claude_code&utm_medium=docs&utm_content=configurator_team_get_started" className="cc-ic-btn-ghost">

440 Get started

441 </a>

442 <a href="https://www.anthropic.com/contact-sales?utm_source=claude_code&utm_medium=docs&utm_content=configurator_team_contact_sales" className="cc-ic-btn-clay">

443 Contact sales {iconArrowRight()}

444 </a>

445 </div>

446 </div>

~~447~~

448 <div className="cc-ic-provider-bar">

449 <span className="cc-ic-label">Run on</span>

450 <div className="cc-ic-provider-pills" role="radiogroup" aria-label="Provider">

452 {p.label}

453 </button>)}

454 </div>

455 </div>

~~456~~

457 {showNotice && <div className="cc-ic-provider-notice">

458 {iconInfo()}

459 <div className="cc-ic-provider-notice-body">

460 {PROVIDER_NOTICE[provider]}

461 </div>

462 </div>}

463 </div>}

~~464~~

465 {}

466 {target === 'terminal' && <div className="cc-ic-card">

467 <div className="cc-ic-subtabs" role="tablist" aria-label="Install method">

468 {Object.keys(TERM).map(k => <button key={k} type="button" role="tab" aria-selected={pkg === k} className={'cc-ic-subtab' + (pkg === k ? ' cc-ic-active' : '')} onClick={() => setPkg(k)}>

469 {TERM[k].label}

470 </button>)}

471 </div>

472 {isWinInstaller && <div className="cc-ic-shell-switch" role="tablist" aria-label="Shell">

473 {[{

474 k: 'ps',

475 label: 'PowerShell'

476 }, {

477 k: 'cmd',

478 label: 'CMD'

479 }].map(({k, label}) => {

480 const active = k === 'cmd' === winCmd;

481 return <button key={k} type="button" role="tab" aria-selected={active} className={'cc-ic-shell-option' + (active ? ' cc-ic-active' : '')} onClick={() => setWinCmd(k === 'cmd')}>

482 {label}

483 </button>;

484 })}

485 </div>}

486 {cardBodyCmd(terminalCmd, isWinPrompt ? '>' : '$')}

487 </div>}

~~488~~

489 {}

490 {target === 'terminal' && <div className="cc-ic-below">

491 {isWinInstaller && <span>

492 <a href="https://git-scm.com/downloads/win" target="_blank" rel="noopener">

493 Git for Windows

494 </a>{' '}

495 recommended. PowerShell is used if Git Bash is absent.

496 </span>}

497 {(pkg === 'brew' || pkg === 'winget') && <span>

498 Does not auto-update. Run{' '}

499 <code>{pkg === 'brew' ? 'brew upgrade claude-code' : 'winget upgrade Anthropic.ClaudeCode'}</code>{' '}

500 periodically.

501 </span>}

502 <a href="/en/troubleshoot-install">Installation troubleshooting</a>

503 </div>}

~~504~~

505 {alt && <div className="cc-ic-handoff">

506 <div className="cc-ic-handoff-title">Claude Code for {alt.name}</div>

507 <div className="cc-ic-handoff-sub">{alt.tagline}</div>

508 <div className="cc-ic-handoff-actions">

509 <a href={alt.installHref} className="cc-ic-btn-clay" {...alt.installHref.startsWith('http') ? {

510 target: '_blank',

511 rel: 'noopener'

512 } : {}}>

513 {alt.installLabel} {iconArrowUpRight(13)}

514 </a>

515 <a href={alt.guideHref} className="cc-ic-btn-ghost">

516 {alt.name} guide {iconArrowRight(12)}

517 </a>

518 </div>

519 {alt.altCmd && <div className="cc-ic-handoff-alt">

520 or run <code>{alt.altCmd}</code>

521 <button type="button" className={'cc-ic-copy-sm' + (copied === 'alt' ? ' cc-ic-copied' : '')} onClick={() => handleCopy(alt.altCmd, 'alt')} aria-label="Copy command">

522 {copied === 'alt' ? iconCheck(11) : iconCopy(11)}

523 </button>

524 </div>}

525 </div>}

526 </div>;

527};

~~528~~

529export const Experiment = ({flag, treatment, children}) => {

530 const VID_KEY = 'exp_vid';

532 const fnv1a = s => {

533 let h = 0x811c9dc5;

534 for (let i = 0; i < s.length; i++) {

535 h ^= s.charCodeAt(i);

536 h += (h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24);

537 }

538 return h >>> 0;

539 };

540 const bucket = (seed, vid) => fnv1a(fnv1a(seed + vid) + '') % 10000 < 5000 ? 'control' : 'treatment';

541 const [decision] = useState(() => {

542 const params = new URLSearchParams(location.search);

543 const preBucketed = document.documentElement.dataset['gb_' + flag.replace(/-/g, '_')];

544 const force = params.get('gb-force');

545 if (force) {

546 for (const p of force.split(',')) {

547 const [k, v] = p.split(':');

548 if (k === flag) return {

549 variant: v || 'treatment',

550 track: false

551 };

552 }

553 }

554 if (navigator.globalPrivacyControl) {

555 return {

556 variant: 'control',

557 track: false

558 };

559 }

560 const prefsMatch = document.cookie.match(/(?:^|; )anthropic-consent-preferences=([^;]+)/);

561 if (prefsMatch) {

562 try {

563 if (JSON.parse(decodeURIComponent(prefsMatch[1])).analytics !== true) {

564 return {

565 variant: 'control',

566 track: false

567 };

568 }

569 } catch {

570 return {

571 variant: 'control',

572 track: false

573 };

574 }

575 } else {

576 const country = params.get('country')?.toUpperCase() || (document.cookie.match(/(?:^|; )cf_geo=([A-Z]{2})/) || [])[1];

577 if (!country || CONSENT_COUNTRIES.has(country)) {

578 return {

579 variant: 'control',

580 track: false

581 };

582 }

583 }

584 let vid;

585 try {

586 const ajsMatch = document.cookie.match(/(?:^|; )ajs_anonymous_id=([^;]+)/);

587 if (ajsMatch) {

588 vid = decodeURIComponent(ajsMatch[1]).replace(/^"|"$/g, '');

589 } else {

590 vid = localStorage.getItem(VID_KEY);

591 if (!vid) {

592 vid = crypto.randomUUID();

593 }

594 document.cookie = `ajs_anonymous_id=${vid}; domain=.claude.com; path=/; Secure; SameSite=Lax; max-age=31536000`;

595 }

596 try {

597 localStorage.setItem(VID_KEY, vid);

598 } catch {}

599 } catch {

600 return {

601 variant: 'control',

602 track: false

603 };

604 }

605 const variant = preBucketed === '1' ? 'treatment' : preBucketed === '0' ? 'control' : bucket(flag, vid);

606 return {

607 variant,

608 track: true,

609 vid

610 };

611 });

612 useEffect(() => {

613 if (!decision.track) return;

614 fetch('https://api.anthropic.com/api/event_logging/v2/batch', {

615 method: 'POST',

616 headers: {

617 'Content-Type': 'application/json',

618 'x-service-name': 'claude_code_docs'

619 },

620 body: JSON.stringify({

621 events: [{

622 event_type: 'GrowthbookExperimentEvent',

623 event_data: {

624 device_id: decision.vid,

625 anonymous_id: decision.vid,

626 timestamp: new Date().toISOString(),

627 experiment_id: flag,

628 variation_id: decision.variant === 'treatment' ? 1 : 0,

629 environment: 'production'

630 }

631 }]

632 }),

633 keepalive: true

634 }).catch(() => {});

635 }, []);

636 return decision.variant === 'treatment' ? treatment : children;

637};

~~638~~

639Este guia de início rápido o colocará usando assistência de codificação alimentada por IA em poucos minutos. Ao final, você entenderá como usar Claude Code para tarefas comuns de desenvolvimento.9Este guia de início rápido o colocará usando assistência de codificação alimentada por IA em poucos minutos. Ao final, você entenderá como usar Claude Code para tarefas comuns de desenvolvimento.

640 10

641<Experiment flag="quickstart-install-configurator" treatment={<InstallConfigurator />} />

~~642~~

643## Antes de começar11## Antes de começar

644 12

645Certifique-se de que você tem:13Certifique-se de que você tem:

647* Um terminal ou prompt de comando aberto15* Um terminal ou prompt de comando aberto

648 * Se você nunca usou o terminal antes, confira o [guia de terminal](/pt/terminal-guide)16 * Se você nunca usou o terminal antes, confira o [guia de terminal](/pt/terminal-guide)

649* Um projeto de código para trabalhar17* Um projeto de código para trabalhar

650* Uma [assinatura Claude](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=quickstart_prereq) (Pro, Max, Teams ou Enterprise), conta do [Claude Console](https://console.anthropic.com/), ou acesso através de um [provedor de nuvem suportado](/pt/third-party-integrations)18* Uma [assinatura Claude](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=quickstart_prereq) (Pro, Max, Team ou Enterprise), conta do [Claude Console](https://console.anthropic.com/), ou acesso através de um [provedor de nuvem suportado](/pt/third-party-integrations)

651 19

652<Note>20<Note>

653 Este guia cobre o CLI do terminal. Claude Code também está disponível na [web](https://claude.ai/code), como um [aplicativo de desktop](/pt/desktop), em [VS Code](/pt/vs-code) e [IDEs JetBrains](/pt/jetbrains), no [Slack](/pt/slack), e em CI/CD com [GitHub Actions](/pt/github-actions) e [GitLab](/pt/gitlab-ci-cd). Veja [todas as interfaces](/pt/overview#use-claude-code-everywhere).21 Este guia cobre o CLI do terminal. Claude Code também está disponível na [web](https://claude.ai/code), como um [aplicativo de desktop](/pt/desktop), em [VS Code](/pt/vs-code) e [IDEs JetBrains](/pt/jetbrains), no [Slack](/pt/slack), e em CI/CD com [GitHub Actions](/pt/github-actions) e [GitLab](/pt/gitlab-ci-cd). Veja [todas as interfaces](/pt/overview#use-claude-code-everywhere).

727 95

728Você pode fazer login usando qualquer um destes tipos de conta:96Você pode fazer login usando qualquer um destes tipos de conta:

729 97

730* [Claude Pro, Max, Teams ou Enterprise](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=quickstart_login) (recomendado)98* [Claude Pro, Max, Team ou Enterprise](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=quickstart_login) (recomendado)

731* [Claude Console](https://console.anthropic.com/) (acesso à API com créditos pré-pagos). No primeiro login, um workspace "Claude Code" é criado automaticamente no Console para rastreamento centralizado de custos.99* [Claude Console](https://console.anthropic.com/) (acesso à API com créditos pré-pagos). No primeiro login, um workspace "Claude Code" é criado automaticamente no Console para rastreamento centralizado de custos.

732* [Amazon Bedrock, Google Vertex AI ou Microsoft Foundry](/pt/third-party-integrations) (provedores de nuvem empresariais)100* [Amazon Bedrock, Google Vertex AI ou Microsoft Foundry](/pt/third-party-integrations) (provedores de nuvem empresariais)

733 101

902| `claude commit` | Criar um commit Git | `claude commit` |

906 273

907Veja a [referência CLI](/pt/cli-reference) para uma lista completa de comandos.274Veja a [referência CLI](/pt/cli-reference) para uma lista completa de comandos.

908 275

settings.md +7 −3

Details

156`settings.json` suporta várias opções:156`settings.json` suporta várias opções:

157 157

159| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------- |159| :-------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------- |

160| `agent` | Executar a thread principal como um subagent nomeado. Aplica o prompt do sistema, restrições de ferramenta e modelo do subagent. Veja [Invocar subagents explicitamente](/pt/sub-agents#invoke-subagents-explicitly) | `"code-reviewer"` |160| `agent` | Executar a thread principal como um subagent nomeado. Aplica o prompt do sistema, restrições de ferramenta e modelo do subagent. Veja [Invocar subagents explicitamente](/pt/sub-agents#invoke-subagents-explicitly) | `"code-reviewer"` |

161| `allowedChannelPlugins` | (Apenas configurações gerenciadas) Lista de permissões de plugins de canal que podem enviar mensagens. Substitui a lista de permissões padrão da Anthropic quando definido. Indefinido = voltar para o padrão, array vazio = bloquear todos os plugins de canal. Requer `channelsEnabled: true`. Veja [Restringir quais plugins de canal podem executar](/pt/channels#restrict-which-channel-plugins-can-run) | `[{ "marketplace": "claude-plugins-official", "plugin": "telegram" }]` |161| `allowedChannelPlugins` | (Apenas configurações gerenciadas) Lista de permissões de plugins de canal que podem enviar mensagens. Substitui a lista de permissões padrão da Anthropic quando definido. Indefinido = voltar para o padrão, array vazio = bloquear todos os plugins de canal. Requer `channelsEnabled: true`. Veja [Restringir quais plugins de canal podem executar](/pt/channels#restrict-which-channel-plugins-can-run) | `[{ "marketplace": "claude-plugins-official", "plugin": "telegram" }]` |

162| `allowedHttpHookUrls` | Lista de permissões de padrões de URL que hooks HTTP podem almejar. Suporta `*` como curinga. Quando definido, hooks com URLs não correspondentes são bloqueados. Indefinido = sem restrição, array vazio = bloquear todos os hooks HTTP. Arrays se mesclam entre fontes de configuração. Veja [Configuração de hooks](#hook-configuration) | `["https://hooks.example.com/*"]` |162| `allowedHttpHookUrls` | Lista de permissões de padrões de URL que hooks HTTP podem almejar. Suporta `*` como curinga. Quando definido, hooks com URLs não correspondentes são bloqueados. Indefinido = sem restrição, array vazio = bloquear todos os hooks HTTP. Arrays se mesclam entre fontes de configuração. Veja [Configuração de hooks](#hook-configuration) | `["https://hooks.example.com/*"]` |

211| `modelOverrides` | Mapear IDs de modelo Anthropic para IDs de modelo específicos do provedor, como ARNs de perfil de inferência Bedrock. Cada entrada do seletor de modelo usa seu valor mapeado ao chamar a API do provedor. Veja [Substituir IDs de modelo por versão](/pt/model-config#override-model-ids-per-version) | `{"claude-opus-4-6": "arn:aws:bedrock:..."}` |211| `modelOverrides` | Mapear IDs de modelo Anthropic para IDs de modelo específicos do provedor, como ARNs de perfil de inferência Bedrock. Cada entrada do seletor de modelo usa seu valor mapeado ao chamar a API do provedor. Veja [Substituir IDs de modelo por versão](/pt/model-config#override-model-ids-per-version) | `{"claude-opus-4-6": "arn:aws:bedrock:..."}` |

212| `otelHeadersHelper` | Script para gerar cabeçalhos OpenTelemetry dinâmicos. Executa na inicialização e periodicamente. Defina o intervalo de atualização com [`CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS`](/pt/env-vars). Veja [Cabeçalhos dinâmicos](/pt/monitoring-usage#dynamic-headers) | `/bin/generate_otel_headers.sh` |212| `otelHeadersHelper` | Script para gerar cabeçalhos OpenTelemetry dinâmicos. Executa na inicialização e periodicamente. Defina o intervalo de atualização com [`CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS`](/pt/env-vars). Veja [Cabeçalhos dinâmicos](/pt/monitoring-usage#dynamic-headers) | `/bin/generate_otel_headers.sh` |

214| `parentSettingsBehavior` | {/* min-version: 2.1.133 */}(Apenas configurações gerenciadas) Controla se configurações gerenciadas fornecidas programaticamente por um processo host de incorporação, como o Agent SDK ou uma extensão IDE, se aplicam quando um nível gerenciado implantado por administrador também está presente. `"first-wins"`: as configurações fornecidas pelo pai são descartadas e apenas o nível de administrador se aplica. `"merge"`: as configurações fornecidas pelo pai se aplicam sob o nível de administrador, filtradas para que possam apertar a política mas não afrouxá-la. Não tem efeito quando nenhum nível de administrador é implantado. Padrão: `"first-wins"`. Requer Claude Code v2.1.133 ou posterior | `"merge"` |

216| `pluginTrustMessage` | (Apenas configurações gerenciadas) Mensagem personalizada anexada ao aviso de confiança de plugin mostrado antes da instalação. Use isto para adicionar contexto específico da organização, por exemplo para confirmar que plugins do seu marketplace interno são verificados. | `"All plugins from our marketplace are approved by IT"` |217| `pluginTrustMessage` | (Apenas configurações gerenciadas) Mensagem personalizada anexada ao aviso de confiança de plugin mostrado antes da instalação. Use isto para adicionar contexto específico da organização, por exemplo para confirmar que plugins do seu marketplace interno são verificados. | `"All plugins from our marketplace are approved by IT"` |

255 256

256### Configurações de worktrees257### Configurações de worktrees

257 258

258Configure como `--worktree` cria e gerencia git worktrees. Use estas configurações para reduzir uso de disco e tempo de inicialização em grandes monorepos.259Configure como `--worktree` cria e gerencia git worktrees.

259 260

261| :---------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------ |262| :---------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------ |

263| `worktree.baseRef` | Qual ref novos worktrees ramificam. `"fresh"` (padrão) ramifica de `origin/<default-branch>` para uma árvore limpa correspondendo ao remoto. `"head"` ramifica de seu `HEAD` local atual, então commits não enviados e estado de branch de feature estão presentes no worktree. Se aplica a `--worktree`, a ferramenta `EnterWorktree`, e isolamento de subagent | `"head"` |

262| `worktree.symlinkDirectories` | Diretórios para criar symlink do repositório principal em cada worktree para evitar duplicar grandes diretórios no disco. Nenhum diretório é criado symlink por padrão | `["node_modules", ".cache"]` |264| `worktree.symlinkDirectories` | Diretórios para criar symlink do repositório principal em cada worktree para evitar duplicar grandes diretórios no disco. Nenhum diretório é criado symlink por padrão | `["node_modules", ".cache"]` |

263| `worktree.sparsePaths` | Diretórios para fazer checkout em cada worktree via git sparse-checkout (modo cone). Apenas os caminhos listados são escritos no disco, o que é mais rápido em grandes monorepos | `["packages/my-app", "shared/utils"]` |265| `worktree.sparsePaths` | Diretórios para fazer checkout em cada worktree via git sparse-checkout (modo cone). Apenas os caminhos listados são escritos no disco, o que é mais rápido em grandes monorepos | `["packages/my-app", "shared/utils"]` |

264 266

318| `network.socksProxyPort` | Porta de proxy SOCKS5 usada se você deseja trazer seu próprio proxy. Se não especificado, Claude executará seu próprio proxy. | `8081` |320| `network.socksProxyPort` | Porta de proxy SOCKS5 usada se você deseja trazer seu próprio proxy. Se não especificado, Claude executará seu próprio proxy. | `8081` |

320| `enableWeakerNetworkIsolation` | (Apenas macOS) Permitir acesso ao serviço de confiança TLS do sistema (`com.apple.trustd.agent`) no sandbox. Necessário para ferramentas baseadas em Go como `gh`, `gcloud`, e `terraform` verificarem certificados TLS ao usar `httpProxyPort` com um proxy MITM e CA personalizada. **Reduz segurança** abrindo um possível caminho de exfiltração de dados. Padrão: false | `true` |322| `enableWeakerNetworkIsolation` | (Apenas macOS) Permitir acesso ao serviço de confiança TLS do sistema (`com.apple.trustd.agent`) no sandbox. Necessário para ferramentas baseadas em Go como `gh`, `gcloud`, e `terraform` verificarem certificados TLS ao usar `httpProxyPort` com um proxy MITM e CA personalizada. **Reduz segurança** abrindo um possível caminho de exfiltração de dados. Padrão: false | `true` |

323| `bwrapPath` | (Apenas configurações gerenciadas, Linux/WSL2) Caminho absoluto para o binário bubblewrap (`bwrap`). Substitui detecção automática via `PATH`. Apenas honrado de [configurações gerenciadas](/pt/settings#settings-files), não de configurações de usuário ou projeto. Útil quando `bwrap` é instalado em um local não padrão em ambientes gerenciados. | `/opt/admin/bwrap` |

324| `socatPath` | (Apenas configurações gerenciadas, Linux/WSL2) Caminho absoluto para o binário `socat` usado para o proxy de rede do sandbox. Substitui detecção automática via `PATH`. Apenas honrado de configurações gerenciadas. | `/opt/admin/socat` |

321 325

322#### Prefixos de caminho de sandbox326#### Prefixos de caminho de sandbox

323 327

setup.md +2 −0

Details

398 398

399As plataformas de instalação npm suportadas são `darwin-arm64`, `darwin-x64`, `linux-x64`, `linux-arm64`, `linux-x64-musl`, `linux-arm64-musl`, `win32-x64` e `win32-arm64`. Seu gerenciador de pacotes deve permitir dependências opcionais. Consulte [solução de problemas](/pt/troubleshoot-install#native-binary-not-found-after-npm-install) se o binário estiver faltando após a instalação.399As plataformas de instalação npm suportadas são `darwin-arm64`, `darwin-x64`, `linux-x64`, `linux-arm64`, `linux-x64-musl`, `linux-arm64-musl`, `win32-x64` e `win32-arm64`. Seu gerenciador de pacotes deve permitir dependências opcionais. Consulte [solução de problemas](/pt/troubleshoot-install#native-binary-not-found-after-npm-install) se o binário estiver faltando após a instalação.

400 400

401Para atualizar uma instalação npm, execute `npm install -g @anthropic-ai/claude-code@latest`. Evite `npm update -g`, que respeita o intervalo semver da instalação original e pode não movê-lo para a versão mais recente.

402

401<Warning>403<Warning>

402 NÃO use `sudo npm install -g` pois isso pode levar a problemas de permissão e riscos de segurança. Se você encontrar erros de permissão, consulte [solução de problemas de erros de permissão](/pt/troubleshoot-install#permission-errors-during-installation).404 NÃO use `sudo npm install -g` pois isso pode levar a problemas de permissão e riscos de segurança. Se você encontrar erros de permissão, consulte [solução de problemas de erros de permissão](/pt/troubleshoot-install#permission-errors-during-installation).

403</Warning>405</Warning>

sub-agents.md +3 −3

Details

262| :---------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |262| :---------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

263| `name` | Yes | Identificador único usando letras minúsculas e hífens |263| `name` | Yes | Identificador único usando letras minúsculas e hífens |

264| `description` | Yes | Quando Claude deve delegar para este subagente |264| `description` | Yes | Quando Claude deve delegar para este subagente |

265| `tools` | No | [Ferramentas](#available-tools) que o subagente pode usar. Herda todas as ferramentas se omitido |265| `tools` | No | [Ferramentas](#available-tools) que o subagente pode usar. Herda todas as ferramentas se omitido. Para pré-carregar Skills no contexto, use o campo `skills` em vez de listar `Skill` aqui |

266| `disallowedTools` | No | Ferramentas a negar, removidas da lista herdada ou especificada |266| `disallowedTools` | No | Ferramentas a negar, removidas da lista herdada ou especificada |

267| `model` | No | [Modelo](#choose-a-model) a usar: `sonnet`, `opus`, `haiku`, um ID de modelo completo (por exemplo, `claude-opus-4-7`), ou `inherit`. Padrão: `inherit` |267| `model` | No | [Modelo](#choose-a-model) a usar: `sonnet`, `opus`, `haiku`, um ID de modelo completo (por exemplo, `claude-opus-4-7`), ou `inherit`. Padrão: `inherit` |

268| `permissionMode` | No | [Modo de permissão](#permission-modes): `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, ou `plan`. Ignorado para [subagentes de plugin](#choose-the-subagent-scope) |268| `permissionMode` | No | [Modo de permissão](#permission-modes): `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, ou `plan`. Ignorado para [subagentes de plugin](#choose-the-subagent-scope) |

269| `maxTurns` | No | Número máximo de turnos de agente antes do subagente parar |269| `maxTurns` | No | Número máximo de turnos de agente antes do subagente parar |

270| `skills` | No | [Skills](/pt/skills) a carregar no contexto do subagente na inicialização. O conteúdo completo da skill é injetado, não apenas disponibilizado para invocação. Subagentes não herdam skills da conversa pai |270| `skills` | No | [Skills](/pt/skills) a pré-carregar no contexto do subagente na inicialização. O conteúdo completo da skill é injetado, não apenas a descrição. Subagentes ainda podem invocar skills de projeto, usuário e plugin não listadas através da ferramenta Skill |

271| `mcpServers` | No | [MCP servers](/pt/mcp) disponíveis para este subagente. Cada entrada é um nome de servidor referenciando um servidor já configurado (por exemplo, `"slack"`) ou uma definição inline com o nome do servidor como chave e uma [configuração completa de MCP server](/pt/mcp#installing-mcp-servers) como valor. Ignorado para [subagentes de plugin](#choose-the-subagent-scope) |271| `mcpServers` | No | [MCP servers](/pt/mcp) disponíveis para este subagente. Cada entrada é um nome de servidor referenciando um servidor já configurado (por exemplo, `"slack"`) ou uma definição inline com o nome do servidor como chave e uma [configuração completa de MCP server](/pt/mcp#installing-mcp-servers) como valor. Ignorado para [subagentes de plugin](#choose-the-subagent-scope) |

272| `hooks` | No | [Lifecycle hooks](#define-hooks-for-subagents) com escopo para este subagente. Ignorado para [subagentes de plugin](#choose-the-subagent-scope) |272| `hooks` | No | [Lifecycle hooks](#define-hooks-for-subagents) com escopo para este subagente. Ignorado para [subagentes de plugin](#choose-the-subagent-scope) |

273| `memory` | No | [Escopo de memória persistente](#enable-persistent-memory): `user`, `project`, ou `local`. Habilita aprendizado entre sessões |273| `memory` | No | [Escopo de memória persistente](#enable-persistent-memory): `user`, `project`, ou `local`. Habilita aprendizado entre sessões |

418Implement API endpoints. Follow the conventions and patterns from the preloaded skills.418Implement API endpoints. Follow the conventions and patterns from the preloaded skills.

419```419```

420 420

421O conteúdo completo de cada skill é injetado no contexto do subagente, não apenas disponibilizado para invocação. Subagentes não herdam skills da conversa pai; você deve listá-las explicitamente.421O conteúdo completo de cada skill listada é injetado no contexto do subagente na inicialização. Este campo controla quais skills são pré-carregadas, não quais skills o subagente pode acessar: sem ele, o subagente ainda pode descobrir e invocar skills de projeto, usuário e plugin através da ferramenta Skill durante a execução. Para impedir que um subagente invoque skills inteiramente, omita `Skill` da lista [`tools`](#available-tools) ou adicione-o a `disallowedTools`.

422 422

423Você não pode pré-carregar skills que definem [`disable-model-invocation: true`](/pt/skills#control-who-invokes-a-skill), já que pré-carregar extrai do mesmo conjunto de skills que Claude pode invocar. Se uma skill listada estiver faltando ou desabilitada, Claude Code a ignora e registra um aviso no log de debug.423Você não pode pré-carregar skills que definem [`disable-model-invocation: true`](/pt/skills#control-who-invokes-a-skill), já que pré-carregar extrai do mesmo conjunto de skills que Claude pode invocar. Se uma skill listada estiver faltando ou desabilitada, Claude Code a ignora e registra um aviso no log de debug.

424 424

terminal-config.md +1 −1

Details

107set -as terminal-features 'xterm*:extkeys'107set -as terminal-features 'xterm*:extkeys'

108```108```

109 109

110A linha `allow-passthrough` permite que notificações e atualizações de progresso cheguem ao iTerm2, Ghostty ou Kitty em vez de serem engolidas pelo tmux. As linhas `extended-keys` permitem que tmux distinga Shift+Enter de Enter simples para que o atalho de quebra de linha funcione.110A linha `allow-passthrough` permite que notificações e atualizações de progresso cheguem ao terminal externo em vez de serem engolidas pelo tmux. As linhas `extended-keys` permitem que tmux distinga Shift+Enter de Enter simples para que o atalho de quebra de linha funcione.

111 111

112## Corresponder ao tema de cores112## Corresponder ao tema de cores

113 113

third-party-integrations.md +73 −1

Details

6 6

7> Saiba como Claude Code pode se integrar com vários serviços de terceiros e infraestrutura para atender aos requisitos de implantação empresarial.7> Saiba como Claude Code pode se integrar com vários serviços de terceiros e infraestrutura para atender aos requisitos de implantação empresarial.

8 8

9export const ContactSalesCard = ({surface}) => {

10 const utm = content => `utm_source=claude_code&utm_medium=docs&utm_content=${surface}_${content}`;

11 const iconArrowRight = (size = 13) => <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">

12 <line x1="5" y1="12" x2="19" y2="12" />

13 <polyline points="12 5 19 12 12 19" />

14 </svg>;

15 const STYLES = `

16.cc-cs {

17 --cs-slate: #141413;

18 --cs-clay: #d97757;

19 --cs-clay-deep: #c6613f;

20 --cs-gray-000: #ffffff;

21 --cs-gray-700: #3d3d3a;

22 --cs-border-default: rgba(31, 30, 29, 0.15);

23 font-family: inherit;

24}

25.dark .cc-cs {

26 --cs-slate: #f0eee6;

27 --cs-gray-000: #262624;

28 --cs-gray-700: #bfbdb4;

29 --cs-border-default: rgba(240, 238, 230, 0.14);

30}

31.cc-cs-card {

32 display: flex; align-items: center; justify-content: space-between;

33 gap: 16px; padding: 14px 16px; margin: 0;

34 background: var(--cs-gray-000); border: 0.5px solid var(--cs-border-default);

35 border-radius: 8px; flex-wrap: wrap;

36}

37.cc-cs-text { font-size: 13px; color: var(--cs-gray-700); line-height: 1.5; flex: 1; min-width: 240px; }

38.cc-cs-text strong { font-weight: 550; color: var(--cs-slate); }

39.cc-cs-actions { display: flex; align-items: center; gap: 8px; flex-shrink: 0; }

40.cc-cs-btn-clay {

41 display: inline-flex; align-items: center; gap: 8px;

42 background: var(--cs-clay-deep); color: #fff; border: none;

43 border-radius: 8px; padding: 8px 14px;

44 font-size: 13px; font-weight: 500;

45 transition: background-color 0.15s; white-space: nowrap;

46}

47.cc-cs-btn-clay:hover { background: var(--cs-clay); }

48.cc-cs-btn-ghost {

49 display: inline-flex; align-items: center; gap: 8px;

50 background: transparent; color: var(--cs-gray-700);

51 border: 0.5px solid var(--cs-border-default);

52 border-radius: 8px; padding: 8px 14px;

53 font-size: 13px; font-weight: 500;

54}

55.cc-cs-btn-ghost:hover { background: rgba(0, 0, 0, 0.04); }

56.dark .cc-cs-btn-ghost:hover { background: rgba(255, 255, 255, 0.04); }

57@media (max-width: 720px) {

58 .cc-cs-actions { width: 100%; }

59}

60`;

61 return <div className="cc-cs not-prose">

62 <style>{STYLES}</style>

63 <div className="cc-cs-card">

64 <div className="cc-cs-text">

65 <strong>Deploying Claude Code across your organization?</strong> Talk to sales about enterprise plans, SSO, and centralized billing.

66 </div>

67 <div className="cc-cs-actions">

68 <a href={`https://claude.com/pricing?${utm('view_plans')}#plans-business`} className="cc-cs-btn-ghost">

69 View plans

70 </a>

71 <a href={`https://claude.com/contact-sales?${utm('contact_sales')}`} className="cc-cs-btn-clay">

72 Contact sales {iconArrowRight()}

73 </a>

74 </div>

75 </div>

76 </div>;

77};

9As organizações podem implantar Claude Code através da Anthropic diretamente ou através de um provedor de nuvem. Esta página ajuda você a escolher a configuração correta.79As organizações podem implantar Claude Code através da Anthropic diretamente ou através de um provedor de nuvem. Esta página ajuda você a escolher a configuração correta.

10 80

81<ContactSalesCard surface="third_party_overview" />

11## Comparar opções de implantação83## Comparar opções de implantação

12 84

13Para a maioria das organizações, Claude for Teams ou Claude for Enterprise oferece a melhor experiência. Os membros da equipe obtêm acesso tanto a Claude Code quanto a Claude na web com uma única assinatura, faturamento centralizado e nenhuma configuração de infraestrutura necessária.85Para a maioria das organizações, Claude for Teams ou Claude for Enterprise oferece a melhor experiência. Os membros da equipe obtêm acesso tanto a Claude Code quanto a Claude na web com uma única assinatura, faturamento centralizado e nenhuma configuração de infraestrutura necessária.

241 313

242### Fixar versões de modelo para provedores de nuvem314### Fixar versões de modelo para provedores de nuvem

243 315

244Se você implantar através de [Bedrock](/pt/amazon-bedrock), [Vertex AI](/pt/google-vertex-ai), ou [Foundry](/pt/microsoft-foundry), fixe versões de modelo específicas usando `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, e `ANTHROPIC_DEFAULT_HAIKU_MODEL`. Sem fixação, os aliases de Claude Code resolvem para a versão mais recente, o que pode quebrar usuários quando a Anthropic lança um novo modelo que ainda não está ativado em sua conta. Veja [Configuração de modelo](/pt/model-config#pin-models-for-third-party-deployments) para detalhes.316Se você implantar através de [Bedrock](/pt/amazon-bedrock), [Vertex AI](/pt/google-vertex-ai), ou [Foundry](/pt/microsoft-foundry), fixe versões de modelo específicas usando `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, e `ANTHROPIC_DEFAULT_HAIKU_MODEL`. Sem fixação, os aliases de modelo resolvem para a versão mais recente, o que pode não estar ainda ativado em sua conta quando a Anthropic lança uma atualização. Fixar permite que você controle quando seus usuários passam para um novo modelo. Veja [Configuração de modelo](/pt/model-config#pin-models-for-third-party-deployments) para o que cada provedor faz quando a versão mais recente não está disponível.

245 317

246### Configurar políticas de segurança318### Configurar políticas de segurança

247 319

vs-code.md +7 −5

Details

27 27

28Clique no link do seu IDE para instalar diretamente:28Clique no link do seu IDE para instalar diretamente:

29 29

~~30* [Install for VS Code](vscode:extension/anthropic.claude-code)~~30* [Instalar para VS Code](vscode:extension/anthropic.claude-code)

~~31* [Install for Cursor](cursor:extension/anthropic.claude-code)~~31* [Instalar para Cursor](cursor:extension/anthropic.claude-code)

32 32

~~33Ou no VS Code, pressione `Cmd+Shift+X` (Mac) ou `Ctrl+Shift+X` (Windows/Linux) para abrir a visualização de Extensões, procure por "Claude Code" e clique em **Install**.~~33Ou no VS Code, pressione `Cmd+Shift+X` (Mac) ou `Ctrl+Shift+X` (Windows/Linux) para abrir a visualização de Extensões, procure por "Claude Code" e clique em **Instalar**.

35A extensão também é instalada em outros forks do VS Code como Windsurf ou Kiro. Procure por "Claude Code" na visualização de Extensões do editor, ou instale a partir do [registro Open VSX](https://open-vsx.org/extension/Anthropic/claude-code). Se o seu editor não conseguir instalar a extensão, execute `claude` no seu terminal integrado. A [CLI](/pt/quickstart) funciona em qualquer terminal.

34 36

35<Note>Se a extensão não aparecer após a instalação, reinicie o VS Code ou execute "Developer: Reload Window" na Paleta de Comandos.</Note>37<Note>Se a extensão não aparecer após a instalação, reinicie o VS Code ou execute "Developer: Reload Window" na Paleta de Comandos.</Note>

36 38

291 293

292Para iniciar uma sessão de terminal em vez de uma aba VS Code, use o manipulador `claude-cli://` da CLI. Consulte [Launch sessions from links](/pt/deep-links).294Para iniciar uma sessão de terminal em vez de uma aba VS Code, use o manipulador `claude-cli://` da CLI. Consulte [Launch sessions from links](/pt/deep-links).

293 295

294## Configure settings296## Configurar configurações

295 297

296A extensão tem dois tipos de configurações:298A extensão tem dois tipos de configurações:

297 299

318| `environmentVariables` | `[]` | Defina variáveis de ambiente para o processo Claude. Use configurações Claude Code em vez disso para configuração compartilhada. |320| `environmentVariables` | `[]` | Defina variáveis de ambiente para o processo Claude. Use configurações Claude Code em vez disso para configuração compartilhada. |

320| `allowDangerouslySkipPermissions` | `false` | Adiciona [Auto mode](/pt/permission-modes#eliminate-prompts-with-auto-mode) e Bypass permissions ao seletor de modo. Auto mode tem [requisitos de plano, admin, modelo e provedor](/pt/permission-modes#eliminate-prompts-with-auto-mode), então pode permanecer indisponível mesmo com este toggle ativado. Use Bypass permissions apenas em sandboxes sem acesso à internet. |322| `allowDangerouslySkipPermissions` | `false` | Adiciona [Auto mode](/pt/permission-modes#eliminate-prompts-with-auto-mode) e Bypass permissions ao seletor de modo. Auto mode tem [requisitos de plano, admin, modelo e provedor](/pt/permission-modes#eliminate-prompts-with-auto-mode), então pode permanecer indisponível mesmo com este toggle ativado. Use Bypass permissions apenas em sandboxes sem acesso à internet. |

321| `claudeProcessWrapper` | - | Caminho executável usado para iniciar o processo Claude |323| `claudeProcessWrapper` | - | Executável usado para iniciar o processo Claude. O caminho do binário incluído é passado como um argumento quando presente. Defina isso para um binário `claude` instalado separadamente se a compilação da extensão não incluir um para sua plataforma. |

322 324

323## VS Code extension vs. Claude Code CLI325## VS Code extension vs. Claude Code CLI

324 326

Documentation 2026-05-07 22:59 UTC to 2026-05-08 22:00 UTC