Guia da CLI do Claude Code: instalação, configuração, comandos e 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 com MCP e subagents. Domine cinco sistemas centrais (configuração, permissões, hooks, MCP e subagents) e você terá uma produtividade multiplicada. 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 no Opus se a qualidade for sua única variável. Use hooks (não prompts) para tudo que sempre precisa ser executado. Desde a v2.1.197 (30 de junho de 2026), Claude Sonnet 5 é o modelo padrão no Claude Code — contexto nativo de 1M, preço promocional de US$ 2/US$ 10 até 31 de agosto — com o Opus disponível a apenas um /model opus de distância (desde a v2.1.219, esse alias seleciona o Claude Opus 5); a v2.1.198 (1º de julho) faz com que subagents sejam 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 rascunho de PR ao concluírem código em uma worktree e aciona o hook Notification (agent_needs_input/agent_completed) para sessões em segundo plano; a v2.1.199 (2 de julho) carrega até 5 invocações empilhadas de slash-skills e repete automaticamente solicitações após erros 429 temporários para assinantes; a v2.1.200 (3 de julho) renomeia o modo de permissão default como “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, por padrão, que as caixas de diálogo AskUserQuestion continuem automaticamente; a v2.1.202 (6 de julho) adiciona um controle de “Dynamic workflow size” em /config e faz /review <pr> voltar a ser uma revisão rápida de passagem única, enquanto a revisão multiagente passa para /code-review <level> <pr#>; as v2.1.203–205 (7–9 de julho) reforçam o auto mode — arquivos de transcrição ficam protegidos contra adulteração, rm -rf aplicado a uma variável que não pode ser resolvida solicita confirmação primeiro e notificações de tarefas em segundo plano informam que não houve intervenção humana (assim, aprovações forjadas na transcrição não podem gerar ações) — e transformam /doctor em uma verificação completa que diagnostica e corrige problemas (alias /checkup).^181182183 A v2.1.217 (21 de julho) mudou novamente o comportamento dos subagents aninhados — subagents deixaram de criar seus próprios subagents por padrão (uma decisão que a v2.1.219 reverteu novamente três dias depois, para 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 por skill com background: false), faz /deep-research iniciar somente quando invocado explicitamente, entrega as verificações de rm perigoso, & em segundo plano e caminhos suspeitos do Windows ao classificador do auto mode, em vez de usar caixas de diálogo de permissão, e impede a execução de hooks do frontmatter de agentes provenientes 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, corte de conhecimento em maio de 2026 — e corrige duas mudanças introduzidas por versões anteriores: o fast mode 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 fast mode) e subagents aninhados voltam a ser 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 agora adotando por padrão uma diretriz de tamanho médio (busque usar menos de 15 agentes), e o encaminhamento de subagents aninhados em stream-json. A v2.1.220 (25 de julho) traz apenas correções de bugs e melhorias de confiabilidade.^196197198 Desde as v2.1.174–176 (12 de junho de 2026), a allowlist availableModels agora também pode restringir o modelo Default por meio da nova configuração gerenciada enforceAvailableModels (as configurações do usuário ou projeto não podem ampliar uma lista gerenciada), os títulos das 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 que faz as condições if dos hooks corresponderem aos padrões de caminho de Read/Edit/Write completam a versão.¹⁷² Desde a 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 utilidade no Opus/Sonnet). Desde a v2.1.172 (10 de junho de 2026), subagents podiam criar recursivamente seus próprios subagents, 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ê a região de ~/.aws quando AWS_REGION não está definido (/status mostra a origem), /plugin adiciona uma barra de pesquisa no marketplace e a métrica OTEL claude_code.lines_of_code.count ganha um atributo model. Desde a 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 aceita toda a escala de esforço de low a max, mas não permite desativar o thinking); o Opus 4.8 continua sendo o padrão agêntico. Desde a 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 a solução de problemas, /cd move uma sessão para um novo diretório de trabalho sem interromper o cache de prompts e disableBundledSkills oculta do modelo as skills e os comandos de barra integrados. Desde a v2.1.166 (6 de junho de 2026), uma configuração fallbackModel encadeia até três modelos de backup quando o principal está sobrecarregado, o glob "*" funciona nas regras de negação do MCP e MAX_THINKING_TOKENS=0 / --thinking disabled desativam totalmente o thinking em modelos que o ativam por padrão. Desde a v2.1.154 (28 de maio de 2026), o Opus 4.8 é o novo padrão, com esforço alto 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 Fast mode 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 voltada apenas à limpeza (separada de /code-review --fix), claude agents aceita ! <command> para criar 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 o modelo como padrão (pressione s para aplicar apenas à sessão) e incluiu COLUMNS/LINES no ambiente da linha de status. A v2.1.152 introduziu /code-review --fix (aplica as constatações à árvore de trabalho), disallowed-tools no frontmatter de 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 opcional ao auto mode.^{162 163 164 165 166 167 168 169 170 211 171}

O Claude Code opera como um sistema agêntico, não como uma interface de chat com conhecimento 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 meio de uma interface de linha de comando integrada à forma 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× nos 13 meses desde a prévia de pesquisa — e 90% do código da própria Anthropic era escrito por IA.¹⁰³

A diferença entre o uso casual e 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: permite automação determinística
4. Protocolo MCP: amplia os recursos
5. Sistema de subagents: lida com tarefas complexas de 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 isolando a exploração em janelas de contexto limpas e retornando 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 executados sempre, independentemente do comportamento do modelo.
• A divisão por níveis de modelo reduz custos sem sacrificar a qualidade: encaminhe a exploração por subagents para modelos mais baratos e reserve o Opus para raciocínios arquiteturais realmente complexos — ou padronize no Opus se a qualidade for sua única variável.
• O MCP conecta o Claude ao seu conjunto de ferramentas: bancos de dados, GitHub, Sentry e mais de 3.000 integrações levam o Claude 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 de configuração práticos e os casos extremos que surpreendem 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 ler tudo do início ao fim. Comece pela seção mais 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 apresenta um resumo de fácil consulta de todos os principais comandos.

Análises relacionadas

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

Início rápido em 60 segundos

Se você só quer executar o Claude Code e ver o resultado, siga estas etapas 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.

Pronto. 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 empresarial — mas nada disso é necessário para começar.

Pré-requisitos: Node 22+ apenas para o método legado via npm (alterado de 18 para 22 na v2.1.198; a documentação de instalação atual informa “Node.js 22 ou posterior”, verificado em 07 de agosto de 2026); o instalador nativo recomendado não depende do Node. Há suporte para macOS / Linux / Windows 10+. Uma assinatura Claude Pro, Max, Team ou Enterprise, ou uma chave API da Anthropic com pagamento por token, cobre o uso. Consulte Como instalo o Claude Code? para ver detalhes específicos de cada plataforma, solucionar problemas e conhecer o método com binário nativo (padrão desde a v2.1.113). As evidências sobre a versão mais recente neste guia foram verificadas com base na v2.1.154.²¹¹

Como o Claude Code funciona: o modelo mental

Antes de explorar os recursos, entenda como a arquitetura do Claude Code determina 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 (up to 10 parallel)       │    │
│  │   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, arquivo lido e resultado de ferramenta consome espaço de uma janela de contexto compartilhada (200 mil tokens como padrão⁹¹ e 1 milhão de tokens com Opus 4.6 ou modelos de contexto estendido). Quando o contexto fica cheio, o Claude perde o fio das decisões anteriores e a qualidade diminui. Essa camada gera custos por token.

Camada de delegação: Subagents são iniciados com contextos limpos, realizam tarefas específicas e retornam resumos. Os resultados da exploração não sobrecarregam sua conversa principal; apenas as conclusões retornam. Direcione os subagents para modelos mais baratos durante a exploração ou use seu modelo principal em todas as etapas caso a qualidade seja 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 do shell independentemente do comportamento do modelo. Skills codificam conhecimentos especializados que o Claude aplica automaticamente. Plugins reúnem tudo isso para distribuição.

O principal insight: A maioria dos usuários trabalha apenas na camada principal, enquanto observa o contexto inchar e os custos aumentarem. Usuários avançados transferem a exploração e o trabalho especializado para a camada de delegação, mantêm a camada de extensão configurada para o próprio 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. Principais modos de interação
4. Análise detalhada do sistema de configuração
5. Qual modelo devo escolher?
6. Quanto custa o Claude Code?
7. Estruturas para tomada 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 Extended Thinking?
13. Estilos de saída
14. Comandos slash
15. Como funcionam as skills?
16. Sistema de plugins
17. Como funciona a memória?
18. Entrada de imagens e multimodal
19. Modo de voz
20. Como funciona a integração com o Git?
21. Como uso o Claude Code na minha IDE?
22. Padrões de uso avançado
23. Agentes remotos e em segundo plano [PRÉVIA DA PESQUISA]
24. Claude no Chrome
25. Claude Code no Slack [PRÉVIA DA PESQUISA]
26. Claude Code na Web [PRÉVIA DA PESQUISA]
27. Otimização de desempenho
28. Como depuro problemas?
29. Implantação empresarial
30. Referência de atalhos de teclado
31. Práticas recomendadas
32. Receitas de fluxo de trabalho
33. Guia de migração
34. Orientações específicas para cada público
35. Cartão de referência rápida
36. Histórico de alterações
37. 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 requer 4 GB de RAM no mínimo e uma conexão ativa com a internet.⁹² A compatibilidade de shell funciona melhor com Bash, Zsh ou Fish.

Para Windows, tanto WSL 1 quanto WSL 2 funcionam. O Git Bash também funciona se você preferir 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 de plataformas

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

Consulta rápida — todos os métodos, todos os comandos, verificação de versão em uma única tela. As subseções abaixo cobrem detalhes específicos por método e 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 para cada plataforma, em vez do JavaScript incluído — use o instalador nativo para a distribuição testada. O caminho via npm ainda funciona, mas recebe o aviso de depreciação adicionado pela primeira vez 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 instalação de 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

Instalação via NPM (depreciada)

Nota: A partir da v2.1.15, instalações via npm exibem um aviso de depreciação. O binário nativo agora é o método de instalação recomendado. Migre com claude install.

Para ambientes legados onde o npm ainda é necessário:

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

Nunca use sudo com a 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 suporta três caminhos de autenticação, cada um com diferentes tradeoffs:

Claude Console (cobrança via API)

Conecte-se diretamente à API da Anthropic por meio de platform.claude.com (anteriormente console.anthropic.com). Crie uma conta, configure a cobrança e autentique-se por meio do CLI. O Console oferece cobrança baseada no uso com acesso completo à API. Um workspace dedicado “Claude Code” é criado automaticamente; você não pode criar chaves de API para esse workspace, mas pode monitorar o uso.

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 uma acesso de nível corporativo com relacionamentos 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 de modelo.¹³⁷ Assistente de configuração do Vertex AI (v2.1.98+): Um assistente equivalente para o Google Cloud, guiando a autenticação no GCP, configuração de projeto e região, verificação de credenciais e fixação de modelo.¹⁴² Vertex AI mTLS Workload Identity Federation (v2.1.121+): O Vertex AI agora aceita Workload Identity Federation baseada em certificado X.509 (mTLS Application Default Credentials) — tokens GCP de curta duração emitidos a partir de um certificado de cliente, sem necessidade de JSON de service-account.¹⁵⁴ Confiança em 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.¹⁴³

# 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 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

Verificação

claude doctor

O comando reporta 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

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

claude auth logout && claude auth login

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

Atualizações

O Claude Code se auto-atualiza por padrão, verificando na inicialização e periodicamente durante as sessões. As atualizações são baixadas em segundo plano e aplicadas no próximo lançamento.

Desativar auto-atualizações:

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 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 de especialista: O REPL mantém o estado durante eventos de compactação. Quando o contexto fica grande demais, Claude resume automaticamente a parte mais antiga da conversa, preservando as principais decisões e os trechos de código. Você pode acionar isso manualmente com /compact ou adicionar instruções personalizadas sobre o que preservar.

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 de 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 o texto e a saída de raciocínio dos subagents para o stream, permitindo que harnesses e pipelines de logs acompanhem o trabalho delegado enquanto ele acontece, em vez de mostrarem apenas o relatório final.¹⁸⁸

Subagents aninhados agora também são encaminhados (v2.1.219). Originalmente, apenas subagents de profundidade 1 apareciam. Agora, subagents iniciados na profundidade 2 ou superior também aparecem no stream encaminhado, cada um identificado pelo id tool_use da chamada Agent que o iniciou — assim, um pipeline pode reconstruir a árvore de delegação em vez de exibir uma lista simples de textos. Isso se combina diretamente com a 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 permaneceriam invisíveis.¹⁹⁶

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-4-5-20250929

# 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

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 permitir sua continuação. 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"

Sessões vinculadas a PRs (v2.1.27+, ampliado na v2.1.119+): Inicie uma sessão vinculada a uma solicitação de pull ou merge específica. Desde a v2.1.119, --from-pr aceita URLs de MR do GitLab, PR do Bitbucket e PR 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 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 (e GitLab auto-hospedado) 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 humanos, prefira /rename e --resume.

/fork inicia uma sessão em segundo plano; /subtask é a ramificação 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 antigo — criar uma ramificação 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 "fork" como origem do hook SessionStart (antes era "resume"), permitindo que hooks baseados na 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 derivada 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 experimentação.¹⁹⁹

Claude Code armazena as sessões como transcrições JSONL. A execução de agentes 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 Claude à exploração somente leitura — sem edição de arquivos, execução do Bash ou ações destrutivas. 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. 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+): Claude oferece três opções: - “Sim, limpar o contexto e aceitar edições automaticamente” (Shift+Tab) — começa do zero com todo o contexto disponível para o plano - “Sim, e aprovar as edições manualmente” — preserva o contexto e você aprova cada alteração - “Sim, aceitar edições automaticamente” — preserva o contexto e Claude executa sem exigir aprovação para cada edição

A limpeza automática do contexto após a aprovação é o fluxo de trabalho recomendado. Ela oferece ao plano uma nova janela de contexto, o que melhora significativamente a adesão ao plano — Claude mantém o foco por mais tempo sem a interferência da conversa anterior.

Quando usar o modo de planejamento: - Implementações de novos recursos que envolvem decisões de arquitetura - Refatorações em vários arquivos quando você quer analisar a abordagem primeiro - Bases de código desconhecidas, nas quais a exploração deve preceder as modificações - Qualquer tarefa com várias abordagens válidas sobre as quais você queira opinar

Dica de especialista: Quanto mais tempo você investir no modo de planejamento, maior será a probabilidade de Claude concluir a implementação com sucesso. O modo de planejamento oferece uma exploração praticamente sem custo — sem chamadas arriscadas de ferramentas nem edições desperdiçadas. Use-o à vontade.

Modo de leitor de tela (v2.1.208)

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 formas:¹⁸⁶

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

# Environment variable
export CLAUDE_AX_SCREEN_READER=1

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

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

Análise aprofundada do sistema de configuração

Claude Code usa um sistema de configuração em camadas. Entender a hierarquia é essencial porque os níveis superiores sobrescrevem os inferiores, e as configurações corporativas não podem ser contornadas.

Hierarquia de configuração

Dica de especialista: use .claude/settings.local.json para preferências pessoais em projetos compartilhados (adicione-o ao .gitignore). Use .claude/settings.json para configurações de toda a equipe que serão adicionadas ao controle de versão.

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

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

Referência completa do settings.json

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

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-4-5-20250929",
  "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": "npx prettier --write \"$FILE_PATH\""
          }
        ]
      }
    ]
  },
  "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": {
    "tips": ["Custom tip 1", "Custom tip 2"],
    "excludeDefault": true
  },
  "skillOverrides": {
    "legacy-skill": "off",
    "manual-only-skill": "user-invocable-only",
    "compact-skill": "name-only"
  },
  "includeGitInstructions": false,
  "modelOverrides": {
    "bedrock": "us.anthropic.claude-opus-4-6-20260312-v1:0",
    "vertex": "claude-opus-4-6@20260312",
    "foundry": "anthropic.claude-opus-4-6"
  },
  "autoMemoryDirectory": ".claude/memory",
  "sandbox": {
    "enableWeakerNetworkIsolation": true
  }
}

skillOverrides é útil quando uma equipe tem uma grande biblioteca de skills, mas quer restringir o que fica disponível durante a execução. Use off para ocultar uma skill tanto do modelo quanto do seletor de comandos slash, user-invocable-only para permitir que ela seja chamada pelo nome enquanto a remove da seleção do modelo e name-only para manter visível apenas o nome da skill, sem sua descrição completa.¹⁵⁶

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

• availableModels / enforceAvailableModels (gerenciada, v2.1.175+): a lista de permissões availableModels restringe quais modelos uma sessão pode selecionar. Com enforceAvailableModels: true, essa lista também limita o modelo Default — se Default resultar em um modelo não permitido, será usado o primeiro modelo permitido — e as configurações de usuário/projeto não poderão mais ampliar uma lista availableModels gerenciada. Uma correção complementar (v2.1.176) elimina a brecha pela qual a seleção de um alias podia redirecionar para um modelo bloqueado por meio de ANTHROPIC_DEFAULT_*_MODEL, e agora /fast se recusa a alternar para um modelo que não esteja na lista de permissões.¹⁷² A partir da v2.1.187, as organizações podem aplicar restrições de modelos diretamente no seletor de /model, em --model, /model e ANTHROPIC_MODEL — selecionar um modelo restrito exibe a mensagem “restrito pelas configurações da sua organização”.¹⁷⁶
• language (aprimoramento da v2.1.176): além de definir o idioma das respostas, agora os títulos das sessões são gerados, por padrão, no idioma da sua conversa; defina language para fixar um idioma específico para os títulos.¹⁷²
• footerLinksRegexes (v2.1.176): badges de links que correspondem a expressões regulares na linha do rodapé, configuráveis pelas configurações de usuário ou gerenciadas.¹⁷²
• wheelScrollAccelerationEnabled (v2.1.174): defina como false para desativar a aceleração da rolagem pela roda do mouse no modo de tela cheia.¹⁷²

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

• vimInsertModeRemaps (v2.1.208): remapeamentos personalizados de teclas para o modo de inserção do vim — o exemplo clássico é mapear jj para Escape (consulte Modo Vim).¹⁸⁶
• axScreenReader (v2.1.208): ativa de forma persistente o modo de leitor de tela (consulte Modo de leitor de tela).¹⁸⁶
• processWrapper (v2.1.208): direciona todos os processos que Claude Code inicia para si mesmo por meio de um executável wrapper — desenvolvido para launchers corporativos (consulte Launcher corporativo).¹⁸⁶
• Restrição da origem de autoMode (v2.1.207): a configuração autoMode não é mais lida do .claude/settings.local.json de um repositório — configure-a em ~/.claude/settings.json. Isso elimina uma possibilidade pela qual um repositório clonado poderia fornecer uma configuração de modo automático.¹⁸⁵

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

• emojiCompletionEnabled (v2.1.217): preenchimento automático de shortcodes de emojis na entrada 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 que não estão na lista de permissões para comandos executados no sandbox sem solicitar confirmação, em vez de abrir uma caixa de diálogo de permissão. Consulte Modo sandbox.¹⁹⁶
• workflowSizeGuideline (v2.1.219): define a recomendação consultiva de tamanho do workflow Dynamic em qualquer arquivo de configurações — de usuário, projeto ou gerenciado — em vez de apenas por meio de /config. Por padrão, os workflows Dynamic usam uma recomendação média (“tente usar menos de 15 agentes”); a linha correspondente em /config fica oculta quando um arquivo de configurações fornece o valor. É uma recomendação, não um limite obrigatório. Consulte Subagents.¹⁹⁶

Referência de variáveis de ambiente

Autenticação e API:

ANTHROPIC_API_KEY=sk-ant-...                    # Direct API authentication
ANTHROPIC_AUTH_TOKEN=token                      # Custom authorization header
ANTHROPIC_CUSTOM_HEADERS="X-Key: val"           # Additional request headers

Configuração de modelos:

ANTHROPIC_MODEL=claude-opus-4-7                 # Override default model (Apr 16, 2026)
ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-7    # Opus 4.7 (Max/Team Premium default)
ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-6
ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5-20251001
CLAUDE_CODE_SUBAGENT_MODEL=sonnet               # Model for subagents
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]

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
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+)
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_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_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                    # Bash output limit
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]
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
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[^50]
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_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 confidenciais:²¹²

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+)
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+)
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 spans de solicitação do LLM na v2.1.121+: stop_reason, gen_ai.response.finish_reasons e user_system_prompt agora são emitidos nos spans de solicitação do LLM. user_system_prompt é controlado por OTEL_LOG_USER_PROMPTS=1, pois pode conter PII.¹⁵⁴

Alterações no nível de eventos na v2.1.122+: os atributos numéricos dos eventos de log api_request e api_error agora são emitidos como números (antes eram strings) — isso corrige coletores OTel downstream que aplicavam tipagem estrita ao esquema. O novo evento de log claude_code.at_mention é disparado quando Claude Code resolve uma menção com @.¹⁵⁴

Evento de log claude_code.assistant_response na v2.1.193+: 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 peculiaridade importante ao fazer upgrade: quando OTEL_LOG_ASSISTANT_RESPONSES não está definido, ele segue OTEL_LOG_USER_PROMPTS. Portanto, qualquer implantação que já registre o conteúdo dos prompts começará 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 limitada aos prompts.¹⁷⁹

Adições de telemetria da v2.1.214: agora, os eventos de log OTel incluem os atributos message.uuid, client_request_id e tool_source para correlacionar mensagens e identificar a origem das ferramentas; o payload de subagentStatusLine inclui o nível de esforço de raciocínio do subagent, permitindo que linhas de status personalizadas exibam o modelo e o esforço juntos; e a nova variável de ambiente CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH configura o limite de truncamento de 60 KB para atributos de conteúdo do OTel.¹⁹⁰

Controle de API / modelos:²¹²

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+)

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+)

Corporativo / 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 skills (v2.1.69+):

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

Identidade do chamador de 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 o 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, respeitando o 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 com o pensamento desativado é rejeitado, mesmo que turnos anteriores da mesma conversa tenham sido aceitos.

Especificamente no Claude Code: o valor padrão de effort é high no Opus 5 (assim como na API da Claude), 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 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 (9 de junho de 2026): Um novo nível de modelo acima do Opus — o modelo mais poderoso e inteligente da Anthropic, estado da arte em quase todos os benchmarks nos quais foi testado e projetado 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 em consultas sobre cibersegurança, biologia e química e destilação de modelos (o Claude Mythos 5 é o mesmo modelo sem essas salvaguardas, destinado a pesquisadores autorizados). Ele passou a poder ser selecionado no Claude Code com a v2.1.170 (9 de junho de 2026) — execute claude update e depois /model fable (o alias curto; /model claude-fable-5 e o alias best também o selecionam) — e está sendo disponibilizado gradualmente nos planos de assinatura até 22 de junho de 2026. 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 o sufixo removido (ele só teve utilidade no Opus/Sonnet, que exigem [1m] para liberar 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 raciocínios realmente difíceis, não para edições rotineiras. Ele compartilha a mesma interface de solicitação do Opus 4.8 (somente pensamento adaptativo; temperature/top_p/top_k e budget_tokens removidos), com uma diferença: definir explicitamente thinking: {type: "disabled"} retorna um erro 400; portanto, omita completamente o parâmetro thinking para executar sem pensamento.²⁰⁵

Especificamente no Claude Code: o Fable 5 oferece toda a escala de esforço (low/medium/high/xhigh/max, com high por padrão), assim como o Opus 5. O pensamento não pode ser desativado no Fable 5 — o controle de pensamento 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ções 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 se aplica aos gateways empresariais. /model opus agora seleciona o Opus 5 (esforço alto por padrão, /effort xhigh para as tarefas mais difíceis), e o Sonnet 5 é o padrão pronto para uso desde a v2.1.197; selecione deliberadamente o Fable 5 por meio de /model fable quando quiser a capacidade máxima absoluta.²⁰⁵¹⁹⁷

Opus 4.7 (16 de abril de 2026): O modelo principal da geração anterior, ainda totalmente disponível. Janela de contexto de 1M de tokens pelo preço padrão — sem custo adicional para contexto longo. Saída máxima de 128K, somente pensamento adaptativo (pensamento estendido 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, de US$ 5/US$ 25 por MTok, com gravação em cache por 5 minutos a US$ 6,25, gravação em cache por 1 hora a US$ 10 e leitura do cache a US$ 0,50 por MTok.¹⁴⁴ O Opus 4.7 resolve três vezes mais tarefas de produção no SWE-Bench 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 da Anthropic.¹⁴⁴ Ele usa um novo tokenizer — espere uma contagem de tokens cerca de 1× a 1,35× maior para o mesmo texto; aumente a margem de max_tokens e ajuste os gatilhos de compactação.¹⁴⁵ A visão oferece suporte a imagens de até 2.576 px/3,75 MP, com coordenadas de pixel na proporção 1:1.¹⁴⁵

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

Modelo padrão por plano (Claude Code):¹⁴⁷

Mudanças incompatíveis na API de Messages no Opus 4.7 (visíveis para quem faz a chamada):¹⁴⁵ - O budget_tokens do extended thinking foi removido. Use thinking: {type: "adaptive"} no lugar. O adaptive thinking 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 do 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 por streaming).

Os orçamentos de tarefa (cabeçalho beta task-budgets-2026-03-13) permitem informar ao modelo uma meta de tokens para um loop agentic completo por meio de output_config.task_budget; o mínimo é de 20 mil 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 128 mil tokens. Considere migrar para o Opus 4.7 para obter melhor desempenho em programação agentic. 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 o esforço high por padrão no Opus 4.6 e no Sonnet 4.6 (antes era medium); o Opus 4.7 permanece em xhigh. Essa mudança recuperou a inteligência após a redução de esforço ocorrida entre 4 de março e 7 de abril, documentada na análise retrospectiva de 23 de abril.¹⁵²¹⁵³

Sonnet 5 (30 de junho de 2026): O nível Sonnet atual, apresentado como “a melhor combinação de velocidade e inteligência”. A Anthropic afirma que seu desempenho é próximo ao do Opus 4.8, mas com preços menores, e que ele representa uma melhoria significativa em relação ao Sonnet 4.6 em raciocínio agentic, 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 cibersegurança muito mais fraca que a dos modelos Opus (a contrapartida de segurança que permitiu seu lançamento sem bloqueios 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 128 mil tokens (até 300 mil no Batches API com o cabeçalho beta output-300k-2026-03-24), somente adaptive thinking. Limite confiável de conhecimento: janeiro de 2026. Preço: US$ 3/US$ 15 por milhão de tokens de entrada/saída, com preço promocional de US$ 2/US$ 10 até 31 de agosto de 2026 — cerca de 40% abaixo dos US$ 5/US$ 25 do Opus 4.8. 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).¹⁸⁰ Desde a v2.1.197 (30 de junho de 2026), o Sonnet 5 é o modelo padrão no Claude Code para novas sessões, substituindo o Opus 4.8 como opção inicial; o Opus continua totalmente disponível para seleção.¹⁸¹

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 milhão de tokens). Melhor desempenho em buscas agentic, consumindo menos tokens. Compatível com extended thinking, adaptive thinking e uma janela de contexto de 1 milhão de tokens (beta). Saída máxima de 64 mil tokens (limite superior de 128 mil 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 voltado ao trabalho de cibersegurança defensiva, oferecido no âmbito do Project Glasswing.¹³⁹ Disponível somente por convite; não há disponibilidade geral. A Anthropic apresenta 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 elevado.¹⁴⁶

Por que essas diferenças de preço importam: Uma sessão típica de programação consome de 50 mil a 200 mil tokens de entrada e de 10 mil a 50 mil 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 em 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 principal para o desenvolvimento cotidiano quando o custo importa. Lida com a maioria das tarefas de programação: implementar recursos, corrigir bugs, escrever testes e revisar código. O Sonnet 4.6 oferece buscas agentic aprimoradas e melhor eficiência de tokens em comparação com o Sonnet 4.5, além de compatibilidade com adaptive thinking e uma janela de contexto de 1 milhão de tokens pelo preço padrão.⁹³ Desde o Opus 4.7 (16 de abril de 2026), o Claude Code usa o Opus por padrão apenas nos planos Max e Team Premium; contas Pro, Team Standard, Enterprise e API mantêm o Sonnet 4.6 como padrão até que Enterprise e API migrem para o Opus 4.7 em 23 de abril de 2026.¹⁴⁷ Use o Sonnet quando precisar de tokens mais baratos, menor latência ou uma melhor relação de custo para subagents.

Opus: O nível principal desde 16 de abril de 2026 e o padrão nos planos Max e Team Premium.¹⁴⁴¹⁴⁷ Reserve o raciocínio de custo mais alto para os casos em que ele compensa: decisões de arquitetura, debugging complexo, compreensão de sistemas complexos, análise de segurança e trabalho agentic de longo prazo. O Opus 4.7 resolve três vezes mais tarefas de produção no SWE-Bench que o Opus 4.6, alcança 70% no CursorBench (contra 58%) e aumenta em 13% a resolução em um benchmark interno de programação com 93 tarefas.¹⁴⁴ O Claude Code usa o esforço xhigh por 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 da Anthropic API, sem exigir --enable-auto-mode; outros planos e provedores têm disponibilidade específica por plano e controlada pelo administrador.¹⁴⁶ Contexto de 1 milhão de tokens pelo preço padrão — sem custo adicional por contexto longo. Mudanças de comportamento que você deve conhecer: O Opus 4.7 segue as instruções de forma mais literal, ajusta o tamanho da resposta à complexidade da tarefa, executa menos subagents por padrão e adota um tom mais direto, com menos frases voltadas à validação. Se os seus prompts contiverem estruturas para forçar mensagens intermediárias de progresso ou uma segunda verificação, experimente removê-las.¹⁴⁵

Opusplan: Um modo híbrido que usa o Opus no planejamento (em que a qualidade do raciocínio é mais importante) e o Sonnet na execução (em que 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 em cada edição individual.

Como trocar de modelo

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-4-5-20250929"
}

Especificamente para subagents:

export CLAUDE_CODE_SUBAGENT_MODEL=haiku

Cadeia de modelos de fallback (v2.1.166+): a configuração fallbackModel permite definir até três modelos de fallback, testados na ordem indicada quando o modelo principal está sobrecarregado ou indisponível. A flag --fallback-model (antes usada somente para trocar de modelo no meio da 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 a API retorna um erro inesperado que não permite nova tentativa, o Claude Code agora também repete a interação uma vez no modelo de fallback antes de apresentar a falha. Assim, um problema transitório no modelo principal causa uma degradação controlada, em vez de interromper a interação.²⁰⁷

Desde a v2.1.178, a compactação também respeita a cadeia de fallback — 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 provocar uma falha na interação. Em uma execução autônoma longa, isso elimina a lacuna pela qual 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 1 milhão de 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]

Opus 4.7, Opus 4.6 e Sonnet 4.6 incluem a janela de contexto completa de 1 milhão de tokens pelo preço padrão — sem custo adicional por contexto longo.¹⁴⁸ Uma solicitação de 900 mil tokens é cobrada pela mesma tarifa por token que uma solicitação de 9 mil tokens. Os descontos de prompt caching e processamento em lote se aplicam às tarifas padrão em toda a janela de contexto.

Nas assinaturas Max, Team e Enterprise, o Opus com contexto de 1 milhão de tokens é incluído automaticamente — não é necessário usar o sufixo [1m] (ativado por padrão desde a v2.1.75, em 13 de março de 2026).¹¹⁷¹⁴⁷ No Pro, o contexto de 1 milhão de tokens está disponível por meio do uso extra. Usuários da API e do modelo de pagamento conforme o uso têm acesso completo ao contexto de 1 milhão de tokens 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. A partir da v2.1.223, o alcance da variável mudou: ela limita todos os modelos com uma janela nativa de 1M a 200K por meio da compactação automática — 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 limitando a sessão a 200K. Se você definir essa variável para ter previsibilidade de custos em uma família de modelos, agora ela também se aplica a novos modelos de 1M desde o dia em que são 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.²⁰⁰

Como verificar o modelo atual

> /status

O comando mostra o modelo atual, as informações da conta, as configurações aplicadas e outros estados 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, com sugestões de upgrade quando há versões mais recentes disponíveis.⁹⁸ A v2.1.219 corrige a exibição da linha mesclada do Opus como apenas “Opus”, em vez de “Opus (contexto de 1M)”, e restringe o destaque de novo lançamento apenas ao nome do modelo mais recente, para que ele indique o que realmente foi lançado, e não uma parte arbitrária da lista.¹⁹⁶

Fast mode (v2.1.36+)

O fast mode oferece uma saída significativamente mais rápida com o mesmo modelo; ele não muda para um modelo mais barato. Ative ou desative 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 no 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.¹⁹⁶¹⁹⁸

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

A armadilha do Opus 4.7 (v2.1.219). Modelos incompatí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 recorre silenciosamente à 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 da degradação silenciosa das solicitações de fast mode, elas agora falham imediatamente; 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 do que o custo - Ao executar sequencialmente uma lista de tarefas semelhantes

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

O fast mode inclui a janela de contexto completa de 1M (v2.1.50+). O preço aplica um multiplicador fixo a todo o contexto, inclusive a 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 um limite de uso próprio, 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 fast e padrão invalida o cache de prompts — solicitações em velocidades diferentes não compartilham prefixos armazenados em cache, portanto alternar /fast no meio da sessão causa uma falha de cache. O fast mode não está disponível com o Batch API nem com um compromisso do Priority Tier.¹⁹⁸

Dica de especialista: o fast mode não funciona em conjunto com o 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 do que o custo e desative-o para trabalhos autônomos ou em lote. O /fast exige uso adicional; administradores de Team/Enterprise talvez precisem ativá-lo primeiro (correção da v2.1.37). Desative-o completamente com CLAUDE_CODE_DISABLE_FAST_MODE=1. A partir da 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 do 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 introduz um novo controle 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

Auto Mode no Max (v2.1.111+)

O Auto Mode — uma alternativa mais segura ao --dangerously-skip-permissions — está disponível para assinantes do Max no Opus 4.7 por meio da Anthropic API, sem --enable-auto-mode.¹⁴⁶ Um classificador do Sonnet 4.6 analisa cada ação antes da execução, verificando a correspondência com a intenção e a segurança. Observação (v2.1.111+): a flag --enable-auto-mode foi removida; inicie uma sessão no Auto Mode com --permission-mode auto. O Auto Mode não está disponível no Pro; segundo a documentação sobre modos de permissão da Anthropic, ele vem habilitado por padrão diretamente na Anthropic API. Bedrock/Vertex/Foundry (v2.1.158+): o Auto Mode passou a exigir ativação no Opus 4.7 e no Opus 4.8 nesses gateways com CLAUDE_CODE_ENABLE_AUTO_MODE=1.²¹⁰ A partir da v2.1.207, essa 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 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 por padrão e deixa de ler a configuração autoMode do .claude/settings.local.json de um repositório — configure as regras do Auto Mode em ~/.claude/settings.json.¹⁸⁵

Regras personalizadas sem perder os padrões (v2.1.118+). Nas versões anteriores, autoMode.allow, autoMode.soft_deny e autoMode.environment funcionavam de forma excludente: ao definir sua própria lista, você perdia as regras de segurança integradas. O sentinela $defaults resolve isso — ele é expandido inline para a lista integrada exatamente na posição em que você o coloca, permitindo combinar regras personalizadas com as 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
    ]
  }
}

Opção “Não perguntar novamente” (v2.1.118+). O prompt de ativação do Auto Mode agora oferece a opção “Não perguntar novamente”, permitindo que usuários frequentes ocultem a explicação sem precisar programar uma flag.¹⁵²

Proteções contra comandos destrutivos (v2.1.183). O Auto Mode agora bloqueia por completo um conjunto de comandos irreversíveis, a menos que você os tenha solicitado explicitamente na 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 nesta sessão; e desativação 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 eliminar trabalho silenciosamente ou desativar ambientes — o agente ainda pode executá-las, mas apenas mediante sua 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 modo automático só analisa 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 para o classificador, trocando um pouco de latência por uma camada de segurança mais rigorosa quando você quer que todas as chamadas de shell sejam avaliadas. A mesma versão também exibe os motivos de recusa do modo automático na transcrição, na notificação de recusa e nas recusas recentes de /permissions, portanto um comando bloqueado agora explica por que foi bloqueado.¹⁷⁹

Mais três regras de reforço de segurança (v2.1.205). Agora, o modo automático 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 categoria de acidentes com rm -rf $DIR quando $DIR é desconhecida; e as notificações de tarefas em segundo plano agora informam explicitamente que não houve nenhuma interação humana, para que uma linha falsa como “usuário aprovou” dentro de uma transcrição não possa ser usada como uma aprovação válida. 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 pode esconder uma catástrofe (v2.1.208). Remoções catastróficas, como rm -rf ~, agora solicitam confirmação mesmo quando estão escondidas dentro de $(...), backticks ou substituição de processo (<(...)) — e a solicitação aparece até mesmo em --dangerously-skip-permissions e no modo automático. 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 modo automático: claude auto-mode reset (v2.1.212). Um novo subcomando redefine o estado do modo automático pelo terminal; use --yes para ignorar a solicitação 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 modo automático com uma caixa de diálogo de permissão — rm perigoso, & em segundo plano e caminhos suspeitos do Windows — não fazem mais isso; agora, o classificador do modo automático decide sobre elas, portanto a análise de segurança continua acontecendo sem exigir sua intervenção a cada ocorrência. A mesma versão estende esse comportamento ao modo de planejamento com o modo automático: comandos Bash que o analisador estático não consegue comprovar como somente leitura não solicitam mais confirmação — o classificador os avalia em vez de recorrer a uma caixa de diálogo.¹⁹⁵

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 “Enviar push quando Claude decidir” habilitada, o Claude pode enviar notificações push para dispositivos móveis por conta própria usando uma nova ferramenta de notificações push. Isso complementa 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+, implantação gradual)

O Claude Code está recebendo gradualmente uma ferramenta Windows PowerShell nativa. No Linux/macOS, habilite-a com CLAUDE_CODE_USE_POWERSHELL_TOOL=1 (requer pwsh no PATH). No Windows, a mesma variável controla a adesão ou desativação durante a implantação gradual.¹⁴⁶

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

Redução das solicitações de permissão: 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> && não acionam mais uma solicitação de permissão.¹⁴⁶ Combinado com /less-permission-prompts, isso deve reduzir significativamente as interrupções nos fluxos de trabalho cotidianos.

Rastreamento distribuído (v2.1.110+)

Sessões do SDK e headless agora leem TRACEPARENT e TRACESTATE do ambiente, vinculando as execuções do Claude Code a rastreamentos distribuídos. Combine isso 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ário nativo (v2.1.113+)¹⁵⁰

A v2.1.113 muda a forma como o CLI é iniciado: agora, claude inicia 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 permanecem 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 recebe navegação no estilo readline em entradas com várias linhas, além de rolagem da área de visualização em tela cheia:

Timeout de inatividade de subagents (v2.1.113+)¹⁵⁰

Subagents que ficam paralisados durante o streaming agora falham com um erro claro após 10 minutos, em vez de permanecerem travados silenciosamente. Combine isso 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 falhar quando um colega de equipe do Agent Teams solicitava permissão para usar uma ferramenta. Atualize se você usa o Agent Teams.

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 modelo para conhecer os recursos dos modelos e Frameworks de decisão para escolher o modelo certo para cada tarefa.

Como visualizar os 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+).¹³⁷

Planos de assinatura

Limites de uso (agosto de 2025): a Anthropic introduziu limites semanais de uso para assinantes de planos pagos. Assinantes Max podem comprar uso adicional além do limite pelas tarifas padrão da 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 licença, eliminou a redução em horários de pico nas contas Pro e Max e aumentou “consideravelmente” os limites de uso da API para os modelos Claude Opus. A garantia de capacidade é o acordo com o SpaceX Colossus 1: “mais de 300 megawatts de nova capacidade (mais de 220.000 NVIDIA GPUs) dentro de um mês”.¹⁵⁷

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

Para usuários cobrados pela API, o preço por milhão de tokens é:

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 custo adicional por contexto longo.¹⁴⁸ Essa é uma consolidação recente; orientações antigas segundo as quais o Opus 4.6 ou o Sonnet 4.6 custavam 2× mais na entrada e 1,5× mais na saída acima de 200K tokens de entrada não são mais atuais. O Opus 4.5 legado e os modelos anteriores mantêm suas estruturas de preços originais.

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

O armazenamento de prompts em cache reduz significativamente os custos de entradas repetidas: gravações no cache custam 1,25× o valor-base (cache de 5 minutos) ou 2× (cache de 1 hora), mas as leituras custam apenas 0,1×, uma economia de 90%. Para sistemas RAG e assistentes de programação com contexto repetido, o cache pode reduzir os custos em 88% a 95%.

A 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 para múltiplas 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 permitidas - As contas são totalmente separadas; não é possível transferir chats ou projetos entre elas

O que é proibido (de acordo com a Política de uso): - Criar contas para evitar bloqueios após uma conta ser banida - Coordenar atividades maliciosas entre contas para evitar detecção - Usar várias contas para burlar 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 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 por várias contas, é exatamente para isso que o serviço foi desenvolvido, mas não tente manipular o sistema.

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

Fatores de custo

Exemplos de custos reais

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

Gerenciamento de custos da equipe

TPM/RPM recomendados por tamanho de 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 custa cerca de 24.500 tokens de entrada adicionais apenas em sobrecarga.

Estratégias para economizar

1. Use Haiku em subagents: a maioria das explorações não precisa do Sonnet
2. Ative o cache de prompts: ele vem ativado por padrão, mas confirme que não foi desativado
3. Defina o máximo de turnos: claude --max-turns 5 evita conversas sem controle
4. Defina um limite em dólares: claude --max-budget-usd 5 interrompe a sessão quando ela atinge o teto de gastos. A partir da v2.1.217, o limite também se aplica aos subagents em segundo plano — quando ele é atingido, novas inicializações são negadas e os agentes em segundo plano que estiverem em execução são interrompidos (antes, os agentes em segundo plano não eram afetados pelo orçamento)¹⁹⁴
5. Use o modo de planejamento para exploração: sem execução = sem operações caras acidentais
6. Compacte de forma proativa: menos contexto = menos tokens
7. Limite a saída: export CLAUDE_CODE_MAX_OUTPUT_TOKENS=2000
8. Use a API em lote para trabalhos não urgentes: 50% de desconto nos tokens de entrada e de saída

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 de custos nativo da nuvem
• LiteLLM: para monitoramento detalhado por usuário com provedores de terceiros

Uso 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

Geralmente, o custo fica abaixo de US$ 0,04 por sessão.

API de analytics do Claude Code (Team/Enterprise)⁴⁶

Acesse por programação os analytics de uso e as métricas de produtividade do Claude Code da sua organização por meio da API de administração.

Endpoint: GET /v1/organizations/usage_report/claude_code

Requisitos: - Chave da API de administração (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.) - Monitoramento e alocação de custos entre equipes - Justificativa de ROI para ferramentas de programação com IA

Observação: os dados aparecem em até 1 hora após a conclusão da atividade. Para garantir consistência, as respostas incluem apenas dados com mais de 1 hora.

Estruturas de decisão

Conhecer os recursos 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 4.7 (xhigh effort default)
                  │         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: Opus 4.7 é o padrão para Max e Team Premium. No Pro/Team Standard/Enterprise/API, Sonnet 4.6 é o padrão (Enterprise + Anthropic API mudarão para Opus 4.7 em 23 de abril de 2026).¹⁴⁷ Use Haiku para subagents. Passe para Opus quando a resposta do Sonnet parecer superficial. Com agent teams (v2.1.32+), 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 o 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 de thinking maiores custam mais; comece com o mínimo e aumente apenas se as respostas parecerem apressadas.

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

Qual ambiente 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, por 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 granular 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 - Encontra 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, encontrar 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 onde um símbolo está definido - Encontrar 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 de 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 permanecem válidas durante a sessão, a menos que você configure explicitamente outro comportamento.

Ferramenta EndConversation (v2.1.214). O Claude Code agora conta com a mesma capacidade de encerrar conversas que o Claude tem no claude.ai desde 2025: em casos raros de conteúdo altamente abusivo ou tentativas persistentes de jailbreak, o Claude pode encerrar imediatamente a sessão por meio da ferramenta integrada EndConversation. Essa é uma medida de resistência a abusos e de bem-estar do modelo, não 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 mudança 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 —, mas o nome 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 um tempo limite de inatividade por meio de /config.

Agora, arquivos de configuração que permitem a execução de código 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, ele 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 similares). O motivo é que editar qualquer um desses arquivos transforma o próximo shell, instalação ou commit em um vetor de execução — por isso, eles recebem uma verificação deliberada, mesmo em um modo para projetos confiáveis que normalmente libera edições sem confirmação. Esse é o mesmo modelo de ameaça das proteções de gravação já existentes para .claude/, .git/ e .vscode/, agora estendido à categoria mais ampla de arquivos nos quais “editar significa permitir execução”.²⁰⁹

Auto Mode (v2.1.85+): Uma alternativa mais segura ao --dangerously-skip-permissions. Um modelo classificador separado (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 e negação são processadas primeiro - Todo o restante é enviado ao classificador para avaliação - Se algo for bloqueado, o Claude tenta automaticamente uma abordagem alternativa

Bloqueados automaticamente por padrão: curl | bash, force-push para a 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 de confirmação manuais.¹²⁵

# Enable at startup
claude --enable-auto-mode

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

Disponibilidade: primeiro para usuários do plano Team, seguidos por Enterprise e API. Exige Sonnet 4.6 ou Opus 4.6.¹²⁴

Modo YOLO (v2.0.68+): Para uma operação totalmente autônoma sem nenhum classificador de segurança, use a flag --dangerously-skip-permissions. Essa flag diz sim a tudo: edições de arquivos, comandos bash e todas as chamadas de ferramentas. A palavra “dangerous” é intencional. O Auto Mode é 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"
  }
}

Sintaxe das regras de permissão

Regras granulares controlam operações específicas. As regras 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 a 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://... porque as opções aparecem antes da URL. Para um bloqueio confiável, negue o comando inteiro: Bash(curl:*).

Padrões de operações com 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 inicial: Read(~/.zshrc)

Agora, regras de permissão dir/** com um único segmento 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 lugar da árvore — vendor/src/, packages/foo/src/, todos eles. Agora, ela corresponde somente ao diretório src diretamente abaixo do diretório de trabalho. Se você dependia do antigo comportamento de correspondência 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 silenciosamente deixa de corresponder aparece como novas solicitações de permissão após a atualização, não como um erro; por isso, verifique todas as regras de permissão escritas no formato de segmento único. As condições if: de hooks receberam o mesmo escopo relativo ao diretório de trabalho nesta versão (consulte Matchers).¹⁹⁰

Use Edit(path)/Read(path), não Write(path)/NotebookEdit(path)/Glob(path) (v2.1.210). Agora, o Claude Code 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 todas as ferramentas de leitura de arquivos (incluindo Glob). Migre as regras legadas para eliminar o aviso e manter a intenção explícita.¹⁸⁷

A opçã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 de confirmação agora são gravadas na raiz do repositório, em vez do 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.¹⁸⁸

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 habilitar 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 libere apenas um conjunto restrito. As regras de permissão, por outro lado, rejeitam globs que não sejam do MCP — você não pode permitir tudo de forma abrangente da mesma maneira, 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 — o próprio início é negado, não apenas a solicitação para evitá-lo. Isso amplia o controle de permissões de “qual ferramenta” para “como ela é chamada”, usando uma regra determinística em vez de uma solicitação no prompt. Essa regra funciona em conjunto com a configuração gerenciada enforceAvailableModels: a lista de permissões define quais níveis de modelo existem para a sessão, enquanto as regras Tool(model:...) restringem como os subagents podem utilizá-los.¹⁷³

Desde a v2.1.186, essas regras Agent(...) também são aplicadas à inicialização de subagents nomeados: regras de negação Agent(agent_type) e restrições de tipos permitidos Agent(x,y) agora se aplicam 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 momento em que ocorre, eliminando uma brecha pela qual um agente nomeado poderia contornar uma regra criada para restringi-lo.¹⁷⁵

Padrões WebFetch:

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

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 defina 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 exfiltração de segredos por um comando no sandbox.¹⁷⁶

Desde a v2.1.221, os arquivos de credenciais contam com 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 — seja do arquivo inteiro ou apenas dos trechos capturados por uma expressão regular extract —, e o proxy do sandbox substitui o valor real no tráfego de saída. O comando funciona (ele pode se autenticar por meio do proxy) sem que o segredo esteja presente em seu ambiente, exatamente a propriedade desejada quando um comando afetado por prompt injection procura tokens. No macOS, onde o mecanismo de substituição do proxy não está disponível, mask recorre a deny — assim, uma configuração criada para CI no Linux perde funcionalidade de forma segura, 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 processam valores estruturados de ambiente; decode: "jwt" com maskClaims mascara claims específicos dentro de um JWT, em vez de mascarar o token inteiro, para que um comando ainda possa ler os metadados de roteamento do token enquanto os claims confidenciais permanecem como valores sentinela; e awsPairs/sigv4 assinam novamente as solicitações AWS SigV4 no proxy, o que torna o mascaramento viável com os CLIs da AWS — caso contrário, uma chave mascarada falharia na verificação de assinatura. Todos esses recursos exigem network.tlsTerminate e só são respeitados nos escopos de usuário, gerenciado ou --settings — um repositório não pode incluir 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 e mantém o controle do tráfego de saída da rede — útil quando a restrição 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 indicada 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 “pergunte sobre tráfego de saída inesperado” não é a política adequada. Ela completa a tríade de rede: allowedDomains informa o que é permitido, deniedDomains (abaixo) cria exceções dentro de uma permissão ampla, e strictAllowlist decide se todo o restante gera uma solicitação ou falha.¹⁹⁶

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

Dica para especialistas: 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 do Anthropic constataram que o sandbox reduz as solicitações de permissão em 84%.³⁸ O sandbox usa recursos no nível do sistema operacional (seatbelt do macOS e bubblewrap do Linux) para isolar o sistema de arquivos e a rede. Assim, até mesmo uma prompt injection bem-sucedida fica totalmente contida. O Anthropic disponibilizou o runtime do sandbox como código aberto para equipes que desenvolvem seus próprios agentes.⁸²

Notas de segurança (v2.1.34+): Anteriormente, comandos excluídos do sandbox por meio de sandbox.excludedCommands ou dangerouslyDisableSandbox podiam ignorar 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 uma 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 liberar subdiretórios específicos.¹¹⁹

Exceção para 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 desse diretório, não apenas a partir da raiz do repositório; em caso de conflito de nomes, a skill aninhada pode ser acessada como <dir>:<name>, de modo que ambas permaneçam disponíveis. O restante da estrutura do projeto é resolvido da mesma maneira — quando o nome de um agente, fluxo de trabalho ou estilo de saída entra em conflito entre diretórios .claude/ aninhados, prevalece aquele mais próximo do diretório de trabalho, e o salvamento de um fluxo de trabalho no escopo do projeto tem como destino o diretório .claude/workflows/ existente mais próximo. Em um monorepo ou repositório de repositórios, isso oferece ferramentas específicas de cada pacote que são ativadas conforme o contexto, em vez de uma única estrutura 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 locais não convencionais dos binários bubblewrap e socat. Isso é útil quando as distribuições instalam essas ferramentas fora do $PATH ou quando a organização fornece builds reforçados.¹⁶⁰

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

• sandbox.network.deniedDomains bloqueia hosts específicos mesmo quando um curinga mais amplo em allowedDomains normalmente 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 fora da lista de permissões seja recusado silenciosamente, em vez de gerar uma solicitação.
• Regras de negação para comandos wrapper. Agora, as regras de negação do Bash 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 semelhantes de desvio.
• As regras de permissão Bash(find:*) não aprovam mais automaticamente find -exec ou 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. Agora, as regras de permissão Bash(rm:*) tratam /private/etc, /private/var, /private/tmp e /private/home como destinos perigosos de remoção. /var, /etc e /tmp são links simbólicos para caminhos dentro de /private/, portanto, o formato anterior da regra não detectava os destinos canônicos.

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

Diversas brechas nas verificações de permissão foram corrigidas em uma única versão, sempre adotando uma postura de falha segura — quando o analisador não consegue ter certeza, ele solicita confirmação:

• Correção de desvio no Windows PowerShell 5.1. Anteriormente, comandos executados em sessões do PowerShell 5.1 podiam escapar da verificação de permissão.
• Redirecionamentos de descritores de arquivo do Bash agora falham de forma segura. 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, 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.
• Variantes não seguras de help/man não são mais aprovadas automaticamente. Certas invocações podiam executar opções não seguras, substituições de comandos ou caminhos com barras invertidas sob o pretexto de consultar a documentação.
• Ordem das solicitações em sessões remotas. As solicitações de permissão em sessões remotas não podem mais prosseguir antes da caixa de diálogo de confirmação local.
• Flags de redirecionamento do daemon do docker solicitam confirmação. Comandos docker (incluindo o shim docker do Podman) com --url, --connection, --identity ou o modo remoto do Podman eram executados anteriormente sem solicitar confirmação — essas flags direcionam o comando para um daemon completamente diferente.
• file perde sua liberação automática de somente leitura quando recebe instruções sobre 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 os hooks funcionam?

Os hooks executam comandos shell determinísticos em pontos específicos do fluxo de trabalho do Claude Code. Ao contrário de pedir ao Claude que execute 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” funciona às vezes. Mas o Claude pode esquecer, priorizar a velocidade ou decidir que a alteração é “pequena demais”. Os hooks garantem a execução: toda ação 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

Valores de source em SessionStart. A entrada do hook SessionStart inclui um campo source que informa como a sessão começou: "startup", "resume", "clear" ou "compact". A partir da v2.1.214, uma sessão que começa como um fork informa source: "fork" em vez de "resume" — a contraparte do hook para a mudança de /fork para segundo plano da v2.1.212. Se um hook SessionStart se ramificar com base em source (por exemplo, reinjetando o contexto apenas em "resume"), atualize sua lista de correspondências para incluir "fork" também.¹⁹⁰

Configuração de hooks

Defina hooks em settings.json ou em um hooks.json dedicado:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$FILE_PATH\""
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/validate-bash.sh"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/inject-context.sh"
          }
        ]
      }
    ]
  }
}

Matchers

O campo matcher determina quais ferramentas acionam um hook:

{"matcher": "*"}              // Match all tools
{"matcher": "Bash"}           // Match Bash only
{"matcher": "Edit|Write"}     // Match Edit or Write
{"matcher": "mcp__github"}    // Match MCP server tools
{"matcher": ""}               // Match for events without tools (like UserPromptSubmit)

Use | para corresponder a várias ferramentas (Edit|Write). A partir da v2.1.191, matchers separados por vírgulas (por exemplo, Bash,PowerShell) também são acionados corretamente — versões anteriores os descartavam silenciosamente, portanto um hook com um matcher que continha vírgula nunca era executado.¹⁷⁸ A partir da v2.1.195, matchers com identificadores que contêm hífen (por exemplo, code-reviewer, mcp__brave-search) fazem uma correspondência exata em vez de corresponderem acidentalmente a substrings. Assim, um matcher não é mais acionado por ferramentas não pretendidas que apenas contêm a string. Para corresponder a todas as ferramentas de um servidor MCP com hífen, use um padrão explícito como mcp__brave-search__.*.¹⁷⁹

A partir da v2.1.214, as condições de caminho if: dos hooks têm o escopo do cwd. A mesma alteração de escopo de segmento único que afetou as regras de permissão allow (consulte Sintaxe das regras de permissão) se aplica às condições if: dos hooks: uma condição como dir/** agora corresponde apenas a <cwd>/dir, e não a todos os diretórios dir/ da árvore. Use **/dir/** quando quiser restaurar a correspondência em qualquer profundidade.¹⁹⁰

Protocolo de entrada/saída dos hooks

Os hooks recebem JSON pela entrada padrão:

{
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite"
  },
  "session_id": "abc-123"
}

Enriquecimento de eventos de hooks (v2.1.69+): Todos os eventos de hooks agora incluem os campos agent_id e agent_type quando são acionados por um subagent ou uma sessão --agent, além de um campo worktree nos comandos de hooks da linha de status.¹¹⁰

Os hooks Stop/SubagentStop (v2.1.47+) recebem um campo adicional last_assistant_message contendo o texto da resposta final do Claude, para que os hooks possam inspecionar a saída sem analisar arquivos de transcrição:

{
  "session_id": "abc-123",
  "last_assistant_message": "I've completed the refactoring. Here's what changed..."
}

Feedback sem bloqueio (v2.1.163+): Os hooks Stop e SubagentStop podem retornar hookSpecificOutput.additionalContext em sua saída JSON para fornecer feedback ao Claude e manter o turno em andamento, sem que a resposta seja identificada como um erro de hook. Antes disso, o único recurso real de um hook Stop era o bloqueio com saída 2 (que aparece como erro e conta para o limite de bloqueios consecutivos); additionalContext adiciona um canal de orientação para instruções como “veja o que você deixou passar e continue”, sem entrar em conflito com o loop.²⁰⁸

Os códigos de saída controlam o comportamento: - 0: Sucesso: a operação prossegue. A saída padrão é exibida no modo detalhado (Ctrl+O). Para UserPromptSubmit e SessionStart, a saída padrão é adicionada ao contexto. - 2: Erro de bloqueio: a operação é interrompida. A saída de erro se torna a mensagem de erro enviada de volta ao Claude. - 1, 3 etc.: Erro sem bloqueio: a operação continua. A saída de erro é exibida como aviso no modo detalhado.

Para controle avançado, os hooks podem gerar JSON:

{
  "decision": "allow",
  "message": "Command validated and modified",
  "modifications": {
    "tool_input": {
      "command": "npm test -- --coverage"
    }
  }
}

Controle de decisão PreToolUse (formato recomendado): Os hooks PreToolUse usam hookSpecificOutput para um controle mais completo: três resultados (permitir/negar/perguntar), além da capacidade de modificar a entrada da ferramenta e injetar contexto:⁸⁹

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "Command validated and modified",
    "updatedInput": {
      "command": "npm test -- --coverage --ci"
    },
    "additionalContext": "Note: This database has a 5-second query timeout."
  }
}

Observação: Os campos decision e reason no nível superior foram descontinuados para PreToolUse. Use hookSpecificOutput.permissionDecision e hookSpecificOutput.permissionDecisionReason. Outros eventos (PostToolUse, Stop etc.) ainda usam decision no nível superior.⁸⁹

Título da sessão em UserPromptSubmit (v2.1.94+): Os hooks UserPromptSubmit podem definir o título da sessão por meio de hookSpecificOutput.sessionTitle.¹⁴⁰

Hooks assíncronos (janeiro de 2026)

Agora os hooks podem ser executados em segundo plano sem bloquear a execução do Claude Code. Adicione async: true à configuração do hook:⁸¹

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/notify-slack.sh",
            "async": true
          }
        ]
      }
    ]
  }
}

Quando usar hooks assíncronos: - Notificações (Slack, e-mail, Pushover) que não devem deixar a sessão mais lenta - Registros e telemetria que podem ser executados em segundo plano - Pós-processamento não crítico (analytics, backups)

Quando NÃO usar hooks assíncronos: - Formatação (deve terminar antes da próxima edição) - Validação (deve bloquear em caso de falha) - Qualquer hook que precise modificar a entrada/saída da ferramenta

Hooks baseados em prompt e em agente (v2.1.32+)

Além dos hooks de comando shell (type: "command"), o Claude Code oferece suporte a dois tipos de hooks baseados em LLM que avaliam condições usando raciocínio de IA, em vez de scripts.⁸⁹

Hooks de prompt (type: "prompt") enviam um prompt de turno único a um modelo rápido do Claude. O modelo retorna { "ok": true } para permitir ou { "ok": false, "reason": "..." } para bloquear:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Evaluate if Claude should stop: $ARGUMENTS. Check if all requested tasks are complete and tests pass.",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Hooks HTTP (type: "http") enviam a entrada JSON do evento como uma solicitação POST para uma URL e recebem JSON de volta. Use-os para webhooks, serviços externos de notificação ou validação baseada em API (v2.1.63+):¹⁰⁴

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "http",
            "url": "https://api.example.com/notify",
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

Os hooks HTTP usam o mesmo formato de decisão dos hooks de comando (retornam JSON com decision e reason). Eles são encaminhados pelo proxy de rede do sandbox quando o sandbox está ativado. Não são compatíveis com os eventos SessionStart/Setup.

Hooks de agente (type: "agent") iniciam um subagent com acesso a ferramentas (Read, Grep, Glob) para verificação em vários turnos. Use-os quando a verificação exigir a inspeção de arquivos reais ou da saída dos testes:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify all unit tests pass. Run the test suite and check results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

Use $ARGUMENTS como placeholder para a entrada JSON do hook. Ambos os tipos aceitam os campos model (o padrão é o modelo rápido) e timeout. Eventos compatíveis: PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, UserPromptSubmit, Stop, SubagentStop, TaskCompleted. TeammateIdle não aceita hooks de prompt/agente.

Hooks de ferramenta MCP (v2.1.118+)

Agora os hooks podem invocar diretamente uma ferramenta MCP por meio de type: "mcp_tool", sem a necessidade de encapsular um subprocesso Bash que chame o servidor.¹⁵²

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "mcp_tool",
            "server": "linear",
            "tool": "create_comment",
            "input": {"issue_id": "ENG-123", "body": "Auto-updated by Claude Code"}
          }
        ]
      }
    ]
  }
}

Isso funciona bem com os servidores MCP que os usuários já configuraram: qualquer ferramenta acessível por /mcp pode ser chamada por um hook.

duration_ms em hooks PostToolUse (v2.1.119+)

As entradas dos hooks PostToolUse e PostToolUseFailure agora incluem duration_ms, o tempo de execução da ferramenta sem contar as solicitações de permissão e os hooks PreToolUse.¹⁵² Isso é útil para detectar ferramentas lentas, manter logs de auditoria e coletar métricas de latência por ferramenta:

# Stderr-flagged warning when an Edit takes more than 10 seconds
DUR=$(jq -r '.duration_ms')
if [ "$DUR" -gt 10000 ]; then
  echo "[slow-edit] ${DUR}ms — investigate $TOOL_INPUT_FILE_PATH" >&2
fi

updatedToolOutput para todas as ferramentas (v2.1.121+)

Na v2.1.118, os hooks de ferramenta MCP ganharam a capacidade de substituir a saída da ferramenta por meio de hookSpecificOutput.updatedToolOutput. A partir da v2.1.121, o mesmo campo funciona para qualquer hook PostToolUse — ferramentas integradas (Bash, Read, Edit, Glob, Grep etc.), ferramentas de subagents e ferramentas MCP. Casos de uso: ocultar conteúdo confidencial da saída de qualquer ferramenta, normalizar a estrutura para consumidores posteriores e injetar metadados antes que o agente leia o resultado.¹⁵⁴

Variáveis de ambiente dos hooks

Os hooks têm acesso a variáveis de ambiente para resolver caminhos:⁸⁹

Manter variáveis de ambiente do SessionStart:

#!/bin/bash
if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"
fi
exit 0

Segurança dos hooks HTTP (v2.1.51+): Os hooks HTTP que interpolam variáveis de ambiente em cabeçalhos agora exigem uma lista explícita allowedEnvVars. Isso impede a exfiltração arbitrária de variáveis de ambiente por meio dos valores dos cabeçalhos. Os hooks HTTP também são encaminhados pelo proxy de rede do sandbox quando o sandbox está ativado, aplicando a lista de domínios permitidos. Os hooks HTTP não são compatíveis com os eventos SessionStart/Setup.⁹⁸

{
  "hooks": {
    "PostToolUse": [{
      "hooks": [{
        "type": "command",
        "command": "curl -H 'Authorization: Bearer $MY_TOKEN' https://api.example.com/notify",
        "allowedEnvVars": ["MY_TOKEN"]
      }]
    }]
  }
}

Confiança no workspace para hooks (v2.1.51+): Os comandos de hooks statusLine e fileSuggestion agora exigem a aceitação da confiança no workspace antes de serem executados no modo interativo, eliminando um possível vetor de segurança.⁹⁸

Exemplos práticos de hooks

Formatar automaticamente arquivos TypeScript depois da edição:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c '[[ \"$FILE_PATH\" == *.ts ]] && npx prettier --write \"$FILE_PATH\" || true'"
          }
        ]
      }
    ]
  }
}

Registrar todos os comandos bash:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/bash-history.log"
          }
        ]
      }
    ]
  }
}