Guia da CLI do Claude Code: instalação, configuração, comandos, variáveis de ambiente

TL;DR: Claude Code é um CLI agêntico que lê sua base de código, executa comandos e modifica arquivos por meio de um sistema em camadas de permissões, hooks, integrações MCP e subagents. Domine cinco sistemas centrais (configuração, permissões, hooks, MCP e subagents) e você terá um salto de produtividade. Escolha o nível de modelo adequado para cada tarefa — Opus para raciocínio complexo, Sonnet para trabalhos gerais, Haiku para exploração rápida — ou padronize o uso do Opus se a qualidade for sua única variável. Use hooks (não prompts) para tudo o que sempre precisa ser executado. O modo automático é o modo de permissão padrão para novas sessões nos planos Pro, Max e Team desde 14 de agosto de 2026 (anunciado em 7 de agosto e verificado em produção na data da mudança; autonomia revisada por classificador — um defaultMode definido por você permanece, a menos que você aceite a solicitação única de mudança, Shift+Tab alterna o modo em qualquer sessão e disableAutoMode o desativa em toda a organização).²⁰³ O modelo padrão depende do seu plano: Max, Team Premium, Enterprise (baseado em licenças desde a v2.1.251) e o Anthropic API usam Claude Opus 5 por padrão, enquanto Pro e Team Standard usam Sonnet 5 — contexto nativo de 1M, US$ 2/US$ 10 por MTok como preço de tabela padrão (o preço promocional de lançamento, agora permanente: o aumento programado para 1º de setembro não ocorrerá)²²⁹²⁰⁷ — o Sonnet 5 como padrão em todos os planos da v2.1.197 (30 de junho de 2026) ficou no passado, e o alias opus aponta para o Claude Opus 5 (v2.1.219+); a v2.1.198 (1º de julho) faz os subagents serem executados em segundo plano por padrão, leva o Claude no Chrome à disponibilidade geral, permite que agentes em segundo plano façam commit, push e abram um PR em rascunho quando concluem o código no worktree e aciona o hook Notification (agent_needs_input/agent_completed) nas sessões em segundo plano; a v2.1.199 (2 de julho) carrega até 5 invocações empilhadas de slash-skills e tenta novamente, de forma automática, erros 429 transitórios para assinantes; a v2.1.200 (3 de julho) renomeia o modo de permissão default para “Manual” no CLI, em --help, no VS Code e no JetBrains (o valor de configuração permanece igual e manual é aceito como alias) e impede que as caixas de diálogo AskUserQuestion continuem automaticamente por padrão; a v2.1.202 (6 de julho) adiciona um controle “Dynamic workflow size” em /config e separa /review <pr> (uma única passagem rápida) de /code-review <level> <pr#> — uma separação desfeita pela v2.1.223: /review voltou a ser um alias de /code-review, e /code-review sem argumentos reutiliza seu último nível de esforço; as versões v2.1.203–205 (7–9 de julho) reforçam o modo automático — arquivos de transcrição são protegidos contra adulteração, rm -rf com uma variável que não pode ser resolvida pede confirmação primeiro, e as notificações de tarefas em segundo plano informam que não houve intervenção humana (portanto, aprovações forjadas na transcrição não podem ser executadas) — e transformam /doctor em uma verificação completa de diagnóstico e correção (com o alias /checkup).^181182183 A v2.1.217 (21 de julho) voltou atrás nos subagents aninhados — por padrão, os subagents deixaram de iniciar seus próprios subagents (uma decisão padrão que a v2.1.219 reverteu novamente três dias depois, estabelecendo uma profundidade de 3; veja abaixo), no máximo 20 subagents são executados simultaneamente por padrão (CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS), e --max-budget-usd agora realmente interrompe subagents em segundo plano quando o limite é atingido.¹⁹⁴ A v2.1.218 (22 de julho) transfere /code-review para um subagent em segundo plano — o trabalho de revisão deixa de ocupar sua conversa —, executa skills com context: fork em segundo plano por padrão (desative isso em cada skill com background: false), faz /deep-research iniciar somente quando invocado explicitamente, transfere as verificações de rm perigoso, & em segundo plano e caminhos suspeitos do Windows para o classificador do modo automático, em vez de caixas de diálogo de permissão, e impede que hooks definidos no frontmatter de agentes sejam executados a partir de pastas não confiáveis.¹⁹⁵ A v2.1.219 (24 de julho) torna o Claude Opus 5 (claude-opus-5) o modelo Opus padrão — contexto de 1M, saída máxima de 128K, US$ 5/US$ 25 por MTok (idêntico ao Opus 4.8), thinking ativado por padrão, effort definido como high por padrão e corte de conhecimento em maio de 2026 — e corrige duas mudanças feitas por versões anteriores: o modo rápido agora se aplica ao Opus 5 e ao Opus 4.8 por US$ 10/US$ 50 por MTok (2× o preço-base, com o Opus 4.7 totalmente removido do modo rápido), e os subagents aninhados voltam a ficar ativados por padrão, com profundidade 3 (CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 desativa o aninhamento). A mesma versão adiciona o evento de hook DirectoryAdded, a configuração sandbox.network.strictAllowlist, uma chave de configurações workflowSizeGuideline, com workflows dinâmicos passando a usar por padrão uma orientação de tamanho médio (tente usar menos de 15 agentes), e o encaminhamento de subagents aninhados em stream-json. A v2.1.220 (25 de julho) contém apenas correções de bugs e melhorias de confiabilidade. As versões v2.1.221–226 (4–7 de agosto) adicionam mensagens entre sessões (SendMessage/ListAgents entre suas sessões, no macOS/Linux), runners auto-hospedados para sessões na nuvem (Team/Enterprise), a fonte de plugins archive com fixação por SHA-256, mascaramento de credenciais JWT/SigV4 no sandbox, a visualização Focus do VSCode e cópias de /fork com worktrees próprios — além de removerem o limite de 200 subagents por sessão e o ultraplan.^{199200201202196197198} As versões v2.1.227–229 (10–12 de agosto) se concentram em correções, com uma camada de melhorias de usabilidade: marketplaces de plugins ganham fontes do tipo command (um programa local imprime o diretório do plugin, que é resolvido novamente a cada sessão; mode: "link" o utiliza no próprio local), claude remote-control --continue retoma sua sessão mais recente do Remote Control, ListAgents rotula peers desconectados do Remote Control como offline e suas sessões na nuvem como cloud, /commit-push-pr deixa de aprovar automaticamente flags perigosas do git (--force, --amend, --no-verify), e a ferramenta Write passa a seguir as mesmas regras da Edit nos modelos mais recentes — sobrescrever um arquivo que não foi lido deixa de exigir uma leitura anterior na mesma sessão.^236234235 A v2.1.232 (13 de agosto) torna o fork de subagents o padrão (subagent_type: "fork" herda toda a conversa e o cache do prompt; processos que não são teammates, iniciados em sessões interativas, são executados em segundo plano), permite que você mencione com @ outra sessão ativa pelo nome no prompt (o Claude encaminha a mensagem via SendMessage, e um nome isolado que corresponda exatamente a uma sessão ativa agora é entregue sem confirmação da referência), mantém nomes de sessões interativas únicos em cada máquina (variantes de name-word-word), exibe os controles de entrada entre sessões como linhas em /config e traz paridade com o GitLab — nove famílias de tokens do GitLab ocultadas no sandbox, proteção de credenciais do CLI glab e URLs simples de marketplaces em gitlab.com (incluindo subgrupos aninhados) clonadas da mesma forma que as do GitHub.²³³ A v2.1.233 (14 de agosto) amplia a paridade com o GitLab para --worktree (URLs de MR, exibidas como !N em claude agents), adiciona limites de memória no Linux para comandos Bash (CLAUDE_CODE_TOOL_MEMORY_LIMIT) e uma opção para o TTL do cache de WebFetch, e desativa por padrão as ferramentas de acompanhamento de tarefas/todos no Opus 4.8, Sonnet 5, Fable 5 e modelos mais recentes (CLAUDE_CODE_ENABLE_TODO_TOOLS=1 as restaura) — além de reverter parte das alterações da v2.1.232 nas permissões do Bash no Windows após uma regressão no modo automático.²³² A v2.1.234 (17 de agosto) faz o Claude Code continuar sua sessão automaticamente quando um limite de uso do claude.ai é redefinido (desative em /config: “Continue automatically at usage limit”), permite abrir /permissions e /add-dir durante uma execução, adiciona CLAUDE_CODE_PROJECT_DIR_NAME e uma verificação de andamento de tarefas em segundo plano com /goal (CLAUDE_CODE_GOAL_CHECKIN_MINUTES), exibe um selo de MR do GitLab (!N) no rodapé de repositórios com um CLI glab autenticado e reduz o custo de contexto da skill integrada claude-api de cerca de 200k para cerca de 25k tokens ao carregar a documentação de referência sob demanda.²³¹ As versões v2.1.235–238 (18–20 de agosto) adicionam um estilo de saída integrado “Concise” (resultados primeiro, sem introdução ou narração — selecione-o em Output style dentro de /config), a variável de ambiente ANTHROPIC_DEFAULT_MODEL (define o modelo usado no início de novas sessões; uma escolha em /model ainda a substitui e persiste, ao contrário de ANTHROPIC_MODEL), uma configuração opcional spellcheck (sublinha palavras com erros ortográficos no prompt usando seu aspell, hunspell ou ispell instalado), uma configuração keybindingFlavor ("readline" faz Ctrl+W apagar até o espaço anterior, como no Bash; a configuração foi descontinuada na v2.1.261 — readline agora é o único comportamento), headersHelper nos marketplaces de plugins e no .mcp.json do projeto (um comando gera cabeçalhos HTTP de curta duração; helpers de entradas do catálogo são executados somente na instalação/atualização após exibirem seu comando, enquanto helpers no escopo de projeto/plugin/agente são executados sem herdar variáveis de ambiente de credenciais e ficam protegidos pela caixa de diálogo de confiança da pasta), notify_when_idle no SendMessage entre sessões (uma notificação única quando outra sessão local ficar ociosa novamente) e duas mudanças no comportamento das permissões: o modo automático agora desconsidera regras de permissão para Monitor (comandos Monitor passam pela mesma revisão do classificador que o Bash), e regras curingas de negação de leitura no sandbox do macOS (**/.env) prevalecem dentro de regiões com leitura permitida e não podem ser contornadas renomeando o arquivo negado — com o classificador do modo automático agora usando os padrões do Claude API no Bedrock, Vertex AI e Foundry, bem como quando a telemetria está desativada²²⁴ (a partir da v2.1.273, esses gateways usam o classificador local por padrão “por enquanto” — CLAUDE_CODE_AUTO_MODE_SERVER=1 ativa o classificador do lado do servidor da plataforma²¹⁷). A v2.1.239 (21 de agosto) adiciona /claude-api upgrade (migra projetos Python do anthropic 0.x para 1.x), inclui o acréscimo de 1,1× pela inferência exclusiva nos EUA para workspaces com residência de dados nas estimativas de custo (/cost, linha de status, --max-budget-usd), leva mensagens entre sessões ao Windows, exibe plugins sincronizados com o claude.ai como name@synced (gerenciáveis com claude plugin enable/disable, sem nunca substituir uma instalação local com o mesmo nome), ensina ListAgents a mostrar o nome da própria sessão e os teammates ativos, estende "readline" às teclas de palavras do Bash, reduz a frequência das verificações de /goal (30 min → 1 h → 2 h) e disponibiliza o renderizador de tela cheia no Bedrock/Vertex/Foundry; as versões v2.1.240–241 (22–23 de agosto) são versões de correção de bugs. O resumo da documentação da mesma semana registra duas mudanças de status: /design — uma skill em prévia de pesquisa que publica uma tela com artboards editáveis de UI por meio de artifacts (Pro/Max/Team/Enterprise, requer v2.1.233+) — e a saída do Remote Control da prévia de pesquisa, com máquinas executando claude remote-control aparecendo como cartões de dispositivo no app do Claude.²⁰⁵ A partir das versões v2.1.174–176 (12 de junho de 2026), a lista de permissões availableModels agora também pode restringir o modelo Default por meio da nova configuração gerenciada enforceAvailableModels (configurações de usuário/projeto não podem ampliar uma lista gerenciada), títulos de sessões são gerados no idioma da sua conversa (fixe um idioma com a configuração language), e as novas configurações footerLinksRegexes e wheelScrollAccelerationEnabled, uma caixa de diálogo de atribuição de /usage no VSCode e uma correção para que condições if de hooks correspondam a padrões de caminho de Read/Edit/Write completam a versão.¹⁷² A partir da v2.1.173 (11 de junho de 2026), um nome de modelo Fable 5 com o sufixo [1m] é automaticamente normalizado e o sufixo é removido — o Fable 5 já inclui contexto de 1M por padrão, portanto o sufixo é desnecessário (ele só teve significado no Opus/Sonnet). A partir da v2.1.172 (10 de junho de 2026), sub-agents podiam iniciar recursivamente seus próprios sub-agents, até 5 níveis de profundidade — um padrão que permaneceu até a v2.1.216 e foi desativado na v2.1.217 (veja acima) —, o Bedrock lê sua região em ~/.aws quando AWS_REGION não está definido (/status mostra a origem), /plugin adiciona uma barra de pesquisa de marketplaces, e a métrica OTEL claude_code.lines_of_code.count ganha um atributo model. A partir da v2.1.170 (9 de junho de 2026), o Claude Fable 5 — um novo nível de modelo acima do Opus — pode ser selecionado no Claude Code por meio de /model fable após claude update (ele é compatível com toda a escala de esforço de low a max, mas o thinking não pode ser desativado); o Opus 4.8 permanece como padrão agêntico. A partir da v2.1.169 (8 de junho de 2026), --safe-mode (e CLAUDE_CODE_SAFE_MODE) inicia uma sessão limpa com todas as personalizações desativadas para solução de problemas, /cd move uma sessão para um novo diretório de trabalho sem invalidar o cache do prompt, e disableBundledSkills oculta do modelo as skills e os comandos de barra integrados. A partir da v2.1.166 (6 de junho de 2026), uma configuração fallbackModel encadeia até três modelos de reserva quando o principal está sobrecarregado, o glob "*" funciona nas regras de negação do MCP, e MAX_THINKING_TOKENS=0 / --thinking disabled desativam completamente o thinking nos modelos que o ativam por padrão. A partir da v2.1.154 (28 de maio de 2026), o Opus 4.8 é o novo padrão, com alto esforço por padrão e um nível /effort xhigh, workflows dinâmicos orquestram dezenas ou centenas de agentes em segundo plano por meio de /workflows, o modo rápido no Opus 4.8 custa 2× a tarifa padrão e oferece velocidade 2,5× maior, o prompt de sistema enxuto agora é o padrão para todos os modelos, exceto Haiku/Sonnet/Opus 4.7 e anteriores, /simplify voltou a ser uma revisão apenas de limpeza (separada de /code-review --fix), claude agents aceita ! <command> para iniciar sessões de shell em segundo plano, plugins podem declarar defaultEnabled: false, a execução de ferramentas por streaming está sempre ativada, e servidores MCP stdio recebem CLAUDE_CODE_SESSION_ID e CLAUDECODE=1 no ambiente. A v2.1.153 adicionou skipLfs aos marketplaces de plugins, fez /model salvar a escolha como padrão (pressione s para aplicá-la somente à sessão) e incluiu COLUMNS/LINES no ambiente da linha de status. A v2.1.152 introduziu /code-review --fix (aplica os resultados à árvore de trabalho), disallowed-tools no frontmatter das skills, /reload-skills, o novo evento de hook MessageDisplay, as saídas reloadSkills/sessionTitle do hook SessionStart, a configuração gerenciada pluginSuggestionMarketplaces, a troca de --fallback-model durante a sessão e removeu a adesão voluntária ao modo automático.^{162 163 164 165 166 167 168 169 170 245 171}

O Claude Code funciona como um sistema agêntico, não como uma interface de chat com conhecimentos de programação. O CLI lê sua base de código, executa comandos, modifica arquivos, gerencia workflows do git, conecta-se a serviços externos por meio do MCP e delega tarefas complexas a subagents especializados. Tudo acontece por uma interface de linha de comando integrada à maneira como os desenvolvedores realmente trabalham. Em fevereiro de 2026, 4% dos commits públicos no GitHub (cerca de 135.000 por dia) eram feitos pelo Claude Code — um crescimento de 42.896× em 13 meses desde a prévia de pesquisa —, e 90% do código do próprio Anthropic era escrito por IA.¹⁰³

A diferença entre o uso casual e o uso eficaz do Claude Code se resume a cinco sistemas centrais. Domine-os e o Claude Code se tornará um multiplicador de produtividade:

1. Hierarquia de configuração: controla o comportamento
2. Sistema de permissões: controla as operações
3. Sistema de hooks: possibilita automação determinística
4. Protocolo MCP: amplia os recursos
5. Sistema de subagents: realiza tarefas complexas com várias etapas

Principais conclusões

• Cinco sistemas determinam sua eficácia: hierarquia de configuração, permissões, hooks, MCP e subagents controlam tudo, do comportamento à automação.
• Transfira o trabalho para a camada de delegação: subagents evitam o inchaço do contexto ao isolar a exploração em janelas de contexto limpas e retornar apenas resumos.
• Hooks garantem a execução; prompts não: use hooks para linting, formatação e verificações de segurança que precisam ser executadas sempre, independentemente do comportamento do modelo.
• A divisão por níveis de modelo reduz custos sem sacrificar a qualidade: encaminhe a exploração feita por subagents para modelos mais baratos e reserve o Opus para raciocínio arquitetural de verdade — ou padronize o uso do Opus se a qualidade for sua única variável.
• O MCP conecta o Claude à sua cadeia de ferramentas: bancos de dados, GitHub, Sentry e mais de 3.000 integrações ampliam o Claude para além da leitura de arquivos e dos comandos bash.

Passei meses levando o Claude Code ao limite em bases de código de produção, pipelines de CI/CD e implantações empresariais. Este guia condensa essa experiência na referência completa que eu gostaria que existisse quando comecei. Cada recurso inclui a sintaxe real, exemplos reais de configuração e os casos extremos que confundem até usuários experientes.

Escolha seu caminho

Como usar este guia

Esta é uma referência com mais de 5.000 linhas — você não precisa lê-la do começo ao fim. Comece pela seção adequada ao seu nível de experiência:

Use Ctrl+F / Cmd+F no navegador para pesquisar flags, comandos ou chaves de configuração específicos. O Cartão de referência rápida no final traz um resumo fácil de consultar de todos os principais comandos.

Análises detalhadas relacionadas

Estes posts do blog exploram em detalhes aspectos específicos do Claude Code:

Início rápido de 60 segundos

Se você só quer executar Claude Code e ver a saída, faça isto na ordem:

# 1. Install (pick one)
npm install -g @anthropic-ai/claude-code          # npm users
brew install anthropic/claude/claude              # macOS + Homebrew
curl -sL claude.ai/install.sh | sh                # native installer

# 2. Launch in any project directory
cd ~/your-project && claude

# 3. Authenticate (browser opens automatically on first run)
/login

# 4. Ask your first question
> What does this repo do? Read the key files and summarize.

É isso. Tudo abaixo desta seção detalha as opções de instalação, configura permissões e hooks, conecta servidores MCP e aborda a implantação corporativa — mas nada disso é necessário para começar.

Pré-requisitos: Node 22+ apenas para o caminho npm legado (aumentado de 18 com a v2.1.198; a documentação de instalação atual diz “Node.js 22 or later”, verificado em 07 de agosto de 2026); o instalador nativo recomendado não depende do Node. macOS / Linux / Windows 10+ são compatíveis. Uma assinatura Claude Pro, Max, Team ou Enterprise, ou uma chave Anthropic API paga por token, cobre o uso. Consulte Como instalo o Claude Code? para detalhes específicos da plataforma, solução de problemas e o caminho do binário nativo (padrão desde a v2.1.113). As evidências da versão mais recente neste guia são mantidas a cada lançamento; consulte a linha mais recente do Changelog para ver a marca de verificação atual.²⁴⁵

Como o Claude Code funciona: o modelo mental

Antes de explorar os recursos, entenda como a arquitetura do Claude Code molda tudo o que você faz com ele. O sistema opera em três camadas:

┌─────────────────────────────────────────────────────────┐
│                    CLAUDE CODE LAYERS                    │
├─────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                         │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐    │
│  │   MCP   │  │  Hooks  │  │ Skills  │  │ Plugins │    │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘    │
│  External tools, deterministic automation, domain       │
│  expertise, packaged extensions                          │
├─────────────────────────────────────────────────────────┤
│  DELEGATION LAYER                                        │
│  ┌─────────────────────────────────────────────────┐    │
│  │           Subagents (20 concurrent default)      │    │
│  │   Explore | Plan | General-purpose | Custom      │    │
│  └─────────────────────────────────────────────────┘    │
│  Isolated contexts for focused work, returns summaries  │
├─────────────────────────────────────────────────────────┤
│  CORE LAYER                                              │
│  ┌─────────────────────────────────────────────────┐    │
│  │         Main Conversation Context                │    │
│  │   Tools: Read, Edit, Bash, Glob, Grep, etc.     │    │
│  └─────────────────────────────────────────────────┘    │
│  Your primary interaction; limited context; costs money │
└─────────────────────────────────────────────────────────┘

Camada principal: Sua conversa principal. Cada mensagem, leitura de arquivo e saída de ferramenta consome contexto de uma janela compartilhada (200 mil tokens como padrão⁹¹, 1 milhão de tokens com Opus 4.6 ou modelos de contexto estendido). Quando o contexto se enche, o Claude perde o acompanhamento de decisões anteriores e a qualidade diminui. Essa camada custa dinheiro por token.

Camada de delegação: Subagents são iniciados com contextos limpos, fazem trabalhos focados e retornam resumos. Os resultados da exploração não sobrecarregam sua conversa principal; apenas as conclusões retornam. Direcione subagents para níveis de modelo mais baratos durante a exploração ou use seu modelo principal em todo o processo se a qualidade for mais importante que o custo.

Camada de extensão: O MCP conecta serviços externos (bancos de dados, GitHub, Sentry). Hooks garantem a execução de comandos de shell independentemente do comportamento do modelo. Skills codificam conhecimento especializado que o Claude aplica automaticamente. Plugins empacotam tudo isso para distribuição.

O insight principal: A maioria dos usuários trabalha inteiramente na camada principal, vendo o contexto aumentar e os custos subirem. Usuários avançados levam a exploração e o trabalho especializado para a camada de delegação, mantêm a camada de extensão configurada para seu fluxo de trabalho e usam a camada principal apenas para orquestração e decisões finais.

Sumário

1. Como instalo o Claude Code?
2. Início rápido: sua primeira sessão
3. Modos principais de interação
4. Análise aprofundada do sistema de configuração
5. Qual modelo devo escolher?
6. Quanto custa o Claude Code?
7. Frameworks de decisão
8. Como funciona o sistema de permissões?
9. Como funcionam os hooks?
10. O que é MCP (Model Context Protocol)?
11. O que são subagents?
12. O que é o modo de raciocínio estendido?
13. Estilos de saída
14. Comandos com barra
15. Como funcionam as skills?
16. Sistema de plugins
17. Como funciona a memória?
18. Entrada de imagem e multimodal
19. Modo de voz
20. Como funciona a integração com Git?
21. Como uso o Claude Code no meu IDE?
22. Padrões avançados de uso
23. Agentes remotos e em segundo plano [RESEARCH PREVIEW]
24. Claude no Chrome
25. Claude Code no Slack [RESEARCH PREVIEW]
26. Claude Code na Web [RESEARCH PREVIEW]
27. Claude no Microsoft 365 (maio de 2026)
28. Otimização de desempenho
29. Como depuro problemas?
30. Implantação corporativa
31. Referência de atalhos de teclado
32. Boas práticas
33. Receitas de fluxo de trabalho
34. Guia de migração
35. Orientações específicas por público
36. Cartão de referência rápida
37. Changelog
38. Referências

Como instalar o Claude Code?

Requisitos do sistema

O Claude Code roda em macOS 13+, Ubuntu 20.04+/Debian 10+ e Windows 10+ (nativo ou WSL). O sistema exige no mínimo 4 GB de RAM e uma conexão ativa com a internet.⁹² A compatibilidade de shell funciona melhor com Bash, Zsh ou Fish.

No Windows, tanto o WSL 1 quanto o WSL 2 funcionam. O Git Bash também funciona se você preferir o Windows nativo. Alpine Linux e outros sistemas baseados em musl exigem pacotes adicionais:

apk add libgcc libstdc++ ripgrep
export USE_BUILTIN_RIPGREP=0

Matriz de suporte por plataforma

Instalação, atualização e desinstalação em um relance

Consulta rápida — todos os métodos, todos os comandos e a verificação de versão em uma só tela. As subseções abaixo cobrem as especificidades de cada método e a solução de problemas.

Desde a v2.1.113, o CLI canônico inicia um binário nativo do Claude Code por meio de uma dependência opcional específica de cada plataforma, em vez do JavaScript incluído no pacote — use o instalador nativo para obter a distribuição testada. O caminho via npm continua funcionando, mas é o primeiro a receber o aviso de descontinuação, adicionado lá na v2.1.15.

Métodos de instalação

Instalação nativa (recomendada)

O binário nativo oferece a experiência mais limpa, sem dependência do Node.js:

# macOS and Linux
curl -fsSL https://claude.ai/install.sh | bash

# Homebrew alternative
brew install --cask claude-code

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Para instalar uma versão específica:

# Install specific version
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

# Install latest explicitly
curl -fsSL https://claude.ai/install.sh | bash -s latest

# Windows PowerShell - specific version
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58

Uma versão que você nunca deve fixar atrás de um proxy ou gateway: a 2.1.275. Nesse build, toda requisição falha com 400 ... Input tag 'advisor_20260301' quando o ANTHROPIC_BASE_URL aponta para um proxy ou gateway; a 2.1.276 corrige a regressão.²¹⁸

Instalação via NPM (obsoleta)

Observação: a partir da v2.1.15, instalações via npm exibem um aviso de descontinuação. O binário nativo agora é o método de instalação recomendado. Faça a migração com claude install.

Para ambientes legados em que o npm ainda é necessário:

npm install -g @anthropic-ai/claude-code

Nunca use sudo na instalação via npm. Isso cria problemas de permissão que complicam tudo dali em diante.

Migração de uma instalação existente

Se você tem uma instalação antiga baseada em npm, migre para o binário nativo:

claude install

Opções de autenticação

O Claude Code oferece três caminhos de autenticação, cada um com compromissos diferentes:

Claude Console (cobrança via API)

Conecte-se diretamente à API da Anthropic por meio do platform.claude.com (antigo console.anthropic.com). Crie uma conta, configure a cobrança e autentique-se pelo CLI. O Console oferece cobrança por uso com acesso completo à API. Um workspace dedicado chamado “Claude Code” é criado automaticamente; você não pode criar chaves de API para esse workspace, mas pode monitorar o uso. A partir da v2.1.243, /login → Anthropic Console oferece um caminho sem chave, “Entrar com sua conta do Console” (recomendado), além da criação de uma chave de API, de modo que organizações que não permitem chaves de API ainda consigam entrar com as credenciais do Console.²²⁸

Assinatura Claude Pro ou Max

Use as credenciais da sua conta claude.ai. A assinatura cobre tanto a interface web quanto o uso do CLI em um único plano mensal. A assinatura simplifica a cobrança para usuários individuais que querem custos previsíveis.

Plataformas corporativas

AWS Bedrock, Google Vertex AI e Microsoft Foundry oferecem, cada um, acesso de nível corporativo com as relações de cobrança em nuvem já existentes. Assistente de configuração do Bedrock (v2.1.92+): um assistente interativo na tela de login guia você pela autenticação na AWS, seleção de região, verificação de credenciais e fixação do modelo.¹³⁷ Assistente de configuração do Vertex AI (v2.1.98+): um assistente equivalente para o Google Cloud, orientando a autenticação no GCP, a configuração de projeto e região, a verificação de credenciais e a fixação do modelo.¹⁴² Workload Identity Federation com mTLS no Vertex AI (v2.1.121+): o Vertex AI agora aceita Workload Identity Federation baseada em certificado X.509 (Application Default Credentials com mTLS) — tokens de curta duração do GCP emitidos a partir de um certificado de cliente, sem precisar de JSON de conta de serviço.¹⁵⁴ Confiança nos certificados CA do sistema operacional (v2.1.101+): proxies TLS corporativos agora funcionam por padrão — o Claude Code confia no armazenamento de certificados do sistema operacional. Defina CLAUDE_CODE_CERT_STORE=bundled para usar apenas as CAs incluídas no pacote.¹⁴³

# AWS Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
export AWS_PROFILE=your-profile

# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=your-project

# Microsoft Foundry
export CLAUDE_CODE_USE_FOUNDRY=1
export ANTHROPIC_FOUNDRY_RESOURCE=your-resource-name
# Optional: API key auth (otherwise uses Entra ID)
export ANTHROPIC_FOUNDRY_API_KEY=your-key

# Amazon Bedrock via Mantle (v2.1.94+)
export CLAUDE_CODE_USE_MANTLE=1

Para implantações corporativas atrás de proxies ou por meio de gateways de LLM:

# Corporate proxy
export HTTPS_PROXY='https://proxy.example.com:8080'

# LLM gateway (skip native auth)
export CLAUDE_CODE_USE_BEDROCK=1
export ANTHROPIC_BEDROCK_BASE_URL='https://your-gateway.com/bedrock'
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1

Cabeçalhos de dica para gateways (v2.1.273, opcional): com CLAUDE_CODE_GATEWAY_HINT_HEADERS=1 definido, o Claude Code adiciona cinco cabeçalhos de requisição que um gateway de LLM pode usar para roteamento e observabilidade – x-claude-code-request-class, x-claude-code-agent-type, x-claude-code-prev-tool-durations, x-claude-code-compaction e x-claude-code-context-compacted.²¹⁷

Verificação

claude doctor

O comando informa o tipo de instalação, a versão, a configuração do sistema e quaisquer problemas detectados.

Gerenciamento de autenticação (v2.1.41+)

Gerencie a autenticação sem entrar no REPL:⁹⁰

claude auth login          # Log in or switch accounts
claude auth status         # Check current auth state (account, plan, expiry)
claude auth logout         # Clear stored credentials

A partir da v2.1.268, claude auth status --json inclui configDirectory – o diretório de configuração que o CLI está realmente lendo, útil quando a indireção do CLAUDE_CONFIG_DIR deixa isso ambíguo.²¹⁶

A partir da v2.1.273, entrar com uma conta Claude também solicita acesso aos seus plugins do claude.ai.²¹⁷

Fluxo comum para alternar entre contas ou organizações:

claude auth logout && claude auth login

Veja também: Como depurar problemas? para solucionar falhas de autenticação.

Atualizações

O Claude Code se atualiza automaticamente por padrão, verificando na inicialização e periodicamente durante as sessões. As atualizações são baixadas em segundo plano e aplicadas na próxima execução.

Desativar as atualizações automáticas:

export DISABLE_AUTOUPDATER=1

Ou no settings.json:

{
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}

Atualização manual:

claude update

Desinstalação

Instalação nativa (macOS/Linux/WSL):

rm -f ~/.local/bin/claude
rm -rf ~/.claude-code

Instalação nativa (Windows PowerShell):

Remove-Item -Path "$env:LOCALAPPDATA\Programs\claude-code" -Recurse -Force
Remove-Item -Path "$env:LOCALAPPDATA\Microsoft\WindowsApps\claude.exe" -Force

Configuração limpa (remove todas as configurações):

rm -rf ~/.claude
rm ~/.claude.json
rm -rf .claude
rm -f .mcp.json

Início rápido: sua primeira sessão

1. Instale e inicie:

claude                           # Launch in current directory

2. Acesse um projeto:

cd ~/my-project && claude        # Or launch from any git repo

3. Peça ao Claude para fazer algo:

> "Explain the architecture of this project"
> "Find all TODO comments and create a summary"
> "Add input validation to the signup form"

4. Use atalhos de teclado durante sua sessão:

/cost                            # Check token usage and cost
/compact                         # Free up context when it gets large
Alt+T                            # Toggle extended thinking for hard problems
Ctrl+C                           # Cancel current response

5. Continue mais tarde:

claude -c                        # Resume your most recent session
claude --resume                  # Pick from session list

Dica de especialista: Crie um arquivo CLAUDE.md na raiz do seu projeto com comandos de build, convenções de código e observações sobre a arquitetura. O Claude lê esse arquivo em todas as sessões — é a ação de maior impacto que você pode realizar para melhorar a qualidade.

Modos principais de interação

REPL interativo

Inicie o Claude Code sem argumentos para entrar no loop interativo de leitura, avaliação e impressão:

cd your-project
claude

O REPL mantém o contexto da conversa entre as interações. Digite as consultas diretamente, receba as respostas e continue até sair com /exit ou Ctrl+D.

Comece com um prompt inicial para direcionar a sessão:

claude "explain the authentication flow in this project"

Dica para especialistas: O REPL mantém o estado durante eventos de compactação. Quando o contexto fica grande demais, o Claude resume automaticamente a parte mais antiga da conversa, preservando as principais decisões e trechos de código. Você pode acionar esse processo manualmente com /compact ou adicionar instruções personalizadas sobre o que deve ser preservado.

Modo não interativo

O modo de impressão (-p) executa uma única consulta e encerra:

# Direct query
claude -p "list all TODO comments in this project"

# Process piped input
cat error.log | claude -p "identify the root cause of these failures"

# Chain with other tools
claude -p "generate a README" > README.md

Para obter uma saída estruturada adequada à análise em scripts:

claude -p "count lines by file type" --output-format json

A saída JSON inclui tudo o que você precisa para automação:

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.0034,
  "is_error": false,
  "duration_ms": 2847,
  "duration_api_ms": 1923,
  "num_turns": 4,
  "result": "Response text here...",
  "session_id": "abc-123-def"
}

Para processar a saída em streaming em tempo real:

claude -p "build the application" --output-format stream-json | while read line; do
  echo "$line" | jq -r 'select(.result) | .result'
done

Opções de formato da saída:

Texto de subagents em stream-json (v2.1.211+): Por padrão, a saída stream-json contém apenas os eventos da sessão principal — o trabalho realizado dentro de subagents aparece como um resumo. A flag --forward-subagent-text (ou CLAUDE_CODE_FORWARD_SUBAGENT_TEXT=1) também encaminha para o stream o texto e a saída de raciocínio dos subagents, permitindo que harnesses e pipelines de logs acompanhem o trabalho delegado à medida que ele acontece, em vez de ver apenas o relatório final.¹⁸⁸

Subagents aninhados agora também são encaminhados (v2.1.219). Originalmente, apenas subagents de profundidade 1 apareciam. Agora, os subagents criados na profundidade 2 ou superior também aparecem no stream encaminhado, cada um identificado pelo tool_use id da chamada Agent que o criou — assim, um pipeline pode reconstruir a árvore de delegação em vez de ver uma lista simples de textos. Isso se integra diretamente à restauração, na mesma versão, da criação aninhada na profundidade 3 por padrão: sem esse recurso, dois dos três níveis ficariam invisíveis.¹⁹⁶

Subagents movidos para segundo plano não ficam mais sem transmitir informações (v2.1.273): A saída de SDK e stream-json deixou de descartar as mensagens restantes e o relatório final de um subagent depois que ele é movido para segundo plano durante a execução (por exemplo, por CLAUDE_AUTO_BACKGROUND_TASKS).²¹⁷

Códigos de saída:

Como controlar o comportamento agêntico no modo -p:

# Limit autonomous turns (prevents runaway loops)
claude -p "refactor the auth module" --max-turns 10

# Allow specific tools without prompting
claude -p "fix lint errors" --allowedTools "Edit,Bash(npm run lint)"

# Use with a specific model
claude -p "explain this code" --model claude-sonnet-5

# Bare mode: skip hooks, LSP, plugin sync, skill walks (v2.1.81+)
claude -p "count files" --bare

# Channel permission relay: send approval prompts to Telegram/Discord (v2.1.81+)
claude --channels

# Restricted mode for eval harnesses and shared machines (v2.1.248+)
claude --restricted -p "query" --tools "Read,Grep,Glob"

# Unattended hosts: deny anything that would prompt (v2.1.259+)
claude -p "run the nightly checks" --permission-prompts none

Modo restrito (v2.1.248+): --restricted (ou CLAUDE_CODE_RESTRICTED=1) foi criado para harnesses de avaliação que executam o claude em uma máquina compartilhada. Ele remove as ferramentas integradas que executam comandos ou código e o WebFetch, a menos que você as especifique individualmente em --tools — o preset default não conta —, restringe as ferramentas de arquivo integradas aos diretórios de trabalho, carrega apenas as configurações gerenciadas e --settings (os arquivos de configurações do usuário, do projeto e locais são ignorados), recusa bypassPermissions e impede a criação de sessões na nuvem.²⁰⁶²⁰⁹

--permission-prompts none (v2.1.259): o complemento para hosts sem supervisão. Tudo o que acionaria uma solicitação de permissão é negado automaticamente, enquanto o modo de permissão ativo — incluindo o modo automático — continua tomando todas as decisões possíveis sem você. Não confunda essa opção com --permission-prompt-tool, que delega as solicitações a uma ferramenta MCP em vez de recusá-las. A referência de CLI ainda não apresenta a nova flag; a fonte é o CHANGELOG.²¹¹

O cd persiste entre interações em sessões não interativas (v2.1.265): sessões -p que recebem entrada stream-json, sessões Agent SDK e sessões na nuvem não redefinem mais o diretório de trabalho do shell a cada nova mensagem do usuário — agora, um cd executado em uma interação continua válido na próxima.²¹⁵

--system-prompt-snapshot off (v2.1.267): por padrão, uma conversa reutiliza o system prompt registrado em todas as solicitações. Essa flag renderiza novamente o system prompt a cada solicitação — é a opção indicada para iterar no texto do prompt, quando cada execução deve incorporar sua edição mais recente em vez do snapshot, ao custo da estabilidade do cache de prompts que o snapshot existe para proteger.²¹⁶

Padrão de integração com CI/CD:

# In a GitHub Action or CI pipeline
result=$(claude -p "review this diff for security issues" --output-format json 2>/dev/null)
is_error=$(echo "$result" | jq -r '.is_error')
if [ "$is_error" = "true" ]; then
  echo "Review failed"
  exit 1
fi
echo "$result" | jq -r '.result'

Gerenciamento de sessões

As sessões preservam o histórico da conversa para que ela possa ser retomada. A persistência das sessões é essencial para trabalhos complexos que abrangem várias sessões:

# Continue most recent session
claude -c

# Continue with additional prompt
claude -c -p "now add error handling"

# Resume specific session by ID
claude -r "abc123" "implement the remaining tests"

# Fork a session for parallel exploration
claude -r "base-session" --fork-session "try a different approach"

Mova uma sessão em execução com /cd (v2.1.169+; configuração imediata desde a v2.1.246): /cd path altera o diretório de trabalho sem invalidar o cache de prompts. Desde a v2.1.246, as configurações do projeto, os hooks, os servidores de .mcp.json (sujeitos à solicitação de aprovação habitual), as skills e os agents do novo diretório entram em vigor logo após a mudança, em vez de aguardar --resume.²⁴⁰²²⁷

Sessões vinculadas a PRs (v2.1.27+, ampliado na v2.1.119+): Inicie uma sessão vinculada a uma solicitação específica de pull ou merge. Desde a v2.1.119, --from-pr aceita URLs de MRs do GitLab, PRs do Bitbucket e PRs do GitHub Enterprise, além de github.com:⁷⁴¹⁵²

claude --from-pr 123                                                # GitHub PR number (assumes current repo's remote)
claude --from-pr https://github.com/org/repo/pull/123               # GitHub URL
claude --from-pr https://gitlab.com/org/repo/-/merge_requests/45    # GitLab MR (v2.1.119+)
claude --from-pr https://bitbucket.org/org/repo/pull-requests/67    # Bitbucket PR (v2.1.119+)
claude --from-pr https://ghe.example.com/org/repo/pull/89           # GitHub Enterprise (v2.1.119+)

As sessões também são vinculadas automaticamente a PRs quando você as cria com gh pr create durante uma sessão. Isso facilita retomar posteriormente o trabalho em um PR específico. O selo do PR no rodapé pode apontar para uma URL personalizada de revisão de código por meio da configuração prUrlTemplate (v2.1.119+) — útil quando sua equipe vincula os PRs a uma ferramenta de revisão separada.¹⁵²

/resume aceita URLs de PRs (v2.1.122+). Ao colar a URL de um PR na caixa de pesquisa de /resume, agora você encontra a sessão que criou originalmente esse PR — funciona com github.com, GitHub Enterprise, gitlab.com (inclusive instalações do GitLab com hospedagem própria) e bitbucket.org.¹⁵⁴

Sessões nomeadas: Dê nomes às sessões ao iniciá-las ou durante uma sessão:

# Name session at startup (v2.1.76+)
claude -n "auth-refactor"                  # --name flag sets display name[^125]

# Name current session
> /rename auth-refactor

# Resume by name or number
> /resume 1                    # Resume first session
> /resume auth-refactor        # Resume by name
claude --resume auth-refactor  # Resume from terminal
claude -r 3                    # Resume by number from terminal

# Fork for parallel exploration
claude --resume auth-refactor --fork-session

Observação: --session-id exige um UUID válido (por exemplo, 550e8400-e29b-41d4-a716-446655440000). Para usar nomes de sessão legíveis por pessoas, prefira /rename e --resume.

/fork cria uma sessão em segundo plano; /subtask é o fork dentro da sessão (v2.1.212). Agora, o comando /fork copia a conversa atual para uma nova sessão em segundo plano — ela recebe sua própria linha em claude agents, permitindo que você envie a cópia para explorar uma alternativa enquanto a sessão principal continua. O comportamento anterior — criar um fork dentro da sessão atual — continua disponível com o novo nome /subtask.¹⁸⁹ Desde a v2.1.214, uma sessão iniciada como fork informa a origem do hook SessionStart como "fork" (antes era "resume"), permitindo que hooks que verificam a origem diferenciem os dois casos.¹⁹⁰ A v2.1.216 reduz a confirmação de /fork a uma única linha que mostra o nome da nova sessão e seu id de claude attach.¹⁹² Desde a v2.1.221, uma sessão criada por fork cria seu próprio worktree, em vez de trabalhar no checkout da sessão original — assim, o fork que explora uma alternativa não pode mais entrar em conflito com os arquivos não commitados da sessão principal, que era o principal risco de enviar uma cópia para experimentar.¹⁹⁹ A v2.1.232 também torna o fork o padrão para subagents: um subagent com subagent_type: "fork" herda toda a conversa e o cache de prompts, e a criação de agents que não são colegas de equipe em sessões interativas agora é executada em segundo plano por padrão.²³³

O Claude Code armazena as sessões como transcrições JSONL. A execução de agents atribui valores agentId exclusivos, com as transcrições armazenadas como agent-{agentId}.jsonl. Ao retomar uma sessão, todo o contexto das conversas anteriores é preservado.

Modo de planejamento

O modo de planejamento restringe o Claude à exploração somente leitura — sem edição de arquivos, execução de Bash ou ações destrutivas. O Claude elabora uma abordagem de implementação, registra-a em um arquivo de plano e aguarda sua aprovação antes de executar qualquer ação.

Como entrar no modo de planejamento:

# Cycle through modes during a session
Shift+Tab           # Cycles: normal → plan → auto-accept

# Or use the /plan command with an optional description (v2.1.72+)
/plan                                     # Enter plan mode
/plan refactor the auth module            # Enter plan mode with a description

# Or ask Claude directly
"Plan how to refactor the auth module"   # Claude may enter plan mode automatically

Como funciona:

1. O Claude entra no modo de planejamento (automaticamente em tarefas complexas ou por meio de Shift+Tab)
2. Explora a base de código usando ferramentas somente leitura: Read, Glob, Grep, WebSearch, WebFetch
3. Registra um plano em .claude/plans/{session-slug}.md
4. Sai do modo de planejamento com ExitPlanMode e apresenta o plano para sua análise
5. Você aprova, solicita alterações ou rejeita

Ferramentas disponíveis no modo de planejamento: Read, Glob, Grep, LS, WebSearch, WebFetch, AskUserQuestion. As ferramentas de edição (Edit, Write, Bash, NotebookEdit) ficam bloqueadas.

Após a aprovação do plano (v2.1.32+): O Claude oferece três opções: - “Sim, limpar o contexto e aceitar edições automaticamente” (Shift+Tab) — começa do zero, com contexto completo para o plano - “Sim, e aprovar as edições manualmente” — preserva o contexto; você aprova cada alteração - “Sim, aceitar edições automaticamente” — preserva o contexto; o Claude executa sem exigir aprovação para cada edição

Limpar o contexto automaticamente após a aprovação é o fluxo de trabalho recomendado. Isso oferece ao plano uma nova janela de contexto, melhorando significativamente a adesão ao plano — o Claude se mantém no rumo por mais tempo, sem a interferência da conversa anterior.

Quando usar o modo de planejamento: - Implementações de novos recursos que exigem decisões arquiteturais - Refatorações em vários arquivos nas quais você quer revisar a abordagem primeiro - Bases de código desconhecidas, nas quais a exploração deve vir antes das alterações - Qualquer tarefa com várias abordagens válidas em que você queira opinar

Dica para especialistas: Quanto mais tempo você passar no modo de planejamento, maior será a probabilidade de o Claude ter sucesso na implementação. O modo de planejamento funciona, na prática, como uma exploração gratuita — sem chamadas arriscadas de ferramentas nem edições desperdiçadas. Use-o à vontade.

Modo de leitor de tela (v2.1.208)

O Claude Code inclui um modo dedicado de leitor de tela que adapta a interface do terminal para tecnologias assistivas. Ative-o de uma destas três maneiras:¹⁸⁶

# Flag at launch
claude --ax-screen-reader

# Environment variable
export CLAUDE_AX_SCREEN_READER=1

# Or persistently in settings.json
{ "axScreenReader": true }

O Anthropic documenta o modo — e seus padrões de interação — em uma nova página de acessibilidade na documentação oficial.¹⁸⁶

Análise profunda do sistema de configuração

O Claude Code usa um sistema de configuração em camadas. Entender a hierarquia é essencial, porque os níveis mais altos sobrescrevem os mais baixos, e as configurações enterprise não podem ser contornadas de forma alguma.

Hierarquia de configuração

Definindo configurações a partir do prompt: /config key=value (v2.1.181)

A partir da v2.1.181, /config key=value define qualquer configuração inline a partir do prompt — por exemplo, /config thinking=false — sem abrir a interface interativa do /config, e funciona em sessões interativas, -p e Remote Control. O /config --help (v2.1.183) lista as chaves abreviadas disponíveis. A v2.1.183 também mudou a interface interativa do /config: Enter e Espaço agora alternam a configuração selecionada e Esc salva e fecha (antes ele revertia).¹⁷⁴

Referência completa do settings.json

Uma configuração completa demonstrando todas as principais opções:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-5",
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(npm run:*)",
      "Bash(git:*)",
      "Bash(make:*)",
      "Edit(src/**)",
      "mcp__github"
    ],
    "deny": [
      "Read(.env*)",
      "Read(secrets/**)",
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Edit(package-lock.json)",
      "Edit(.git/**)"
    ],
    "ask": [
      "WebFetch",
      "Bash(curl:*)",
      "Bash(docker:*)"
    ],
    "additionalDirectories": [
      "../shared-lib",
      "../docs"
    ],
    "defaultMode": "acceptEdits"
  },
  "env": {
    "NODE_ENV": "development",
    "DEBUG": "app:*"
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  },
  "sandbox": {
    "enabled": false,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"]
  },
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  },
  "includeCoAuthoredBy": true,
  "cleanupPeriodDays": 30,
  "outputStyle": "Explanatory",
  "language": "en",
  "respectGitignore": true,
  "showTurnDuration": true,
  "plansDirectory": ".claude/plans",
  "spinnerVerbs": ["Thinking", "Processing", "Analyzing"],
  "spinnerTipsOverride": {
    "label": "Team tips",
    "tips": [
      "Custom tip 1",
      {"id": "tip-2", "text": "Custom tip 2", "cooldownSessions": 5, "priority": 1}
    ],
    "tipsFile": "~/.claude/team-tips.json",
    "excludeDefault": true
  },
  "skillOverrides": {
    "legacy-skill": "off",
    "manual-only-skill": "user-invocable-only",
    "compact-skill": "name-only"
  },
  "includeGitInstructions": false,
  "modelOverrides": {
    "bedrock": "us.anthropic.claude-opus-5",
    "vertex": "claude-opus-5",
    "foundry": "claude-opus-4-8"
  },
  "autoMemoryDirectory": ".claude/memory",
  "sandbox": {
    "enableWeakerNetworkIsolation": true
  }
}

O skillOverrides é útil quando uma equipe tem uma biblioteca grande de skills, mas quer uma exposição mais restrita em runtime. Use off para ocultar uma skill tanto do modelo quanto do seletor de slash commands, user-invocable-only para mantê-la chamável pelo nome removendo-a da seleção do modelo, e name-only para manter visível apenas o nome da skill, sem a descrição completa.¹⁵⁶

Configurações mais recentes (v2.1.174–176):

• availableModels / enforceAvailableModels (gerenciado, v2.1.175+): a allowlist availableModels restringe quais modelos uma sessão pode selecionar. Com enforceAvailableModels: true, a allowlist também limita o modelo Default — um Default que resolveria para um modelo não permitido cai para o primeiro modelo permitido — e as configurações de usuário/projeto não podem mais ampliar uma lista availableModels gerenciada. Uma correção complementar (v2.1.176) fecha a brecha em que a escolha de um alias podia redirecionar para um modelo bloqueado via ANTHROPIC_DEFAULT_*_MODEL, e o /fast agora se recusa a alternar para um modelo fora da allowlist.¹⁷² A partir da v2.1.187, as organizações podem impor restrições de modelo diretamente no seletor /model, no --model, no /model e no ANTHROPIC_MODEL — ao selecionar um modelo restrito, aparece a mensagem “restricted by your organization’s settings”.¹⁷⁶
• language (refinamento da v2.1.176): além de definir o idioma das respostas, os títulos das sessões agora são gerados no idioma da sua conversa por padrão; defina language para fixar um idioma específico para os títulos.¹⁷²
• footerLinksRegexes (v2.1.176): badges de links correspondidos por regex na linha de rodapé, configuráveis por configurações de usuário ou gerenciadas.¹⁷²
• wheelScrollAccelerationEnabled (v2.1.174): defina como false para desativar a aceleração de rolagem do mouse no modo tela cheia.¹⁷²

Configurações mais recentes (v2.1.207–v2.1.212):

• vimInsertModeRemaps (v2.1.208): remapeamentos de teclas personalizados para o modo de inserção do vim — o exemplo clássico é mapear jj para Escape (veja Modo Vim).¹⁸⁶
• axScreenReader (v2.1.208): ativa o modo leitor de tela de forma persistente (veja Modo leitor de tela).¹⁸⁶
• processWrapper (v2.1.208): roteia todos os processos que o Claude Code inicia para si mesmo através de um executável wrapper — feito para launchers corporativos (veja Launcher corporativo).¹⁸⁶
• Restrição de origem do autoMode (v2.1.207): a configuração autoMode não é mais lida do .claude/settings.local.json de um repositório — configure-a no ~/.claude/settings.json. Isso fecha um caminho pelo qual um repositório clonado poderia trazer configuração de auto-mode.¹⁸⁵

Configurações mais recentes (v2.1.217):

• emojiCompletionEnabled (v2.1.217): autocompletar de shortcodes de emoji no campo do prompt — digite :heart: para inserir ❤️, ou algo parcial como :hea para ver sugestões. Ativado por padrão; defina como false para desativar.¹⁹⁴

Configurações mais recentes (v2.1.219):

• sandbox.network.strictAllowlist (v2.1.219): nega hosts fora da allowlist para comandos em sandbox sem perguntar, em vez de abrir uma caixa de diálogo de permissão. Veja Modo sandbox.¹⁹⁶
• workflowSizeGuideline (v2.1.219): define a orientação consultiva de tamanho de workflow dinâmico a partir de qualquer arquivo de configuração — usuário, projeto ou gerenciado — em vez de somente pelo /config. Workflows dinâmicos usam por padrão uma orientação medium (“mire em menos de 15 agentes”); a linha do /config se oculta enquanto um arquivo de configuração fornecer o valor. É consultivo, não um limite imposto. Veja Subagents.¹⁹⁶

Configurações mais recentes (v2.1.242–243):

• modelPicker (usuário ou gerenciado, v2.1.242+): monta o seletor /model com uma lista ordenada e rotulada de modelos. É um objeto com um array options (cada linha exige um model, mais label e description opcionais; o model é usado literalmente, então aliases, IDs da Anthropic e IDs de Bedrock/Vertex/Foundry/gateway funcionam) e um Boolean opcional replaceBuiltInOptions (false, o padrão, acrescenta as linhas depois da lista integrada; true mostra apenas as suas linhas, o Default e o modelo que a sessão já está usando). O Claude Code lê a chave das configurações gerenciadas, do --settings e das configurações de usuário, e a ignora nas configurações de projeto e locais, de modo que um repositório clonado não consegue renomear o seletor; a fonte de maior precedência que a define fornece a lista inteira. Uma allowlist availableModels continua valendo para cada linha, e um label muda o que o seletor mostra, não qual modelo roda.²²⁸²²⁶
• promptCacheTtl / subagentPromptCacheTtl (qualquer arquivo, v2.1.242+): "5m" ou "1h" por bucket de requisição, para que usuários de chave da API e de provedores de nuvem possam manter um cache de uma hora na conversa principal enquanto os subagents ficam em cinco minutos. Veja Estratégias de cache.²²⁸²²⁶
• modelPricing (gerenciado, v2.1.243+): as tarifas contratadas por modelo de uma organização e o multiplicador de desconto, usados pelo /cost, pela status line e pelos números de custo da telemetria em vez do preço de tabela. Veja Visualizando custos.²²⁸

Configurações mais recentes (v2.1.247): - feedbackDrafts (v2.1.247): controla a nova ferramenta SendFeedback – quando algo dá errado em uma sessão, o Claude pode rascunhar um relatório de feedback para você revisar e enviar pelo /feedback; desative esse rascunho com essa configuração. Veja a linha /feedback em Comandos slash.²²³ - Extensão do formato de spinnerTipsOverride (v2.1.247): as entradas de dica agora podem ser objetos {id, text, cooldownSessions, priority} além de strings simples, e o objeto ganha as chaves tipsFile e label, para que as organizações possam alternar suas próprias dicas junto com as embutidas (o exemplo acima mostra o formato estendido). A documentação de configurações ainda não documenta as novas chaves – o CHANGELOG é a única fonte para elas.²²³

Configurações mais recentes (v2.1.248–251):

• desktopSessionCleanupPeriodDays (v2.1.248): limita por quanto tempo as sessões criadas no desktop ficam isentas da limpeza de transcrições. A correção que vem junto importa mais do que o botão: as sessões do Claude Desktop e do Cowork costumavam sumir depois de cleanupPeriodDays (padrão de 30 dias); agora a limpeza as preserva enquanto elas estiverem no app, a menos que a política da organização gerencie a retenção.²⁰⁶
• Restrições de env no projeto (v2.1.251): um bloco env em um .claude/settings.json de nível de projeto não pode mais definir CLAUDE_CONFIG_DIR, CLAUDE_CODE_TMPDIR nem TMPDIR/TMP/TEMP – defina essas variáveis no seu shell ou nas configurações de usuário ou gerenciadas, para que um repositório clonado não consiga redirecionar onde o Claude Code grava seus arquivos de configuração e temporários.²⁰⁶

Configurações mais recentes (v2.1.257-259):

• timeFormat / timeZone (v2.1.257): controlam como o Claude Code exibe os horários – o relógio de conclusão no fim do turno e os timestamps das transcrições. timeFormat aceita 12 horas, 24 horas, 24 horas em UTC ou um padrão strftime explícito; timeZone indica o fuso horário. A documentação de configurações ainda não os documenta – o CHANGELOG é a fonte.²¹¹
• permissions.blockReadsOutsideWorkingDirectories (v2.1.257): recusa de imediato leituras de arquivos fora dos diretórios de trabalho da sessão. Sem ela, o modo automático agora pergunta uma vez antes da primeira leitura desse tipo na sessão (veja Modo automático).²¹¹ A v2.1.273 fecha duas brechas: um comando Bash que o verificador não consegue analisar por completo passa a pedir confirmação em vez de pular a verificação, e um diretório de memória escolhido pelas configurações de um repositório não é carregado, recuperado nem indexado sob essa configuração.²¹⁷
• managedMcpServers / managedSourcesBehavior: chaves de escopo gerenciado, cobertas em Implantação corporativa – organizações que fornecem servidores MCP para todos os usuários (v2.1.259) e a mesclagem opcional entre fontes gerenciadas (refinada na v2.1.257).²¹¹²²²

Configurações mais recentes (v2.1.261):

• bashOutputMaxChars / taskOutputMaxChars (v2.1.261): aumentam quanta saída de comando (e de tarefa em segundo plano, respectivamente) o Claude recebe inline antes de o restante ser salvo em um arquivo, até 128 mil caracteres. É um mecanismo diferente da variável de ambiente BASH_MAX_OUTPUT_LENGTH, que define a janela de releitura a partir do arquivo de saída do comando (30.000 caracteres por padrão, com limite de 150.000): essas chaves governam o limiar entre inline e arquivo persistido – passado esse ponto, a saída vai para um arquivo que o Claude pode ler sob demanda, em vez de ser cortada.²¹⁴ A partir da v2.1.265, o lado persistido também tem um teto: os resultados de ferramenta salvos em disco são limitados a 1 GB, e a prévia na conversa informa quando um arquivo salvo foi truncado.²¹⁵

Configurações mais recentes (v2.1.267-269):

• maxEffortLevel (v2.1.267): limita o nível de esforço que os usuários podem escolher – no nível superior ou por modelo em modelSettings – e vale em todos os provedores, incluindo Bedrock, Vertex e Foundry. Os usuários ainda podem escolher um nível abaixo do limite; é o complemento administrativo do /effort.²¹⁶
• bashEditDiffEnabled (v2.1.269): quando a ferramenta Bash faz a edição de um arquivo, o resultado da ferramenta traz um diff dos arquivos que o comando alterou, de modo que a conversa mostra o que uma edição no estilo sed realmente fez.²¹⁶

Configurações mais recentes (v2.1.275):

• syncClaudeAiSkills / syncClaudeAiPlugins (v2.1.275): as skills e os plugins habilitados na sua conta claude.ai agora sincronizam com as sessões de terminal conectadas a essa conta. Defina qualquer uma das chaves como false para manter as sessões de terminal apenas com skills e plugins locais. Veja Skills e Sistema de plugins.²¹⁸

Consulta de configurações: as flags mais procuradas

Se você chegou aqui atrás de uma configuração específica pelo nome, este é o índice curto. Cada entrada indica a versão em que ela foi lançada e, quando pertence a um escopo, qual é ele:

ANTHROPIC_API_KEY=sk-ant-...                    # Direct API authentication
ANTHROPIC_AUTH_TOKEN=token                      # Custom authorization header
ANTHROPIC_CUSTOM_HEADERS="X-Key: val"           # Additional request headers; credential/org/routing/API-behavior headers set from managed or project settings require approval (v2.1.251)[^238]

Configuração de modelo:

ANTHROPIC_MODEL=claude-opus-4-7                 # Override default model (Apr 16, 2026)
ANTHROPIC_DEFAULT_MODEL=claude-opus-5           # Model new sessions START on; a /model pick overrides + persists (v2.1.236)
ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5      # What the `opus` alias resolves to (Opus 5 since v2.1.219)
ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-6
ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5-20251001
CLAUDE_CODE_SUBAGENT_MODEL=sonnet               # Default model for subagents; an agent's model: field and per-spawn picks win (v2.1.251 demoted it from override to default)[^238]
CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1              # Force every subagent onto CLAUDE_CODE_SUBAGENT_MODEL (or the main model), ignoring agent-definition and per-spawn overrides -- the pre-v2.1.251 behavior, opt-in (v2.1.257)[^243]
CLAUDE_CODE_WORKFLOWS=1                         # Enable Workflow tool for deterministic multi-agent orchestration (v2.1.147+)
MAX_THINKING_TOKENS=10000                       # (Opus 4.6 and Sonnet 4.6 only — removed in Opus 4.7)
CLAUDE_CODE_MAX_OUTPUT_TOKENS=4000              # Limit output length
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1          # Enable agent teams (v2.1.32+)

Configuração de provedores de nuvem:

CLAUDE_CODE_USE_BEDROCK=1                       # Use AWS Bedrock
CLAUDE_CODE_USE_VERTEX=1                        # Use Google Vertex AI
CLAUDE_CODE_USE_FOUNDRY=1                       # Use Microsoft Foundry
ANTHROPIC_BEDROCK_BASE_URL=https://...          # Custom Bedrock endpoint
ANTHROPIC_BEDROCK_SERVICE_TIER=priority         # Bedrock service tier (v2.1.122+): 'default', 'flex', or 'priority'; sent as X-Amzn-Bedrock-Service-Tier header[^162]
CLAUDE_CODE_SKIP_BEDROCK_AUTH=1                 # Skip Bedrock auth (for gateways)
CLAUDE_CODE_SKIP_VERTEX_AUTH=1                  # Skip Vertex auth
AWS_BEARER_TOKEN_BEDROCK=token                  # Bedrock bearer token
VERTEX_REGION_CLAUDE_3_7_SONNET=us-west1        # Override Vertex region
CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1    # Opt in gateway /v1/models discovery for /model picker (v2.1.129+)[^164]
CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS=3000  # Extend the LLM gateway /v1/models discovery timeout (default 3s; v2.1.269+)[^252]
CLAUDE_CODE_GATEWAY_HINT_HEADERS=1              # Send five x-claude-code-* hint headers (request-class, agent-type, prev-tool-durations, compaction, context-compacted) for LLM gateways (opt-in; v2.1.273+)[^253]
CLAUDE_CODE_AUTO_MODE_SERVER=1                  # Use the platform's server-side auto-mode classifier on Bedrock/Vertex/Foundry; since v2.1.273 the local classifier is the default there "for now"[^253]

Controle de comportamento:

DISABLE_AUTOUPDATER=1                           # Prevent automatic background updates
DISABLE_UPDATES=1                               # Block ALL update paths including manual `claude update` (v2.1.118+, stricter than DISABLE_AUTOUPDATER)[^160]
CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1       # Homebrew/WinGet installs run package-manager upgrade in background, then prompt restart (v2.1.129+)[^164]
DISABLE_TELEMETRY=1                             # Opt out of usage telemetry
DISABLE_ERROR_REPORTING=1                       # Disable Sentry
DISABLE_BUG_COMMAND=1                           # Disable /bug command
CLAUDE_CODE_RESTRICTED=1                        # Restricted mode: no command/code tools or WebFetch unless named in --tools; only managed settings load (v2.1.248+)[^238]
DISABLE_COST_WARNINGS=1                         # Hide cost warnings
DISABLE_PROMPT_CACHING=1                        # Disable prompt caching globally
DISABLE_PROMPT_CACHING_SONNET=1                 # Disable for Sonnet only
DISABLE_PROMPT_CACHING_OPUS=1                   # Disable for Opus only
DISABLE_NON_ESSENTIAL_MODEL_CALLS=1             # Skip non-critical API calls
ENABLE_PROMPT_CACHING_1H=1                      # Opt into 1-hour prompt cache TTL (v2.1.108+, API/Bedrock/Vertex/Foundry)
ENABLE_PROMPT_CACHING_1H_BEDROCK=1              # Deprecated alias for the above; v2.1.108+ still honors it on Bedrock but logs a deprecation notice
FORCE_PROMPT_CACHING_5M=1                       # Force 5-minute cache TTL (v2.1.108+)
CLAUDE_CODE_PROMPT_CACHE_TTL=1h                 # Main-conversation cache TTL, 5m or 1h; beats the promptCacheTtl setting (v2.1.242+)[^234]
CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL=5m        # TTL for subagents, workflows, forks, compaction, titles; beats subagentPromptCacheTtl (v2.1.242+)[^234]
ENABLE_TOOL_SEARCH=true                         # Re-enable tool search on Vertex AI (disabled by default v2.1.119+ to avoid unsupported beta header). Valid values: true, false, auto, auto:N[^160]
CLAUDE_CODE_HIDE_CWD=1                          # Hide the working directory in the startup logo (v2.1.119+)[^160]
CLAUDE_CODE_FORK_SUBAGENT=1                     # Enable forked subagents on external builds (v2.1.117+)[^160]
CLAUDE_CODE_FORCE_SYNC_OUTPUT=1                 # Force synchronized terminal output when auto-detection misses it, such as Emacs eat (v2.1.129+)[^164]
CLAUDE_CODE_SESSION_ID=...                      # Read-only: present in the Bash tool subprocess; matches the session_id passed to hooks (v2.1.132+)[^168]
CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1          # Skip the fullscreen alternate-screen renderer; keep the conversation in the terminal's native scrollback (v2.1.132+)[^168]
CLAUDE_EFFORT=...                               # Read-only: current effort level inside hooks and Bash tool subprocess (v2.1.133+)[^169]
CLAUDE_CODE_FORWARD_SUBAGENT_TEXT=1             # Include subagent text + thinking in stream-json output; pairs with --forward-subagent-text (v2.1.211+). Covers depth-2+ nested subagents as of v2.1.219[^205][^213]
CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION=200    # Per-session WebSearch cap (default 200; v2.1.212+)[^206]
CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS=900000        # WebFetch per-URL session cache TTL (default 15 min; v2.1.233+)[^226]
CLAUDE_CODE_WEBFETCH_DEADLINE_MS=300000         # WebFetch hard deadline: a server that never finishes its response fails the fetch after 300s by default; 0 disables (v2.1.268+)[^252]
CLAUDE_CODE_PROJECT_DIR_NAME=myproj             # Short name for the per-project transcript directory, for hosts that give each session its own config dir (v2.1.234+)[^227]
CLAUDE_CODE_GOAL_CHECKIN_MINUTES=30             # How long background tasks may keep a /goal waiting before Claude checks in on them; 0 disables (v2.1.234+)[^227]
CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION=200       # Per-session subagent-spawn cap (default 200 in v2.1.212–223; the default cap was REMOVED in v2.1.224 — set this to reimpose one)[^206][^218]
CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS=20         # Cap on concurrently-RUNNING subagents (default 20; distinct from the per-session total above; v2.1.217+)[^211]
CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS=0        # Disable the v2.1.229 workflow fan-out stagger (same-prefix sibling agents launch staggered so they read the cached prompt prefix instead of re-paying it)[^224]
CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS=64   # Raise the Workflow tool's per-run concurrent agent limit, 1-256, for inference-bound fan-outs (v2.1.269+)[^252]
CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=3          # Nested subagent spawn depth. Default 3 as of v2.1.219; set 1 to disable nesting. Default history: 5 (v2.1.172–v2.1.216) → 1 (v2.1.217) → 3 (v2.1.219). Set it explicitly[^211][^213]

Configuração de ferramentas:

BASH_DEFAULT_TIMEOUT_MS=30000                   # Bash command timeout (30s)
BASH_MAX_TIMEOUT_MS=600000                      # Maximum bash timeout (10min)
BASH_MAX_OUTPUT_LENGTH=50000                    # Read-back window from the Bash working output file (default 30,000 chars, hard ceiling 150,000)
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1     # Reset CWD after each bash
MCP_TIMEOUT=5000                                # MCP server startup timeout
MCP_TOOL_TIMEOUT=30000                          # MCP tool execution timeout
MAX_MCP_OUTPUT_TOKENS=25000                     # MCP output limit
CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=120000       # Threshold before a long MCP tool call moves to the background (default 2 min; v2.1.212+)[^206]
CLAUDE_CODE_MCP_STARTUP_WAIT_MS=10000           # Bound how long the FIRST non-interactive turn waits for still-connecting MCP servers; 0 = don't wait (v2.1.274+)[^254]
CLAUDE_CODE_TOOL_MEMORY_LIMIT=4096              # Opt-in Linux memory cgroup (MB) for Bash tool commands — a runaway build can't stall the session (v2.1.233+)[^226]
CLAUDE_CODE_ENABLE_TODO_TOOLS=1                 # Offer the TodoWrite/TaskCreate-family tools on models outside v2.1.268's allowlist (Claude 3.x, Opus 4.0-4.7, Sonnet 4.0-4.6, Haiku 4.5); elsewhere they are off unless set (first turned off on newer models in v2.1.233)[^226][^252]
SLASH_COMMAND_TOOL_CHAR_BUDGET=15000            # Slash command context limit

Rede e proxy:

HTTP_PROXY=http://proxy:8080                    # HTTP proxy
HTTPS_PROXY=https://proxy:8080                  # HTTPS proxy
NO_PROXY=localhost,example.com                  # Bypass proxy for domains
CLAUDE_CODE_CLIENT_CERT=/path/to/cert           # mTLS certificate
CLAUDE_CODE_CLIENT_KEY=/path/to/key             # mTLS private key
CLAUDE_CODE_CLIENT_KEY_PASSPHRASE=pass          # mTLS passphrase

Interface e terminal:

CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1            # Don't update terminal title
CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL=1             # Skip IDE extension install
CLAUDE_CODE_SHELL=/bin/zsh                      # Override shell detection
USE_BUILTIN_RIPGREP=1                           # Use included ripgrep (default)
CLAUDE_CONFIG_DIR=~/.myconfig                   # Custom config directory; not settable from project-settings env (v2.1.251)[^238]
IS_DEMO=1                                       # Hide sensitive UI elements[^37]
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1          # Disable background tasks and Ctrl+B[^46]
CLAUDE_CODE_TMPDIR=/path/to/tmp                 # Override temp directory; not settable from project-settings env, nor are TMPDIR/TMP/TEMP (v2.1.251)[^50][^238]
CLAUDE_CODE_DISABLE_1M_CONTEXT=1               # Hold ALL native-1M models to 200K via auto-compaction (v2.1.223 widened scope)[^103][^217]
CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1  # Let unrecognized model IDs exceed the assumed context window (v2.1.223)[^217]
CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=120000       # Plugin marketplace git timeout (default 120s, was 30s)[^105]
CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=1        # Remove built-in commit/PR instructions[^117]
CLAUDE_CODE_DISABLE_CRON=1                    # Stop scheduled cron jobs mid-session[^121]
CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=30000 # SessionEnd hooks timeout (default varies)[^123]
CLAUDE_CODE_USE_POWERSHELL_TOOL=1             # Enable Windows PowerShell tool on Linux/macOS (requires pwsh on PATH; v2.1.111+)[^153]
CLAUDE_CODE_DISABLE_MOUSE_CLICKS=1           # Disable mouse click/drag/hover in fullscreen mode; wheel scroll still works (v2.1.195+)[^196]
CLAUDE_ENABLE_STREAM_WATCHDOG=0              # Disable the streaming idle watchdog (on by default for all providers since v2.1.196: aborts+retries after 5 min of silence)[^198]
CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP=1 # Turn off automatic memory-pressure reaping of idle background shell commands (v2.1.193+)[^196]
CLAUDE_CODE_ENABLE_AWAY_SUMMARY=1             # Force Session Recap when telemetry disabled (v2.1.108+)[^153]
CLAUDE_CODE_BG_TASKS_REPORT_RUNNING=0         # Restore pre-v2.1.269 behavior: remote/headless sessions may report "waiting for your input" while background agents still run[^252]
CLAUDE_AX_SCREEN_READER=1                     # Enable screen reader mode; same as --ax-screen-reader or "axScreenReader": true (v2.1.208+)[^203]
OTEL_LOG_RAW_API_BODIES=1                     # Emit full API request/response bodies as OTel log events (v2.1.111+)[^153]
TRACEPARENT=00-...                            # W3C Trace Context parent (v2.1.110+, SDK/headless)[^153]
TRACESTATE=vendor=value                       # W3C Trace Context state (v2.1.110+, SDK/headless)[^153]

Exportadores OpenTelemetry + controle de campos sensíveis:²⁴⁶

OTEL_LOGS_EXPORTER=none                       # OTel logs exporter (supports 'none' for disable; v2.1.85 fixed crash)
OTEL_METRICS_EXPORTER=none                    # OTel metrics exporter (supports 'none'; v2.1.85 fixed crash)
OTEL_TRACES_EXPORTER=none                     # OTel traces exporter (supports 'none'; v2.1.85 fixed crash)
OTEL_LOG_TOOL_CONTENT=1                       # Opt in to emitting tool content in OTel spans (v2.1.101+, sensitive by default)
OTEL_LOG_TOOL_DETAILS=1                       # Opt in to tool_parameters in OTel tool_result events (v2.1.85+); as of v2.1.273 also puts real agent, skill, plugin, and MCP server names on cost and token metrics[^253]
OTEL_LOG_USER_PROMPTS=1                       # Opt in to emitting user prompts in OTel traces (v2.1.101+, sensitive by default)
OTEL_LOG_ASSISTANT_RESPONSES=0                # Gate the claude_code.assistant_response log event holding the model's response text (v2.1.193+)
OTEL_METRICS_INCLUDE_REPOSITORY=1             # Tag OTel metrics and events with vcs.* repository attributes; with OTEL_LOG_TOOL_DETAILS, commit events carry vcs.ref.head.* (v2.1.269+)[^252]
CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH=60000     # Truncation limit for OTel content attributes (default 60 KB; v2.1.214+)[^207]
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1    # Disable release-notes fetch (v2.0.17+); v2.1.110 also stopped the auto-title Haiku request in headless/SDK when set

Atributos de span de requisição LLM na v2.1.121+: stop_reason, gen_ai.response.finish_reasons e user_system_prompt agora são emitidos nos spans de requisição LLM. O user_system_prompt fica protegido por OTEL_LOG_USER_PROMPTS=1, já que pode conter PII.¹⁵⁴

Mudanças em nível de evento na v2.1.122+: Atributos numéricos nos eventos de log api_request e api_error agora são emitidos como números (antes eram strings) — o que corrige coletores OTel downstream que tipavam o schema de forma estrita. O novo evento de log claude_code.at_mention dispara quando o Claude Code resolve uma menção com @.¹⁵⁴

Evento de log claude_code.assistant_response na v2.1.193+: O Claude Code pode emitir o texto completo da resposta do modelo como um evento de log OTel, controlado por OTEL_LOG_ASSISTANT_RESPONSES. Esse controle tem uma pegadinha de upgrade que vale conhecer: quando OTEL_LOG_ASSISTANT_RESPONSES não está definido, ele segue o OTEL_LOG_USER_PROMPTS, então qualquer deployment que já registre o conteúdo dos prompts passará a receber também o conteúdo das respostas do assistente após o upgrade. Defina OTEL_LOG_ASSISTANT_RESPONSES=0 para manter a telemetria apenas com os prompts.¹⁷⁹

Adições de telemetria na v2.1.214: Eventos de log OTel agora carregam os atributos message.uuid, client_request_id e tool_source para correlação em nível de mensagem e rastreio de origem das ferramentas; o payload subagentStatusLine inclui o esforço de raciocínio do subagent, de modo que linhas de status personalizadas podem exibir modelo e esforço juntos; e a nova variável de ambiente CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH configura o limite de truncamento de 60 KB nos atributos de conteúdo OTel.¹⁹⁰

Telemetria do gateway na v2.1.265: Sessões do gateway de apps Claude agora exportam OpenTelemetry diretamente para um coletor quando as configurações gerenciadas do gateway indicam um em OTEL_EXPORTER_OTLP_ENDPOINT, em vez de passar pelo relay do gateway; sessões sem um coletor indicado continuam usando o relay. A mesma versão adiciona user.email e user.groups à telemetria que o Claude Desktop e o Cowork enviam por um gateway de apps Claude, igualando as sessões de terminal.²¹⁵

API / Controle de modelo:²⁴⁶

CLAUDE_CODE_EXTRA_BODY='{...}'                # Inject extra body fields into API calls; v2.1.113 fixed 400 errors with output_config.effort on Vertex/subagent calls
CLAUDE_CODE_MAX_CONTEXT_TOKENS=200000         # Override max context tokens (pre-existing var; v2.1.98 fixed handling of DISABLE_COMPACT when both are set)
CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS=25000 # Override default token limit for file read operations (v2.1.0+)
CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1   # Do not fall back to non-streaming API on streaming failures (v2.1.83+)
ANTHROPIC_BETAS=beta1,beta2                   # Enable beta API headers; v2.1.78 fixed silent ignore on Haiku models
ANTHROPIC_SMALL_FAST_MODEL=arn:...            # Fast model ID (Bedrock ARN supported; v0.2.125 stopped escaping slashes in ARN)

Plugins / MCP:²⁴⁶

CLAUDE_CODE_PLUGIN_CACHE_DIR=~/.claude/plugins # Plugin cache directory (v2.1.72 fixed literal '~' dir on some shells)
CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 # Preserve plugin marketplace cache when git pull fails (offline-friendly; v2.1.90+)
CLAUDE_CODE_MCP_SERVER_NAME=server1           # Passed to MCP headersHelper scripts so one helper can serve multiple servers (v2.1.85+)
CLAUDE_CODE_MCP_SERVER_URL=https://...        # Passed to MCP headersHelper scripts alongside the name (v2.1.85+)
MCP_SDK_GENERATION=v1                         # Opt out of the v2 MCP client; v2.1.274 made v2 the default on the last holdouts (Bedrock/Vertex/Foundry + telemetry-disabled installs)[^254]
MCP_PROTOCOL_NEGOTIATION=legacy               # Opt out of MCP 2026-07-28 protocol negotiation with direct HTTP servers (default everywhere as of v2.1.274)[^254]

Shell / IDE:²⁴⁶

CLAUDE_CODE_SHELL_PREFIX="time "              # Wrap every Claude-invoked shell command with a prefix (v1.0.61+)
CLAUDE_CODE_GIT_BASH_PATH=C:\Program\ Files\Git\bin\bash.exe  # Custom Git Bash path on Windows (v2.1.98+)
CLAUDE_CODE_EXIT_AFTER_STOP_DELAY=60000       # SDK: exit after N ms idle (v2.0.35+)
CLAUDE_CODE_AUTO_CONNECT_IDE=false            # Disable IDE auto-connection (v1.0.61+)

Enterprise / autenticação:²⁴⁶

CLAUDE_CODE_PROXY_RESOLVES_HOSTS=1            # Opt into proxy-side DNS resolution (v2.0.55 moved this from default-on to opt-in)
CLAUDE_CODE_API_KEY_HELPER_TTL_MS=300000      # TTL for dynamically generated API keys via apiKeyHelper (apiKeyHelper refresh added v0.2.74 with 5-min default; env var added v0.2.117)
CLAUDE_CODE_PROCESS_WRAPPER=/path/to/wrapper  # Route all Claude Code self-spawned processes through a wrapper executable; same as the processWrapper setting (v2.1.208+)[^203]

Variáveis de skill (v2.1.69+):

${CLAUDE_SKILL_DIR}                            # Self-reference for skills to locate their own directory[^117]

Identidade do chamador do SDK (v2.1.51+):

CLAUDE_CODE_ACCOUNT_UUID=uuid                  # Provide account UUID synchronously for SDK callers
CLAUDE_CODE_USER_EMAIL=user@example.com        # Provide user email for SDK callers
CLAUDE_CODE_ORGANIZATION_UUID=uuid             # Provide organization UUID for SDK callers

Depuração:

ANTHROPIC_LOG=debug                             # Enable API request logging

Qual modelo devo escolher?

Escolher o modelo certo para cada tarefa afeta significativamente tanto o custo quanto a qualidade. O Claude Code oferece flexibilidade para alternar entre modelos em vários níveis.

Modelos disponíveis

Duas mudanças incompatíveis ao migrar um harness do Opus 4.8 para o Opus 5:¹⁹⁷

1. O pensamento vem ativado por padrão. No Opus 4.8, uma solicitação sem o campo thinking era executada sem pensamento; no Opus 5, a mesma solicitação é executada com pensamento adaptativo. max_tokens continua sendo um limite rígido para a saída total — pensamento mais texto da resposta —, portanto, verifique novamente a margem disponível em qualquer carga de trabalho que antes era executada sem pensamento. Passe thinking: {type: "disabled"} para restaurar o comportamento anterior, sujeito ao próximo item.
2. Desativar o pensamento limita o esforço a high. Combinar thinking: {type: "disabled"} com o esforço xhigh ou max retorna um erro 400. A verificação é aplicada a cada solicitação — aumentar o esforço para xhigh enquanto o pensamento está desativado é rejeitado, mesmo que turnos anteriores da mesma conversa tenham sido aceitos.

Especificamente no Claude Code: o padrão de effort é high no Opus 5 (assim como no Claude API), e toda a escala está disponível — low, medium, high, xhigh, max. A própria orientação de migração da Anthropic recomenda testar o esforço max quando a capacidade for mais importante do que o consumo de tokens. O modo rápido inclui o Opus 5 por US$ 10/US$ 50 por MTok (consulte Modo rápido).¹⁹⁷¹⁹⁸

Claude Fable 5.1 (1º de setembro de 2026): O novo topo do nível Fable e, desde a v2.1.257, o modelo para o qual o alias fable aponta (a menos que ANTHROPIC_DEFAULT_FABLE_MODEL fixe outro modelo); agora, best significa “o modelo Fable mais recente disponível para você”. A versão mínima exige uma explicação: a documentação de configuração de modelos informa que o alias mudou na v2.1.255, e a página do modelo diz que o Fable 5.1 “requer o Claude Code v2.1.255 ou posterior”, mas as versões 2.1.253-256 nunca foram publicadas no npm – a v2.1.257 (1º de setembro) é a primeira versão instalável que inclui o modelo. ID do modelo: claude-fable-5-1 (Bedrock: anthropic.claude-fable-5-1). Mesmo nível e preço por token do Fable 5 – US$ 10/MTok de entrada, US$ 50/MTok de saída, contexto de 1M, saída máxima de 128K, pensamento adaptativo sempre ativo e padrão de effort definido como high – com uma mudança de preço relevante para sessões longas com agentes: as leituras de cache custam US$ 0,25/MTok, 0,025 vez o preço da entrada (2,5%), em comparação com os 10% padrão; somente o Fable 5.1 e o Mythos 5.1 têm essa tarifa, e as gravações em cache permanecem com os valores padrão (US$ 12,50 por 5 minutos e US$ 20 por 1 hora). Data de corte do conhecimento confiável: junho de 2026 (os dados de treinamento também vão até junho de 2026) – a mais recente entre todos os modelos Claude atuais. A descontinuação não ocorrerá antes de 1º de setembro de 2027. Três mudanças incompatíveis em relação ao Fable 5: o uso forçado de ferramentas retorna um erro, modelos anteriores não conseguem ler seus blocos de pensamento e editar turnos anteriores invalida os blocos de pensamento. Cinco mudanças incrementais: esforço por mensagem (beta), mensagens do sistema limitadas ao turno (beta), atualizações de progresso entre chamadas de ferramentas (display: "updates", beta), leituras de cache mais baratas e procedência do conteúdo. O Claude Mythos 5.1 é o mesmo modelo, com as mesmas especificações, disponível somente por convite por meio do Project Glasswing. Com o lançamento, o Fable 5 passa para a tabela de modelos legados da documentação, junto com o Opus 4.8/4.7/4.6/4.5 e o Sonnet 4.6/4.5. Uma ressalva sobre gateways nas notas da versão: nas sessões do gateway de aplicativos Claude, fable e best continuam apontando para o Fable 5 por enquanto – um gateway que ainda não esteja configurado para a versão 5.1 a rejeita –, portanto, selecione explicitamente o Fable 5.1 em /model nesse ambiente; antes da v2.1.260, o seletor /model não listava o Fable 5.1, então selecioná-lo explicitamente exigia digitar o comando completo /model claude-fable-5-1 (consulte abaixo as correções relacionadas ao lançamento). Os padrões dos planos permanecem iguais: Opus 5 nos planos premium e Sonnet 5 no Pro e Team Standard.^211219220

Correções relacionadas ao lançamento do Fable 5.1 (v2.1.260, 3 de setembro): a primeira versão após o lançamento corrige quatro problemas. Agora, o seletor /model exibe o Fable 5.1 para as organizações que podem usá-lo – antes dessa correção, o modelo só era aceito quando digitado por completo como /model claude-fable-5-1. Agora, o cache de prompts no Fable 5.1 inclui o contexto anexado após os resultados das ferramentas, que antes era reenviado como entrada não armazenada em cache a cada turno com chamada de ferramenta – comprometendo discretamente a economia das leituras de cache a 0,025 vez o preço justamente nas sessões longas com agentes para as quais essa tarifa existe. Alterar /effort no meio da sessão não invalida mais o cache de prompts. Além disso, agentes com model: fable agora respeitam a tag [1m] em um modelo fixado por ANTHROPIC_DEFAULT_FABLE_MODEL, em vez de executar silenciosamente com uma janela de contexto de 200K.²¹²

Claude Fable 5 (9 de junho de 2026; legado desde 1º de setembro de 2026): Um novo nível de modelo acima do Opus — o modelo mais poderoso e inteligente da Anthropic, de última geração em praticamente todos os benchmarks nos quais foi testado e desenvolvido para manter a coerência ao longo de milhões de tokens de contexto. O Fable 5 é o modelo de fronteira da “classe Mythos” adaptado para uso geral com segurança: ele inclui classificadores de segurança que recorrem ao Opus 4.8 para consultas sobre cibernética, bioquímica e destilação de modelos (o Claude Mythos 5 é o mesmo modelo, mas sem essas proteções para pesquisadores autorizados). Ele passou a estar disponível para seleção no Claude Code com a v2.1.170 (9 de junho de 2026) — execute claude update e depois /model fable (o alias curto, que desde a v2.1.257 aponta para o Fable 5.1 – hoje, selecione o Fable 5 com /model claude-fable-5) — e foi disponibilizado gradualmente nos planos de assinatura até 22 de junho de 2026 (implantação concluída). ID do modelo: claude-fable-5. O Fable 5 inclui uma janela de contexto de 1M por padrão, portanto, o sufixo [1m] é desnecessário — e, desde a v2.1.173 (11 de junho de 2026), um nome de modelo claude-fable-5[1m] é automaticamente normalizado para claude-fable-5, com a remoção do sufixo (ele só teve utilidade no Opus/Sonnet, que condicionam o contexto de 1M ao uso de [1m]); saída máxima de 128K. O preço é de US$ 10/MTok de entrada e US$ 50/MTok de saída — aproximadamente o dobro do Opus 4.8 —, portanto, reserve-o para problemas de raciocínio realmente difíceis, não para edições rotineiras. Ele compartilha a interface de solicitações do Opus 4.8 (somente pensamento adaptativo; temperature/top_p/top_k e budget_tokens foram removidos), com uma particularidade: definir explicitamente thinking: {type: "disabled"} retorna um erro 400, portanto, omita totalmente o parâmetro thinking para executar sem pensamento.²³⁹ Especificamente no Claude Code: o Fable 5 oferece suporte a toda a escala de esforço (low/medium/high/xhigh/max, com high como padrão), assim como o Opus 5. O thinking não pode ser desativado no Fable 5 — o controle de thinking da sessão, a configuração alwaysThinkingEnabled e MAX_THINKING_TOKENS=0 não têm efeito; ele sempre raciocina de forma adaptativa. Uma superfície completa de configuração da família fable espelha os controles do Opus: ANTHROPIC_DEFAULT_FABLE_MODEL fixa o modelo para o qual o alias fable aponta (útil no Bedrock/Vertex/Foundry), DISABLE_PROMPT_CACHING_FABLE exclui o Fable do cache de prompts, e o fallback automático baseado em conteúdo é aplicado nos gateways empresariais. /model opus agora seleciona o Opus 5 (esforço high por padrão, /effort xhigh para as tarefas mais difíceis), e o padrão inicial segue o seu plano – Opus 5 nos planos premium, Sonnet 5 no Pro/Team Standard; escolha deliberadamente o nível Fable usando /model fable quando quiser o máximo absoluto – que, desde a v2.1.257, significa o Fable 5.1.^239197207220

Opus 4.7 (16 de abril de 2026): O modelo principal da geração anterior, ainda totalmente disponível. Janela de contexto de 1 milhão de tokens pelo preço padrão — sem cobrança adicional por contexto longo. Saída máxima de 128K, apenas thinking adaptativo (o extended thinking foi removido) e um novo nível de esforço xhigh, recomendado como ponto de partida para programação e cargas de trabalho agênticas.¹⁴⁵ Limite de conhecimento confiável: janeiro de 2026. Limite dos dados de treinamento: janeiro de 2026. ID do modelo: claude-opus-4-7. O preço é igual ao do Opus 4.6: US$ 5/US$ 25 por MTok, com gravação em cache de 5 minutos por US$ 6,25, gravação em cache de 1 hora por US$ 10 e leitura do cache por US$ 0,50 por MTok.¹⁴⁴ O Opus 4.7 resolve 3 vezes mais tarefas de produção no SWE-Bench do que o Opus 4.6, alcança 70% no CursorBench (contra 58% da versão 4.6) e aumenta em 13% a taxa de resolução no benchmark interno de programação com 93 tarefas do Anthropic.¹⁴⁴ Usa um novo tokenizer — espere contagens de tokens aproximadamente 1 a 1,35 vez maiores para o mesmo texto; aumente a margem de max_tokens e os gatilhos de compactação.¹⁴⁵ O recurso de visão aceita imagens de até 2.576 px/3,75 MP com coordenadas de pixel em escala 1:1.¹⁴⁵

Benchmarks de programação do Opus 4.7 (abril de 2026):¹⁵¹

Modelo padrão por plano (Claude Code):²⁰⁷

Mudanças incompatíveis no Messages API do Opus 4.7 (visíveis para quem faz a chamada):¹⁴⁵

• O budget_tokens do extended thinking foi removido. Use thinking: {type: "adaptive"}. O thinking adaptativo fica desativado por padrão; solicitações sem o campo thinking são executadas sem thinking.
• Definir temperature, top_p ou top_k com um valor diferente do padrão retorna HTTP 400. Omita esses parâmetros e oriente o modelo por meio do prompt.
• O conteúdo de thinking é omitido das respostas por padrão. Defina thinking.display: "summarized" para voltar a exibir o raciocínio (obrigatório se o seu produto transmite o thinking aos usuários).

Os orçamentos de tarefas (cabeçalho beta task-budgets-2026-03-13) permitem informar ao modelo uma meta de tokens para todo um loop agêntico por meio de output_config.task_budget; mínimo de 20K tokens.¹⁴⁵

Opus 4.6 (legado): Continua disponível como claude-opus-4-6, com contexto de 1 milhão e saída máxima de 128K. Considere migrar para o Opus 4.7 para obter melhor desempenho em programação agêntica. O Opus 4.6 foi lançado originalmente em 5 de fevereiro de 2026.⁷⁹¹⁴⁴ Desde a v2.1.117 (22 de abril de 2026), assinantes Pro e Max usam por padrão o esforço high no Opus 4.6 e no Sonnet 4.6 (antes era medium); o Opus 4.7 permanece em xhigh. Essa mudança restaurou a capacidade do modelo após a redução de esforço ocorrida entre 4 de março e 7 de abril, documentada no post-mortem de 23 de abril.¹⁵²¹⁵³

Sonnet 5 (30 de junho de 2026): O nível atual do Sonnet, apresentado como “a melhor combinação de velocidade e inteligência”. O Anthropic afirma que seu desempenho é próximo ao do Opus 4.8, mas com preços menores, e que ele representa uma melhoria substancial em relação ao Sonnet 4.6 em raciocínio agêntico, uso de ferramentas, programação e trabalho intelectual — ao mesmo tempo que apresenta uma taxa geral menor de comportamentos indesejáveis e uma capacidade de segurança cibernética muito inferior à dos modelos Opus (a contrapartida de segurança que permitiu seu lançamento sem restrições de controle de exportação). ID do modelo: claude-sonnet-5 (snapshot fixo sem data). Janela de contexto de 1 milhão de tokens, saída máxima de 128K (até 300K no Batches API com o cabeçalho beta output-300k-2026-03-24) e apenas thinking adaptativo. Limite de conhecimento confiável: janeiro de 2026. Preço: US$ 2/US$ 10 por MTok de entrada/saída, agora o preço padrão de tabela. No lançamento, o Anthropic anunciou US$ 2/US$ 10 como preço promocional até 31 de agosto de 2026, mas depois o manteve: a página de preços informa que o aumento previsto para 1º de setembro, para US$ 3/US$ 15, “não ocorrerá”, e a v2.1.243 atualizou o seletor /model e a skill claude-api incluída para exibir US$ 2/US$ 10 como preço de tabela, em vez de uma promoção por tempo limitado.²²⁹ Isso representa 60% menos que os US$ 5/US$ 25 do Opus 5. No Claude Code, o parâmetro effort usa high por padrão no Sonnet 5 (defina-o explicitamente para alterar). Selecione-o com /model sonnet (ou /model claude-sonnet-5).¹⁸⁰ A v2.1.197 (30 de junho de 2026) tornou o Sonnet 5 o modelo padrão no Claude Code para novas sessões naquela época; hoje, ele continua sendo o padrão no nível standard (Pro, Team Standard), enquanto os planos premium e o Anthropic API usam o Opus 5 por padrão – consulte a tabela de planos acima.¹⁸¹²⁰⁷

Sonnet 4.6 (17 de fevereiro de 2026, agora substituído pelo Sonnet 5): Modelo equilibrado; substituiu o Sonnet 4.5 como padrão no claude.ai e no Claude Cowork.⁹³ Mesmo preço do Sonnet 4.5 (US$ 3/US$ 15 por MTok). Desempenho aprimorado em buscas agênticas, consumindo menos tokens. Oferece suporte a extended thinking, thinking adaptativo e uma janela de contexto de 1 milhão de tokens (beta). Saída máxima de 64K (limite superior de 128K na v2.1.77).¹¹⁹ Limite de conhecimento: agosto de 2025 (confiável), janeiro de 2026 (dados de treinamento). ID do modelo: claude-sonnet-4-6.

Claude Mythos Preview (7 de abril de 2026): Um modelo de fronteira em versão prévia para pesquisa voltada à segurança cibernética defensiva, oferecido pelo Project Glasswing.¹³⁹ Disponível apenas por convite; não está disponível ao público em geral. O Anthropic descreve o Opus 4.7 como deliberadamente menos capaz que o Mythos em aspectos cibernéticos — uma contrapartida de segurança — e abriu um Cyber Verification Program em https://claude.com/form/cyber-use-case para pesquisadores legítimos de segurança que precisam de acesso ampliado.¹⁴⁶

Por que essas diferenças de preço importam: Uma sessão típica de programação consome de 50K a 200K tokens de entrada e de 10K a 50K tokens de saída. Com o Haiku, isso custa de US$ 0,10 a US$ 0,45 por sessão. Com o Opus, a mesma sessão custa de US$ 0,50 a US$ 2,25, cinco vezes mais. Reserve o Opus para problemas realmente difíceis.¹

Quando usar cada modelo

Haiku: Use para subagents que realizam exploração, buscas simples de arquivos e perguntas rápidas. Ele custa cerca de cinco vezes menos que o Opus e responde mais rápido. É perfeito para tarefas em segundo plano que não exigem raciocínio profundo. Sonnet: O modelo ideal para o desenvolvimento diário quando o custo importa — e o modelo padrão no plano padrão, Pro e Team Standard (contexto nativo de 1M, US$ 2/US$ 10 por MTok como preço de tabela padrão; o aumento planejado para 1º de setembro foi cancelado).^181229207 Lida com a maioria das tarefas de programação: implementar recursos, corrigir bugs, escrever testes e fazer revisão de código. Histórico: a v2.1.197 (30 de junho de 2026) foi descrita por muito tempo — inclusive aqui — como a versão que tornou o Sonnet 5 o padrão em todos os planos, mas a documentação de configuração de modelos, que detalha o comportamento por plano, indica que o padrão premium/API passou a ser o Opus 4.8 a partir da v2.1.154 e o Opus 5 a partir da v2.1.219; portanto, “todos os planos” referia-se, na verdade, ao plano padrão. O Sonnet 4.6 ocupou a função do Sonnet até junho de 2026.^93147207 Use o Sonnet quando precisar de tokens mais baratos, menor latência ou melhor custo-benefício para subagents.

Opus: O nível de raciocínio profundo — desde a v2.1.219, o alias opus seleciona o Claude Opus 5 (US$ 5/US$ 25 por MTok, contexto de 1M, com effort definido como high por padrão).¹⁹⁷ O parágrafo abaixo descreve o Opus 4.7 em seu lançamento, em 16 de abril de 2026, preservado como registro histórico.¹⁴⁴¹⁴⁷ Reserve o raciocínio de maior custo para situações em que ele compensa: decisões de arquitetura, depuração complexa, compreensão de sistemas complexos, análise de segurança e trabalho agentivo de longo prazo. O Opus 4.7 resolve 3 vezes mais tarefas de produção no SWE-Bench do que o Opus 4.6, alcança 70% no CursorBench (contra 58%) e aumenta a taxa de resolução em 13% em um benchmark interno de programação com 93 tarefas.¹⁴⁴ Claude Code usa xhigh como nível de esforço padrão no Opus 4.7, ajustável por meio de /effort (v2.1.111+).¹⁴⁶¹⁴⁷ O Auto Mode está disponível para assinantes Max no Opus 4.7 por meio do Anthropic API, sem exigir --enable-auto-mode; outros planos/provedores têm disponibilidade específica por plano e controlada pelo administrador.¹⁴⁶ Contexto de 1M com preços padrão — sem custo adicional para contexto longo. Mudanças de comportamento que vale a pena conhecer: o Opus 4.7 segue instruções de maneira mais literal, ajusta o tamanho das respostas à complexidade da tarefa, executa menos subagents por padrão e adota um tom mais direto, com menos frases voltadas à validação. Se seus prompts contêm estruturas para forçar mensagens intermediárias de progresso ou comportamentos de verificação dupla, experimente removê-las.¹⁴⁵

Opusplan: Um modo híbrido que usa o Opus para o planejamento (quando a qualidade do raciocínio é mais importante) e o Sonnet para a execução (quando a velocidade importa). Excelente para refatorações complexas nas quais você quer o melhor plano, mas não precisa do nível de raciocínio do Opus para cada edição individual.

Como alternar entre modelos

Durante a sessão:

> /model opus
> /model sonnet
> /model haiku

Na inicialização:

claude --model opus

Por variável de ambiente:

export ANTHROPIC_MODEL=opus

No settings.json:

{
  "model": "claude-sonnet-5"
}

Personalize o próprio seletor (modelPicker, v2.1.242+): um arquivo de configurações do usuário ou gerenciado pode listar os modelos oferecidos por /model, na ordem e com os rótulos que você definir, em vez de limitar o menu às opções integradas. Cada linha especifica um model (qualquer formato aceito por --model, incluindo IDs do Vertex e do Bedrock), com label e description opcionais; defina replaceBuiltInOptions como true para mostrar somente essas linhas, além de Default e do modelo atual da sessão. As configurações do projeto e locais são ignoradas para essa chave, e uma lista de permissões availableModels ainda filtra as linhas. Claude Code remove uma linha que não consegue atender, exibe em cinza uma linha que você ainda não pode selecionar junto com o motivo e retorna às opções integradas se nenhuma linha permanecer.²²⁸²²⁶

{
  "modelPicker": {
    "options": [
      { "model": "us.anthropic.claude-opus-4-8", "label": "Opus (production)" },
      {
        "model": "us.anthropic.claude-sonnet-4-6",
        "label": "Sonnet (production)",
        "description": "Day-to-day work"
      }
    ]
  }
}

Especificamente para subagents:

export CLAUDE_CODE_SUBAGENT_MODEL=haiku

Desde a v2.1.251, CLAUDE_CODE_SUBAGENT_MODEL define o modelo padrão dos subagents, em vez de substituir todas as escolhas: o model: da definição de um agente e um modelo especificado explicitamente em cada inicialização têm precedência sobre essa variável.²⁰⁶ Desde a v2.1.257, CLAUDE_CODE_SUBAGENT_MODEL_FORCE permite reativar o comportamento anterior: ela aplica CLAUDE_CODE_SUBAGENT_MODEL (ou o modelo da conversa principal, quando a variável não estiver definida) a todos os subagents, ignorando as escolhas feitas em cada inicialização e o model: das definições de agentes.²¹¹

Cadeia de modelos alternativos (v2.1.166+): a configuração fallbackModel permite definir até três modelos alternativos, testados em ordem quando o modelo principal está sobrecarregado ou indisponível. A flag --fallback-model (antes restrita à troca durante uma sessão) agora também se aplica a sessões interativas desde a inicialização.²⁴¹

{
  "model": "claude-opus-4-8",
  "fallbackModel": ["claude-sonnet-4-6", "claude-haiku-4-5"]
}

Quando o API retorna um erro inesperado que não permite nova tentativa, Claude Code agora também repete o turno uma vez com o modelo alternativo antes de apresentar a falha. Assim, um problema transitório no modelo principal causa uma degradação suave, em vez de descartar o turno.²⁴¹

Desde a v2.1.178, a compactação também respeita a cadeia de modelos alternativos — se o modelo principal estiver sobrecarregado ou indisponível durante a compactação, essa etapa recorre à cadeia configurada em fallbackModel/--fallback-model, em vez de causar a falha do turno. Em uma execução autônoma longa, isso elimina a situação em que uma compactação recuperável poderia encerrar a sessão devido a um erro transitório do modelo.¹⁷³

Contexto estendido

Para bases de código grandes ou sessões longas, ative o contexto de 1M tokens:

claude --model sonnet[1m]
claude --model opus[1m]           # Opus 4.7 with 1M context

Ou durante uma sessão:

> /model sonnet[1m]
> /model opus[1m]

O Opus 4.7, o Opus 4.6 e o Sonnet 4.6 incluem a janela de contexto completa de 1M tokens com preços padrão — sem custo adicional para contexto longo.¹⁴⁸ Uma solicitação de 900K tokens é cobrada pela mesma tarifa por token que uma solicitação de 9K tokens. Os descontos de cache de prompts e processamento em lote aplicam-se às tarifas padrão em toda a janela de contexto.

Nas assinaturas Max, Team e Enterprise, o Opus com contexto de 1M é incluído automaticamente — não é necessário usar o sufixo [1m] (ativado por padrão desde a v2.1.75, de 13 de março de 2026).¹¹⁷¹⁴⁷ No Pro, o contexto de 1M está disponível por meio de uso adicional. Usuários do API e de planos de pagamento conforme o uso têm acesso completo a 1M pelas tarifas padrão por token.¹⁴⁷

Para desativar as variantes de contexto de 1M no seletor de modelos, defina CLAUDE_CODE_DISABLE_1M_CONTEXT=1. Desde a v2.1.223, o alcance da variável mudou: ela limita a 200K, por meio da compactação automática, todos os modelos com uma janela nativa de 1M — não apenas uma lista fixa de variantes conhecidas — e um aviso aparece na inicialização quando a compactação automática não está realmente mantendo a sessão em 200K. Se você definir essa variável para ter custos previsíveis em uma família de modelos, ela passará a abranger novos modelos de 1M no dia em que forem lançados, em vez de deixar de funcionar silenciosamente. A mesma versão faz com que a compactação automática mantenha as sessões com IDs de modelos não reconhecidos dentro da janela de contexto presumida, em vez de permitir que ultrapassem esse limite; CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1 restaura o comportamento anterior para gateways que registram IDs personalizados com janelas reais maiores.²⁰⁰

Desde a v2.1.247, a janela padrão de compactação automática do Sonnet 5 corresponde ao contexto completo de 1M: sessões na janela de 1M agora são compactadas automaticamente em cerca de 967K tokens, em vez de aproximadamente 934K.²²³ A v2.1.260 estende a compactação automática próxima ao limite para o restante do nível de 1M: as sessões do Opus e do Fable agora também são compactadas pouco antes do limite de 1M tokens, e a compactação de recuperação em contextos muito grandes não atinge mais o tempo limite de 10 minutos.²¹²

Desde a v2.1.271, --resume preserva a janela [1m]: retomar uma sessão cuja família de modelos difere do modelo padrão configurado não remove mais o sufixo [1m].²¹⁶

A v2.1.273 corrige o medidor de contexto e a compactação automática, que contabilizavam os turnos de advisor-tool com aproximadamente o dobro do tamanho real no contexto — a compactação automática era acionada quando a janela real estava apenas pela metade.²¹⁷

Como verificar o modelo atual

> /status

O comando mostra o modelo atual, as informações da conta, as configurações aplicadas e outros dados da sessão.

Rótulos do seletor de modelos (v2.1.51+): o seletor /model agora mostra rótulos legíveis (por exemplo, “Sonnet 4.6”) em vez de IDs brutos para versões fixadas, além de sugestões de atualização quando há versões mais recentes disponíveis.⁹⁸ A v2.1.219 corrige a exibição da linha consolidada do Opus como simplesmente “Opus”, em vez de “Opus (contexto de 1M)”, e limita o destaque de novo lançamento apenas ao nome do modelo mais recente. Assim, o destaque indica o que realmente foi lançado, e não uma parte arbitrária da lista.¹⁹⁶

Fast Mode (v2.1.36+)

O Fast Mode fornece respostas significativamente mais rápidas usando o mesmo modelo; ele não muda para um modelo mais barato. Ative ou desative esse modo durante uma sessão com /fast.⁸⁶

> /fast            # Toggle fast mode on/off

Quais modelos (a partir da v2.1.219): o fast mode se aplica ao Claude Opus 5 e ao Claude Opus 4.8. A v2.1.219 removeu o Opus 4.7 do fast mode, e o recurso nunca esteve disponível no Sonnet, Haiku ou Fable. Ele continua sendo uma prévia de pesquisa apenas na Claude API (incluindo Claude Managed Agents) — não no Amazon Bedrock, Google Cloud, Microsoft Foundry ou Claude Platform on AWS. O acesso é restrito: entre em contato com seu gerente de conta ou inscreva-se na lista de espera.¹⁹⁶¹⁹⁸

Sessões remotas (v2.1.271): agora o fast mode também está disponível nas sessões Remote do Claude Code — sessões na nuvem e runners auto-hospedados. A configuração de fast mode do host é aplicada, ou você pode digitar /fast na própria sessão; ambas as opções funcionam somente quando sua organização permite o fast mode. A mesma versão corrige o /fast off: agora ele desativa o fast mode, em vez de responder “Fast mode unavailable” quando a organização desativou o fast mode.²¹⁶

Preços (fast mode do Opus 5 / Opus 4.8):¹⁹⁸

A armadilha do Opus 4.7 (v2.1.219). Modelos não compatíveis não se comportam da mesma forma. Uma solicitação ao claude-opus-4-7 com speed: "fast" agora retorna um erro — ela não volta silenciosamente para a velocidade padrão. O Opus 4.6 é a exceção que torna isso importante: ele aceita speed: "fast", mas é executado na velocidade padrão, cobra as tarifas padrão e informa usage.speed: "standard". Se o seu harness fixava a versão 4.7 e dependia de solicitações de fast mode voltarem silenciosamente ao modo padrão, agora elas falham por completo; migre a versão fixada para o Opus 5 ou 4.8.¹⁹⁸

Quando usar o fast mode: - Ao iterar rapidamente em pequenas alterações nas quais a latência é o gargalo - Ao gerar testes, boilerplate ou código repetitivo quando a velocidade importa mais que o custo - Ao executar sequencialmente uma lista de tarefas semelhantes

Quando NÃO usar o fast mode: - Em tarefas agênticas de longa duração (o custo ainda dobra durante toda a execução) - Em trabalhos de subagents em segundo plano (ninguém está esperando a saída) - Em sessões com orçamento limitado

O fast mode inclui a janela de contexto completa de 1M (v2.1.50+). O preço é um multiplicador fixo aplicado a todo o contexto, incluindo solicitações com mais de 200K tokens de entrada — sem cobrança adicional por contexto longo — e é acumulado com os multiplicadores de cache de prompts e residência de dados.⁹⁶¹⁹⁸

Notas operacionais. O fast mode tem seu próprio limite de uso, separado dos limites padrão do Opus; excedê-lo retorna um 429 com retry-after (os cabeçalhos de resposta anthropic-fast-*-tokens-* informam a capacidade restante). Alternar entre os modos rápido e padrão invalida o cache de prompts — solicitações com velocidades diferentes não compartilham prefixos em cache, portanto alternar /fast no meio da sessão causa uma perda de cache. O fast mode não está disponível com a API de Batch nem com um compromisso de Priority Tier.¹⁹⁸

Dica de especialista: o fast mode não funciona em conjunto com opusplan (o opusplan já combina Opus e Sonnet; o fast mode afeta apenas a etapa do Opus). Use-o quando a latência for mais importante que o custo e desative-o para trabalhos autônomos ou em lote. O /fast exige uso adicional; administradores Team/Enterprise talvez precisem ativá-lo primeiro (correção da v2.1.37). Desative-o por completo com CLAUDE_CODE_DISABLE_FAST_MODE=1. Desde a v2.1.218, o Claude Code avisa quando uma troca de modelo por /config model=<x> ou Remote Control altera o estado do fast mode, e a v2.1.219 corrigiu clientes Remote Control que mantinham um estado desatualizado do fast mode após uma troca, reconexão ou falha na verificação da organização.^86149195196

Controle de esforço (v2.1.111+, Opus 4.7)

O Opus 4.7 apresenta um novo seletor de esforço que ajusta o equilíbrio entre velocidade e inteligência. Use /effort durante uma sessão:

> /effort              # opens an interactive slider (arrow keys + Enter)
> /effort xhigh        # set directly

Salvo por modelo (v2.1.251+): agora o /effort salva seu nível de esforço padrão por modelo, para que cada modelo mantenha sua própria configuração quando você alternar — o hábito de usar xhigh no Opus não acompanha mais você ao mudar para o Haiku (CHANGELOG: “Changed /effort to save your default effort level per model, so each model keeps its own setting when you switch”). A exceção de max, que vale apenas para a sessão, continua sendo aplicada.²⁰⁶ A v2.1.257 aprimora os dois seletores: o /effort aceita s para uma escolha válida somente durante a sessão, seguindo a convenção do /model, e a flag --effort agora fica restrita à sessão — ela substitui a retenção do esforço padrão de um novo modelo apenas naquela sessão, em vez de alterá-la permanentemente (segundo a referência do CLI, ela “Overrides” o padrão “for this session and does not persist”).²¹¹²²¹

Auto Mode no Max (v2.1.111+)

O Auto Mode é o modo de permissão padrão nos planos Pro, Max e Team desde 14 de agosto de 2026 (anunciado em 7 de agosto) — consulte Modos de permissão para ver os números do estudo mencionados no anúncio, as formas de desativação e os planos/gateways nos quais ainda é necessário ativá-lo.²⁰³ Ele surgiu como um substituto mais seguro para --dangerously-skip-permissions, inicialmente disponível para assinantes Max no Opus 4.7 por meio da Anthropic API.¹⁴⁶ Um modelo classificador separado — Claude Sonnet 5 desde a v2.1.210 — analisa cada ação antes da execução, verificando se ela corresponde à intenção e se é segura.¹⁸⁷ Observação (v2.1.111+): a flag --enable-auto-mode foi removida; para iniciar uma sessão no Auto Mode, use --permission-mode auto. O Pro ficou excluído do Auto Mode durante a maior parte da existência do recurso — uma restrição encerrada pelo lançamento como padrão em 14 de agosto. Bedrock/Vertex/Foundry (v2.1.158+): o Auto Mode passou a poder ser ativado no Opus 4.7 e no Opus 4.8 nesses gateways com CLAUDE_CODE_ENABLE_AUTO_MODE=1.²⁴⁴ A partir da v2.1.207, a ativação não é mais necessária: o Auto Mode funciona no AWS Bedrock, Google Vertex AI e Microsoft Foundry sem CLAUDE_CODE_ENABLE_AUTO_MODE, e os administradores que quiserem desativá-lo podem usar a configuração gerenciada disableAutoMode. A mesma versão faz com que Bedrock, Vertex AI e Claude Platform on AWS usem o Claude Opus 4.8 como padrão e deixa de ler a configuração autoMode do arquivo .claude/settings.local.json de um repositório — configure as regras do Auto Mode em ~/.claude/settings.json.¹⁸⁵ Desde a v2.1.247, os prompts de permissão do Bash mostram uma dica sobre o Auto Mode, com a opção “Yes, and switch to auto mode” acionada por uma única tecla.²²³ Desde a v2.1.273, o Auto Mode no Bedrock, Vertex AI e Foundry usa o classificador local por padrão “for now” — defina CLAUDE_CODE_AUTO_MODE_SERVER=1 para usar o classificador do lado do servidor da plataforma. Essa é uma mudança de estado em um aspecto diferente da observação da v2.1.236 sobre os padrões do classificador: local ou do lado do servidor é um mecanismo que as versões anteriores nunca expuseram.²¹⁷ O que o Auto Mode não é: uma barreira de segurança. A maior parte do que vem a seguir reforça um classificador, e um classificador não é um sandbox. Em 26 de agosto de 2026, o pesquisador de prompt injection Johann Rehberger publicou uma cadeia funcional contra o Claude Code Opus 5 no auto mode, relatando uma taxa de sucesso de ataque de 60% a 80% em amostras pequenas — 3 de 5 execuções para a cadeia principal, que inicia um processo filho python3 isolado, e 3 de 5 e 4 de 5 execuções para duas configurações de uma variante cuja carga útil inicia uma instância headless de claude -p — com a ressalva do próprio pesquisador de que essas são amostras pequenas, não uma medição universal da taxa de sucesso do ataque.²¹⁰ Vale a pena entender a cadeia porque cada etapa, isoladamente, parece razoável: um servidor responde ao WebFetch com HTTP 415, então o agente recorre ao curl; o arquivo compactado baixado é extraído em uma pasta temporária contendo um manifesto, sete registros de dados codificados com Base85/zlib, um binário nativo e um struct.py; o Claude se recusa a executar o binário não confiável e então escreve seu próprio decodificador em Python e o executa dentro dessa pasta; o decodificador importa base64, base64 importa struct, e o Python encontra primeiro o struct.py do invasor. Nenhuma etapa da sequência contém uma instrução obviamente maliciosa — a injeção só precisa fazer com que o caminho comprometido pareça a maneira mais razoável de concluir a tarefa. Rehberger também relata que, em algumas execuções, o Claude tentou encerrar o processo de malware depois de perceber o comprometimento, mas o auto mode negou o comando de limpeza.²¹⁰ Ele contrapõe toda a descoberta a um número divulgado pelo Anthropic: uma avaliação encomendada a terceiros relatou uma taxa de sucesso de 0,00% para ataques de prompt injection contra o Opus 5 no auto mode, em 72 cenários executados dez vezes cada. A cadeia dele não fazia parte desse conjunto, o que explica como um resultado de benchmark de 0,00% e uma cadeia funcional de execução de código podem ser verdadeiros ao mesmo tempo; para ele, as duas mensagens não combinam.²¹⁰ Observe também a classificação: a atualização de Simon Willison de 30 de agosto concorda com a observação de um leitor de que isso não é uma prompt injection clássica — o modelo nunca lê nem segue as instruções do invasor —, mas um ataque de ambiente confuso.²¹⁰

O Anthropic encerrou o relatório como Informative — o comportamento estava funcionando conforme projetado —, e a posição que Rehberger relata ter recebido é aquela que deve orientar o projeto: o auto mode é um classificador baseado em melhor esforço, não uma garantia de segurança; cadeias de injeção deliberadas, montadas a partir de etapas individualmente benignas, ficam fora do que se espera que um classificador detecte; e a verdadeira barreira de contenção é o isolamento no nível do sistema operacional e o controle do tráfego de saída da rede.²¹⁰ Isso não contradiz as medidas de reforço abaixo — esse é o enquadramento correto para elas. O auto mode reduz o número de prompts aos quais você precisa responder e bloqueia uma lista documentada de operações destrutivas; ele não torna segura uma sessão que recebe entradas não confiáveis. Se uma sessão acessar conteúdo influenciado por invasores — páginas obtidas, arquivos compactados baixados, textos de issues, servidores MCP de terceiros —, os controles que realmente limitam os danos são aqueles externos ao modelo: um container ou uma VM, tráfego de saída da rede restrito, monitoramento do que o agente realmente faz e uma pasta pessoal que não contenha as chaves do SSH nem as credenciais de nuvem que você não gostaria de perder. A aprovação do auto mode não comprova que uma ação era segura.

Regras personalizadas sem perder os padrões (v2.1.118+). Nas versões anteriores, autoMode.allow, autoMode.soft_deny e autoMode.environment funcionavam como uma escolha excludente: ao definir sua própria lista, você perdia as regras de segurança integradas. O sentinela $defaults resolve isso — ele é expandido no próprio local para a lista integrada, exatamente na posição em que você o coloca, permitindo sobrepor regras personalizadas às regras padrão:¹⁵²

// .claude/settings.json
{
  "autoMode": {
    "allow": [
      "Bash(npm test:*)",        // your additions, prepended
      "$defaults",                // built-in allow list inserted here
      "Bash(git push:origin/feature/*)"  // appended after
    ]
  }
}

Edite as regras do classificador em /permissions (v2.1.246). Execute /permissions e abra a aba Auto mode, que só aparece quando o auto mode está disponível para a sessão. Ela lista as entradas de allow, soft_deny, hard_deny e environment de todos os escopos lidos pelo classificador e mostra se as regras integradas estão ativas em cada seção; entradas provenientes de configurações gerenciadas ou de --settings são somente leitura, e todas as alterações são salvas em ~/.claude/settings.json. Ao adicionar a primeira regra a uma seção, "$defaults" também é inserido para manter as regras integradas ativas. Você pode ativar ou desativar essas regras em cada seção (uma seção precisa ter pelo menos uma regra própria para que suas regras integradas possam ser desativadas), e environment é aberto como um único documento no seu editor.²²⁷²²⁵

Opção “Don’t ask again” (v2.1.118+). O prompt de ativação do Auto Mode agora oferece a opção “Don’t ask again”, permitindo que usuários frequentes dispensem a explicação sem precisar automatizar uma flag.¹⁵²

Proteções contra comandos destrutivos (v2.1.183). O auto mode agora bloqueia completamente um conjunto de comandos irreversíveis, a menos que você os solicite explicitamente durante a sessão: operações destrutivas do git (git reset --hard, git checkout -- ., git clean -fd, git stash drop) quando você não pediu para descartar o trabalho local; git commit --amend quando o commit não foi criado pelo agente na sessão atual; e desmontagem de infraestrutura (terraform destroy, pulumi destroy, cdk destroy), a menos que você tenha indicado a stack específica. Isso reduz o raio de impacto do classificador justamente nas operações que podem apagar trabalho silenciosamente ou derrubar ambientes — o agente ainda pode executá-las, mas somente quando você der uma instrução explícita, não por iniciativa própria.¹⁷⁴

Classifique todos os comandos de shell (v2.1.193). Por padrão, o classificador do auto mode analisa somente comandos de shell que correspondem a padrões de execução arbitrária de código; comandos rotineiros não passam por ele. A nova configuração autoMode.classifyAllShell encaminha todos os comandos Bash/PowerShell ao classificador, trocando um pouco de latência por uma camada de segurança mais rigorosa quando você quiser que todas as chamadas de shell sejam verificadas. A mesma versão também exibe os motivos das recusas do auto mode na transcrição, na notificação de recusa e nas recusas recentes de /permissions, para que um comando bloqueado agora explique por que foi impedido.¹⁷⁹

Mais três regras de reforço (v2.1.205). O auto mode agora bloqueia alterações nos arquivos de transcrição da sessão — o próprio registro de auditoria fica fora do alcance do agente; ele pede confirmação antes de executar rm -rf em uma variável que não consegue resolver pelo contexto — evitando a classe de acidentes com rm -rf $DIR quando $DIR é desconhecido; e as notificações de tarefas em segundo plano agora declaram explicitamente que não houve nenhuma interação humana, impedindo que uma linha falsa de “usuário aprovou” dentro de uma transcrição seja disfarçada como uma aprovação válida e executável.¹⁸³ A terceira é uma defesa contra prompt injection que vale a pena assimilar: a aprovação precisa chegar pelo canal de aprovação, e o harness agora deixa essa premissa explícita.

A substituição de comandos não consegue esconder uma catástrofe (v2.1.208). Remoções catastróficas como rm -rf ~ agora exibem um prompt mesmo quando estão escondidas dentro de $(...), backticks ou substituição de processo (<(...)) — e o prompt é acionado até mesmo em --dangerously-skip-permissions e no auto mode. Encapsular um comando destrutivo em uma substituição não permite mais que ele passe despercebido pela camada de segurança.¹⁸⁶

Redefina o estado do auto mode: claude auto-mode reset (v2.1.212). Um novo subcomando redefine o estado do auto mode pelo terminal; use --yes para ignorar o prompt de confirmação:¹⁸⁹

claude auto-mode reset          # Confirmation prompt
claude auto-mode reset --yes    # Skip confirmation (scripts)

Menos caixas de diálogo, o mesmo rigor (v2.1.218). Três verificações que antes interrompiam o auto mode com uma caixa de diálogo de permissão — rm perigoso, & em segundo plano e caminhos suspeitos do Windows — deixaram de fazer isso; agora, o classificador do auto mode decide sobre elas, mantendo a análise de segurança sem colocar você no circuito a cada ocorrência. A mesma versão estende isso ao plan mode com auto: comandos Bash que o analisador estático não consegue comprovar como somente leitura deixam de exibir prompts — o classificador decide sobre eles em vez de recorrer a uma caixa de diálogo.¹⁹⁵

Regra contra fuga da contenção (v2.1.257). A lista de ações que o classificador nunca aprova automaticamente ganhou uma regra chamada “Containment Escape”: obtenção de credenciais em metadados de nuvem, evasão das restrições de tráfego de saída da rede e acesso entre tenants deixam de receber aprovação automática, a menos que o ambiente os marque como esperados. Interprete isso segundo o enquadramento estabelecido pela ressalva acima: é mais um reforço contínuo do classificador — outra classe documentada de recusa, não uma mudança na natureza do auto mode.²¹¹ Prompt único para leituras fora dos diretórios de trabalho (v2.1.257). Agora, o modo automático pergunta uma vez antes da primeira leitura de arquivo da sessão fora dos diretórios de trabalho. A configuração complementar permissions.blockReadsOutsideWorkingDirectories transforma o prompt em uma recusa — essas leituras são bloqueadas por completo.²¹¹ A v2.1.273 estende os dois comportamentos ao que o verificador não consegue enxergar: um comando Bash que ele não consegue analisar por completo gera um prompt em vez de ignorar a verificação, e um diretório de memória escolhido pelas configurações de um repositório deixa de ser carregado no prompt, recuperado, indexado ou usado pela extração de memória quando a configuração de bloqueio está ativada.²¹⁷

URLs de renderizadores de diagramas contam como uploads (v2.1.261). Um link que incorpora conteúdo à URL de um renderizador público de diagramas — como no estilo do mermaid.live, com os dados codificados na própria URL — deixa de ser aprovado automaticamente, a menos que você tenha solicitado isso. O classificador trata esse tipo de link como upload: os dados incorporados são transportados na própria URL, onde os scripts do site de renderização podem lê-los assim que a página é aberta — links no estilo do mermaid.live carregam o conteúdo no fragmento da URL, que o navegador entrega ao JavaScript da página em vez de enviá-lo com a solicitação de rede. Aplica-se a mesma perspectiva da ressalva acima: trata-se do fechamento de mais um canal de exfiltração em um classificador em processo de reforço, não de um novo limite.²¹⁴

O shell ! inline sai do classificador; as devoluções dos subagents passam a fazer parte dele (v2.1.271). São duas mudanças de funcionamento, não novas classes de negação. Agora, os comandos de shell ! inline de uma skill ou de um slash command seguem as regras de permissão do modo padrão, em vez do classificador — um comando não abrangido por nenhuma regra é executado como uma chamada de ferramenta sujeita a revisão. Além disso, agora um subagent retorna o resultado ao chamador por meio de uma chamada dedicada de devolução, revisada pelo classificador de segurança, em vez de ter sua última mensagem revisada após o ocorrido — o ponto de verificação passou de depois da entrega para a própria entrega.²¹⁶

Novos comandos nas versões v2.1.105–v2.1.114¹⁴⁶¹⁵⁰

Notificações push (v2.1.110+)

Quando o Remote Control está configurado com a opção “Push when Claude decides” ativada, agora o Claude pode enviar notificações push para dispositivos móveis quando considerar apropriado, por meio de uma nova ferramenta de notificação push. Funciona em conjunto com a interface existente do Remote Control para dispositivos móveis/web.¹⁴⁶ Agora, /context, /exit e /reload-plugins também funcionam em clientes Remote Control.

Ferramenta Windows PowerShell (v2.1.111+, lançamento gradual)

O Claude Code está lançando gradualmente uma ferramenta nativa para Windows PowerShell. No Linux/macOS, ative-a com CLAUDE_CODE_USE_POWERSHELL_TOOL=1 (requer pwsh no PATH). No Windows, a mesma variável controla a adesão ou não ao recurso durante o lançamento gradual.¹⁴⁶

Aprovação automática pelo modo de permissão (v2.1.119+). Agora, comandos da ferramenta PowerShell podem receber aprovação automática no modo de permissão da mesma forma que comandos Bash. Regras de permissão como PowerShell(Get-*:*) e a sintaxe de padrões existente agora dispensam o prompt em operações somente leitura, oferecendo a mesma praticidade operacional que as equipes já têm no Linux/macOS.¹⁵²

Redução de permissões: Bash somente leitura (v2.1.111+)

Padrões Bash somente leitura com argumentos glob (por exemplo, ls *.ts, cat src/*.md) e comandos que começam com cd <project-dir> && deixam de acionar um prompt de permissão.¹⁴⁶ Em conjunto com /less-permission-prompts, isso deve reduzir significativamente as interrupções nos fluxos de trabalho cotidianos.

Rastreamento distribuído (v2.1.110+)

Agora, sessões do SDK e sessões headless leem TRACEPARENT e TRACESTATE do ambiente, vinculando execuções do Claude Code a rastreamentos distribuídos. Use em conjunto com OTEL_LOG_RAW_API_BODIES=1 (v2.1.111+) para emitir os corpos completos das solicitações/respostas do API como eventos de log do OpenTelemetry para depuração.¹⁴⁶

Distribuição de binários nativos (v2.1.113+)¹⁵⁰

A v2.1.113 muda a forma como o CLI é iniciado: agora, claude executa um binário nativo do Claude Code por meio de uma dependência opcional específica de cada plataforma, em vez de executar o JavaScript incluído no pacote. Os comandos de instalação e atualização continuam os mesmos, e as equipes não precisam alterar os scripts de implantação.

Atalhos do editor de prompts (v2.1.113+)¹⁵⁰

O editor de prompts ganha navegação no estilo readline em entradas de várias linhas, além de rolagem da área de visualização em tela cheia:

Tempo limite de inatividade dos subagents (v2.1.113+)¹⁵⁰

Agora, subagents que ficam paralisados durante o streaming falham com um erro claro após 10 minutos, em vez de ficarem travados silenciosamente. Use em conjunto com CLAUDE_STREAM_IDLE_TIMEOUT_MS (v2.1.84+) para ampliar a cobertura contra processos travados em APIs com streaming.

Correção de estabilidade da v2.1.114¹⁵⁰

A v2.1.114 (18 de abril de 2026) inclui uma única correção: a caixa de diálogo de permissão podia travar quando um integrante de uma equipe de agentes solicitava permissão para usar uma ferramenta. Atualize se você usa Agent Teams.

Marcação de conteúdo: marcas d’água em texto e metadados C2PA em arquivos (agosto de 2026)

A Anthropic anunciou a marcação legível por máquinas para conteúdo gerado pelo Claude, motivada pelo Artigo 50 da Lei de IA da União Europeia (aplicável a partir de 2 de agosto de 2026 para sistemas de IA recém-lançados). O sistema tem dois componentes: uma marca d’água estatística invisível no texto gerado e metadados de procedência assinados — seguindo o padrão aberto C2PA — em arquivos gerados, como .svg, .png e .jpg.²³⁰²⁰⁴ O detalhe que as manchetes deixam de lado: os dois componentes seguem o mesmo cronograma dos modelos. Segundo a página de suporte, “os modelos do Claude lançados em 2 de agosto de 2026 ou depois dessa data oferecerão suporte à marcação legível por máquinas desde o lançamento” — os modelos lançados antes dessa data, o que inclui toda a linha atual (Fable 5, Opus 5, Sonnet 5, Haiku 4.5), estão sujeitos ao período de transição da legislação da UE, e a Anthropic está “trabalhando para também adicionar suporte à marcação nesses modelos”.²⁰⁴ Nada do que você gera hoje por meio do Claude Code contém uma marca, seja em texto ou em arquivos; os resultados de modelos futuros conterão essa marca em todas as interfaces — Claude Platform (API), claude.ai, Claude Code, Claude Cowork, Claude Tag e os gateways de nuvem — pois a marcação ocorre no nível do modelo. Vale explicitar um desdobramento porque uma discussão viral afirmou o contrário: qualquer mudança de estilo ou comportamento que você perceba em um modelo atual não pode ser causada pela marca d’água — ela não está ativa em nenhum modelo atual.

Como funciona: é uma variante do SynthID-Text, do Google DeepMind. A marca d’água altera “a fonte da aleatoriedade usada para escolher entre palavras” quando o Claude escolhe entre opções semanticamente equivalentes — nenhum caractere é adicionado, não há pós-processamento e, segundo os testes internos da Anthropic, não há “nenhum impacto da marca d’água no conteúdo, no nível de criatividade ou na legibilidade”.²³⁰ O que os usuários do Claude Code vão querer saber: o código contém uma marca-d’água discreta. Um código funcional deixa pouco espaço para escolhas arbitrárias, então a marca se concentra onde há liberdade — comentários, nomenclatura — com o que o Anthropic chama de “um efeito insignificante sobre o código efetivamente produzido”.²³⁰ A durabilidade é probabilística e varia de acordo com o componente: em textos, pequenas edições “provavelmente não removerão a marca-d’água por completo”, uma reescrita completa a removerá, e uma tradução produzida pelo Claude terá sua própria marca nova; nos metadados de arquivos, a conversão de formato, o salvamento em outro arquivo e as capturas de tela podem remover a assinatura C2PA.²⁰⁴ Está previsto um API de detecção; um resultado positivo comprova que “o Claude provavelmente esteve envolvido com o conteúdo em algum momento” e não consegue distinguir explicitamente entre “o Claude escreveu isto” e “o Claude fez uma edição substancial disto” — e, segundo a página de suporte, a ausência da marca também não comprova nada. Não há menção à opção de desativá-la para nenhum nível de cliente.²³⁰²⁰⁴

Quanto custa o Claude Code?

Entender e controlar os custos é essencial para usar o Claude Code de forma sustentável. Consulte também Seleção de modelos para conhecer os recursos de cada modelo e Estruturas de decisão para escolher o modelo certo para cada tarefa.

Visualização dos custos

> /cost

Saída:

Total cost:            $0.55
Total duration (API):  6m 19.7s
Total duration (wall): 6h 33m 10.2s
Total code changes:    247 lines added, 89 lines removed

Os usuários de planos por assinatura veem no /cost um detalhamento por modelo e por acertos de cache, mostrando exatamente quais modelos consumiram tokens e quanto foi fornecido pelo cache (v2.1.92+).¹³⁷

Tarifas contratadas em vez do preço de tabela (modelPricing, gerenciado, v2.1.243+): organizações com tarifas negociadas por modelo ou um multiplicador de desconto podem implantá-los como a configuração gerenciada modelPricing; o /cost, a linha de status e os valores de custo da telemetria passam a usar essas tarifas em vez do preço de tabela, para que os números exibidos aos desenvolvedores correspondam ao que a organização paga.²²⁸ Desde a v2.1.271, o multiplicador também pode ser maior que 1 — até 10 — para organizações que cobram das equipes internas tarifas com acréscimo.²¹⁶

Linha de cache de prompts por sessão (v2.1.251+): o /cost adiciona uma linha de cache de prompts da sessão — taxa de acertos, falhas, tokens armazenados novamente em cache e se o cache está aquecido ou frio — com um objeto prompt_cache correspondente para scripts da linha de status. O objeto aparece após a primeira resposta do API na conversa principal, não contabiliza solicitações de subagents e é calculado com base nas contagens de tokens de cache presentes nas respostas do API, por isso funciona com qualquer provedor. O /usage mostra as mesmas estatísticas na linha Prompt cache (main).²⁰⁶²⁰⁹ Desde a v2.1.260, a linha do /cost e o objeto prompt_cache da linha de status também indicam uma causa provável para as falhas de cache — por exemplo, as definições das ferramentas ou o prompt do sistema mudaram, ou a sessão ficou inativa por mais tempo que o TTL do cache.²¹²

O tráfego de agentes não invalida mais o próprio prefixo de cache (v2.1.265): duas correções eliminam vazamentos do cache de prompts em trabalhos delegados. Retomar um subagent iniciado em primeiro plano não altera mais sua lista de ferramentas nem o prefixo do prompt do sistema, e os agentes de equipe e subagents retomados não retiram mais o contexto do hook SubagentStart e as skills pré-carregadas do prefixo do prompt nos turnos posteriores. Os dois bugs impediam a reutilização do cache de prompts — o prefixo mudava, então tudo depois dele era reenviado como entrada sem cache — justamente nas sessões longas com agentes em que a economia do cache mais importa (o mesmo modo de falha corrigido pela v2.1.260 nos turnos com chamadas de ferramentas do Fable 5.1).²¹⁵

O conjunto de correções de estabilidade do cache da v2.1.267: uma versão, cerca de dez correções, todas para o mesmo modo de falha — algo reescrevia o prefixo do prompt no meio da conversa, e tudo depois dele era reenviado como entrada sem cache. Sessões retomadas não reescrevem mais listas de ferramentas, não renderizam novamente as descrições das ferramentas nem reescrevem anúncios anteriores de ferramentas do MCP antes que seus conectores se reconectem; trocar de modelo com /model não reenvia mais todas as definições de ferramentas (o texto de atribuição de commits e PRs agora chega como uma nota na conversa, atualizada quando o modelo muda); subagents e sessões iniciados com --system-prompt ou --append-system-prompt registram o prompt do sistema e as definições das ferramentas uma única vez; e ferramentas do MCP e de plugins adicionadas no meio da sessão chegam às sessões sem ToolSearch como definições adiadas, em vez de uma lista de ferramentas reescrita. Esse conjunto amplia as correções das versões v2.1.260 e v2.1.265 para retomadas, trocas de modelo e reconexões do MCP.²¹⁶

A v2.1.273 mantém a conversa em andamento: /login, /upgrade e /extra-usage descartavam raciocínios anteriores da conversa, o que forçava uma reescrita completa do cache de prompts na solicitação seguinte.²¹⁷

Planos por assinatura

Limites de uso (agosto de 2025): a Anthropic introduziu limites semanais de uso para assinantes pagos. Assinantes do Max podem comprar uso adicional além do limite pelas tarifas padrão do API.¹⁴

Duplicação dos limites de uso (6 de maio de 2026): durante o evento Code with Claude SF, a Anthropic duplicou os limites de cinco horas do Claude Code nos planos Pro, Max, Team e Enterprise por assento, removeu a redução em horários de pico das contas Pro e Max e aumentou “consideravelmente” os limites de uso do API para os modelos Claude Opus. A garantia de capacidade vem do acordo com o SpaceX Colossus 1: “mais de 300 megawatts de nova capacidade (mais de 220.000 GPUs) dentro de um mês”.¹⁵⁷

Limites semanais a partir de 14 de setembro de 2026 (anunciados em 29 de agosto): o aumento temporário de 50% nos limites semanais, em vigor desde o reforço de maio, termina em 14 de setembro e será substituído por um aumento permanente de 25% em relação à base anterior ao reforço nos planos Pro, Max, Team e Enterprise por assento. Segundo os próprios cálculos da Anthropic sobre a mudança: “Em comparação com hoje, isso representa uma redução de 17% nos limites semanais do Claude Code”. Se seu limite semanal atual é de 150 unidades, ele passará a 125 em 14 de setembro. Os limites de cinco horas não fazem parte deste anúncio; a duplicação de maio continua válida. Planeje-se desde já para o limite menor caso você execute sessões longas sem supervisão: a opção de continuar automaticamente após a redefinição do limite (v2.1.234) e o /usage são os dois controles que importam.²¹³

Preços por token do API (abril de 2026)¹¹⁴⁴

Para usuários cobrados pelo API, os preços por milhão de tokens são:

Preço do contexto de 1M (abril de 2026): Opus 4.7, Opus 4.6, Sonnet 4.6 e Mythos Preview incluem 1M pelas tarifas padrão por MTok — sem adicional por contexto longo.¹⁴⁸ Essa consolidação é recente; orientações anteriores que indicavam que o Opus 4.6 ou o Sonnet 4.6 custavam 2 vezes mais na entrada e 1,5 vez mais na saída acima de 200K tokens de entrada não estão mais atualizadas. O Opus 4.5 legado e os modelos anteriores mantêm suas estruturas de preços originais.

Preços por residência de dados: especificar inferência apenas nos EUA com inference_geo adiciona um multiplicador de 1,1 a todos os preços por token, incluindo leituras e gravações em cache (modelos Opus 4.6+).¹⁴⁸

O cache de prompts reduz significativamente os custos de entradas repetidas: as gravações em cache custam 1,25 vez o valor-base (cache de 5 minutos) ou 2 vezes (cache de 1 hora), mas as leituras do cache custam apenas 0,1 vez esse valor, uma economia de 90% — e somente no Claude Fable 5.1 e no Mythos 5.1, as leituras caem para 0,025 vez (US$ 0,25/MTok no Fable 5.1), uma economia de 97,5%.²¹⁹ Para sistemas RAG e assistentes de código com contexto repetido, o cache pode reduzir os custos em 88% a 95%.

O API em lote oferece 50% de desconto, com prazo de até 24 horas, para tarefas não urgentes, como suítes de testes executadas durante a noite.

Política sobre várias contas⁵²

Você pode ter várias contas do Claude? Sim, para casos de uso legítimos. A Anthropic permite explicitamente várias contas quando elas atendem a finalidades distintas.

O que é permitido:

Limites técnicos: - Até 3 contas podem ser verificadas com o mesmo número de telefone - Várias assinaturas pagas no mesmo IP ou na mesma rede são explicitamente compatíveis - As contas são totalmente separadas; chats e projetos não podem ser transferidos entre elas

O que é proibido (de acordo com a Política de Uso): - Criar contas para evitar bloqueios após ter sido banido - Coordenar atividades maliciosas entre contas para evitar a detecção - Usar várias contas para contornar limites de uso ou créditos do plano gratuito

Observação prática: em janeiro de 2026, o usuário avançado Jeffrey Emanuel (@doodlestein) teve suas 22 contas Max sinalizadas automaticamente e banidas temporariamente. Thariq (@trq212), funcionário da Anthropic, resolveu o problema em até 4 horas após confirmar que o uso era legítimo. Se você usa o Claude Code intensivamente em projetos profissionais e pessoais distribuídos entre várias contas, é exatamente para isso que o serviço foi projetado, mas não tente manipular o sistema.

Em caso de dúvida: entre em contato com o suporte da Anthropic para confirmar sua configuração específica por escrito.

Fatores de custo

Exemplos de custos reais

Dica para economizar: usar Haiku nos subagents de exploração e Sonnet na implementação costuma reduzir os custos entre 40% e 50% em comparação com o uso do Sonnet para tudo.

Gestão de custos da equipe

TPM/RPM recomendados por tamanho da equipe:

Taxas ocultas de ferramentas

Além do preço por token, algumas ferramentas geram cobranças separadas:⁹

Esses custos se acumulam em loops de agentes. Um ciclo de depuração com 100 iterações usando Bash consome cerca de 24.500 tokens adicionais de entrada apenas em sobrecarga.

Estratégias para economizar

1. Use Haiku nos subagents: a maior parte da exploração não precisa do Sonnet
2. Ative o cache de prompts: ele é ativado por padrão, mas verifique se não foi desativado
3. Defina o máximo de turnos: claude --max-turns 5 evita conversas descontroladas
4. Defina um limite em dólares: claude --max-budget-usd 5 interrompe a sessão quando ela atinge o teto de gastos. Desde a v2.1.217, o limite também controla os subagents em segundo plano — quando ele é atingido, novos subagents não podem ser iniciados e os agentes em segundo plano que estiverem em execução são interrompidos (antes, os agentes em segundo plano escapavam do orçamento)¹⁹⁴
5. Use o plan mode para exploração: sem execução = sem operações caras acidentais
6. Faça a compactação de forma proativa: contexto menor = menos tokens
7. Limite a saída: export CLAUDE_CODE_MAX_OUTPUT_TOKENS=2000
8. Use o API em lote para trabalhos não urgentes: 50% de desconto nos tokens de entrada e saída
9. Analise os gastos de um projeto com o API do Claude: /claude-api cost-optimize (v2.1.247+) analisa os gastos de um projeto existente com o API do Claude e aborda os fatores de custo (cache, higiene de tokens, processamento em lote, esforço, escolha do modelo) aplicando uma alteração mensurável de cada vez — para os aplicativos que você cria com o API, não para a própria sessão do Claude Code²²³

Monitoramento do uso

• Console do Claude: platform.claude.com (requer a função Admin ou Billing)
• Limites do workspace: defina limites de gastos por workspace
• Bedrock/Vertex: use o monitoramento nativo de custos da nuvem
• LiteLLM: para acompanhamento detalhado por usuário com provedores terceirizados

Consumo de tokens em segundo plano

Algumas operações consomem tokens em segundo plano: - Resumo da conversa para /resume - Comandos /cost e /status - Compactação automática

Normalmente, menos de US$ 0,04 por sessão.

API de análise do Claude Code (Team/Enterprise)⁴⁶

Acesse programaticamente as análises de uso e as métricas de produtividade do Claude Code da sua organização por meio do API de administração.

Endpoint: GET /v1/organizations/usage_report/claude_code

Requisitos: - Chave de administração do API (sk-ant-admin...) - Plano Team ou Enterprise - Função Admin, Billing ou Developer

Métricas disponíveis:

Exemplo de solicitação:

curl "https://api.anthropic.com/v1/organizations/usage_report/claude_code?starting_at=2026-01-15" \
  -H "x-api-key: sk-ant-admin..." \
  -H "anthropic-version: 2023-06-01"

Casos de uso: - Análise da produtividade dos desenvolvedores (sessões, commits, PRs) - Métricas de uso das ferramentas (taxas de aceitação/rejeição de Edit, Write etc.) - Acompanhamento e alocação de custos entre equipes - Justificativa de ROI para ferramentas de programação com IA

Observação: os dados aparecem até 1 hora após a conclusão da atividade. Para garantir a consistência, somente dados com mais de 1 hora são incluídos nas respostas.

Estruturas de decisão

Conhecer os recursos disponíveis não basta. Você precisa saber quando usar cada um. Estas árvores de decisão transformam conhecimento em ação.

Qual modelo devo usar?

START → Is the task simple? (file search, quick question, formatting)
         │
         ├── YES → Use Haiku
         │         Cost: ~$0.03/task
         │         Speed: Fastest
         │
         └── NO → Does it require deep reasoning?
                  (architecture, complex debugging, security analysis)
                  │
                  ├── YES → Use Opus 5 (high effort default; /effort xhigh for harder)
                  │         Cost: ~$2.00/task
                  │         Quality: Highest (1M context at standard price, adaptive reasoning)
                  │
                  └── NO → Use Sonnet
                           Cost: ~$0.75/task
                           Balance: Best overall when cost matters

Regra geral: o padrão acompanha seu plano — Opus 5 nos planos premium e no Anthropic API, Sonnet 5 no Pro e no Team Standard; /model opus promove uma sessão do Sonnet para o Opus 5.^181197207 Use Haiku para subagents. Mude para Opus quando a resposta do Sonnet parecer superficial. Com agent teams (v2.1.32+), o Opus pode coordenar vários agentes trabalhando em paralelo em diferentes subtarefas.⁷⁹

Comando, skill, subagent ou agent team?

Do you want explicit control over when it runs?
│
├── YES → Use Slash Command
│         Example: /deploy, /test, /security-review
│         You invoke it. You control timing.
│
└── NO → Should the expertise apply automatically based on context?
         │
         ├── YES → Use Skill
         │         Example: Security patterns, domain rules, code standards
         │         Claude recognizes context and applies expertise.
         │
         └── NO → Does the work need isolated context?
                  │
                  ├── YES → Is there one subtask or many parallel subtasks?
                  │         │
                  │         ├── ONE → Use Subagent (Task tool)
                  │         │         Example: Deep exploration, parallel analysis
                  │         │         Prevents context bloat in main conversation.
                  │         │
                  │         └── MANY → Use Agent Team (v2.1.32+)
                  │                   Example: 5 agents reviewing different modules simultaneously
                  │                   Opus coordinates; each agent works independently.
                  │
                  └── NO → Just prompt directly
                           Not everything needs abstraction.

Hook ou prompt?

Must the action ALWAYS happen, regardless of Claude's judgment?
│
├── YES → Use Hook (deterministic)
│         Examples:
│         - Format code after every edit
│         - Log all bash commands
│         - Block access to .env files
│         Claude cannot skip, forget, or decide otherwise.
│
└── NO → Use Prompt (probabilistic)
         Examples:
         - "Consider adding tests"
         - "Think about edge cases"
         - "Review for security if relevant"
         Claude decides based on context.

Quando usar extended thinking?

Is this a genuinely hard problem?
│
├── Architectural decision with many tradeoffs → YES, use thinking
├── Complex debugging with unclear root cause → YES, use thinking
├── Security analysis requiring careful reasoning → YES, use thinking
├── Understanding unfamiliar codebase → YES, use thinking
│
├── Routine bug fix → NO, skip thinking
├── Simple refactoring → NO, skip thinking
├── Code formatting → NO, skip thinking
└── Quick questions → NO, skip thinking

Ative ou desative com Alt+T durante a sessão. Orçamentos maiores de raciocínio custam mais; comece com o mínimo e aumente apenas se as respostas parecerem apressadas.

Adaptive thinking do Opus 4.6: o Opus 4.6 ajusta automaticamente a profundidade do raciocínio de acordo com a complexidade do problema. Para a maioria das tarefas, não é necessário controlar explicitamente o orçamento de raciocínio — o Opus aprofunda a análise em problemas difíceis e mantém a agilidade nos mais simples. Alternar o raciocínio manualmente é mais útil com o Sonnet quando você quer forçar uma análise mais profunda.

Qual interface de execução usar?

Where should this work happen?
│
├── Requires YOUR local files and tools
│   │
│   ├── Interactive, iterative work → Main REPL session
│   ├── One-shot scripted task → claude -p "prompt" (print mode)
│   ├── CI/CD automation → claude -p --json (non-interactive + structured output)
│   └── Parallel isolated tasks → Subagents via Task tool
│
├── Requires SOMEONE ELSE'S environment
│   │
│   └── Remote codebase or server → Background agent (cloud)
│
└── Doesn't require any environment
    │
    ├── Research or analysis → Subagent with Explore type
    └── Web content extraction → WebFetch / WebSearch tools

Agent teams, subagents ou sessões paralelas

Do you need multiple agents working on related subtasks?
│
├── YES → Are the subtasks independent (no shared state)?
│         │
│         ├── YES → Can they share the same codebase?
│         │         │
│         │         ├── YES → Use Agent Team (v2.1.32+)
│         │         │         Opus coordinates. Agents share repo access.
│         │         │         Example: "Review auth, API, and DB modules in parallel"
│         │         │
│         │         └── NO → Use Parallel Sessions (separate terminals)
│         │                  Each has its own working directory.
│         │                  Example: "Fix repo-A and repo-B simultaneously"
│         │
│         └── NO → Use Sequential Subagents
│                  Results from one feed into the next.
│                  Example: "Explore → Plan → Implement"
│
└── NO → Use Single Subagent or Main REPL

Qual tipo de hook usar?

What kind of automation do you need?
│
├── Run a shell command at a specific event?
│   │
│   └── Use Command Hook
│       Trigger: PreToolUse, PostToolUse, Notification, Stop, SubagentStop
│       Example: "Run prettier after every file edit"
│       Config: hooks.PostToolUse[].command = "prettier --write $FILE"
│
├── Modify Claude's system prompt based on context?
│   │
│   └── Use Prompt Hook (v2.1.35+)
│       Trigger: Same events
│       Example: "Inject project rules when working in /src/auth/"
│       Config: hooks.PreToolUse[].prompt = "When editing auth files..."
│
└── Have Claude make a judgment call before proceeding?
    │
    └── Use Agent Hook (v2.1.35+)
        Trigger: Same events
        Example: "Evaluate if this bash command is safe before running"
        Config: hooks.PreToolUse[].agent = { prompt: "Is this safe?" }

Quando usar /fast?

Is response speed more important than depth right now?
│
├── YES → Use /fast   (Opus 5 or Opus 4.8 only, v2.1.219+)
│         Same model, ~2.5× output speed at 2× price
│         Good for: quick questions, simple edits, code explanations,
│                   file searches, formatting tasks
│
└── NO → Stay in normal mode
         Good for: architecture decisions, complex debugging,
                   security reviews, multi-file refactors,
                   anything requiring deep reasoning

/fast ativa ou desativa o modo rápido na sessão atual. Ele usa o mesmo modelo — Opus 5 ou Opus 4.8, os únicos dois modelos compatíveis com o modo rápido desde a v2.1.219 — com velocidade de saída otimizada. Ele NÃO muda para um modelo mais barato e, a US$ 10/US$ 50 por MTok, também não custa menos.¹⁹⁶¹⁹⁸

Como funciona o sistema de permissões?

O sistema de permissões do Claude Code oferece controle detalhado sobre quais operações podem ser executadas. Entendê-lo é essencial tanto para a segurança quanto para a eficiência do fluxo de trabalho. Consulte também Implantação empresarial para conhecer as configurações gerenciadas que aplicam permissões em toda a organização.

Níveis de permissão

Ferramentas somente leitura (aprovadas automaticamente): - Read - Lê o conteúdo de arquivos - Glob - Localiza arquivos por padrão - Grep - Pesquisa o conteúdo de arquivos - WebSearch - Pesquisa na web - LSP - Inteligência de código (ir para a definição, localizar referências, documentação ao passar o cursor)¹⁸

Recursos da ferramenta LSP (v2.0.74+): a ferramenta LSP oferece inteligência de código semelhante à de uma IDE: - Ir para a definição: vá até o local em que um símbolo foi definido - Localizar referências: liste todos os usos de um símbolo na base de código - Documentação ao passar o cursor: obtenha informações de tipo e documentação para qualquer símbolo - Funciona com TypeScript, Python, Go, Rust e outras linguagens compatíveis com LSP - Exige que o servidor de linguagem esteja disponível (normalmente instalado com seu conjunto de ferramentas)

Ferramentas de modificação (exigem aprovação): - Edit - Modifica arquivos existentes - Write - Cria novos arquivos - Bash - Executa comandos do shell - WebFetch - Busca o conteúdo de URLs - NotebookEdit - Modifica notebooks Jupyter

Na primeira vez que uma ferramenta de modificação é executada, o Claude Code solicita aprovação. As aprovações persistem durante a sessão, a menos que você configure explicitamente o contrário.

Ferramenta EndConversation (v2.1.214). O Claude Code agora tem a mesma capacidade de encerrar conversas que o Claude oferece no claude.ai desde 2025: em casos raros de entradas extremamente abusivas ou tentativas persistentes de jailbreak, o Claude pode encerrar a sessão imediatamente por meio da ferramenta integrada EndConversation. Trata-se de uma medida de resistência a abusos e bem-estar do modelo, não de um recurso de fluxo de trabalho — ela nunca é acionada em sessões normais de desenvolvimento.¹⁹⁰¹⁹³

Modos de permissão

O modo default é identificado como “Manual” desde a v2.1.200. A alteração de nome abrange o CLI, --help, VS Code e JetBrains; o valor de configuração não mudou, portanto "defaultMode": "default" continua funcionando, e --permission-mode manual / "defaultMode": "manual" agora são aceitos como aliases. O comportamento é idêntico — solicitar confirmação no primeiro uso de cada ferramenta —, apenas o rótulo deixou de sugerir “o modo que você recebe por padrão” quando, na verdade, é o modo de aprovação manual. Na mesma versão, as caixas de diálogo AskUserQuestion deixaram de continuar automaticamente por padrão; agora, um subagent que faz uma pergunta aguarda sua resposta em vez de prosseguir após um tempo limite, e você pode reativar o tempo limite de inatividade por meio de /config.

O modo Auto é o padrão inicial nos planos Pro, Max e Team desde 14 de agosto de 2026 — anunciado em 7 de agosto e confirmado como ativo na documentação oficial dos modos de permissão na data da mudança. A redação atual acrescenta dois detalhes importantes sobre o escopo: o padrão se aplica a novas sessões, e “um padrão definido por você permanece em vigor, a menos que você aceite a solicitação única de mudança, e um padrão gerenciado pela sua organização não é alterado”. Novas sessões nesses planos começam no modo auto, que “encaminha cada chamada de ferramenta por um classificador voltado a bloquear ações irreversíveis, destrutivas ou direcionadas para fora do seu ambiente”. O argumento apresentado pela Anthropic para a mudança: em um estudo com 1.053 participantes, o modo auto detectou 89% dos comandos perigosos, contra 13,6% na análise humana — e os usuários aprovam 97% das solicitações de permissão de qualquer maneira, o que torna a análise manual fraca na prática. O custo adicional de tokens do classificador não é mais cobrado nos planos Pro/Max/Team (desde o anúncio). Para voltar, basta pressionar Shift+Tab uma vez (ou usar o menu suspenso de modo no aplicativo para desktop); fixe outro padrão com defaultMode nas configurações; administradores da organização podem desativar completamente o modo auto com a configuração gerenciada disableAutoMode. Enterprise, o Claude API, a Claude Platform on AWS, Bedrock, Agent Platform do Google Cloud e Foundry continuam com adesão opcional por enquanto — a Anthropic planeja estender o padrão a eles “no próximo mês”.²⁰³ Para entender o que o modo auto não promete — e o desvio demonstrado por pesquisadores que levou a Anthropic a esclarecer isso —, consulte Modo Auto no Max.

Arquivos de configuração de execução de código agora geram uma solicitação de confirmação mesmo com acceptEdits (v2.1.160). O acceptEdits aprova automaticamente edições comuns, mas, desde a v2.1.160, interrompe a operação e solicita confirmação antes de gravar arquivos que podem permitir a execução silenciosa de comandos: arquivos de inicialização do shell (.zshenv, .zlogin, .bash_login), ~/.config/git/ e configurações de ferramentas de build (.npmrc, .yarnrc*, bunfig.toml, .bazelrc, .pre-commit-config.yaml, .devcontainer/ e semelhantes). O motivo é que editar qualquer um deles transforma a próxima inicialização do shell, instalação ou commit em um vetor de execução — por isso, eles recebem uma barreira deliberada mesmo em um modo para projetos confiáveis que normalmente libera edições. Esse é o mesmo modelo de ameaça das proteções existentes contra gravação em .claude/, .git/ e .vscode/, ampliado para a categoria mais abrangente de arquivos nos quais uma “edição se transforma em execução”.²⁴³

Modo Auto (v2.1.85+): uma alternativa mais segura a --dangerously-skip-permissions. Um modelo classificador separado — Claude Sonnet 5 desde a v2.1.210 (originalmente Sonnet 4.6) — analisa cada ação antes da execução, verificando se ela corresponde à intenção do usuário e se é segura.¹²⁴¹⁸⁷

Como funciona: - Ações somente leitura e edições de arquivos no diretório de trabalho são aprovadas automaticamente - Regras personalizadas de permissão ou negação são resolvidas primeiro - Todo o restante é enviado ao classificador para avaliação - Em caso de bloqueio, o Claude tenta automaticamente uma abordagem alternativa

Bloqueados automaticamente por padrão: curl | bash, force-push para a branch main, implantações/migrações em produção, exclusões em massa na nuvem, alterações de IAM/permissões e envio externo de dados confidenciais.¹²⁵

Disjuntor: 3 bloqueios consecutivos ou 20 no total durante uma sessão fazem o sistema voltar às solicitações manuais de confirmação.¹²⁵

# Enable at startup
claude --permission-mode auto

# Or cycle into it during a session
Shift+Tab  # Cycles through: Manual (aka default) → acceptEdits → auto → plan

O modo auto não exige mais adesão opcional (v2.1.152), funciona no Bedrock/Vertex/Foundry sem uma variável de ambiente (v2.1.207) e é o padrão inicial nos planos Pro/Max/Team desde 14 de agosto de 2026.^245185203

Modo YOLO (v2.0.68+): para uma operação totalmente autônoma e sem qualquer classificador de segurança, use a flag --dangerously-skip-permissions. A flag diz sim para tudo: edições de arquivos, comandos bash e todas as chamadas de ferramentas. A palavra “dangerous” é intencional. O Modo Auto é a alternativa recomendada para a maioria dos casos de uso.⁵⁴

claude --dangerously-skip-permissions

Defina o modo pelo CLI:

claude --permission-mode auto  # or acceptEdits, plan, bypassPermissions

Alterne durante a sessão:

Shift+Tab  # Cycles through modes

Em settings.json:

{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

Restrição de escopo em defaultMode (v2.1.257): os arquivos .claude/settings.json ou .claude/settings.local.json de um projeto não podem mais definir defaultMode: "bypassPermissions" – o valor é ignorado nesses arquivos, assim como "auto" já era. Agora, a documentação descreve explicitamente a regra: os valores auto e bypassPermissions de permissions.defaultMode “não entram em vigor quando vêm de configurações locais ou do projeto” – defina-os nas configurações do usuário ou gerenciadas, ou para cada sessão com --permission-mode. Portanto, um repositório clonado não pode fornecer um arquivo de configurações que inicie sessões ignorando as permissões. (O exemplo acima usa acceptEdits, que pode ser definido em qualquer escopo; este guia também nunca havia registrado a restrição preexistente de auto – agora ambas estão documentadas.)²¹¹²²¹

Sintaxe das regras de permissão

Regras detalhadas controlam operações específicas. Elas são avaliadas em ordem: a primeira correspondência vence.

Padrões de comandos Bash:

{
  "allow": [
    "Bash(npm run build)",
    "Bash(npm run test:*)",
    "Bash(git commit:*)",
    "Bash(make:*)"
  ],
  "deny": [
    "Bash(rm -rf:*)",
    "Bash(sudo:*)",
    "Bash(curl|wget:*)"
  ]
}

O asterisco permite correspondência por prefixo: Bash(npm run test:*) permite npm run test, npm run test:unit e npm run test:integration.

Limitação importante: os padrões Bash correspondem apenas a prefixos, não a expressões regulares. Um padrão como Bash(curl http:*) não corresponderá a curl -X GET http://..., pois as opções aparecem antes da URL. Para um bloqueio confiável, negue o comando inteiro: Bash(curl:*).

Coloque o * após o subcomando. O Claude Code corresponde literalmente a tudo o que vem antes do primeiro *, portanto são essas palavras que delimitam a regra: Bash(git log *) permite apenas comandos git log, enquanto, em Bash(git * main), o * representa o subcomando e todas as opções anteriores a ele. Isso inclui -c, que faz o git executar um programa indicado por você; portanto, Bash(git * main) também aprova git -c core.fsmonitor=<script> diff main. Desde a v2.1.246, o Claude Code exibe um aviso na inicialização quando uma regra de permissão contém um curinga antes do subcomando, esteja ela em um arquivo de configurações, nas configurações gerenciadas ou em um valor de --allowedTools/--settings; a correção é usar o valor exato desejado, como Bash(git checkout main) no lugar de Bash(git * main).²²⁷²²⁵

As regras de negação de arquivos alcançam redirecionamentos; a ampliação para argumentos foi lançada e revertida em um dia (v2.1.257-260). As regras de negação Read(...) e Edit(...) em comandos Bash abrangem redirecionamentos de entrada (< file) e comandos de leitura como tac e egrep (v2.1.257) – a versão mais restrita prometida quando as verificações de redirecionamento de entrada da v2.1.232 foram revertidas na v2.1.233; essa parte permanece. A v2.1.259 estendeu a mesma cobertura a caminhos de arquivos ocultos em valores de opções e operandos (--ignore-revs-file=.env, -f.env, argumentos @file, operandos de git diff e git grep, comandos compostos cd DIR && cat FILE, com grep -r/cp -r em um diretório que contém um arquivo negado solicitando confirmação), e a v2.1.260 reverteu essa ampliação no dia seguinte: ela negava npm run build sob uma regra Read(./**/build/**) em todos os modos e fazia cd ... && grep solicitar confirmação até no modo auto. Essa foi a terceira mudança de direção na cobertura em nível de argumentos – a v2.1.232 a lançou, a v2.1.233 a reverteu, a v2.1.257 implementou o subconjunto de redirecionamentos e comandos de leitura que permanece, a v2.1.259 o estendeu aos argumentos e a v2.1.260 reverteu a extensão – portanto, desde a v2.1.260, as regras de negação detectam redirecionamentos e comandos de leitura, mas não caminhos ocultos em argumentos arbitrários de comandos – um estado definido pela v2.1.260 que continua em vigor; o que veio depois foram correções pontuais para desvios específicos, não uma quarta mudança de direção (próximo parágrafo).²¹¹²¹²

Correções pontuais após a reversão e uma segunda reversão restrita (v2.1.268-273). A reversão referente aos argumentos permanece; estas alterações fecham desvios específicos – e uma delas foi posteriormente desfeita. v2.1.268: regras de negação e solicitação aplicadas a diretórios de sistema que são links simbólicos (/etc, /tmp, /var no macOS; /bin no Linux) agora também valem quando um caminho é escrito usando sua localização real, e os comandos Bash não ignoram mais regras de negação escritas com o caminho de um link simbólico – ambas permanecem. A mesma versão também impediu que um comando env -C, eval ou semelhante, que o verificador de permissões não consegue analisar na mesma linha, contornasse uma regra de negação de Read ou Edit – e a v2.1.273 reverteu exatamente essa verificação: “comandos como time -p make build voltam a solicitar confirmação em vez de serem negados”. v2.1.269: as regras de negação Edit() e a verificação do caminho de gravação agora abrangem o arquivo no qual um comando Bash tee grava, uma regra de permissão Bash(tee:*) não abrange mais destinos fora dos diretórios de trabalho, e uma regra de negação ou solicitação iniciada com ! aplica-se somente à fonte de configurações que a definiu (uma negação ! isolada é ignorada). A v2.1.271 corrige o próprio verificador: o arquivo lido por fmt, column e comandos semelhantes é verificado mesmo quando aparece depois de uma opção que o verificador não reconhece; os arquivos expandidos por um curinga são verificados quando o curinga aparece em um padrão ou valor de opção (por exemplo, grep -v dir/* file); flags de declaração de variáveis do shell não podem mais representar incorretamente o comando executado; e comandos com duas mudanças de diretório, um subshell ou uma cadeia de cd+git não ignoram mais a solicitação de confirmação quando permissions.blockReadsOutsideWorkingDirectories está ativo nos modos bypass e auto. A v2.1.273 combina sua reversão com três correções pontuais próprias: um comando Bash que não pode ser analisado não ignora mais a solicitação quando permissions.blockReadsOutsideWorkingDirectories está ativo, um subshell que oculta um rm perigoso não ignora mais a confirmação no modo bypass, e um diretório de memória escolhido pelas configurações de um repositório não é mais carregado, recuperado nem indexado com base nessa configuração. Em termos simples, a regra final para linhas Bash que o verificador não consegue analisar é: regras de negação solicitam confirmação em vez de negar, e blockReadsOutsideWorkingDirectories solicita confirmação em vez de ignorar.²¹⁶²¹⁷

Padrões de operações em arquivos:

{
  "allow": [
    "Edit(src/**)",
    "Read(docs/**)"
  ],
  "deny": [
    "Read(.env*)",
    "Read(secrets/**)",
    "Edit(.git/**)",
    "Edit(node_modules/**)"
  ]
}

Sintaxe dos caminhos: - Caminhos relativos: Edit(src/**) - relativos ao diretório de trabalho - Caminhos absolutos a partir do arquivo de configurações: Edit(/build/**) - relativos à localização do arquivo de configurações - Caminhos realmente absolutos: Edit(//tmp/**) - começam com // - Diretório pessoal: Read(~/.zshrc)

Regras de permissão dir/** com um único segmento agora correspondem somente a <cwd>/dir (v2.1.214) — revise suas regras existentes. Antes da v2.1.214, uma regra de permissão como Edit(src/**) aprovava automaticamente gravações em qualquer diretório chamado src em qualquer nível da árvore — vendor/src/, packages/foo/src/, todos eles. Agora, ela corresponde apenas ao diretório src diretamente abaixo do diretório de trabalho. Se você dependia do comportamento antigo em qualquer profundidade, reescreva a regra como Edit(**/src/**). As regras deny e ask mantêm a correspondência em qualquer profundidade — a mudança restringe o que é aprovado automaticamente, nunca o que é bloqueado. Uma regra que deixou silenciosamente de corresponder se manifesta como novas solicitações de permissão após a atualização, não como um erro; portanto, verifique todas as regras de permissão escritas no formato de segmento único. As condições if: dos hooks receberam o mesmo escopo relativo ao cwd nessa versão (consulte Correspondências).¹⁹⁰

Use Edit(path)/Read(path), não Write(path)/NotebookEdit(path)/Glob(path) (v2.1.210). O Claude Code agora exibe um aviso na inicialização para regras de permissão escritas com Write(path), NotebookEdit(path) ou Glob(path). As formas canônicas são as duas famílias de regras que realmente controlam o acesso a arquivos: Edit(path) abrange todas as ferramentas de gravação de arquivos (incluindo Write e NotebookEdit), e Read(path) abrange as ferramentas de leitura de arquivos (incluindo Glob). Migre todas as regras legadas para eliminar o aviso e manter explícita a intenção.¹⁸⁷

“Always allow” salva na raiz do repositório (v2.1.211). As regras de permissão criadas pela opção “Always allow” da solicitação agora são gravadas na raiz do repositório, e não no worktree atual. Assim, uma aprovação concedida em um worktree persiste entre sessões e em todos os worktrees desse repositório — você não precisa mais aprovar novamente o mesmo comando em cada checkout paralelo.¹⁸⁸

Caminhos com parênteses e padrões malformados falham de forma segura (v2.1.260). Três correções na análise de regras de permissão de arquivos, sendo a primeira uma correção de segurança. Regras Edit/Write/Read cujo caminho contém parênteses – por exemplo, um grupo de rotas do Next.js como Edit(src/app/(admin)/**) – eram descartadas como inválidas ou ignoradas pelo sandbox Bash, deixando graváveis pastas que um administrador acreditava serem somente leitura; agora elas são aplicadas. Uma regra de negação de arquivos com um padrão impossível de compilar (como um [ sem fechamento) antes fazia todas as edições de arquivos falharem com Invalid regular expression; agora, essa regra protege o caminho literal que especifica. Além disso, o erro de configurações para uma regra como Edit(C:\dir\(name)\**), em que \( é interpretado como um parêntese escapado em vez de um separador de caminho, agora sugere uma grafia inequívoca. A mesma versão também deixa de ignorar silenciosamente regras que contêm texto após o parêntese de fechamento (Bash(ls) x nunca correspondia a nada); agora elas são informadas como configurações inválidas.²¹²

Padrões de ferramentas do MCP:

{
  "allow": [
    "mcp__github",
    "mcp__database__query",
    "mcp__myserver__*"
  ],
  "deny": [
    "mcp__dangerous_server",
    "mcp__untrusted__*"
  ]
}

Use a sintaxe curinga mcp__server__* para permitir ou negar todas as ferramentas de um servidor MCP específico.³² A sintaxe curinga é útil para ativar rapidamente todas as ferramentas de servidores confiáveis ou bloquear servidores inteiros de fontes não confiáveis.

Desde a v2.1.166, as regras de negação também aceitam um glob na posição do nome da ferramenta: um "*" isolado no campo do nome da ferramenta nega todas as ferramentas, permitindo que você bloqueie tudo e depois volte a liberar apenas um conjunto restrito. Em contrapartida, as regras de permissão rejeitam globs que não sejam do MCP — você não pode liberar tudo de forma ampla do mesmo modo, o que mantém a postura padrão restritiva.²⁴¹

Correspondência no nível dos parâmetros — Tool(param:value) (v2.1.178):

Além do nome da ferramenta, uma regra pode corresponder aos parâmetros de entrada da ferramenta, usando * como curinga no valor:

{
  "deny": [
    "Agent(model:opus)"
  ]
}

Agent(model:opus) bloqueia qualquer subagent iniciado no nível Opus — a própria inicialização é negada, não se trata apenas de pedir no prompt que ele seja evitado. Isso estende o controle de permissões de “qual ferramenta” para “como ela é chamada”, como uma regra determinística em vez de uma solicitação no nível do prompt. Ele funciona em conjunto com a configuração gerenciada enforceAvailableModels: a lista de permissões define quais níveis de modelo existem na sessão, enquanto as regras Tool(model:...) restringem como os subagents os utilizam.¹⁷³

Desde a v2.1.186, essas regras Agent(...) também são aplicadas à inicialização de subagents nomeados: as regras de negação Agent(agent_type) e as restrições de tipos permitidos Agent(x,y) agora valem quando um agente nomeado específico é iniciado (por meio de um fluxo de trabalho, --agents ou uma equipe de agentes), não apenas em inicializações anônimas no estilo Task. A inicialização é bloqueada no início, fechando uma brecha pela qual um agente nomeado podia contornar uma regra criada para restringi-lo.¹⁷⁵

Padrões WebFetch:

{
  "allow": [
    "WebFetch(domain:github.com)",
    "WebFetch(domain:api.example.com)"
  ]
}

Desde a v2.1.268, regras simples de negação e solicitação WebFetch não se aplicam mais a leituras e atualizações da ferramenta Artifact – escreva uma regra Artifact ou WebFetch(domain:claude.ai) para bloqueá-las ou exigir confirmação.²¹⁶

Diretórios adicionais

Amplie o acesso do Claude para além do projeto atual:

{
  "permissions": {
    "additionalDirectories": [
      "../shared-lib",
      "../docs",
      "~/reference-projects/design-system"
    ]
  }
}

Diretórios adicionais são essenciais para monorepos ou quando o Claude precisa consultar código em diretórios irmãos.

Modo sandbox

Ative o isolamento do sistema de arquivos e da rede:

> /sandbox

Ou configure nas configurações:

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"],
    "network": {
      "allowUnixSockets": ["~/.ssh/agent-socket"],
      "allowLocalBinding": true,
      "deniedDomains": ["pastebin.com", "transfer.sh", "0x0.st"]
    }
  }
}

Desde a v2.1.187, a configuração sandbox.credentials impede que comandos no sandbox leiam arquivos de credenciais e variáveis de ambiente secretas — uma defesa em profundidade contra a extração de segredos por um comando no sandbox.¹⁷⁶

Desde a v2.1.221, os arquivos de credenciais ganharam um terceiro modo além de permitir/negar: mode: "mask" (Linux e WSL). Um comando no sandbox que lê o arquivo recebe uma cópia sentinela — do arquivo inteiro ou somente dos trechos capturados por uma expressão regular extract —, e o proxy do sandbox substitui o valor real na saída. O comando funciona (ele consegue se autenticar por meio do proxy) sem que o segredo jamais esteja presente em seu ambiente, exatamente a propriedade desejada quando um comando afetado por prompt injection sai à procura de tokens. No macOS, onde o mecanismo de substituição pelo proxy não está disponível, mask recorre a deny — assim, uma configuração escrita para CI no Linux falha de modo seguro em vez de expor silenciosamente o arquivo.¹⁹⁹

A v2.1.224 amplia o mascaramento para além do conteúdo estático de arquivos. extract e onExtractNoMatch lidam com valores estruturados de ambiente; decode: "jwt" com maskClaims mascara declarações selecionadas dentro de um JWT em vez do token inteiro, para que um comando ainda possa ler os metadados de roteamento do token enquanto as declarações confidenciais permanecem como sentinelas; e awsPairs/sigv4 assinam novamente no proxy as solicitações AWS SigV4, o que torna o mascaramento utilizável com os CLIs da AWS — caso contrário, uma chave mascarada falharia na verificação da assinatura. Todos esses recursos exigem network.tlsTerminate e só são respeitados nos escopos do usuário, gerenciado ou --settings — um repositório não pode fornecer uma configuração de mascaramento que redirecione silenciosamente suas credenciais.²⁰¹

Desde a v2.1.216, a configuração sandbox.filesystem.disabled ignora o isolamento do sistema de arquivos, mas mantém o controle de saída da rede — útil quando a barreira do sistema de arquivos impede o funcionamento de uma ferramenta de build, mas você ainda quer aplicar a lista de domínios permitidos ao tráfego de saída.¹⁹²

Desde a v2.1.219, a configuração sandbox.network.strictAllowlist nega imediatamente hosts que não estejam na lista de permissões, sem solicitar confirmação. Por padrão, um comando no sandbox que acessa um host fora de allowedDomains gera uma solicitação de permissão; com strictAllowlist ativado, a conexão é simplesmente recusada. Essa é a configuração ideal para execuções sem supervisão — CI, agentes em segundo plano, loops noturnos —, nas quais uma solicitação que ninguém responde causa uma paralisação e em que “pergunte sobre uma saída inesperada” é a política errada de qualquer forma. Ela completa a tríade da rede: allowedDomains define o que é permitido, deniedDomains (abaixo) cria exceções dentro de uma permissão abrangente, e strictAllowlist determina se todo o restante solicita confirmação ou falha.¹⁹⁶ A v2.1.229 também torna mais rígida a própria sintaxe da lista de domínios: literais IPv6 devem estar entre colchetes ([::1]:443), grafias ambíguas são tratadas de forma restritiva, e /doctor as sinaliza.²³⁵ A v2.1.236 acrescenta mais duas medidas de proteção: no macOS, regras curinga de negação de leitura (por exemplo, **/.env) agora têm precedência dentro de regiões em que a leitura é permitida, abrangem o conteúdo dos diretórios correspondentes e não podem ser contornadas renomeando o arquivo negado; e, enquanto o modo auto estiver ativo, as regras de permissão Monitor são desconsideradas — comandos Monitor passam pela mesma análise do classificador aplicada aos comandos Bash. O próprio classificador do modo auto agora é executado com os mesmos padrões usados no Claude API — incluindo classificação por nível de gravidade — no Bedrock, Vertex AI e Foundry, inclusive quando a telemetria está desativada.²²⁴ A v2.1.273 altera o padrão do mecanismo nesses gateways: por enquanto, o modo auto passa a usar o classificador local por padrão, e CLAUDE_CODE_AUTO_MODE_SERVER=1 ativa o classificador do lado do servidor da plataforma.²¹⁷

allowed_domains por comando no modo auto (v2.1.271): com o sandbox ativado, comandos Bash, PowerShell e Monitor no modo auto podem incluir seus próprios allowed_domains – os hosts necessários ao comando são analisados junto com ele e liberados somente para aquele comando, enquanto os demais hosts são recusados. O acesso de saída deixa de ser uma permissão válida para toda a sessão: cada comando informa seus destinos, e a análise abrange exatamente essa combinação.²¹⁶

Modo sandbox estrito e a exceção ! (sandbox.allowUnsandboxedCommands, v2.1.260). Uma configuração que este guia ainda não havia mencionado: por padrão, um comando que falha no sandbox pode ser executado novamente fora dele por meio da saída de emergência dangerouslyDisableSandbox, sujeita ao fluxo normal de permissões. sandbox.allowUnsandboxedCommands: false – exibida como Strict sandbox mode na aba Overrides de /sandbox – desativa essa saída: o parâmetro é ignorado, e todos os comandos precisam ser executados no sandbox ou estar listados em excludedCommands. Desde a v2.1.260, os comandos que você mesmo digita no prompt do modo bash ! são executados fora do sandbox mesmo no modo sandbox estrito, “como se fossem digitados em seu próprio terminal” – a rigidez controla o que o Claude executa, não o que você digita. Se seu modelo de ameaça pressupunha que comandos ! herdavam o isolamento, isso não acontece mais.²¹²

No sandbox: - O acesso ao sistema de arquivos fica restrito ao diretório do projeto - O acesso à rede é controlado - Determinados comandos ficam excluídos das restrições do sandbox - Comandos Bash são permitidos automaticamente se autoAllowBashIfSandboxed for true

Dica de especialista: o modo sandbox é excelente para executar o Claude em bases de código não confiáveis. Ative-o ao explorar projetos desconhecidos ou quando quiser uma camada adicional de proteção. Testes internos da Anthropic constataram que o sandbox reduz as solicitações de permissão em 84%.³⁸ O sandbox usa recursos do sistema operacional (seatbelt do macOS e bubblewrap do Linux) para isolar o sistema de arquivos e a rede; portanto, até mesmo um prompt injection bem-sucedido fica totalmente contido. A Anthropic disponibilizou o código-fonte do runtime do sandbox para equipes que desenvolvem seus próprios agentes.⁸²

Observações de segurança (v2.1.34+): comandos excluídos do sandbox por meio de sandbox.excludedCommands ou dangerouslyDisableSandbox antes podiam contornar a regra de solicitação de permissão do Bash quando autoAllowBashIfSandboxed estava ativado; isso foi corrigido na v2.1.34.⁸⁷ Desde a v2.1.38, gravações em .claude/skills são bloqueadas no modo sandbox, impedindo que um prompt injection modifique as definições de skills.⁸⁸ A v2.1.77 adiciona uma configuração allowRead ao sistema de arquivos do sandbox para voltar a permitir acesso de leitura dentro de regiões denyRead — útil quando você quer bloquear a maior parte de uma árvore de diretórios, mas incluir determinados subdiretórios na lista de permissões.¹¹⁹

Exceção das configurações de agentes em .claude/ (v2.1.121+): --dangerously-skip-permissions não solicita mais confirmação para gravações em .claude/skills/, .claude/agents/ e .claude/commands/.¹⁵⁴

Resolução de .claude/ aninhados (v2.1.178): skills em diretórios .claude/skills aninhados agora são carregadas automaticamente quando você trabalha em arquivos dentro daquele diretório, não apenas a partir da raiz do repositório; quando há conflito de nomes, a skill aninhada pode ser acessada como <dir>:<name>, mantendo ambas disponíveis. O restante da superfície do projeto é resolvido da mesma forma — quando há conflito entre o nome de um agente, fluxo de trabalho ou estilo de saída em diretórios .claude/ aninhados, vence o que estiver mais próximo do diretório de trabalho, e um fluxo de trabalho salvo no escopo do projeto é direcionado ao .claude/workflows/ existente mais próximo. Em um monorepo ou repositório de repositórios, isso fornece ferramentas específicas por pacote que são ativadas conforme o contexto, em vez de uma única superfície global e plana.¹⁷³

Caminhos personalizados para bubblewrap e socat (v2.1.133+): as configurações gerenciadas sandbox.bwrapPath e sandbox.socatPath permitem que administradores direcionem implantações Linux/WSL para localizações não convencionais dos binários bubblewrap e socat. Isso é útil quando as distribuições instalam essas ferramentas fora de $PATH ou quando a organização fornece builds reforçados.¹⁶⁰

Reforço da segurança na v2.1.113:¹⁵⁰

• sandbox.network.deniedDomains bloqueia hosts específicos mesmo quando um curinga mais abrangente em allowedDomains os permitiria. Use a lista de bloqueios para impedir o acesso a pastebins, serviços de compartilhamento de arquivos ou hosts maliciosos conhecidos sem reescrever toda a sua política de permissões. Combine-a com sandbox.network.strictAllowlist (v2.1.219, acima) quando quiser que tudo o que estiver fora da lista de permissões seja recusado silenciosamente em vez de gerar uma solicitação.
• Regras de negação para comandos wrapper. As regras de negação do Bash agora correspondem a comandos envolvidos por env, sudo, watch, ionice, setsid e wrappers de execução semelhantes. Regras como Bash(rm:*) agora detectam env rm -rf, sudo rm -rf e padrões de desvio semelhantes.
• As regras de permissão Bash(find:*) não aprovam mais automaticamente find -exec nem find -delete. Essas flags executam comandos e excluem arquivos, portanto o Claude Code as encaminha pelo fluxo normal de permissões.
• Proteção contra remoção no macOS. As regras de permissão Bash(rm:*) agora tratam /private/etc, /private/var, /private/tmp e /private/home como destinos de remoção perigosos. /var, /etc e /tmp são links simbólicos para /private/, portanto o formato anterior da regra não detectava os destinos canônicos.

Reforço das permissões com falha restritiva na v2.1.214:¹⁹⁰

Um conjunto de lacunas na verificação de permissões foi fechado em uma única versão, sempre de forma restritiva — quando o analisador não consegue ter certeza, ele solicita confirmação:

• Corrigido o desvio no Windows PowerShell 5.1. Comandos executados em sessões do PowerShell 5.1 antes podiam escapar da verificação de permissões.
• Redirecionamentos de descritores de arquivos do Bash falham de forma restritiva. Formas de redirecionamento que o bash interpreta de maneira diferente do analisador de permissões agora solicitam confirmação em vez de serem executadas.
• Comandos com mais de 10.000 caracteres sempre solicitam confirmação. Comandos muito longos eram avaliados incorretamente; agora eles nunca são executados automaticamente.
• Subscritos e modificadores do zsh em [[ ]] solicitam confirmação. Subscritos e modificadores de variáveis dentro de comparações [[ ]] eram tratados como texto inerte; como podem executar código, agora exigem aprovação.
• Variações inseguras de help/man não são mais aprovadas automaticamente. Determinadas invocações podiam executar opções inseguras, substituições de comandos ou caminhos com barras invertidas sob o pretexto de consultar documentação.
• Ordem das solicitações em sessões remotas. Solicitações de permissão em sessões remotas não podem mais prosseguir antes da caixa de diálogo local de confirmação.
• Flags de redirecionamento do daemon do docker solicitam confirmação. Comandos docker (incluindo o shim docker do Podman) que contêm --url, --connection, --identity ou o modo remoto do Podman antes eram executados sem confirmação — essas flags direcionam o comando para um daemon totalmente diferente.
• file perde seu passe livre de somente leitura quando recebe instruções de onde gravar. file -m/--magic-file e -f/--files-from agora exigem permissão em vez de serem aprovados automaticamente como operações somente leitura.

Como funcionam os hooks?

Hooks executam comandos shell determinísticos em pontos específicos do fluxo de trabalho do Claude Code. Ao contrário de instruir o Claude a realizar ações, os hooks garantem a execução independentemente do comportamento do modelo. Eles são essenciais para aplicar os padrões da equipe e automatizar tarefas repetitivas. Consulte Estruturas de decisão para ver a árvore de decisão “Qual tipo de hook?”, que abrange hooks de comando, prompt e agente.

Por que usar hooks em vez de prompts: Dizer ao Claude “sempre execute o Prettier depois de editar arquivos” às vezes funciona. Porém, o Claude pode esquecer, priorizar a velocidade ou decidir que a alteração é “pequena demais”. Hooks garantem a execução: cada Edit ou Write aciona seu formatador, sempre, sem exceções. Para conformidade, segurança e padrões de equipe, o determinístico supera o probabilístico.⁴

Eventos disponíveis