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

TL;DR: Claude Code é um CLI agentic que lê sua base de código, executa comandos e modifica arquivos por meio de um sistema em camadas de permissões, hooks, integrações MCP e subagents. Domine cinco sistemas centrais (configuração, permissões, hooks, MCP e subagents) e você libera uma produtividade multiplicadora. Escolha o nível de modelo adequado para cada tarefa — Opus para raciocínio complexo, Sonnet para trabalho geral, Haiku para exploração rápida — ou padronize em Opus se qualidade for sua única variável. Use hooks (não prompts) para qualquer coisa que sempre precise ser executada. A partir da v2.1.174–176 (12 de junho de 2026), a allowlist availableModels agora pode restringir o modelo Default por meio da nova configuração gerenciada enforceAvailableModels (configurações de usuário/projeto não podem ampliar uma lista gerenciada), os títulos de sessão são gerados no idioma da sua conversa (fixe um com a configuração language), e novas configurações footerLinksRegexes e wheelScrollAccelerationEnabled, uma caixa de diálogo de atribuição /usage no VSCode e uma correção que faz as condições if de hooks corresponderem aos padrões de caminho Read/Edit/Write completam a release.¹⁷² A partir da v2.1.173 (11 de junho de 2026), um nome de modelo Fable 5 com sufixo [1m] é automaticamente normalizado/removido — Fable 5 já inclui contexto de 1M por padrão, então o sufixo é desnecessário (ele só foi relevante em Opus/Sonnet). A partir da v2.1.172 (10 de junho de 2026), sub-agents podem criar recursivamente seus próprios sub-agents, até 5 níveis de profundidade, Bedrock lê sua 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. A partir da v2.1.170 (9 de junho de 2026), Claude Fable 5 — um novo nível de modelo acima do Opus — pode ser selecionado no Claude Code via /model fable depois de claude update (ele oferece suporte à escala completa de esforço de low a max, mas não permite desativar thinking); Opus 4.8 continua sendo o padrão agentic. A partir da v2.1.169 (8 de junho de 2026), --safe-mode (e CLAUDE_CODE_SAFE_MODE) inicia uma sessão limpa com todas as customizações desativadas para troubleshooting, /cd move uma sessão para um novo diretório de trabalho sem quebrar o cache de prompt, e disableBundledSkills oculta as skills e os slash commands integrados do modelo. A partir da 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 em regras deny de MCP, e MAX_THINKING_TOKENS=0 / --thinking disabled desativam completamente o thinking em modelos que pensam por padrão. A partir da v2.1.154 (28 de maio de 2026), Opus 4.8 é o novo padrão, com esforço alto por padrão e um nível /effort xhigh, dynamic workflows orquestram dezenas a centenas de agentes em segundo plano via /workflows, o Fast mode no Opus 4.8 custa 2× a tarifa padrão para 2,5× a velocidade, o lean system prompt agora é padrão para todos os modelos, exceto Haiku/Sonnet/Opus 4.7 e anteriores, /simplify voltou a ser uma revisão apenas de limpeza (separada de /code-review --fix), claude agents aceita ! <command> para criar sessões de shell em segundo plano, plugins podem declarar defaultEnabled: false, a execução de ferramentas em streaming está sempre ativada, e servidores MCP stdio recebem CLAUDE_CODE_SESSION_ID mais CLAUDECODE=1 no env. A v2.1.153 adicionou skipLfs aos marketplaces de plugins, fez /model ser salvo como padrão (pressione s para aplicar apenas à sessão) e colocou COLUMNS/LINES no env da linha de status. A v2.1.152 introduziu /code-review --fix (aplica os findings à working tree), disallowed-tools no frontmatter de skills, /reload-skills, o novo evento de hook MessageDisplay, saídas reloadSkills/sessionTitle do hook SessionStart, a configuração gerenciada pluginSuggestionMarketplaces, troca de --fallback-model no meio da sessão, e removeu o opt-in do auto-mode.^{162 163 164 165 166 167 168 169 170 180 171}

Claude Code opera como um sistema agentic, 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 de git, conecta-se a serviços externos via MCP e delega tarefas complexas a subagents especializados. Tudo flui por uma interface de linha de comando que se integra à forma como desenvolvedores realmente trabalham. Em fevereiro de 2026, 4% dos commits públicos no GitHub (~135.000 por dia) eram de autoria do Claude Code — um crescimento de 42.896× em 13 meses desde o research preview — e 90% do código da própria Anthropic é escrito por IA.¹⁰³

A diferença entre o uso casual e o uso eficaz do Claude Code se resume a cinco sistemas centrais. Domine estes sistemas e o Claude Code se torna um multiplicador de força:

1. Hierarquia de configuração: controla o comportamento
2. Sistema de permissões: controla o acesso às operações
3. Sistema de hooks: permite automação determinística
4. Protocolo MCP: amplia capacidades
5. Sistema de subagents: lida com tarefas complexas de várias etapas

Principais pontos

• Cinco sistemas determinam sua eficácia: hierarquia de configuração, permissões, hooks, MCP e subagents controlam tudo, do comportamento à automação.
• Empurre trabalho para a camada de delegação: subagents evitam inchaço de contexto ao isolar exploração em janelas de contexto limpas, retornando apenas resumos.
• Hooks garantem execução; prompts não: use hooks para linting, formatação e verificações de segurança que precisam rodar sempre, independentemente do comportamento do modelo.
• Níveis de modelo reduzem custo sem sacrificar qualidade: direcione a exploração de subagents para modelos mais baratos e reserve Opus para raciocínio arquitetural real — ou padronize em Opus se qualidade for sua única variável.
• MCP conecta Claude à sua toolchain: bancos de dados, GitHub, Sentry e mais de 3.000 integrações ampliam Claude para além de leitura de arquivos e 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 enterprise. Este guia condensa essa experiência na referência completa que eu gostaria que existisse quando comecei. Cada recurso inclui sintaxe real, exemplos reais de configuração e os edge cases que pegam até usuários experientes.

Escolha seu caminho

Como usar este guia

Esta é uma referência com mais de 5.000 linhas — você não precisa lê-la de ponta a ponta. Comece pelo ponto que combina com seu nível de experiência:

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

Aprofundamentos relacionados

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

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                           # Inicia no diretório atual

2. Navegue até um projeto:

cd ~/my-project && claude        # Ou inicie a partir de qualquer repositório git

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 a sessão:

/cost                            # Verifica o uso de tokens e o custo
/compact                         # Libera contexto quando ele fica muito grande
Alt+T                            # Alterna o pensamento estendido para problemas difíceis
Ctrl+C                           # Cancela a resposta atual

5. Continue depois:

claude -c                        # Retoma sua sessão mais recente
claude --resume                  # Escolhe a partir da lista de sessões

Dica de especialista: Crie um arquivo CLAUDE.md na raiz do seu projeto com comandos de build, convenções de código e notas de arquitetura. O Claude lê esse arquivo em toda sessão — é a coisa de maior alavancagem que você pode fazer pela qualidade.

Modos principais de interação

REPL interativo

Inicie o Claude Code sem argumentos para entrar no read-eval-print loop interativo:

cd your-project
claude

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

Inicie com um prompt inicial para focar a sessão:

claude "explain the authentication flow in this project"

Dica de especialista: O REPL preserva o estado entre eventos de compactação. Quando o contexto fica muito grande, o Claude resume automaticamente as conversas mais antigas, preservando decisões importantes e trechos de código. Você pode acionar isso manualmente com /compact ou adicionar instruções personalizadas sobre o que preservar.

Modo não-interativo

O modo print (-p) executa uma única consulta e sai:

# 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 saída estruturada adequada para parsing 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 processamento em tempo real de saída em streaming:

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:

Códigos de saída:

Controlando o comportamento agêntico no modo -p:

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

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

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

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

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

Padrão de integração 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ão

As sessões preservam o histórico de conversas para continuação. A persistência de sessão é essencial para trabalhos complexos com múltiplas 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 PR (v2.1.27+, expandido em v2.1.119+): Inicie uma sessão vinculada a um pull ou merge request específico. A partir da v2.1.119, --from-pr aceita URLs de MR do GitLab, PR do Bitbucket e PR do GitHub Enterprise, além de github.com:⁷⁴¹⁵²

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

As sessões também são automaticamente vinculadas a PRs quando você os cria via gh pr create durante uma sessão. Isso facilita retomar o trabalho em um PR específico depois. O badge de 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 seu time vincula PRs a uma ferramenta de revisão separada.¹⁵²

/resume aceita URLs de PR (v2.1.122+). Colar uma URL de PR na caixa de busca do /resume agora encontra a sessão que originalmente criou aquele PR — funciona em github.com, GitHub Enterprise, gitlab.com (e GitLab auto-hospedado) e bitbucket.org.¹⁵⁴

Sessões nomeadas: Nomeie 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

Nota: --session-id requer um UUID válido (por exemplo, 550e8400-e29b-41d4-a716-446655440000). Para nomeação de sessão legível, use /rename e --resume.

O Claude Code armazena sessões como transcrições JSONL. A execução de agentes atribui valores únicos de agentId com transcrições armazenadas como agent-{agentId}.jsonl. A retomada preserva o contexto completo de conversas anteriores.

Modo plano

O modo plano restringe o Claude a exploração somente leitura — sem edições de arquivo, sem execução de bash, sem ações destrutivas. O Claude projeta uma abordagem de implementação, escreve em um arquivo de plano e aguarda sua aprovação antes de executar qualquer coisa.

Entrando no modo plano:

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

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

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

Como funciona:

1. O Claude entra no modo plano (automaticamente para tarefas complexas, ou via Shift+Tab)
2. Explora o código usando ferramentas somente leitura: Read, Glob, Grep, WebSearch, WebFetch
3. Escreve um plano em .claude/plans/{session-slug}.md
4. Sai do modo plano com ExitPlanMode, apresentando o plano para sua revisão
5. Você aprova, solicita mudanças ou rejeita

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

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

Limpar o contexto automaticamente na aprovação é o fluxo recomendado. Isso dá ao plano uma janela de contexto fresca, o que melhora significativamente a aderência ao plano — o Claude mantém o foco por mais tempo sem que conversas antigas interfiram.

Quando usar o modo plano: - Implementações de novas funcionalidades com decisões arquiteturais - Refatorações em múltiplos arquivos onde você quer revisar a abordagem antes - Bases de código desconhecidas em que a exploração deve preceder a modificação - Qualquer tarefa em que existam várias abordagens válidas e você queira opinar

Dica de especialista: Quanto mais tempo você passa no modo plano, mais provável que o Claude tenha sucesso na implementação. O modo plano é exploração praticamente gratuita — sem chamadas de ferramentas arriscadas, sem edições desperdiçadas. Use à vontade.

Análise profunda do sistema de configuração

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

Hierarquia de configuração

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

Referência completa do settings.json

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

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

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

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

• availableModels / enforceAvailableModels (gerenciado, v2.1.175+): a allowlist availableModels restringe quais modelos uma sessão pode selecionar. Com enforceAvailableModels: true, a allowlist também limita o modelo Default — um Default que resolveria para um modelo não permitido volta para o primeiro modelo permitido — e configurações de usuário/projeto não podem mais ampliar uma lista availableModels gerenciada. Uma correção complementar (v2.1.176) fecha a lacuna em que a escolha de um alias podia redirecionar para um modelo bloqueado via ANTHROPIC_DEFAULT_*_MODEL, e /fast agora se recusa a alternar para um modelo fora da allowlist.¹⁷²
• language (refinamento 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 correspondidos por regex na linha do rodapé, configuráveis via configurações de usuário ou gerenciadas.¹⁷²
• wheelScrollAccelerationEnabled (v2.1.174): defina como false para desativar a aceleração de rolagem da roda do mouse no modo fullscreen.¹⁷²

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 modelo:

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 provedor de cloud:

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]

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

UI 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_ENABLE_AWAY_SUMMARY=1             # Force Session Recap when telemetry disabled (v2.1.108+)[^153]
OTEL_LOG_RAW_API_BODIES=1                     # Emit full API request/response bodies as OTel log events (v2.1.111+)[^153]
TRACEPARENT=00-...                            # W3C Trace Context parent (v2.1.110+, SDK/headless)[^153]
TRACESTATE=vendor=value                       # W3C Trace Context state (v2.1.110+, SDK/headless)[^153]

Exportadores OpenTelemetry + controle de campos sensíveis:¹⁸¹

OTEL_LOGS_EXPORTER=none                       # OTel logs exporter (supports 'none' for disable; v2.1.85 fixed crash)
OTEL_METRICS_EXPORTER=none                    # OTel metrics exporter (supports 'none'; v2.1.85 fixed crash)
OTEL_TRACES_EXPORTER=none                     # OTel traces exporter (supports 'none'; v2.1.85 fixed crash)
OTEL_LOG_TOOL_CONTENT=1                       # Opt in to emitting tool content in OTel spans (v2.1.101+, sensitive by default)
OTEL_LOG_TOOL_DETAILS=1                       # Opt in to tool_parameters in OTel tool_result events (v2.1.85+)
OTEL_LOG_USER_PROMPTS=1                       # Opt in to emitting user prompts in OTel traces (v2.1.101+, sensitive by default)
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 LLM na v2.1.121+: stop_reason, gen_ai.response.finish_reasons e user_system_prompt agora são emitidos em spans de solicitação LLM. user_system_prompt é protegido por OTEL_LOG_USER_PROMPTS=1, já que pode conter PII.¹⁵⁴

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

API / Controle de modelo:¹⁸¹

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

Plugins / MCP:¹⁸¹

CLAUDE_CODE_PLUGIN_CACHE_DIR=~/.claude/plugins # Plugin cache directory (v2.1.72 fixed literal '~' dir on some shells)
CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 # Preserve plugin marketplace cache when git pull fails (offline-friendly; v2.1.90+)
CLAUDE_CODE_MCP_SERVER_NAME=server1           # Passed to MCP headersHelper scripts so one helper can serve multiple servers (v2.1.85+)
CLAUDE_CODE_MCP_SERVER_URL=https://...        # Passed to MCP headersHelper scripts alongside the name (v2.1.85+)

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)

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

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

Identidade do chamador SDK (v2.1.51+):

CLAUDE_CODE_ACCOUNT_UUID=uuid                  # Provide account UUID synchronously for SDK callers
CLAUDE_CODE_USER_EMAIL=[email protected]        # Provide user email for SDK callers
CLAUDE_CODE_ORGANIZATION_UUID=uuid             # Provide organization UUID for SDK callers

Debugging:

ANTHROPIC_LOG=debug                             # Enable API request logging

Qual modelo devo escolher?

Escolher o modelo certo para cada tarefa impacta bastante tanto o custo quanto a qualidade. Claude Code oferece troca flexível de modelos em vários níveis.

Modelos disponíveis

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 em que foi testado, e criado para manter coerência ao longo de milhões de tokens de contexto. Fable 5 é o modelo de fronteira “Mythos-class” tornado seguro para uso geral: ele vem com classificadores de segurança que fazem fallback para Opus 4.8 em consultas sobre cyber, bioquímica e destilação de modelos (Claude Mythos 5 é o mesmo modelo com essas proteções removidas para pesquisadores autorizados). Ele passou a ficar selecionável no Claude Code com a v2.1.170 (9 de junho de 2026) — execute claude update, depois /model fable (o alias curto; /model claude-fable-5 e o alias best também o selecionam) — e está sendo liberado para planos de assinatura até 22 de junho de 2026. Model ID: claude-fable-5. Fable 5 inclui uma janela de contexto de 1M por padrão, então o sufixo [1m] é desnecessário — e desde a v2.1.173 (11 de junho de 2026) um nome de modelo claude-fable-5[1m] é automaticamente normalizado/removido para claude-fable-5 (o sufixo só fazia sentido em Opus/Sonnet, que bloqueiam 1M atrás de [1m]); saída máxima de 128K. O preço é $10/MTok de entrada e $50/MTok de saída — cerca de 2× o Opus 4.8 — então reserve-o para raciocínios realmente difíceis, não para edições rotineiras. Ele compartilha a superfície de requisição do Opus 4.8 (apenas adaptive thinking; temperature/top_p/top_k e budget_tokens removidos), com uma novidade: um thinking: {type: "disabled"} explícito retorna 400, então omita completamente o parâmetro thinking para executar sem thinking.¹⁷⁴

Especificamente no Claude Code: Fable 5 oferece suporte à escala completa de esforço (low/medium/high/xhigh/max, high por padrão), assim como o Opus 4.8. Thinking não pode ser desativado no Fable 5 — o toggle de thinking da sessão, a configuração alwaysThinkingEnabled e MAX_THINKING_TOKENS=0 não têm efeito; ele sempre raciocina de forma adaptativa. Uma superfície completa de configuração da família fable espelha os controles do Opus: ANTHROPIC_DEFAULT_FABLE_MODEL fixa o modelo para o qual o alias fable resolve (útil em Bedrock/Vertex/Foundry), DISABLE_PROMPT_CACHING_FABLE exclui o Fable do prompt caching, e fallback automático baseado em conteúdo se aplica nos gateways corporativos. Opus 4.8 continua sendo o padrão agentic do Claude Code (esforço high por padrão, /effort xhigh para as tarefas mais difíceis); escolha Fable 5 deliberadamente via /model fable quando quiser o teto absoluto.¹⁷⁴

Opus 4.7 (16 de abril de 2026): O flagship da geração anterior, ainda totalmente disponível. Janela de contexto de 1M tokens com preço padrão — sem prêmio de contexto longo. Saída máxima de 128K, apenas adaptive thinking (extended thinking removido), e um novo nível de esforço xhigh recomendado como ponto de partida para cargas de trabalho de codificação e agentic.¹⁴⁵ Corte de conhecimento confiável: janeiro de 2026. Corte de dados de treinamento: janeiro de 2026. Model ID: claude-opus-4-7. O preço corresponde ao Opus 4.6, a $5/$25 por MTok, com gravação de cache de 5 min a $6,25, gravação de cache de 1 h a $10 e leitura de cache a $0,50 por MTok.¹⁴⁴ Opus 4.7 resolve 3× mais tarefas de produção no SWE-Bench do que Opus 4.6, marca 70% no CursorBench (contra 58% do 4.6) e aumenta a resolução em 13% no benchmark interno de codificação de 93 tarefas da Anthropic.¹⁴⁴ Usa um novo tokenizer — espere contagens de tokens de cerca de 1×–1,35× para o mesmo texto; aumente a folga de max_tokens e os gatilhos de compactação.¹⁴⁵ Vision oferece suporte a imagens de até 2.576 px / 3,75 MP com coordenadas de pixel 1:1.¹⁴⁵

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

Opus 4.7 lidera o SWE-bench Verified por 12,7 pontos sobre o baseline GPT-5-Codex amplamente citado e o SWE-bench Pro por 6,6 pontos sobre o GPT-5.4 (57,7%). No Terminal-Bench 2.0, GPT-5.3-Codex ainda supera ligeiramente o GPT-5.4 (77,3% contra 75,1%) e ambos ficam à frente do Opus 4.7 (69,4%). A liderança em benchmarks é fluida; confira as páginas dos fornecedores antes de se comprometer com uma escolha para vários trimestres.

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

Opus 4.7 exige Claude Code v2.1.111 ou posterior; execute claude update para atualizar.¹⁴⁷ Bedrock, Vertex e Foundry expõem Opus 4.7 via nomes completos explícitos de modelo ou fixações ANTHROPIC_DEFAULT_OPUS_MODEL, não pelo alias opus por padrão.¹⁴⁷

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

• Extended thinking budget_tokens foi removido. Use thinking: {type: "adaptive"}. Adaptive thinking fica desativado por padrão; requisições sem campo thinking rodam sem thinking.
• Definir temperature, top_p ou top_k como um valor não padrão retorna HTTP 400. Omita esses parâmetros e direcione o modelo via prompting.
• O conteúdo de thinking é omitido das respostas por padrão. Defina thinking.display: "summarized" para restaurar o raciocínio visível (obrigatório se seu produto transmite thinking para usuários).

Orçamentos de tarefa (beta header task-budgets-2026-03-13) permitem informar ao modelo uma meta de tokens ao longo de um loop agentic completo via output_config.task_budget; mínimo de 20K tokens.¹⁴⁵

Opus 4.6 (legado): Ainda disponível em claude-opus-4-6 com contexto de 1M e saída máxima de 128K. Considere migrar para Opus 4.7 para melhor codificação agentic. Opus 4.6 foi lançado originalmente em 5 de fevereiro de 2026.⁷⁹¹⁴⁴ A partir da v2.1.117 (22 de abril de 2026), assinantes Pro e Max usam esforço high por padrão no Opus 4.6 e Sonnet 4.6 (antes era medium); Opus 4.7 permanece em xhigh. Essa mudança restaurou a inteligência após o downgrade de esforço de 4 de março → 7 de abril documentado no postmortem de 23 de abril.¹⁵²¹⁵³

Sonnet 4.6 (17 de fevereiro de 2026): Modelo equilibrado; substituiu o Sonnet 4.5 como padrão no claude.ai e no Claude Cowork.⁹³ Mesmo preço do Sonnet 4.5 ($3/$15 por MTok). Melhor desempenho de busca agentic consumindo menos tokens. Oferece suporte a extended thinking, adaptive thinking e janela de contexto de 1M tokens (beta). Saída máxima de 64K (limite superior de 128K na v2.1.77).¹¹⁹ Corte de conhecimento: agosto de 2025 (confiável), janeiro de 2026 (dados de treinamento). Model ID: claude-sonnet-4-6.

Claude Mythos Preview (7 de abril de 2026): Um modelo de fronteira em research preview para trabalho defensivo de cibersegurança, oferecido sob o Project Glasswing.¹³⁹ Apenas por convite; não disponível de forma geral. A Anthropic apresenta o Opus 4.7 como deliberadamente menos capaz que o Mythos nas dimensões cyber — um tradeoff de segurança — e abriu um Cyber Verification Program em https://claude.com/form/cyber-use-case para pesquisadores de segurança legítimos que precisam de acesso elevado.¹⁴⁶

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

Quando usar cada modelo

Haiku: Use para subagents fazendo exploração, buscas simples de arquivos, perguntas rápidas. É ~5x mais barato que Opus e responde mais rápido. Perfeito para tarefas em segundo plano em que você não precisa de raciocínio profundo.

Sonnet: O cavalo de batalha para desenvolvimento diário quando custo importa. Lida com a maioria das tarefas de codificação: implementar recursos, corrigir bugs, escrever testes, code review. Sonnet 4.6 entrega busca agentic aprimorada e melhor eficiência de tokens em comparação com Sonnet 4.5, com suporte a adaptive thinking e uma janela de contexto de 1M com preço padrão.⁹³ Desde o Opus 4.7 (16 de abril de 2026), Claude Code usa Opus por padrão apenas nos planos Max e Team Premium; contas Pro, Team Standard, Enterprise e API mantêm Sonnet 4.6 como padrão até Enterprise e API mudarem para Opus 4.7 em 23 de abril de 2026.¹⁴⁷ Use Sonnet quando precisar de tokens mais baratos, latência menor ou boa economia para subagents.

Opus: O nível flagship 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 onde ele compensa: decisões de arquitetura, debugging complicado, entender sistemas complexos, análise de segurança, trabalho agentic de longo horizonte. Opus 4.7 resolve 3× mais tarefas de produção no SWE-Bench do que Opus 4.6, marca 70% no CursorBench (contra 58%) e aumenta a resolução em 13% em um benchmark interno de codificação de 93 tarefas.¹⁴⁴ Claude Code usa esforço xhigh por padrão no Opus 4.7, ajustável via /effort (v2.1.111+).¹⁴⁶¹⁴⁷ Auto Mode está disponível para assinantes Max no Opus 4.7 via Anthropic API sem exigir --enable-auto-mode; outros planos/provedores têm disponibilidade específica do plano e controlada por admin.¹⁴⁶ Contexto de 1M com preço padrão — sem prêmio de contexto longo. Mudanças de comportamento que vale conhecer: Opus 4.7 segue instruções de forma mais literal, calibra o tamanho da resposta à complexidade da tarefa, executa menos subagents por padrão e adota um tom mais direto, com menos frases de validação. Se seus prompts contêm scaffolding para forçar mensagens intermediárias de progresso ou comportamento de double-check, tente removê-lo.¹⁴⁵

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

Troca de modelos

Durante a sessão:

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

Na inicialização:

claude --model opus

Via ambiente:

export ANTHROPIC_MODEL=opus

Em 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 define até três modelos de fallback, tentados em ordem, quando o modelo principal está sobrecarregado ou indisponível. A flag --fallback-model (antes apenas uma troca no meio da sessão) agora também se aplica a sessões interativas desde a inicialização.¹⁷⁶

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

Quando o API retorna um erro inesperado não retentável, Claude Code agora também tenta novamente o turno uma vez no modelo de fallback antes de mostrar a falha, então um problema transitório do modelo principal degrada de forma elegante em vez de derrubar o turno.¹⁷⁶

A partir da v2.1.178, a compactação também respeita a cadeia de fallback — se o modelo principal estiver sobrecarregado ou indisponível no meio da compactação, a etapa de compactação recorre à cadeia fallbackModel/--fallback-model configurada em vez de falhar o turno. Para uma execução autônoma longa, isso fecha a lacuna em que uma compactação que seria recuperável poderia derrubar a sessão por causa de um erro transitório de modelo.¹⁷³

Contexto estendido

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

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

Ou dentro de uma sessão:

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

Opus 4.7, Opus 4.6 e Sonnet 4.6 incluem a janela completa de contexto de 1M tokens com preço padrão — sem prêmio de contexto longo.¹⁴⁸ Uma requisição de 900K tokens é cobrada pela mesma taxa por token que uma requisição de 9K tokens. Descontos de prompt caching e processamento em batch se aplicam às taxas padrão em toda a janela de contexto.

Em assinaturas Max, Team e Enterprise, Opus com contexto de 1M é incluído automaticamente — sem necessidade do sufixo [1m] (habilitado por padrão desde a v2.1.75, 13 de março de 2026).¹¹⁷¹⁴⁷ No Pro, o contexto de 1M é acessível via extra usage. Usuários de API e pay-as-you-go têm acesso completo a 1M nas taxas padrão por token.¹⁴⁷

Para desabilitar variantes de contexto de 1M no seletor de modelos, defina CLAUDE_CODE_DISABLE_1M_CONTEXT=1.

Verificar o modelo atual

> /status

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

Rótulos do seletor de modelos (v2.1.51+): O seletor /model agora mostra rótulos legíveis por humanos (por exemplo, “Sonnet 4.6”) em vez de model IDs brutos para versões fixadas, com dicas de upgrade quando versões mais novas estão disponíveis.⁹⁸

Fast Mode (v2.1.36+)

Fast mode fornece saída significativamente mais rápida do mesmo modelo; ele não troca para um modelo mais barato. Ative ou desative durante uma sessão com /fast.⁸⁶

> /fast            # Toggle fast mode on/off

Preço (fast mode do Opus 4.6):

Fast mode é research preview, apenas Opus 4.6, e entrega saída ~2,5× mais rápida a 6× o preço base.¹⁴⁹ Habilitar /fast troca automaticamente a sessão para Opus 4.6 se você estava em outro modelo; desabilitar /fast deixa você no Opus 4.6 até trocar via /model. Fast mode não está disponível no Opus 4.7, Sonnet, Haiku nem via Bedrock/Vertex/Foundry. Ele exige que extra usage esteja habilitado e, para Team/Enterprise, habilitação pelo admin.

Quando usar fast mode: - Iterar rapidamente em mudanças pequenas quando a latência é o gargalo - Gerar testes, boilerplate ou código repetitivo quando velocidade importa mais que custo - Trabalhar por uma lista de tarefas semelhantes sequencialmente

Quando NÃO usar fast mode: - Tarefas agentic de longa duração (o custo sobe rápido a 6x as taxas) - Trabalho de subagent em segundo plano (ninguém está esperando a saída) - Sessões com orçamento apertado

O fast mode do Opus 4.6 inclui a janela completa de contexto de 1M (v2.1.50+). O preço do fast mode é fixo em todo o contexto de 1M — sem cobrança adicional por contexto longo.⁹⁶¹⁴⁹

Dica de especialista: Fast mode não combina com opusplan (opusplan já mistura Opus e Sonnet; fast mode só afeta Opus 4.6). Use fast mode diretamente quando a latência importar mais que o custo, e desabilite-o para trabalho autônomo ou em batch. /fast exige extra usage; admins Team/Enterprise podem precisar habilitá-lo primeiro (correção da v2.1.37).⁸⁶¹⁴⁹

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

Opus 4.7 introduz um novo dial de esforço que ajusta o tradeoff entre velocidade e inteligência. Use /effort durante uma sessão:

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

Claude Code agora usa esforço xhigh por padrão para Opus 4.7. xhigh é exclusivo do Opus 4.7 — outros modelos caem para high. Claude Managed Agents gerencia esforço automaticamente; o parâmetro de esforço é um conceito do Messages API.¹⁴⁵¹⁴⁶

Auto Mode no Max (v2.1.111+)

Auto Mode — um substituto mais seguro para --dangerously-skip-permissions — está disponível para assinantes Max no Opus 4.7 via Anthropic API sem --enable-auto-mode.¹⁴⁶ Um classificador Sonnet-4.6 revisa cada ação antes da execução, verificando correspondência de intenção e segurança. Observação (v2.1.111+): a flag --enable-auto-mode foi removida; inicie uma sessão em Auto Mode com --permission-mode auto. Auto Mode não está disponível no Pro; segundo a documentação de permission modes da Anthropic, ele é direto no Anthropic API por padrão. Bedrock/Vertex/Foundry (v2.1.158+): Auto Mode agora é opt-in no Opus 4.7 e Opus 4.8 nesses gateways com CLAUDE_CODE_ENABLE_AUTO_MODE=1.¹⁷⁹

Regras personalizadas sem perder os padrões (v2.1.118+). Versões anteriores tornavam autoMode.allow, autoMode.soft_deny e autoMode.environment mutuamente exclusivos: defina sua própria lista e perca as regras de segurança embutidas. O sentinela $defaults resolve isso — ele se expande inline para a lista embutida exatamente na posição em que você o coloca, permitindo sobrepor regras personalizadas ao redor delas:¹⁵²

// .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
    ]
  }
}

Opt-in “Don’t ask again” (v2.1.118+). O prompt de opt-in do Auto Mode agora oferece uma opção “Don’t ask again”, para que usuários frequentes possam suprimir a explicação sem criar uma flag em script.¹⁵²

Novos comandos na v2.1.105–v2.1.114¹⁴⁶¹⁵⁰

Recap da sessão (v2.1.108+)

Um novo recurso no nível da sessão que mostra contexto quando você volta a uma sessão pausada. Habilitado por padrão e com opt-out via /config ou CLAUDE_CODE_ENABLE_AWAY_SUMMARY=0. O modelo também pode invocar slash commands embutidos (/init, /review, /security-review) via a ferramenta Skill — estende o padrão de subagent/skill.¹⁴⁶

Push Notifications (v2.1.110+)

Quando Remote Control está configurado com “Push when Claude decides” habilitado, Claude agora pode enviar push notifications mobile a seu próprio critério por meio de uma nova ferramenta de push-notification. Combina com a superfície mobile/web existente do Remote Control.¹⁴⁶ /context, /exit e /reload-plugins agora também funcionam a partir de clientes Remote Control.

Ferramenta Windows PowerShell (v2.1.111+, rollout)

Claude Code está lançando uma ferramenta nativa de Windows PowerShell. No Linux/macOS, habilite-a com CLAUDE_CODE_USE_POWERSHELL_TOOL=1 (exige pwsh no PATH). No Windows, a mesma variável controla opt-in/opt-out durante o rollout.¹⁴⁶

Aprovação automática em permission-mode (v2.1.119+). Comandos da ferramenta PowerShell agora podem receber aprovação automática no permission mode da mesma forma que comandos Bash. Regras de allow como PowerShell(Get-*:*) e a sintaxe de padrões existente agora ignoram o prompt para operações read-only, combinando com a ergonomia de operador que equipes já têm no Linux/macOS.¹⁵²

Redução de permissões: Bash read-only (v2.1.111+)

Padrões Bash read-only com argumentos glob (por exemplo, ls *.ts, cat src/*.md) e comandos que começam com cd <project-dir> && não disparam mais um prompt de permissão.¹⁴⁶ Combinado com /less-permission-prompts, espere bem menos interrupções nos fluxos de trabalho cotidianos.

Distributed Tracing (v2.1.110+)

SDK e sessões headless agora leem TRACEPARENT e TRACESTATE do ambiente, conectando execuções do Claude Code a traces distribuídos. Combine com OTEL_LOG_RAW_API_BODIES=1 (v2.1.111+) para emitir corpos completos de requisição/resposta do API como eventos de log OpenTelemetry para debugging.¹⁴⁶

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

A v2.1.113 muda como o CLI inicia: claude agora gera um binário nativo do Claude Code via uma dependência opcional por plataforma em vez de executar o JavaScript empacotado. Comandos de instalação e atualização continuam iguais, e equipes não precisam alterar scripts de rollout.

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

O editor de prompt ganha navegação no estilo readline em entrada multilinha, além de rolagem de viewport em tela cheia:

Eles ficam ativados por padrão. Não exige configuração de keybinding.

Timeout de stall de subagent (v2.1.113+)¹⁵⁰

Subagents que travam no meio do stream agora falham com um erro claro após 10 minutos em vez de ficar pendurados silenciosamente. Combine com CLAUDE_STREAM_IDLE_TIMEOUT_MS (v2.1.84+) para uma cobertura mais ampla de processos travados em APIs com streaming.

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

A v2.1.114 (18 de abril de 2026) traz uma única correção: o diálogo de permissões podia travar quando um colega de agent-teams solicitava permissão de ferramenta. Atualize se você usa Agent Teams.

Quanto Custa o Claude Code?

Entender e controlar custos é essencial para o uso sustentável do Claude Code. Veja também Seleção de Modelo para capacidades dos modelos e Frameworks de Decisão para escolher o modelo certo por tarefa.

Visualizando 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

Usuários de assinatura veem um detalhamento por modelo e por cache-hit em /cost, mostrando exatamente quais modelos consumiram tokens e quanto foi servido a partir do cache (v2.1.92+).¹³⁷

Planos de Assinatura

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

Duplicação dos limites de taxa (6 de maio de 2026): Durante o evento Code with Claude SF, a Anthropic duplicou os limites de taxa de cinco horas do Claude Code nos planos Pro, Max, Team e Enterprise por assento, removeu a redução de horário de pico nas contas Pro e Max, e elevou “consideravelmente” os limites de taxa da API para os modelos Claude Opus. O suporte de capacidade é o acordo SpaceX Colossus 1: “mais de 300 megawatts de nova capacidade (mais de 220.000 NVIDIA GPUs) dentro do mês.”¹⁵⁷

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

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

Preço de contexto de 1M (abril de 2026): Opus 4.7, Opus 4.6, Sonnet 4.6 e Mythos Preview todos incluem 1M com tarifas padrão por MTok — sem prêmio de contexto longo.¹⁴⁸ Esta é uma consolidação recente; orientações antigas sobre Opus 4.6 ou Sonnet 4.6 pagando 2× entrada / 1,5× saída acima de 200K tokens de entrada não estão mais atualizadas. O Opus 4.5 legado e modelos anteriores mantêm suas estruturas de preços originais.

Preço de residência de dados: Especificar inferência apenas nos EUA via inference_geo adiciona um multiplicador de 1,1× em todos os preços de tokens, incluindo leituras e escritas de cache (modelos Opus 4.6+).¹⁴⁸

Prompt caching reduz significativamente os custos de entradas repetidas: escritas de cache custam 1,25× a base (cache de 5 min) ou 2× (cache de 1 h), mas leituras de cache custam apenas 0,1×, uma economia de 90%. Para sistemas RAG e assistentes de código com contexto repetido, o caching pode reduzir custos em 88-95%.

Batch API oferece 50% de desconto com prazo de 24 horas para tarefas não urgentes, como suítes de testes noturnas.

Política de Múltiplas Contas⁵²

Você pode ter múltiplas contas Claude? Sim, para casos de uso legítimos. A Anthropic permite explicitamente múltiplas contas quando elas atendem a propósitos distintos.

O que é permitido:

Limites técnicos: - Até 3 contas podem ser verificadas com o mesmo número de telefone - Múltiplas assinaturas pagas do mesmo IP/rede são explicitamente suportadas - As contas são completamente separadas; sem transferência de chat ou projeto entre elas

O que é proibido (conforme a Política de Uso): - Criar contas para burlar banimentos após ter sido banido - Coordenar atividade maliciosa entre contas para evitar detecção - Usar múltiplas contas para contornar limites de taxa ou créditos do nível gratuito

Nota do mundo real: Em janeiro de 2026, o usuário avançado Jeffrey Emanuel (@doodlestein) teve 22 contas Max sinalizadas automaticamente e temporariamente banidas. O funcionário da Anthropic Thariq (@trq212) resolveu o caso em 4 horas após confirmar uso legítimo. Se você está usando o Claude Code extensivamente para projetos de trabalho e pessoais em múltiplas contas, é exatamente para isso que o serviço foi projetado, mas não tente burlar o sistema.

Em caso de dúvida: Contate o Suporte da Anthropic para confirmar sua configuração específica por escrito.

Fatores de Custo

Exemplos de Custo do Mundo Real

Insight de economia: Usar Haiku para subagents de exploração e Sonnet para implementação tipicamente reduz custos em 40-50% comparado a usar Sonnet para tudo.

Gestão de Custos em Equipe

TPM/RPM recomendado por tamanho de equipe:

Taxas Ocultas de Ferramentas

Além dos preços por token, algumas ferramentas incorrem em cobranças separadas:⁹

Eles se acumulam em loops de agentes. Um ciclo de debug de 100 iterações com Bash custa ~24.500 tokens de entrada extras apenas em overhead.

Estratégias de Economia

1. Use Haiku para subagents: A maioria das explorações não precisa de Sonnet
2. Ative prompt caching: Padrão, mas verifique se não está desativado
3. Defina máximo de turnos: claude --max-turns 5 previne conversas descontroladas
4. Use modo de plano para exploração: Sem execução = sem operações caras acidentais
5. Compacte proativamente: Contexto menor = menos tokens
6. Limite a saída: export CLAUDE_CODE_MAX_OUTPUT_TOKENS=2000
7. Batch API para trabalho não urgente: 50% de desconto em tokens de entrada e saída

Monitorando o Uso

• Claude Console: platform.claude.com (requer função Admin ou Billing)
• Limites de workspace: Defina limites de gastos por workspace
• Bedrock/Vertex: Use o monitoramento de custos nativo da nuvem
• LiteLLM: Para rastreamento detalhado por usuário com provedores terceirizados

Uso de Tokens em Segundo Plano

Algumas operações consomem tokens em segundo plano: - Sumarização de conversas para /resume - Comandos /cost e /status - Auto-compactação

Tipicamente abaixo de $0,04 por sessão.

Claude Code Analytics API (Team/Enterprise)⁴⁶

Acesse programaticamente as métricas de uso e produtividade do Claude Code da sua organização via Admin API.

Endpoint: GET /v1/organizations/usage_report/claude_code

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

Métricas Disponíveis:

Exemplo de Requisiçã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 de produtividade dos desenvolvedores (sessões, commits, PRs) - Métricas de uso de ferramentas (taxas de aceitação/rejeição para Edit, Write, etc.) - Rastreamento e alocação de custos entre equipes - Justificativa de ROI para ferramentas de codificação com IA

Nota: Os dados aparecem em até 1 hora após a conclusão da atividade. Apenas dados com mais de 1 hora são incluídos nas respostas para consistência.

Frameworks de decisão

Saber que os recursos existem não é suficiente. 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.6
                  │         Cost: ~$2.00/task
                  │         Quality: Highest (1M context, adaptive thinking)
                  │
                  └── NO → Use Sonnet (default)
                           Cost: ~$0.75/task
                           Balance: Best overall

Regra geral: Comece com Sonnet. Use Haiku para subagents. Escale para Opus 4.6 apenas quando a resposta do Sonnet parecer superficial. Com agent teams (v2.1.32+), Opus pode coordenar múltiplos agentes trabalhando em paralelo em diferentes subtarefas.⁷⁹

Command vs Skill vs Subagent vs 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 vs Prompt?

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

Quando usar Extended Thinking?

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

Alterne com Alt+T durante a sessão. Orçamentos de thinking mais altos custam mais; comece com o mínimo e aumente apenas se as respostas parecerem apressadas.

Opus 4.6 adaptive thinking: Opus 4.6 ajusta automaticamente a profundidade de thinking com base na complexidade do problema. Para a maioria das tarefas, o controle explícito do orçamento de thinking não é necessário — Opus escala para problemas difíceis e permanece rápido para os simples. O ajuste manual de thinking é mais útil com Sonnet quando você quer forçar uma análise mais profunda.

Qual superfície de execução?

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 vs Subagents vs 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?

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
│         Same Opus 4.6 model, faster output
│         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 alterna o modo rápido para a sessão atual. Ele usa o mesmo modelo (Opus 4.6) com velocidade de saída otimizada — NÃO muda para um modelo mais barato.

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. Entender esse sistema é essencial tanto para a segurança quanto para a eficiência do fluxo de trabalho. Veja também implantação corporativa para configurações gerenciadas que impõem permissões em toda a organização.

Níveis de permissão

Ferramentas somente leitura (aprovadas automaticamente): - Read - Ler o conteúdo de arquivos - Glob - Encontrar arquivos por padrão - Grep - Buscar no conteúdo de arquivos - WebSearch - Pesquisar na web - LSP - Inteligência de código (ir para definição, encontrar referências, docs ao passar o mouse)¹⁸

Capacidades da ferramenta LSP (v2.0.74+): A ferramenta LSP oferece inteligência de código parecida com a de uma IDE: - Ir para definição: Pule para onde um símbolo é definido - Encontrar referências: Liste todos os usos de um símbolo em toda a base de código - Docs ao passar o mouse: Obtenha informações de tipo e documentação de qualquer símbolo - Funciona com TypeScript, Python, Go, Rust e outras linguagens com suporte a LSP - Exige que o servidor de linguagem esteja disponível (normalmente instalado com seu toolchain)

Ferramentas de modificação (exigem aprovação): - Edit - Modificar arquivos existentes - Write - Criar novos arquivos - Bash - Executar comandos shell - WebFetch - Buscar conteúdo de URLs - NotebookEdit - Modificar 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 configuradas explicitamente de outra forma.

Modos de permissão

Arquivos de configuração com execução de código agora geram solicitação mesmo em acceptEdits (v2.1.160). acceptEdits aprova automaticamente edições comuns, mas a partir da v2.1.160 ele para e solicita confirmação antes de gravar arquivos que podem conceder 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 raciocínio é que uma edição em qualquer um desses arquivos transforma o próximo shell, install ou commit em um vetor de execução, então eles recebem uma barreira deliberada mesmo em um modo de projeto confiável que, de outra forma, deixaria as edições passarem. Esse é o mesmo modelo de ameaça das proteções de escrita existentes em .claude/, .git/ e .vscode/, estendido para a classe mais ampla de arquivos em que “edição vira execução”.¹⁷⁸

Auto Mode (v2.1.85+): Uma substituição mais segura para --dangerously-skip-permissions. Um modelo classificador separado (Sonnet 4.6) revisa cada ação antes da execução, verificando se ela corresponde à intenção do usuário e se é segura.¹²⁴

Como funciona: - Ações somente leitura e edições de arquivo no diretório de trabalho são aprovadas automaticamente - Regras personalizadas de permitir/negar são resolvidas primeiro - Todo o resto vai para o classificador para avaliação - Se for bloqueado, o Claude tenta automaticamente uma abordagem alternativa

Bloqueado automaticamente por padrão: curl | bash, force-push para main, deploys/migrações em produção, exclusões em massa na cloud, mudanças de IAM/permissões, envio de dados sensíveis para fora.¹²⁵

Circuit breaker: 3 bloqueios consecutivos ou 20 no total em uma sessão pausam e voltam para solicitações manuais.¹²⁵

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

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

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

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

claude --dangerously-skip-permissions

Defina o modo via CLI:

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

Alterne durante a sessão:

Shift+Tab  # Cycles through modes

Em settings.json:

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

Sintaxe das regras de permissão

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

Padrões de comandos Bash:

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

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

Limitação importante: Padrões Bash correspondem apenas a prefixos, não a regex. Um padrão como Bash(curl http:*) não corresponde a curl -X GET http://... porque as opções vêm antes da URL. Para bloqueio confiável, negue o comando inteiro: Bash(curl:*).

Padrões de operações de arquivo:

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

Sintaxe de caminhos: - Caminhos relativos: Edit(src/**) - relativo ao diretório de trabalho - Absoluto a partir do arquivo de configurações: Edit(/build/**) - relativo ao local do arquivo de configurações - Absoluto real: Edit(//tmp/**) - começa com // - Diretório home: Read(~/.zshrc)

Padrões de ferramentas MCP:

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

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

A partir da v2.1.166, regras de negação também aceitam um glob na posição do nome da ferramenta: um "*" sozinho no slot de nome da ferramenta nega todas as ferramentas, então você pode bloquear tudo e depois permitir de volta um conjunto estreito. Regras de permissão, por outro lado, rejeitam globs que não sejam MCP — você não pode permitir tudo amplamente da mesma forma, o que mantém a postura padrão restritiva.¹⁷⁶

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

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

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

Agent(model:opus) bloqueia qualquer subagent iniciado no nível Opus — o início em si é negado, não apenas o prompt pedindo para evitá-lo. Isso estende o controle de permissões de “qual ferramenta” para “como ela é chamada”, como uma regra determinística em vez de uma solicitação em nível de prompt. Ele funciona junto com a configuração gerenciada enforceAvailableModels: a allowlist define quais níveis de modelo existem para a sessão, e regras Tool(model:...) restringem como subagents usam esses níveis.¹⁷³

Padrões de WebFetch:

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

Diretórios adicionais

Estenda o acesso do Claude 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.

Sandbox Mode

Habilite isolamento de filesystem e rede:

> /sandbox

Ou configure nas settings:

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

Quando em sandbox: - Acesso ao filesystem restrito ao diretório do projeto - Acesso à rede controlado - Certos comandos excluídos das restrições do sandbox - Comandos Bash permitidos automaticamente se autoAllowBashIfSandboxed for true

Dica avançada: Sandbox mode é excelente para executar o Claude em bases de código não confiáveis. Habilite ao explorar projetos desconhecidos ou quando você quiser uma camada extra de proteção. Testes internos da Anthropic descobriram que o sandbox reduz solicitações de permissão em 84%.³⁸ O sandbox usa primitivas no nível do sistema operacional (macOS seatbelt, Linux bubblewrap) para isolamento de filesystem e rede, então até uma prompt injection bem-sucedida fica totalmente contida. A Anthropic tornou o runtime de sandbox open source para equipes que estão criando seus próprios agents.⁸²

Notas de segurança (v2.1.34+): Comandos excluídos do sandbox por sandbox.excludedCommands ou dangerouslyDisableSandbox antes podiam contornar a regra de solicitação de permissão do Bash quando autoAllowBashIfSandboxed estava habilitado; isso foi corrigido na v2.1.34.⁸⁷ A partir da v2.1.38, gravações em .claude/skills são bloqueadas em sandbox mode, impedindo que prompt injection modifique definições de skills.⁸⁸ v2.1.77 adiciona uma configuração de filesystem de sandbox allowRead para permitir novamente 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.¹¹⁹

Isenção de configuração de agent 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/ aninhado (v2.1.178): Skills em diretórios .claude/skills aninhados agora carregam automaticamente quando você trabalha em arquivos dentro desse diretório, não apenas a partir da raiz do repo; em caso de conflito de nome, a skill aninhada pode ser acessada como <dir>:<name>, então ambas continuam disponíveis. O restante da superfície do projeto é resolvido da mesma forma — quando o nome de um agent, workflow ou output-style colide entre diretórios .claude/ aninhados, vence aquele mais próximo do diretório de trabalho, e um salvamento de workflow no escopo do projeto mira o .claude/workflows/ existente mais próximo. Para um monorepo ou repo de repos, isso oferece tooling por pacote que é ativado em contexto, em vez de uma superfície global plana.¹⁷³

Caminhos customizados de bubblewrap e socat (v2.1.133+): As configurações gerenciadas sandbox.bwrapPath e sandbox.socatPath permitem que admins apontem implantações Linux/WSL para locais não padrão dos binários bubblewrap e socat. Útil quando distribuições instalam essas ferramentas fora de $PATH ou quando a organização fornece builds endurecidos próprios.¹⁶⁰

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

• sandbox.network.deniedDomains bloqueia hosts específicos mesmo quando um curinga mais amplo em allowedDomains permitiria esses hosts. Use a blocklist para cortar pastebins, file drops ou hosts sabidamente maliciosos sem reescrever toda a sua política de permissão.
• Regras de negação para comandos wrapper. Regras de negação Bash agora correspondem a comandos encapsulados por env, sudo, watch, ionice, setsid e wrappers de execução similares. Regras como Bash(rm:*) agora capturam env rm -rf, sudo rm -rf e padrões de bypass semelhantes.
• Regras de permissão Bash(find:*) não aprovam mais automaticamente find -exec ou find -delete. Essas flags executam comandos e excluem arquivos, então o Claude Code as encaminha pelo caminho normal de permissões.
• Proteção contra remoção no macOS. Regras de permissão Bash(rm:*) agora tratam /private/etc, /private/var, /private/tmp e /private/home como alvos perigosos de remoção. /var, /etc e /tmp são symlinks para dentro de /private/, então o formato anterior da regra deixava passar os alvos canônicos.

Como os hooks funcionam?

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

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

Eventos disponíveis

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)

Protocolo de entrada/saída de hooks

Hooks recebem JSON em stdin:

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

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

Hooks Stop/SubagentStop (v2.1.47+) recebem um campo adicional last_assistant_message contendo o texto da resposta final do Claude, para que hooks possam inspecionar a saída sem fazer parsing de arquivos de transcript:

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

Feedback leve sem bloqueio (v2.1.163+): Hooks Stop e SubagentStop podem retornar hookSpecificOutput.additionalContext na saída JSON para entregar feedback ao Claude e manter o turno em andamento, sem que a resposta seja rotulada como erro de hook. Antes disso, a única alavanca real de um hook Stop era o bloqueio exit-2 (que aparece como erro e conta para o limite de bloqueios consecutivos); additionalContext adiciona um canal de direcionamento para orientações do tipo “isto ficou faltando, continue” que não atrapalham o loop.¹⁷⁷

Códigos de saída controlam o comportamento: - 0: Sucesso: a operação prossegue. Stdout exibido no modo verbose (Ctrl+O). Para UserPromptSubmit e SessionStart, stdout é adicionado ao contexto. - 2: Erro bloqueante: a operação para. Stderr vira a mensagem de erro enviada de volta ao Claude. - 1, 3, etc.: Erro não bloqueante: a operação continua. Stderr exibido como aviso no modo verbose.

Para controle avançado, hooks podem gerar JSON:

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

Controle de decisão PreToolUse (formato preferido): Hooks PreToolUse usam hookSpecificOutput para um controle mais rico: três resultados (allow/deny/ask), 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 de nível superior decision e reason estão obsoletos para PreToolUse. Use hookSpecificOutput.permissionDecision e hookSpecificOutput.permissionDecisionReason em vez disso. Outros eventos (PostToolUse, Stop etc.) ainda usam decision no nível superior.⁸⁹

Título de sessão UserPromptSubmit (v2.1.94+): Hooks UserPromptSubmit podem definir o título da sessão via hookSpecificOutput.sessionTitle.¹⁴⁰

Hooks assíncronos (janeiro de 2026)

Hooks agora podem rodar em segundo plano sem bloquear a execução do Claude Code. Adicione async: true à configuração do seu 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, email, Pushover) que não devem deixar a sessão mais lenta - Logging e telemetria que podem rodar em segundo plano - Pós-processamento não crítico (analytics, backups)

Quando NÃO usar hooks assíncronos: - Formatação (precisa concluir antes da próxima edição) - Validação (precisa bloquear em caso de falha) - Qualquer hook que precise modificar entrada/saída de 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 hook com LLM que avaliam condições usando raciocínio de AI em vez de scripts.⁸⁹

Hooks de prompt (type: "prompt") enviam um prompt de turno único para um modelo Claude rápido. 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 requisição POST para uma URL e recebem JSON de volta. Use 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"]
          }
        ]
      }
    ]
  }
}

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

Hooks de agente (type: "agent") iniciam um subagent com acesso a ferramentas (Read, Grep, Glob) para verificação em múltiplos turnos. Use quando a checagem exigir inspecionar arquivos reais ou saída de 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 (padrão: modelo rápido) e timeout. Eventos compatíveis: PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, UserPromptSubmit, Stop, SubagentStop, TaskCompleted. TeammateIdle não oferece suporte a hooks de prompt/agente.

Hooks de ferramenta MCP (v2.1.118+)

Hooks agora podem invocar uma ferramenta MCP diretamente via type: "mcp_tool", sem precisar encapsular um subprocesso Bash que chama 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 combina bem com os servidores MCP que os usuários já têm configurados: qualquer ferramenta acessível por /mcp passa a poder ser chamada por hook.

duration_ms em hooks PostToolUse (v2.1.119+)

Entradas de hook PostToolUse e PostToolUseFailure agora incluem duration_ms, o tempo de execução da ferramenta excluindo prompts de permissão e hooks PreToolUse.¹⁵² Útil para detectar ferramentas lentas, logs de auditoria e 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, hooks de ferramenta MCP ganharam a capacidade de substituir a saída da ferramenta via 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 subagent e ferramentas MCP. Casos de uso: remover conteúdo sensível da saída de qualquer ferramenta, normalizar estrutura para consumidores posteriores, injetar metadados antes que o agente leia o resultado.¹⁵⁴

Variáveis de ambiente de hooks

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

Persistir variáveis de ambiente a partir de SessionStart:

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

Segurança de hooks HTTP (v2.1.51+): Hooks HTTP que interpolam variáveis de ambiente em headers agora exigem uma lista explícita allowedEnvVars. Isso impede a exfiltração arbitrária de variáveis de ambiente por valores de header. Hooks HTTP também são roteados pelo proxy de rede do sandbox quando o sandboxing está ativado, aplicando a allowlist de domínios. Hooks HTTP não são compatíveis com 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 do workspace para hooks (v2.1.51+): Comandos de hook statusLine e fileSuggestion agora exigem aceitação de confiança do workspace antes de executar no modo interativo, fechando 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 acesso a arquivos sensíveis:

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

Executar testes depois de mudanças no código:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c '[[ \"$FILE_PATH\" == *.test.ts ]] || npm run test:affected'"
          }
        ]
      }
    ]
  }
}

Sistema personalizado de notificações:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Waiting for your input'"
          }
        ]
      }
    ]
  }
}

Injetar contexto dinâmico em prompts:

#!/bin/bash
# .claude/hooks/inject-context.sh
# Add current git branch and recent commits to every prompt

branch=$(git branch --show-current 2>/dev/null)
commits=$(git log --oneline -3 2>/dev/null | tr '\n' ' ')

if [ -n "$branch" ]; then
  echo "[Context: Branch '$branch', Recent: $commits]"
fi
exit 0

Debugging de hooks

Ative o modo debug para diagnosticar hooks:

claude --debug

O modo debug registra: - Tempos de execução de hooks - Dados de entrada/saída - Mensagens de erro e stack traces - Resultados de decisão (allow/reject/ask)

Exibição da fonte do hook (v2.1.75+): Quando um hook exige confirmação do usuário, o prompt de permissão agora mostra a fonte do hook (settings, plugin ou skill), facilitando identificar qual componente está solicitando acesso.¹¹⁷

Hooks com escopo por componente (v2.1.0+)

Hooks podem ser definidos diretamente em Skills, subagents e slash commands usando frontmatter. Esses hooks têm escopo limitado ao ciclo de vida do componente e só rodam quando esse componente está ativo.³⁴

Skill com hooks embutidos:

---
name: secure-deployment
description: Deployment skill with security validation
hooks:
  PreToolUse:
    - matcher: Bash
      command: ".claude/hooks/validate-deploy.sh"
  PostToolUse:
    - matcher: Bash
      command: ".claude/hooks/log-deploy.sh"
  Stop:
    - command: ".claude/hooks/cleanup.sh"
      once: true  # Run only once per session
---

Eventos compatíveis: PreToolUse, PostToolUse, Stop

A opção once (apenas skills e slash commands) garante que o hook rode apenas uma vez por sessão, o que é útil para tarefas de limpeza ou finalização.

Estratégia para sessões longas

Para sessões Claude Code durante a noite ou sem supervisão, configure hooks para manter o Claude no rumo certo sem intervenção manual. O ponto central: use hooks de linting e testes como proteções que obrigam o Claude a corrigir problemas antes de continuar.⁵⁷

O padrão “não pare até os testes passarem”:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint && npm run typecheck",
            "timeout": 60000
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npm test || echo 'Tests failing - Claude should fix before stopping'"
          }
        ]
      }
    ]
  }
}

Estratégia para sessões durante a noite:

1. Checagem prévia: Use um hook Setup para verificar se o ambiente está pronto
2. Validação contínua: Hooks PostToolUse executam testes depois de cada mudança
3. Gate de conclusão: Hooks Stop verificam todos os critérios de aceite antes que o Claude declare “concluído”
4. Notificação: Hooks Stop podem notificar você via Slack/Pushover quando o Claude termina ou fica travado

Combine com --dangerously-skip-permissions em um contêiner com sandbox para execuções totalmente autônomas durante a noite. O Claude continuará iterando até os testes passarem ou até esgotar suas opções.

O que é MCP (Model Context Protocol)?

MCP amplia o Claude Code com acesso a ferramentas externas, bancos de dados, APIs e serviços por meio de um protocolo padronizado. O ecossistema explodiu: MCP agora tem 100 milhões de downloads mensais e mais de 3.000 servidores indexados em MCP.so (janeiro de 2026), consolidando sua posição como o padrão da indústria para conectar IA a ferramentas e dados.³⁴⁷ Entender MCP é essencial para integrar o Claude à sua toolchain existente.

Por que MCP é importante para desenvolvedores: Sem MCP, o Claude Code só consegue ler arquivos e executar comandos bash. Com MCP, o Claude pode consultar seu banco de dados de produção, criar tickets no Jira, revisar PRs do GitHub, verificar erros no Sentry e interagir com qualquer API que sua equipe use, tudo a partir de solicitações em linguagem natural. O protocolo padroniza como ferramentas de IA se conectam a serviços externos, evitando vendor lock-in. Veja Decision Frameworks para orientação sobre quando usar MCP versus outros mecanismos de extensão.

Suporte a MCP remoto (junho de 2025)

O Claude Code agora suporta servidores MCP remotos com autenticação OAuth nativa.²¹ Conecte-se a ferramentas e fontes de dados sem gerenciar servidores locais. Basta autenticar uma vez e o Claude Code cuida do refresh de tokens automaticamente.

# Connect to remote MCP server with OAuth
claude mcp add --transport http linear https://mcp.linear.app/sse
# Browser opens for OAuth flow, tokens stored securely

SDK mcp_authenticate redirectUri (v2.1.121+): O mcp_authenticate do Agent SDK aceita um parâmetro redirectUri para completar OAuth em esquemas de URI customizados — necessário para apps desktop e fluxos de connector do claude.ai que não conseguem usar o redirect de loopback padrão.¹⁵⁴

Connectors MCP do claude.ai (v2.1.46+)

O Claude Code agora pode usar connectors MCP configurados na sua conta claude.ai. Isso preenche a lacuna entre web e CLI: servidores MCP que você configurou pela interface do claude.ai ficam automaticamente disponíveis no Claude Code sem precisar reconfigurá-los localmente.⁹⁵

Opt out: Defina ENABLE_CLAUDEAI_MCP_SERVERS=false no seu ambiente ou no bloco env do settings.json para impedir o carregamento dos servidores MCP do claude.ai.¹⁰⁴

MCP Tool Search (v2.1.7+)

À medida que servidores MCP cresceram em capacidade (alguns expondo mais de 50 ferramentas), as descrições de ferramentas começaram a consumir contexto excessivo. MCP Tool Search resolve isso carregando dinamicamente as descrições das ferramentas apenas quando necessário, uma forma de lazy loading para ferramentas de IA.⁴⁷

Impacto na performance: Benchmarks internos mostram melhorias dramáticas de precisão: - Opus 4: 49% → 74% em avaliações MCP - Opus 4.5: 79,5% → 88,1% em avaliações MCP - Redução de overhead de tokens: 85%

Como funciona: Quando as descrições de ferramentas MCP excedem 10% da janela de contexto (limite padrão), o Claude Code adia o carregamento das descrições completas até que sejam realmente necessárias. O Claude vê os nomes das ferramentas mas busca as descrições sob demanda.

Configuração:

{
  "mcpToolSearchAutoEnable": "auto:15"  // Enable when tools exceed 15% of context
}

Valores: - true - Sempre habilita tool search - false - Sempre desabilita (carrega todas as descrições de ferramentas antecipadamente) - auto:N - Habilita quando as ferramentas excedem N% do contexto (0-100)

Dica de especialista: Com Tool Search habilitado, você pode se conectar a muitos mais servidores MCP sem se preocupar com limites de contexto. A redução de 95% no contexto significa que servidores que antes competiam por contexto agora coexistem pacificamente.

Override de always-load do MCP (v2.1.121+)

Tool Search adia o carregamento das descrições completas até que uma ferramenta seja necessária (limite: mcpToolSearchAutoEnable, padrão auto:10). Para servidores confiáveis cujas ferramentas você espera usar a cada turno, opte por sair por servidor com alwaysLoad: true — toda ferramenta daquele servidor é carregada no prompt no início da sessão, sem round-trip de ToolSearch:¹⁵⁴

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "alwaysLoad": true
    }
  }
}

Auto-retry de inicialização do MCP (v2.1.121+): Um servidor que apresenta erro durante a inicialização agora é tentado novamente até 3 vezes antes de ser marcado como desconectado — útil para servidores stdio que disputam um processo pai lento ou servidores HTTP atrás de um backend com cold start.¹⁵⁴

MCP Elicitation (v2.1.76+)

Servidores MCP agora podem solicitar input estruturado do usuário durante uma tarefa via diálogos interativos.¹¹⁸ Quando um servidor MCP precisa de informações adicionais (por exemplo, selecionar um branch, inserir um nome de projeto, confirmar uma ação), ele envia uma solicitação de elicitation que o Claude Code renderiza como campos de formulário ou uma URL de browser.

Integração com hooks: Dois novos eventos de hook — Elicitation (antes do diálogo aparecer) e ElicitationResult (depois que o usuário responde) — permitem que você intercepte, valide ou sobreponha respostas de elicitation programaticamente. Isso habilita workflows enterprise onde prompts de servidor MCP são pré-preenchidos ou restringidos por política.

Override de tamanho de resultado MCP (v2.1.91+)

Resultados de ferramentas MCP são truncados por padrão. Servidores podem sobrepor isso por resultado usando a anotação _meta["anthropic/maxResultSizeChars"], permitindo até 500K caracteres.¹³⁶ Isso é útil para retornar payloads grandes como schemas de banco de dados, respostas de API ou conteúdo de arquivos sem truncamento.

Wizard interativo de configuração MCP

Execute claude mcp add sem argumentos para abrir uma interface passo a passo para adicionar servidores MCP. O wizard percorre seleção de tipo de transporte, autenticação e configuração.⁸

Tipos de transporte

HTTP (recomendado para servidores remotos):

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# With authentication
claude mcp add --transport http api https://api.example.com/mcp \
  --header "Authorization: Bearer $API_TOKEN"

SSE (deprecated mas funcional):

claude mcp add --transport sse asana https://mcp.asana.com/sse \
  --header "X-API-Key: your-key"

Stdio (servidores locais):

# PostgreSQL
claude mcp add --transport stdio postgres \
  --env "DATABASE_URL=postgresql://user:pass@localhost/db" \
  -- npx -y @anthropic-ai/mcp-server-postgres

# Custom server
claude mcp add --transport stdio custom -- python /path/to/server.py --port 8000

Windows requer um wrapper cmd para stdio:

claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

Gerenciamento de escopo

Servidores MCP existem em três escopos com precedência clara (local sobrepõe project que sobrepõe user):

Especifique o escopo durante a instalação:

claude mcp add --scope project --transport http github https://...
claude mcp add --scope user --transport stdio personal-tool -- ./my-tool

Formato do arquivo de configuração

O arquivo .mcp.json define servidores no nível do projeto:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${SENTRY_API_KEY}"
      }
    },
    "internal-api": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "X-API-Key": "${INTERNAL_API_KEY}"
      }
    }
  }
}