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 206 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 Claude Code e ver a saída, faça isto nesta 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 cobre implantação corporativa — mas nada disso é necessário para começar.

Pré-requisitos: Node 18+ apenas para o caminho legado via npm; o instalador nativo recomendado não depende do Node. macOS / Linux / Windows 10+ são compatíveis. Uma assinatura Claude Pro, Max, Team ou Enterprise, ou uma chave Anthropic API com pagamento por token, cobre o uso. Consulte Como instalar Claude Code? para detalhes por plataforma, solução de problemas e o caminho do binário nativo (padrão desde a v2.1.113). As evidências da versão mais recente neste guia foram verificadas contra a v2.1.154.²⁰⁶

Como Claude Code funciona: o modelo mental

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

┌─────────────────────────────────────────────────────────┐
│                    CLAUDE CODE LAYERS                    │
├─────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                         │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐    │
│  │   MCP   │  │  Hooks  │  │ Skills  │  │ Plugins │    │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘    │
│  External tools, deterministic automation, domain       │
│  expertise, packaged extensions                          │
├─────────────────────────────────────────────────────────┤
│  DELEGATION LAYER                                        │
│  ┌─────────────────────────────────────────────────┐    │
│  │              Subagents (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 central: Sua conversa principal. Cada mensagem, leitura de arquivo e saída de ferramenta consome contexto de uma janela compartilhada (200K tokens por padrão⁹¹, 1M tokens com Opus 4.6 ou modelos de contexto estendido). Quando o contexto fica cheio, Claude perde o rastro de decisões anteriores e a qualidade cai. Esta camada custa dinheiro por token.

Camada de delegação: Subagents são iniciados com contextos limpos, fazem trabalho focado e retornam resumos. Os resultados da exploração não incham sua conversa principal; apenas as conclusões retornam. Direcione subagents para tiers de modelo mais baratos para exploração, ou use seu modelo principal do início ao fim se a qualidade for mais importante que o custo.

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

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

sumário

1. Como instalar Claude Code?
2. Início rápido: sua primeira sessão
3. Modos principais de interação
4. Aprofundamento no sistema de configuração
5. Qual modelo devo escolher?
6. Quanto custa Claude Code?
7. Frameworks de decisão
8. Como funciona o sistema de permissões?
9. Como funcionam os hooks?
10. O que é MCP (Model Context Protocol)?
11. O que são subagents?
12. O que é o modo Extended Thinking?
13. Estilos de saída
14. Slash commands
15. Como funcionam as skills?
16. Sistema de plugins
17. Como funciona a memória?
18. Entrada de imagem e multimodal
19. Modo de voz
20. Como funciona a integração com Git?
21. Como usar Claude Code no meu IDE?
22. Padrões de uso avançado
23. Remote & Background Agents [RESEARCH PREVIEW]
24. Claude no Chrome
25. Claude Code no Slack [RESEARCH PREVIEW]
26. Claude Code na web [RESEARCH PREVIEW]
27. Otimização de performance
28. Como depurar problemas?
29. Implantação corporativa
30. Referência de atalhos de teclado
31. Boas práticas
32. Receitas de workflow
33. Guia de migração
34. Orientação por público
35. Cartão de referência rápida
36. Changelog
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 de interação principais

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 mesmo após 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 deve ser preservado.

Modo não interativo

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

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

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

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

Para gerar uma saída estruturada adequada para processamento 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 no stream-json (v2.1.211+): por padrão, a saída stream-json inclui apenas os eventos da sessão principal — o trabalho realizado dentro de subagents aparece como um resumo. A flag --forward-subagent-text (ou CLAUDE_CODE_FORWARD_SUBAGENT_TEXT=1) também encaminha para o stream os textos e o raciocínio dos subagents. Assim, sistemas de execução e pipelines de logs podem acompanhar o trabalho delegado conforme ele acontece, em vez de ver apenas o relatório final.¹⁸⁸

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

Códigos de saída:

Como controlar o comportamento autônomo 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 que você possa retomá-la. Essa persistência é 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 um pull request ou merge request específico. Desde a v2.1.119, --from-pr aceita URLs de MRs do GitLab, PRs do Bitbucket e PRs do GitHub Enterprise, além de github.com:⁷⁴¹⁵²

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

As sessões também são vinculadas automaticamente aos PRs quando você os 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 direciona os links dos PRs para uma ferramenta de revisão separada.¹⁵²

/resume aceita URLs de PRs (v2.1.122+). Ao colar a URL de um PR na caixa de busca de /resume, agora você encontra a sessão que criou originalmente esse PR — funciona com github.com, GitHub Enterprise, gitlab.com (inclusive GitLab auto-hospedado) e bitbucket.org.¹⁵⁴

Sessões nomeadas: dê nomes às sessões na inicialização 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, prefira /rename e --resume.

/fork cria uma sessão em segundo plano; /subtask é a bifurcaçã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 anterior — bifurcar dentro da sessão atual — continua disponível com o novo nome /subtask.¹⁸⁹ Desde a v2.1.214, uma sessão iniciada como bifurcação informa a origem "fork" no hook SessionStart (antes era "resume"), permitindo que hooks baseados na origem diferenciem as duas situações.¹⁹⁰ A v2.1.216 simplifica a confirmação de /fork para uma única linha que mostra o nome da nova sessão e seu id de claude attach.¹⁹²

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

Modo de planejamento

O modo de planejamento restringe Claude à exploração somente leitura — sem editar arquivos, executar Bash ou realizar ações destrutivas. Claude elabora uma abordagem de implementação, grava-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 para 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. Grava 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 as edições automaticamente” (Shift+Tab) — recomeça com todo o contexto disponível para o plano - “Sim, e aprovar as edições manualmente” — preserva o contexto; você aprova cada alteração - “Sim, aceitar as edições automaticamente” — preserva o contexto; Claude executa sem solicitar aprovação para cada edição

Limpar o contexto automaticamente após a aprovação é o fluxo de trabalho recomendado. Isso oferece ao plano uma nova janela de contexto, 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 envolvam decisões de arquitetura - Refatorações em vários arquivos quando você quiser analisar primeiro a abordagem - Bases de código desconhecidas, nas quais a exploração deve preceder as modificações - Qualquer tarefa com várias abordagens válidas em que você queira participar da decisão

Dica de especialista: quanto mais tempo você dedicar ao 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 maneiras:¹⁸⁶

# 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 detalhada do sistema de configuração

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

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.

Como definir 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 biblioteca grande de skills, mas quer limitar melhor 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 continue sendo chamada pelo nome, mas removê-la 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 (gerenciadas, v2.1.175+): a lista de permissões availableModels restringe os modelos que uma sessão pode selecionar. Com enforceAvailableModels: true, a lista também limita o modelo Default — se um Default resultar em um modelo não permitido, o primeiro modelo autorizado será usado — e as configurações de usuário ou projeto não poderão mais ampliar uma lista gerenciada de availableModels. Uma correção complementar (v2.1.176) elimina a brecha que permitia redirecionar a escolha de um alias 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 modelo diretamente no seletor de /model, em --model, /model e ANTHROPIC_MODEL — ao selecionar um modelo restrito, é exibida a mensagem “restrito pelas configurações da sua organização”.¹⁷⁶
• language (aperfeiçoamento da v2.1.176): além de definir o idioma das respostas, os títulos das sessões agora 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 identificados por regex 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 o modo de leitor de tela permanentemente (consulte Modo de leitor de tela).¹⁸⁶
• processWrapper (v2.1.208): encaminha, por meio de um executável wrapper, todos os processos que Claude Code inicia para si mesmo — desenvolvido para launchers corporativos (consulte Launcher corporativo).¹⁸⁶
• Restrição de 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 forma de um repositório clonado fornecer uma configuração de modo automático.¹⁸⁵

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

• emojiCompletionEnabled (v2.1.217): preenchimento automático de códigos abreviados de emoji 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): bloqueia hosts que não estejam na lista de permissões para comandos executados no sandbox sem solicitar confirmação, em vez de exibir uma caixa de diálogo de permissão. Consulte Modo sandbox.¹⁹⁶
• workflowSizeGuideline (v2.1.219): define a diretriz 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. Os workflows Dynamic usam, por padrão, uma diretriz média (“tenha como meta 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; /clear resets the budget; v2.1.212+)[^206]
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               # Disable 1M context window (use standard 200K)[^103]
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 de 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 de LLM. user_system_prompt é condicionado a OTEL_LOG_USER_PROMPTS=1, pois pode conter PII.¹⁵⁴

Alterações no nível dos eventos na v2.1.122+: os atributos numéricos nos eventos de log api_request e api_error agora são emitidos como números (antes eram strings) — isso corrige coletores OTel posteriores 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, condicionado a OTEL_LOG_ASSISTANT_RESPONSES. Esse controle tem uma peculiaridade importante ao atualizar: 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 o conteúdo das respostas do assistente após a atualização. Defina OTEL_LOG_ASSISTANT_RESPONSES=0 para manter a telemetria limitada aos prompts.¹⁷⁹

Adições de telemetria da v2.1.214: os eventos de log OTel agora incluem os atributos message.uuid, client_request_id e tool_source para correlação no nível das mensagens e rastreamento da origem das ferramentas; o payload 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 os atributos de conteúdo OTel.¹⁹⁰

API / Controle de 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 alterações incompatíveis ao migrar um harness do Opus 4.8 para o Opus 5:¹⁹⁷

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

Especificamente no Claude Code: o padrão de effort é high no Opus 5 (assim como 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 do que o consumo de tokens. O modo rápido abrange 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 desenvolvido para manter a coerência em contextos com milhões de tokens. O Fable 5 é o modelo de fronteira da “classe Mythos” preparado para uso geral com segurança: ele inclui classificadores de segurança que recorrem ao Opus 4.8 em consultas sobre cibersegurança, bioquímica e destilação de modelos (o Claude Mythos 5 é o mesmo modelo sem essas proteções, 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 para os 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), o nome de modelo claude-fable-5[1m] é automaticamente normalizado para claude-fable-5, removendo o sufixo (ele só teve utilidade no Opus/Sonnet, que condicionam o contexto de 1M ao uso de [1m]); saída máxima de 128K. O preço é de US$ 10/MTok de entrada e US$ 50/MTok de saída — cerca de 2 vezes o preço do Opus 4.8 —, portanto, reserve-o para problemas de raciocínio realmente difíceis, não para edições rotineiras. Ele compartilha a interface de solicitação do Opus 4.8 (somente raciocínio adaptativo; temperature/top_p/top_k e budget_tokens removidos), com uma particularidade: usar explicitamente thinking: {type: "disabled"} retorna um erro 400, portanto, omita totalmente o parâmetro thinking para executar sem raciocínio.²⁰⁰

Especificamente no Claude Code: o Fable 5 é compatível com toda a escala de esforço (low/medium/high/xhigh/max, sendo high o padrão), assim como o Opus 5. O raciocínio não pode ser desativado no Fable 5 — o controle de raciocínio da sessão, a configuração alwaysThinkingEnabled e MAX_THINKING_TOKENS=0 não têm efeito; ele sempre raciocina de forma adaptativa. Uma interface 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 é resolvido (útil no Bedrock/Vertex/Foundry), DISABLE_PROMPT_CACHING_FABLE exclui o Fable do cache de prompts, e o fallback automático baseado no conteúdo é aplicado nos 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 inicial desde a v2.1.197; selecione o Fable 5 de propósito por meio de /model fable quando quiser o máximo absoluto de capacidade.²⁰⁰¹⁹⁷

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 acréscimo por contexto longo. Saída máxima de 128K, somente raciocínio adaptativo (raciocínio 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.¹⁴⁵ Data-limite de conhecimento confiável: janeiro de 2026. Data-limite dos dados de treinamento: janeiro de 2026. ID do modelo: claude-opus-4-7. O preço corresponde ao do Opus 4.6, a 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 3 vezes mais tarefas de produção no SWE-Bench do que o Opus 4.6, alcança 70% no CursorBench (contra 58% da versão 4.6) e aumenta em 13% a taxa de resolução no benchmark interno de programação com 93 tarefas da Anthropic.¹⁴⁴ Ele usa um novo tokenizer — espere contagens de tokens aproximadamente 1 a 1,35 vez maiores para o mesmo texto; aumente a margem de max_tokens e ajuste os gatilhos de compactação.¹⁴⁵ O recurso de visão aceita imagens de até 2.576 px/3,75 MP com coordenadas de pixel 1:1.¹⁴⁵

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

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

Alterações incompatíveis da API Messages no Opus 4.7 (visíveis para quem faz a chamada):¹⁴⁵ - O budget_tokens do extended thinking foi removido. Use thinking: {type: "adaptive"}. 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 restaurar o raciocínio visível (obrigatório se o seu produto transmite o thinking aos usuários).

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

Opus 4.6 (legado): Ainda disponível como claude-opus-4-6, com contexto de 1 milhão e saída máxima de 128 mil. Considere migrar para o Opus 4.7 para obter melhor desempenho em programação agêntica. O Opus 4.6 foi lançado originalmente em 5 de fevereiro de 2026.⁷⁹¹⁴⁴ Desde a v2.1.117 (22 de abril de 2026), assinantes Pro e Max usam high como esforço padrão no Opus 4.6 e no Sonnet 4.6 (antes era medium); o Opus 4.7 permanece em xhigh. Essa mudança restaurou 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”. 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 agêntico, uso de ferramentas, programação e trabalho intelectual — ao mesmo tempo que apresenta uma taxa geral menor de comportamentos indesejáveis e uma capacidade de cibersegurança muito mais limitada 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 fixado sem data). Janela de contexto de 1 milhão de tokens, saída máxima de 128 mil (até 300 mil na API Batches com o cabeçalho beta output-300k-2026-03-24), apenas adaptive thinking. Limite de conhecimento confiável: 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 agênticas com menor consumo de 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 (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 prévia de pesquisa para trabalhos defensivos de cibersegurança, oferecido pelo Project Glasswing.¹³⁹ Disponível apenas por convite; não está disponível de forma geral. 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 entre 50 mil e 200 mil tokens de entrada e entre 10 mil e 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 fazem exploração, buscas simples de arquivos e perguntas rápidas. Ele custa cerca de cinco vezes menos que o Opus e responde mais rápido. É perfeito para tarefas em segundo plano que não exigem raciocínio profundo.

Sonnet: A principal opção para o desenvolvimento diário quando o custo importa. Resolve a maioria das tarefas de programação: implementar recursos, corrigir bugs, escrever testes e revisar código. O Sonnet 4.6 oferece melhores buscas agênticas e maior eficiência no uso 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 pelo preço padrão.⁹³ Desde o Opus 4.7 (16 de abril de 2026), o Claude Code usa o Opus como 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 melhor economia 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 situações em que ele compensa: decisões de arquitetura, depuração complexa, compreensão de sistemas complexos, análise de segurança e trabalho agêntico 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 taxa de resolução em um benchmark interno de programação com 93 tarefas.¹⁴⁴ O Claude Code usa 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 pelo preço padrão — sem 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 das respostas à 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 incluírem estruturas para forçar mensagens intermediárias de progresso ou verificações adicionais, experimente removê-las.¹⁴⁵

Opusplan: Um modo híbrido que usa o Opus para o planejamento (quando a qualidade do raciocínio é mais importante) e o Sonnet para a execução (quando a velocidade importa). Excelente para refatorações complexas nas quais você quer o melhor plano, mas não precisa do nível de raciocínio do Opus 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 configurar até três modelos de fallback, testados em ordem quando o modelo principal está sobrecarregado ou indisponível. A flag --fallback-model (antes usada apenas para trocar de modelo durante a 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 o turno uma vez usando o modelo de fallback antes de apresentar a falha. Assim, um problema transitório no modelo principal causa uma degradação controlada, em vez de descartar o turno.²⁰²

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 causar falha no turno. Em uma execução autônoma longa, isso elimina a situação em que uma compactação que poderia ser recuperada derrubava a sessão por causa de 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]

O Opus 4.7, o Opus 4.6 e o Sonnet 4.6 incluem a janela de contexto completa de 1 milhão de tokens pelo preço padrão — sem 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 está 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 pode ser acessado por meio do uso extra. Usuários da API e do modelo de pagamento conforme o uso têm acesso completo a 1 milhão de tokens pelas tarifas padrão por token.¹⁴⁷

Para desativar as variantes de contexto de 1 milhão no seletor de modelos, defina CLAUDE_CODE_DISABLE_1M_CONTEXT=1.

Como verificar o modelo atual

> /status

O comando mostra o modelo atual, as informações da conta, as configurações aplicadas e outros dados do estado da sessão. Rótulos do seletor de modelos (v2.1.51+): o seletor /model agora exibe rótulos legíveis (por exemplo, “Sonnet 4.6”) em vez de IDs brutos de modelos para versões fixadas, com sugestões de upgrade quando há versões mais recentes disponíveis.⁹⁸ A v2.1.219 corrige a renderização da linha mesclada do Opus como simplesmente “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 (desde a 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 nem na 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 sem suporte não se comportam da mesma forma. Uma solicitação ao claude-opus-4-7 com speed: "fast" agora retorna um erro — ela não volta silenciosamente para a velocidade padrão. O Opus 4.6 é a exceção que torna isso importante: ele aceita speed: "fast", mas executa 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 redução silenciosa das solicitações do Fast Mode para a velocidade padrão, elas agora falham de imediato; 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 usa um multiplicador fixo em todo o contexto, inclusive para solicitações com mais de 200K tokens de entrada — sem sobretaxa adicional por contexto longo — e é aplicado sobre os multiplicadores de cache de prompts e residência de dados.⁹⁶¹⁹⁸

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

Dica de especialista: o Fast Mode não funciona em conjunto com opusplan (opusplan já combina Opus e Sonnet; o Fast Mode afeta apenas a parte 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. /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. Desde a v2.1.218, o Claude Code avisa quando uma troca de modelo por /config model=<x> ou Remote Control altera o estado do Fast Mode, e a v2.1.219 corrigiu clientes 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 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; em vez disso, 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 está disponível diretamente na Anthropic API por padrão. 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.²⁰⁵ Desde a v2.1.207, a ativação não é mais necessária: o Auto Mode funciona no AWS Bedrock, Google Vertex AI e Microsoft Foundry sem CLAUDE_CODE_ENABLE_AUTO_MODE, e administradores que quiserem desativá-lo podem usar a configuração gerenciada disableAutoMode. A mesma versão faz com que Bedrock, Vertex AI e Claude Platform on AWS usem o Claude Opus 4.8 como padrão e deixa de ler a configuração autoMode do .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 eram mutuamente exclusivos: ao definir sua própria lista, você perdia as regras de segurança integradas. O sentinela $defaults resolve isso — ele se expande diretamente para a lista integrada exatamente na posição em que você o insere, 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”, para que usuários frequentes possam ocultar a explicação sem precisar criar um script com uma flag.¹⁵²

Proteções contra comandos destrutivos (v2.1.183). O Auto Mode agora bloqueia completamente um conjunto de comandos irreversíveis, a menos que você os 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 desmonte 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 para as operações que podem eliminar trabalho silenciosamente ou desmontar ambientes — o agente ainda pode executá-las, mas apenas mediante sua instrução explícita, não por iniciativa própria.¹⁷⁴

Classificar todos os comandos do shell (v2.1.193). Por padrão, o classificador do Auto Mode analisa apenas comandos do 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 faz com que todos os comandos Bash/PowerShell passem pelo classificador, trocando um pouco de latência por uma camada de segurança mais rigorosa quando você quer que todas as chamadas do shell sejam avaliadas. A mesma versão também exibe os motivos de negação do Auto Mode na transcrição, na notificação de negação e nas negações recentes de /permissions, portanto um comando bloqueado agora explica por que foi bloqueado.¹⁷⁹ Mais três regras de proteção (v2.1.205). O modo auto agora bloqueia alterações nos arquivos de transcrição da sessão — o próprio registro de auditoria fica fora do alcance do agente; ele pede confirmação antes de executar rm -rf em uma variável que não consegue resolver pelo contexto — eliminando a classe de acidentes envolvendo rm -rf $DIR com $DIR desconhecido; e as notificações de tarefas em segundo plano agora declaram explicitamente que não houve nenhuma interação humana, portanto, uma linha falsa dizendo “usuário aprovou” dentro de uma transcrição não pode ser validada e transformada em uma aprovação efetiva.¹⁸³ A terceira é uma defesa contra injeção de prompt que vale a pena internalizar: a aprovação precisa chegar pelo canal de aprovação, e o harness agora torna essa premissa explícita.

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

Redefina o estado do modo auto: claude auto-mode reset (v2.1.212). Um novo subcomando redefine o estado do modo auto pelo terminal; use --yes para pular 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 auto com uma caixa de diálogo de permissão — rm perigoso, & em segundo plano e caminhos suspeitos do Windows — não fazem mais isso; o classificador do modo auto passa a avaliá-las, portanto, a revisão de segurança continua acontecendo sem colocar você no circuito a cada ocorrência. A mesma versão estende isso ao modo plan com auto: os 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 “Push when Claude decides” ativada, o Claude agora pode enviar notificações push para dispositivos móveis a seu critério por meio de uma nova ferramenta de notificações push. Funciona em conjunto com a interface móvel/web existente do Remote Control.¹⁴⁶ /context, /exit e /reload-plugins agora também funcionam em clientes do Remote Control.

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

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

Aprovação automática no modo de permissão (v2.1.119+). Os comandos da ferramenta PowerShell agora 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 ignoram a confirmação em operações somente leitura, oferecendo a mesma praticidade operacional que as equipes já têm no Linux/macOS.¹⁵²

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

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

Rastreamento distribuído (v2.1.110+)

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

Distribuição do binário nativo (v2.1.113+)¹⁵⁰

A v2.1.113 altera 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 lançamento.

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

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

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

Subagents que travam no meio de um fluxo agora falham com um erro claro após 10 minutos, em vez de ficarem parados silenciosamente. Use em conjunto com CLAUDE_STREAM_IDLE_TIMEOUT_MS (v2.1.84+) para ampliar a cobertura contra processos travados em APIs de streaming.

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

A v2.1.114 (18 de abril de 2026) traz uma única correção: a caixa de diálogo de permissão podia travar 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á para 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: Consulte 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 persistem durante a sessão, a menos que sejam explicitamente configuradas de outra forma.

Ferramenta EndConversation (v2.1.214). Agora, o Claude Code conta com o mesmo recurso para 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 a sessão imediatamente por meio da ferramenta integrada EndConversation. Trata-se de uma medida de resistência a abusos e de bem-estar do modelo, não de um recurso de fluxo de trabalho — ela nunca é acionada em sessões normais de desenvolvimento.¹⁹⁰¹⁹³

Modos de permissão

O modo default passou a ser identificado como “Manual” na 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 parecer “o modo que você recebe por padrão”, quando na verdade se trata do modo de aprovação manual. Na mesma versão, as caixas de diálogo AskUserQuestion deixaram de continuar automaticamente por padrão; agora, um subagent que faz uma pergunta aguarda sua resposta em vez de prosseguir após um tempo limite, e você pode reativar o tempo limite de inatividade por meio de /config.

Agora, arquivos de configuração que podem executar código geram uma solicitação de confirmação até no modo 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 em 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 uma edição em qualquer um desses arquivos transforma o próximo shell, instalação ou commit em um vetor de execução — por isso, eles recebem uma barreira deliberada até em um modo para projetos confiáveis que normalmente aprova edições sem intervenção. Esse é o mesmo modelo de ameaças das proteções de gravação existentes para .claude/, .git/ e .vscode/, ampliado para a categoria mais abrangente de arquivos nos quais uma “edição se transforma em 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 é 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 resolvidas primeiro - Todas as outras ações são encaminhadas ao classificador para avaliação - Se uma ação for bloqueada, o Claude tenta automaticamente uma abordagem alternativa

Bloqueados automaticamente por padrão: curl | bash, force-push para a branch principal, 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 bloqueios no total durante uma sessão fazem o sistema voltar às solicitações manuais de confirmação.¹²⁵

# 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, com Enterprise e API na sequência. Exige Sonnet 4.6 ou Opus 4.6.¹²⁴

YOLO Mode (v2.0.68+): Para uma operação totalmente autônoma sem nenhum classificador de segurança, use a flag --dangerously-skip-permissions. A flag aceita 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 prevalece.

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://..., pois 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 de 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 absolutos verdadeiros: Edit(//tmp/**) - começam com // - Diretório pessoal: Read(~/.zshrc)

Agora, regras de permissão dir/** com um único segmento correspondem somente a <cwd>/dir (v2.1.214) — audite suas regras existentes. Antes da v2.1.214, uma regra de permissão como Edit(src/**) aprovava automaticamente gravações em qualquer diretório chamado src em qualquer nível da árvore — vendor/src/, packages/foo/src/, todos eles. Agora, ela corresponde somente ao diretório src diretamente abaixo do diretório de trabalho. Se você dependia do antigo comportamento 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 resulta em novas solicitações de permissão após a atualização, não em um erro; por isso, verifique todas as regras de permissão escritas no formato de segmento único. As condições if: dos hooks receberam o mesmo escopo baseado no cwd nessa versão (consulte Padrões de correspondência).¹⁹⁰

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). Os formatos canônicos 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 (inclusive Write e NotebookEdit), enquanto Read(path) abrange as ferramentas de leitura de arquivos (inclusive 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). Agora, as regras de permissão criadas pela opção “Always allow” da solicitação de confirmação são gravadas na raiz do repositório, e não no worktree atual. Assim, uma aprovação concedida em um worktree persiste entre sessões e em todos os worktrees desse repositório — não é mais necessário 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 novamente apenas um conjunto restrito. Já as regras de permissão rejeitam globs que não sejam do MCP — você não pode permitir tudo de forma tão abrangente, o que mantém a postura padrão restritiva.²⁰²

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

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

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

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

Desde a v2.1.186, essas regras Agent(...) também são aplicadas à inicialização de subagents nomeados: as regras de negação Agent(agent_type) e as restrições de tipos permitidos Agent(x,y) agora se aplicam quando um agente nomeado específico é iniciado (por meio de um fluxo de trabalho, de --agents ou de 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 de 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 executados no sandbox leiam arquivos de credenciais e variáveis de ambiente secretas — uma defesa em profundidade contra a exfiltração de segredos por comandos executados no sandbox.¹⁷⁶

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

Desde a v2.1.219, a configuração sandbox.network.strictAllowlist nega imediatamente os hosts que não estão na lista de permissões, sem solicitar confirmação. Por padrão, quando um comando executado no sandbox acessa um host que não consta em allowedDomains, uma solicitação de permissão é exibida; com strictAllowlist ativado, a conexão é simplesmente recusada. Essa é a configuração ideal para execuções sem supervisão — CI, agentes em segundo plano e loops noturnos —, nas quais uma solicitação que ninguém responde paralisa o processo e “pergunte-me sobre tráfego de saída inesperado” não é a política adequada. Ela completa o trio de controles de rede: allowedDomains define o que é permitido, deniedDomains (abaixo) cria exceções em uma permissão abrangente e strictAllowlist determina se todo o restante solicita confirmação ou falha.¹⁹⁶

Durante a execução no sandbox: - O acesso ao sistema de arquivos fica restrito ao diretório do projeto - O acesso à rede é controlado - Determinados comandos ficam isentos das restrições do sandbox - Os comandos Bash são permitidos automaticamente quando autoAllowBashIfSandboxed é 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 extra de proteção. Testes internos do Anthropic constataram que o sandbox reduz as solicitações de permissão em 84%.³⁸ O sandbox usa recursos do sistema operacional (seatbelt do macOS e bubblewrap do Linux) para isolar o sistema de arquivos e a rede. Assim, até uma injeção de prompt 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 contornar a regra de solicitação de permissão do Bash quando autoAllowBashIfSandboxed estava ativado; isso foi corrigido na v2.1.34.⁸⁷ Desde a v2.1.38, gravações em .claude/skills são bloqueadas no modo sandbox, impedindo que uma injeção de prompt modifique as definições de skills.⁸⁸ A v2.1.77 adiciona uma configuração de sistema de arquivos allowRead ao 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): As skills presentes em diretórios .claude/skills aninhados agora são carregadas automaticamente quando você trabalha em arquivos dentro desse diretório, e 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 superfície do projeto é resolvido da mesma maneira — quando há conflito entre nomes de agentes, fluxos de trabalho ou estilos de saída em diretórios .claude/ aninhados, prevalece aquele mais próximo do diretório de trabalho, e um fluxo de trabalho salvo no escopo do projeto é direcionado ao .claude/workflows/ existente mais próximo. Para um monorepo ou um repositório de repositórios, isso oferece ferramentas específicas para cada pacote, ativadas conforme o contexto, em vez de uma única superfície global e plana.¹⁷³

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

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

• sandbox.network.deniedDomains bloqueia hosts específicos mesmo quando um curinga mais abrangente em allowedDomains permitiria o acesso. Use a lista de bloqueios para impedir acesso a pastebins, serviços de compartilhamento de arquivos ou hosts reconhecidamente maliciosos sem precisar reescrever toda a 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 encapsuladores. Agora, as regras de negação do Bash correspondem a comandos encapsulados 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 usados para contornar restrições.
• As regras de permissão Bash(find:*) não aprovam mais automaticamente find -exec nem find -delete. Essas flags executam comandos e excluem arquivos, portanto, o Claude Code as encaminha pelo fluxo normal de permissões.
• Proteção contra remoção no macOS. Agora, as regras de permissão Bash(rm:*) tratam /private/etc, /private/var, /private/tmp e /private/home como destinos perigosos para remoção. /var, /etc e /tmp são links simbólicos para /private/, portanto, o formato anterior da regra não detectava os destinos canônicos.

Reforço do bloqueio seguro de permissões na v2.1.214:¹⁹⁰

Um conjunto de brechas na verificação de permissões foi corrigido em uma única versão, sempre adotando o bloqueio seguro — quando o analisador não consegue ter certeza, ele solicita confirmação:

• Correção do bypass no Windows PowerShell 5.1. Anteriormente, comandos executados em sessões do PowerShell 5.1 podiam escapar da verificação de permissões.
• Redirecionamentos de descritores de arquivo do Bash agora adotam o bloqueio seguro. Formas de redirecionamento interpretadas pelo bash de maneira diferente da usada pelo analisador de permissões agora solicitam confirmação em vez de serem executadas.
• Comandos com mais de 10.000 caracteres sempre solicitam confirmação. Comandos muito longos eram avaliados incorretamente; agora, eles nunca são executados automaticamente.
• Subscritos e modificadores do zsh dentro de [[ ]] solicitam confirmação. Subscritos e modificadores de variáveis em comparações [[ ]] eram tratados como texto inerte; como podem executar código, agora exigem aprovação.
• Variantes inseguras de help/man não são mais aprovadas automaticamente. Determinadas invocações podiam executar opções inseguras, substituições de comandos ou caminhos com barras invertidas sob o pretexto de consultar documentação.
• Ordem das solicitações em sessões remotas. 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 de daemon do docker solicitam confirmação. Comandos docker (inclusive o shim docker do Podman) com --url, --connection, --identity ou o modo remoto do Podman eram executados sem confirmação — essas flags direcionam o comando para um daemon completamente diferente.
• O comando file perde sua aprovação automática de somente leitura quando recebe instruções para gravar. Agora, file -m/--magic-file e -f/--files-from 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"
          }
        ]
      }
    ]
  }
}

Bloquear o acesso a arquivos confidenciais:

#!/bin/bash
# .claude/hooks/protect-files.sh
data=$(cat)
path=$(echo "$data" | jq -r '.tool_input.file_path // empty')

if [[ "$path" == *".env"* ]] || [[ "$path" == *"secrets/"* ]] || [[ "$path" == *".pem"* ]]; then
  echo "Blocked: Cannot access sensitive file $path" >&2
  exit 2  # Exit 2 = block the tool call. Exit 1 = non-blocking error (hook failure only).
fi
exit 0