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

TL;DR: Claude Code é uma CLI agêntica que lê sua base de código, executa comandos e modifica arquivos por meio de um sistema em camadas de permissões, hooks, integrações com MCP e subagents. Domine cinco sistemas centrais (configuração, permissões, hooks, MCP e subagents) e você desbloqueia 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 executar. A partir da v2.1.140, as adições recentes incluem Agent View via claude agents, loops de conclusão de /goal, args para hooks de comando, continueOnBlock em PostToolUse, CLAUDE_PROJECT_DIR para servidores stdio de MCP e comandos de plugin, subagent_type na entrada de hook de agente e correções para hooks ConfigChange, além do comportamento de hierarquia de disableAllHooks / allowManagedHooksOnly.^{162 163}

Claude Code opera como um sistema agêntico, não como uma interface de chat com conhecimento de programação. A CLI lê sua base de código, executa comandos, modifica arquivos, gerencia fluxos de trabalho do git, conecta-se a serviços externos via MCP e delega tarefas complexas a subagents especializados. Tudo passa por uma interface de linha de comando que se integra ao modo como desenvolvedores realmente trabalham. Em fevereiro de 2026, 4% dos commits públicos do GitHub (~135.000 por dia) são criados pelo Claude Code — um crescimento de 42.896× em 13 meses desde o research preview — e 90% do código do próprio 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 esses sistemas e o Claude Code se torna um multiplicador de produtividade:

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 as capacidades
5. Sistema de subagents: lida com tarefas complexas de várias etapas

Principais aprendizados

• Cinco sistemas determinam sua eficácia: hierarquia de configuração, permissões, hooks, MCP e subagents controlam tudo, do comportamento à automação.
• Empurre o trabalho para a camada de delegação: subagents evitam inchaço de contexto ao isolar a 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 economizam custo sem sacrificar qualidade: direcione a exploração de subagents para modelos mais baratos e reserve Opus para raciocínio arquitetural de verdade — ou padronize em Opus se qualidade for sua única variável.
• MCP conecta Claude ao seu toolchain: bancos de dados, GitHub, Sentry e mais de 3.000 integrações levam Claude além da leitura de arquivos e comandos bash.

Passei meses levando o Claude Code aos seus limites em bases de código de produção, pipelines de CI/CD e implantações enterprise. Este guia destila essa experiência na referência completa que eu gostaria que existisse quando comecei. Cada recurso inclui sintaxe real, exemplos de configuração de verdade e os casos-limite 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 no ponto adequado ao seu nível de experiência:

Use Ctrl+F / Cmd+F no seu navegador para buscar flags, comandos ou chaves de configuração específicos. O Cartão de referência rápida no final oferece um resumo fácil de escanear 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 uma saída, faça isto na ordem:

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

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

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

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

É isso. Tudo abaixo desta seção aprofunda as opções de instalação, configura permissões e hooks, conecta servidores MCP e aborda implantação empresarial — 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 tem dependência do Node. macOS / Linux / Windows 10+ são compatíveis. Uma assinatura Claude Pro, Max, Team ou Enterprise, ou uma chave Anthropic API paga por token, cobre o uso. Consulte Como instalo Claude Code? para detalhes por plataforma, solução de problemas e o caminho do binário nativo (padrão desde a v2.1.113). A evidência da versão mais recente neste guia foi verificada com a v2.1.140.¹⁶³

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 3 camadas:

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

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

Camada de delegação: Subagents são iniciados com contextos limpos, fazem um trabalho focado e retornam resumos. Os resultados da exploração não incham sua conversa principal; só as conclusões voltam. Direcione subagents para tiers de modelo mais baratos para exploração, ou use seu modelo principal o tempo todo se a qualidade importar mais 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 insight principal: A maioria dos usuários trabalha inteiramente na camada principal, 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 principal apenas para orquestração e decisões finais.

Sumário

1. Como instalo 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 de pensamento estendido?
13. Estilos de saída
14. Slash Commands
15. Como funcionam as skills?
16. Sistema de plugins
17. Como a memória funciona?
18. Entrada de imagem e multimodal
19. Modo de voz
20. Como funciona a integração com Git?
21. Como uso Claude Code no meu IDE?
22. Padrões avançados de uso
23. Agentes remotos e em segundo plano [RESEARCH PREVIEW]
24. Claude no Chrome
25. Claude Code no Slack [RESEARCH PREVIEW]
26. Claude Code na Web [RESEARCH PREVIEW]
27. Otimização de performance
28. Como depuro problemas?
29. Implantação empresarial
30. Referência de atalhos de teclado
31. Boas práticas
32. Receitas de workflow
33. Guia de migração
34. Orientações 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.

Mergulho profundo no sistema de configuração

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

Hierarquia de configuração

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

Referência completa de 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 mais restrita em runtime. Use off para esconder uma skill tanto do modelo quanto do seletor de slash, user-invocable-only para mantê-la chamável por nome enquanto a remove da seleção do modelo, e name-only para manter apenas o nome da skill visível sem sua descrição completa.¹⁵⁶

Referência de variáveis de ambiente

Autenticação e API:

ANTHROPIC_API_KEY=sk-ant-...                    # Autenticação direta da API
ANTHROPIC_AUTH_TOKEN=token                      # Header de autorização customizado
ANTHROPIC_CUSTOM_HEADERS="X-Key: val"           # Headers de requisição adicionais

Configuração de modelo:

ANTHROPIC_MODEL=claude-opus-4-7                 # Sobrescreve modelo padrão (16 de abril de 2026)
ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-7    # Opus 4.7 (padrão Max/Team Premium)
ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-6
ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5-20251001
CLAUDE_CODE_SUBAGENT_MODEL=sonnet               # Modelo para subagents
MAX_THINKING_TOKENS=10000                       # (Apenas Opus 4.6 e Sonnet 4.6 — removido no Opus 4.7)
CLAUDE_CODE_MAX_OUTPUT_TOKENS=4000              # Limita tamanho da saída
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1          # Ativa agent teams (v2.1.32+)

Configuração de provedor de nuvem:

CLAUDE_CODE_USE_BEDROCK=1                       # Usa AWS Bedrock
CLAUDE_CODE_USE_VERTEX=1                        # Usa Google Vertex AI
CLAUDE_CODE_USE_FOUNDRY=1                       # Usa Microsoft Foundry
ANTHROPIC_BEDROCK_BASE_URL=https://...          # Endpoint Bedrock customizado
ANTHROPIC_BEDROCK_SERVICE_TIER=priority         # Tier de serviço Bedrock (v2.1.122+): 'default', 'flex' ou 'priority'; enviado como header X-Amzn-Bedrock-Service-Tier[^162]
CLAUDE_CODE_SKIP_BEDROCK_AUTH=1                 # Pula auth do Bedrock (para gateways)
CLAUDE_CODE_SKIP_VERTEX_AUTH=1                  # Pula auth do Vertex
AWS_BEARER_TOKEN_BEDROCK=token                  # Bearer token do Bedrock
VERTEX_REGION_CLAUDE_3_7_SONNET=us-west1        # Sobrescreve região do Vertex
CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1    # Opt in para descoberta de gateway /v1/models no seletor /model (v2.1.129+)[^164]

Controle de comportamento:

DISABLE_AUTOUPDATER=1                           # Impede atualizações automáticas em background
DISABLE_UPDATES=1                               # Bloqueia TODOS os caminhos de atualização incluindo `claude update` manual (v2.1.118+, mais restrito que DISABLE_AUTOUPDATER)[^160]
CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1       # Instalações via Homebrew/WinGet executam upgrade do package manager em background, depois pedem reinício (v2.1.129+)[^164]
DISABLE_TELEMETRY=1                             # Opt out de telemetria de uso
DISABLE_ERROR_REPORTING=1                       # Desativa Sentry
DISABLE_BUG_COMMAND=1                           # Desativa comando /bug
DISABLE_COST_WARNINGS=1                         # Esconde avisos de custo
DISABLE_PROMPT_CACHING=1                        # Desativa prompt caching globalmente
DISABLE_PROMPT_CACHING_SONNET=1                 # Desativa apenas para Sonnet
DISABLE_PROMPT_CACHING_OPUS=1                   # Desativa apenas para Opus
DISABLE_NON_ESSENTIAL_MODEL_CALLS=1             # Pula chamadas de API não críticas
ENABLE_PROMPT_CACHING_1H=1                      # Opt in para TTL de prompt cache de 1 hora (v2.1.108+, API/Bedrock/Vertex/Foundry)
ENABLE_PROMPT_CACHING_1H_BEDROCK=1              # Alias deprecado do anterior; v2.1.108+ ainda honra no Bedrock mas registra aviso de deprecação
FORCE_PROMPT_CACHING_5M=1                       # Força TTL de cache de 5 minutos (v2.1.108+)
ENABLE_TOOL_SEARCH=true                         # Reativa tool search no Vertex AI (desativado por padrão a partir do v2.1.119+ para evitar header beta não suportado). Valores válidos: true, false, auto, auto:N[^160]
CLAUDE_CODE_HIDE_CWD=1                          # Esconde o diretório de trabalho no logo de inicialização (v2.1.119+)[^160]
CLAUDE_CODE_FORK_SUBAGENT=1                     # Ativa subagents forkados em builds externos (v2.1.117+)[^160]
CLAUDE_CODE_FORCE_SYNC_OUTPUT=1                 # Força saída sincronizada do terminal quando a auto-detecção falha, como no Emacs eat (v2.1.129+)[^164]
CLAUDE_CODE_SESSION_ID=...                      # Somente leitura: presente no subprocess da ferramenta Bash; corresponde ao session_id passado aos hooks (v2.1.132+)[^168]
CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1          # Pula o renderizador fullscreen de tela alternativa; mantém a conversa no scrollback nativo do terminal (v2.1.132+)[^168]
CLAUDE_EFFORT=...                               # Somente leitura: nível de esforço atual dentro de hooks e subprocess da ferramenta Bash (v2.1.133+)[^169]

Configuração de ferramentas:

BASH_DEFAULT_TIMEOUT_MS=30000                   # Timeout de comandos Bash (30s)
BASH_MAX_TIMEOUT_MS=600000                      # Timeout máximo do bash (10min)
BASH_MAX_OUTPUT_LENGTH=50000                    # Limite de saída do Bash
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1     # Reseta CWD após cada bash
MCP_TIMEOUT=5000                                # Timeout de inicialização do servidor MCP
MCP_TOOL_TIMEOUT=30000                          # Timeout de execução de ferramenta MCP
MAX_MCP_OUTPUT_TOKENS=25000                     # Limite de saída do MCP
SLASH_COMMAND_TOOL_CHAR_BUDGET=15000            # Limite de contexto de slash command

Rede e proxy:

HTTP_PROXY=http://proxy:8080                    # Proxy HTTP
HTTPS_PROXY=https://proxy:8080                  # Proxy HTTPS
NO_PROXY=localhost,example.com                  # Bypass de proxy para domínios
CLAUDE_CODE_CLIENT_CERT=/path/to/cert           # Certificado mTLS
CLAUDE_CODE_CLIENT_KEY=/path/to/key             # Chave privada mTLS
CLAUDE_CODE_CLIENT_KEY_PASSPHRASE=pass          # Passphrase mTLS

UI e terminal:

CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1            # Não atualiza título do terminal
CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL=1             # Pula instalação de extensão da IDE
CLAUDE_CODE_SHELL=/bin/zsh                      # Sobrescreve detecção de shell
USE_BUILTIN_RIPGREP=1                           # Usa ripgrep embutido (padrão)
CLAUDE_CONFIG_DIR=~/.myconfig                   # Diretório de config customizado
IS_DEMO=1                                       # Esconde elementos sensíveis da UI[^37]
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1          # Desativa tarefas em background e Ctrl+B[^46]
CLAUDE_CODE_TMPDIR=/path/to/tmp                 # Sobrescreve diretório temporário[^50]
CLAUDE_CODE_DISABLE_1M_CONTEXT=1               # Desativa janela de contexto de 1M (usa 200K padrão)[^103]
CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=120000       # Timeout do git no marketplace de plugins (padrão 120s, era 30s)[^105]
CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=1        # Remove instruções nativas de commit/PR[^117]
CLAUDE_CODE_DISABLE_CRON=1                    # Para cron jobs agendados no meio da sessão[^121]
CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=30000 # Timeout dos hooks SessionEnd (padrão varia)[^123]
CLAUDE_CODE_USE_POWERSHELL_TOOL=1             # Ativa ferramenta PowerShell do Windows no Linux/macOS (requer pwsh no PATH; v2.1.111+)[^153]
CLAUDE_CODE_ENABLE_AWAY_SUMMARY=1             # Força Session Recap quando telemetria está desativada (v2.1.108+)[^153]
OTEL_LOG_RAW_API_BODIES=1                     # Emite bodies completos de requisição/resposta da API como eventos de log OTel (v2.1.111+)[^153]
TRACEPARENT=00-...                            # Pai do W3C Trace Context (v2.1.110+, SDK/headless)[^153]
TRACESTATE=vendor=value                       # Estado do W3C Trace Context (v2.1.110+, SDK/headless)[^153]

Exporters do OpenTelemetry + gating de campos sensíveis:¹⁶⁴

OTEL_LOGS_EXPORTER=none                       # Exporter de logs OTel (suporta 'none' para desativar; v2.1.85 corrigiu crash)
OTEL_METRICS_EXPORTER=none                    # Exporter de métricas OTel (suporta 'none'; v2.1.85 corrigiu crash)
OTEL_TRACES_EXPORTER=none                     # Exporter de traces OTel (suporta 'none'; v2.1.85 corrigiu crash)
OTEL_LOG_TOOL_CONTENT=1                       # Opt in para emitir conteúdo de ferramenta em spans OTel (v2.1.101+, sensível por padrão)
OTEL_LOG_TOOL_DETAILS=1                       # Opt in para tool_parameters em eventos tool_result do OTel (v2.1.85+)
OTEL_LOG_USER_PROMPTS=1                       # Opt in para emitir prompts de usuário em traces OTel (v2.1.101+, sensível por padrão)
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1    # Desativa fetch de release notes (v2.0.17+); v2.1.110 também parou a requisição auto-title do Haiku em headless/SDK quando definido

Atributos de span de requisição LLM no v2.1.121+: stop_reason, gen_ai.response.finish_reasons e user_system_prompt agora são emitidos em spans de requisição LLM. user_system_prompt é gated por OTEL_LOG_USER_PROMPTS=1 por poder conter PII.¹⁵⁴

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

Controle de API / Modelo:¹⁶⁴

CLAUDE_CODE_EXTRA_BODY='{...}'                # Injeta campos extras de body em chamadas da API; v2.1.113 corrigiu erros 400 com output_config.effort em chamadas de Vertex/subagent
CLAUDE_CODE_MAX_CONTEXT_TOKENS=200000         # Sobrescreve máximo de tokens de contexto (var pré-existente; v2.1.98 corrigiu tratamento de DISABLE_COMPACT quando ambos estão definidos)
CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS=25000 # Sobrescreve limite padrão de tokens para operações de leitura de arquivo (v2.1.0+)
CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1   # Não faz fallback para API não-streaming em falhas de streaming (v2.1.83+)
ANTHROPIC_BETAS=beta1,beta2                   # Ativa headers beta da API; v2.1.78 corrigiu silent ignore em modelos Haiku
ANTHROPIC_SMALL_FAST_MODEL=arn:...            # ID do modelo rápido (ARN do Bedrock suportado; v0.2.125 parou de escapar barras no ARN)

Plugins / MCP:¹⁶⁴

CLAUDE_CODE_PLUGIN_CACHE_DIR=~/.claude/plugins # Diretório de cache de plugins (v2.1.72 corrigiu literal '~' em alguns shells)
CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 # Preserva cache do marketplace de plugins quando git pull falha (offline-friendly; v2.1.90+)
CLAUDE_CODE_MCP_SERVER_NAME=server1           # Passado para scripts headersHelper de MCP para que um helper sirva múltiplos servidores (v2.1.85+)
CLAUDE_CODE_MCP_SERVER_URL=https://...        # Passado para scripts headersHelper de MCP junto com o nome (v2.1.85+)

Shell / IDE:¹⁶⁴

CLAUDE_CODE_SHELL_PREFIX="time "              # Envolve cada comando shell invocado pelo Claude com um prefixo (v1.0.61+)
CLAUDE_CODE_GIT_BASH_PATH=C:\Program\ Files\Git\bin\bash.exe  # Caminho customizado do Git Bash no Windows (v2.1.98+)
CLAUDE_CODE_EXIT_AFTER_STOP_DELAY=60000       # SDK: sai após N ms ocioso (v2.0.35+)
CLAUDE_CODE_AUTO_CONNECT_IDE=false            # Desativa auto-conexão da IDE (v1.0.61+)

Enterprise / auth:¹⁶⁴

CLAUDE_CODE_PROXY_RESOLVES_HOSTS=1            # Opt in para resolução DNS no lado do proxy (v2.0.55 mudou de default-on para opt-in)
CLAUDE_CODE_API_KEY_HELPER_TTL_MS=300000      # TTL para chaves API geradas dinamicamente via apiKeyHelper (refresh do apiKeyHelper adicionado no v0.2.74 com padrão de 5min; env var adicionada no v0.2.117)

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

${CLAUDE_SKILL_DIR}                            # Auto-referência para skills localizarem seu próprio diretório[^117]

Identidade do caller SDK (v2.1.51+):

CLAUDE_CODE_ACCOUNT_UUID=uuid                  # Fornece UUID da conta sincronamente para callers SDK
CLAUDE_CODE_USER_EMAIL=[email protected]        # Fornece email do usuário para callers SDK
CLAUDE_CODE_ORGANIZATION_UUID=uuid             # Fornece UUID da organização para callers SDK

Debugging:

ANTHROPIC_LOG=debug                             # Ativa logging de requisições da API

Qual modelo eu devo escolher?

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

Modelos disponíveis

Opus 4.7 (16 de abril de 2026): O carro-chefe atual. Janela de contexto de 1M de tokens com preço padrão — sem prêmio por contexto longo. Saída máxima de 128K, apenas adaptive thinking (extended thinking foi removido) e um novo nível de esforço xhigh recomendado como ponto de partida para cargas de trabalho de codificação e agênticas.¹⁴⁵ 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 em $5/$25 por MTok com cache write de 5 minutos a $6,25, cache write de 1 hora a $10 e cache read a $0,50 por MTok.¹⁴⁴ O Opus 4.7 resolve 3× mais tarefas de produção no SWE-Bench que o Opus 4.6, pontua 70% no CursorBench (vs 58% do 4.6) e eleva a resolução em 13% no benchmark interno de codificação de 93 tarefas da Anthropic.¹⁴⁴ Usa um novo tokenizer — espere contagens de tokens aproximadamente 1×–1,35× para o mesmo texto; aumente a margem de max_tokens e os gatilhos de compactação.¹⁴⁵ Visão suporta 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):¹⁵¹

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

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

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

Mudanças incompatíveis na Messages API no Opus 4.7 (visíveis ao chamador):¹⁴⁵

• O budget_tokens do extended thinking foi removido. Use thinking: {type: "adaptive"} em vez disso. O adaptive thinking está desativado por padrão; requisições sem campo thinking rodam sem thinking.
• Definir temperature, top_p ou top_k com 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 faz streaming de thinking para os usuários).

Task budgets (header beta task-budgets-2026-03-13) permitem que você informe o modelo sobre uma meta de tokens em todo o loop agêntico 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 o Opus 4.7 para melhor codificação agêntica. O Opus 4.6 foi lançado originalmente em 5 de fevereiro de 2026.⁷⁹¹⁴⁴ A partir do v2.1.117 (22 de abril de 2026), assinantes Pro e Max têm high como esforço padrão no Opus 4.6 e Sonnet 4.6 (anteriormente medium); o 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 Claude Cowork.⁹³ Mesmo preço do Sonnet 4.5 ($3/$15 por MTok). Desempenho aprimorado de busca agêntica consumindo menos tokens. Suporta extended thinking, adaptive thinking e janela de contexto de 1M de tokens (beta). Saída máxima de 64K (limite superior 128K no 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 prévia de pesquisa para trabalho defensivo de cibersegurança, oferecido sob o Project Glasswing.¹³⁹ Apenas por convite; não disponível ao público em geral. A Anthropic enquadra o Opus 4.7 como deliberadamente menos capaz que o Mythos em dimensões cibernéticas — uma escolha 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 50K-200K tokens de entrada e 10K-50K tokens de saída. Com o Haiku, isso custa $0,10-$0,45 por sessão. Com o Opus, a mesma sessão custa $0,50-$2,25, 5× mais. Reserve o Opus para problemas genuinamente difíceis.¹

Quando usar cada modelo

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

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

Opus: O nível flagship a partir de 16 de abril de 2026, e o padrão nos planos Max e Team Premium.¹⁴⁴¹⁴⁷ Reserve o raciocínio de maior custo onde ele compensa: decisões arquiteturais, debugging complicado, entendimento de sistemas complexos, análise de segurança, trabalho agêntico de longo prazo. Opus 4.7 resolve 3× mais tarefas de produção no SWE-Bench que o Opus 4.6, pontua 70% no CursorBench (vs 58%) e eleva a resolução em 13% em um benchmark interno de codificação de 93 tarefas.¹⁴⁴ Claude Code usa xhigh como esforço 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 administrador.¹⁴⁶ Contexto de 1M com preço padrão — sem prêmio por contexto longo. Mudanças de comportamento que vale a pena conhecer: O Opus 4.7 segue instruções de forma mais literal, calibra o tamanho da resposta para a 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 de progresso intermediárias 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 a velocidade importa). Excelente para refatoração complexa onde você quer o melhor plano, mas não precisa de raciocínio nível Opus para cada edição individual.

Trocando de modelo

Durante a sessão:

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

Na inicialização:

claude --model opus

Via ambiente:

export ANTHROPIC_MODEL=opus

No settings.json:

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

Especificamente para subagents:

export CLAUDE_CODE_SUBAGENT_MODEL=haiku

Contexto estendido

Para bases de código grandes ou sessões longas, ative o contexto de 1M de 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 todos a janela de contexto completa de 1M de tokens com preço padrão — sem prêmio por contexto longo.¹⁴⁸ Uma requisição de 900K tokens é cobrada à mesma taxa por token que uma requisição de 9K tokens. Os descontos de prompt caching e batch processing se aplicam às taxas padrão em toda a janela de contexto.

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

Para desativar variantes de contexto de 1M no seletor de modelo, defina CLAUDE_CODE_DISABLE_1M_CONTEXT=1.

Verificando 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 modelo (v2.1.51+): O seletor /model agora mostra rótulos legíveis (ex.: “Sonnet 4.6”) em vez de IDs brutos de modelo para versões fixadas, com dicas de upgrade quando versões mais novas estão disponíveis.⁹⁸

Fast Mode (v2.1.36+)

O fast mode oferece saída significativamente mais rápida do mesmo modelo; ele não muda para um modelo mais barato. Alterne durante uma sessão com /fast.⁸⁶

> /fast            # Toggle fast mode on/off

Preço (Opus 4.6 fast mode):

O fast mode é prévia de pesquisa, apenas Opus 4.6, e entrega saída ~2,5× mais rápida a 6× o preço base.¹⁴⁹ Ativar /fast muda automaticamente a sessão para Opus 4.6 se você estava em outro modelo; desativar /fast te deixa no Opus 4.6 até trocar via /model. Fast mode não está disponível no Opus 4.7, Sonnet, Haiku ou via Bedrock/Vertex/Foundry. Requer extra usage ativado e, para Team/Enterprise, ativação por administrador.

Quando usar fast mode: - Iterando rapidamente em pequenas mudanças onde a latência é o gargalo - Gerando testes, boilerplate ou código repetitivo onde a velocidade importa mais que o custo - Trabalhando sequencialmente em uma lista de tarefas similares

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

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

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

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

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

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

Claude Code agora usa xhigh como esforço padrão para Opus 4.7. xhigh é apenas para Opus 4.7 — outros modelos voltam para high. Claude Managed Agents lida com o esforço automaticamente; o parâmetro de esforço é um conceito da Messages API.¹⁴⁵¹⁴⁶

Auto Mode no Max (v2.1.111+)

Auto Mode — uma substituição mais segura 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. Nota (v2.1.111+): a flag --enable-auto-mode foi removida; inicie uma sessão em Auto Mode com --permission-mode auto em vez disso. Auto Mode não está disponível no Pro; conforme a documentação de permission modes da Anthropic, atualmente é apenas Anthropic-API direto — Bedrock, Vertex e Foundry ainda não são suportados.

Regras customizadas sem perder os padrões (v2.1.118+). Versões anteriores tornavam autoMode.allow, autoMode.soft_deny e autoMode.environment excludentes: definir sua própria lista significava perder as regras de segurança embutidas. O sentinela $defaults resolve isso — ele se expande inline para a lista embutida exatamente na posição onde você o coloca, então você pode sobrepor regras customizadas em torno 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
    ]
  }
}

Opção “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 o explicador sem precisar criar script para uma flag.¹⁵²

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

Session Recap (v2.1.108+)

Um novo recurso em nível de sessão que traz à tona o contexto quando você retorna a uma sessão pausada. Ativado por padrão e desativável via /config ou CLAUDE_CODE_ENABLE_AWAY_SUMMARY=0. O modelo também pode invocar slash commands embutidos (/init, /review, /security-review) via a Skill tool — estende o padrão subagent/skill.¹⁴⁶

Push Notifications (v2.1.110+)

Quando o Remote Control está configurado com “Push when Claude decides” ativado, Claude agora pode enviar notificações push para mobile a seu próprio critério via uma nova ferramenta de push-notification. Combina com a superfície existente do Remote Control mobile/web.¹⁴⁶ /context, /exit e /reload-plugins agora também funcionam em clientes Remote Control.

Ferramenta Windows PowerShell (v2.1.111+, rollout)

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

Auto-aprovação no permission-mode (v2.1.119+). Comandos da ferramenta PowerShell agora podem receber auto-aprovação 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 somente leitura, igualando a ergonomia de operação que as equipes já têm no Linux/macOS.¹⁵²

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

Padrões Bash somente leitura com argumentos glob (ex.: ls *.ts, cat src/*.md) e comandos começando com cd <project-dir> && não disparam mais um prompt de permissão.¹⁴⁶ Combinado com /less-permission-prompts, espere significativamente menos interrupções nos workflows do dia a dia.

Distributed Tracing (v2.1.110+)

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

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

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 rodar JavaScript embutido. Os comandos de instalação e atualização permanecem os mesmos, e equipes não precisam mudar scripts de rollout.

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

O editor de prompts ganha navegação no estilo readline em entrada multilinha, além de scroll de viewport em fullscreen:

Esses atalhos estão ativados por padrão. Não é necessária configuração de keybinding.

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

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

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

v2.1.114 (18 de abril de 2026) traz uma única correção: o diálogo de permissão poderia travar quando um colega de agent-teams solicitasse 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. Entendê-lo é 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 aplicam permissões em toda a organização.

Níveis de permissão

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

Capacidades da ferramenta LSP (v2.0.74+): A ferramenta LSP fornece inteligência de código semelhante à de uma IDE: - Ir para definição: Saltar para onde um símbolo é definido - Encontrar referências: Listar todos os usos de um símbolo em todo o código - Documentação ao passar o mouse: Obter informações de tipo e documentação para qualquer símbolo - Funciona com TypeScript, Python, Go, Rust e outras linguagens com suporte a LSP - Requer que o language server esteja disponível (normalmente instalado com sua toolchain)

Ferramentas de modificação (requerem aprovação): - Edit - Modificar arquivos existentes - Write - Criar novos arquivos - Bash - Executar comandos shell - WebFetch - Buscar conteúdo de URL - NotebookEdit - Modificar Jupyter notebooks

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

Modo Auto (v2.1.85+): Uma alternativa mais segura ao --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 arquivos no diretório de trabalho são aprovadas automaticamente - Regras personalizadas de allow/deny são resolvidas primeiro - Todo o resto vai para o classificador para avaliação - Se bloqueado, o Claude tenta uma abordagem alternativa automaticamente

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

Disjuntor: 3 bloqueios consecutivos ou 20 no total em uma sessão pausa de volta para o modo manual.¹²⁵

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

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

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

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

claude --dangerously-skip-permissions

Defina o modo via CLI:

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

Alterne durante a sessão:

Shift+Tab  # Cycles through modes

No settings.json:

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

Sintaxe de 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: Os padrões Bash correspondem apenas a prefixos, não a regex. Um padrão como Bash(curl http:*) não corresponderá a curl -X GET http://... porque as opções vêm antes da URL. Para um bloqueio confiável, negue o comando inteiramente: Bash(curl:*).

Padrões de operação 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/**) - relativos ao diretório de trabalho - Absoluto a partir do arquivo de configurações: Edit(/build/**) - relativo à localização do arquivo de configurações - Absoluto verdadeiro: 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 curinga mcp__server__* para permitir ou negar todas as ferramentas de um servidor MCP específico.³² A sintaxe curinga é útil para habilitar rapidamente todas as ferramentas de servidores confiáveis ou bloquear servidores inteiros de fontes não confiáveis.

Padrões 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 referenciar código em diretórios irmãos.

Modo Sandbox

Habilite isolamento de sistema de arquivos e de rede:

> /sandbox

Ou configure nas configurações:

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

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

Dica de especialista: O modo sandbox é excelente para executar o Claude em bases de código não confiáveis. Habilite-o ao explorar projetos desconhecidos ou quando quiser uma camada extra de proteção. Testes internos da Anthropic descobriram que o sandboxing reduz as solicitações de permissão em 84%.³⁸ O sandbox usa primitivas de nível de sistema operacional (seatbelt do macOS, bubblewrap do Linux) para isolamento de sistema de arquivos e de rede, então mesmo uma injeção de prompt bem-sucedida fica totalmente contida. A Anthropic tornou o runtime do sandbox open-source para equipes que constroem seus próprios agentes.⁸²

Notas de segurança (v2.1.34+): Comandos excluídos do sandboxing via sandbox.excludedCommands ou dangerouslyDisableSandbox podiam anteriormente contornar a regra de permissão Bash ask 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 no modo sandbox, impedindo que injeção de prompt modifique definições de skills.⁸⁸ A v2.1.77 adiciona uma configuração de sistema de arquivos do sandbox allowRead para reativar o 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 agente em .claude/ (v2.1.121+): --dangerously-skip-permissions não solicita mais aprovação para gravações em .claude/skills/, .claude/agents/ e .claude/commands/.¹⁵⁴

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

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

• sandbox.network.deniedDomains bloqueia hosts específicos mesmo quando um curinga mais amplo em allowedDomains os permitiria. Use a lista de bloqueio para cortar pastebins, file drops ou hosts conhecidamente ruins sem reescrever toda a sua política de permissão.
• Regras de negação para comandos wrapper. As regras de negação Bash agora correspondem a comandos envolvidos em env, sudo, watch, ionice, setsid e wrappers de exec semelhantes. Regras como Bash(rm:*) agora capturam env rm -rf, sudo rm -rf e padrões irmãos de bypass.
• Regras allow 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ão.
• Proteção de remoção no macOS. Regras allow Bash(rm:*) agora tratam /private/etc, /private/var, /private/tmp e /private/home como alvos de remoção perigosos. /var, /etc e /tmp são symlinks para /private/, então o formato anterior da regra perdia os alvos canônicos.

Como Funcionam os Hooks?

Hooks executam comandos shell determinísticos em pontos específicos do fluxo de trabalho do Claude Code. Diferente de instruir o Claude via prompt para executar ações, hooks garantem a execução independentemente do comportamento do modelo. Eles são essenciais para impor padrões de equipe e automatizar tarefas repetitivas. Veja Frameworks de Decisão para a árvore de decisão “Qual Tipo de Hook?” cobrindo hooks de comando, prompt e agente.

Por que hooks em vez de prompts: Dizer ao Claude “sempre execute Prettier após editar arquivos” funciona às vezes. Mas o Claude pode esquecer, priorizar velocidade ou decidir que a alteração é “pequena demais.” Hooks garantem a execução: cada Edit ou Write aciona seu formatador, sempre, sem exceções. Para conformidade, segurança e padrões de equipe, 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": "*"}              // Corresponde a todas as ferramentas
{"matcher": "Bash"}           // Corresponde apenas a Bash
{"matcher": "Edit|Write"}     // Corresponde a Edit ou Write
{"matcher": "mcp__github"}    // Corresponde a ferramentas do servidor MCP
{"matcher": ""}               // Corresponde a eventos sem ferramentas (como UserPromptSubmit)

Protocolo de Entrada/Saída de Hooks

Hooks recebem JSON via 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 campos agent_id e agent_type quando acionados a partir de um subagent ou sessão --agent, além de um campo worktree em comandos de hook da status line.¹¹⁰

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 analisar arquivos de transcrição:

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

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

Para controle avançado, hooks podem produzir 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 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."
  }
}

Nota: 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 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, e-mail, Pushover) que não devem atrasar a sessão - 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 (deve concluir antes da próxima edição) - Validação (deve bloquear em caso de falha) - Qualquer hook que precise modificar a entrada/saída da ferramenta

Hooks Baseados em Prompt e em Agente (v2.1.32+)

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

Hooks de prompt (type: "prompt") enviam um prompt de turno único 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-os para webhooks, serviços de notificação externos 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 dos hooks de comando (retornam JSON com decision e reason). Eles são roteados pelo proxy de rede do sandbox quando o sandboxing está habilitado. Não suportados para eventos SessionStart/Setup.

Hooks de agente (type: "agent") iniciam um subagent com acesso a ferramentas (Read, Grep, Glob) para verificação multi-turno. Use-os quando a verificação exigir inspeção de 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 suportam os campos model (padrão: modelo rápido) e timeout. Eventos suportados: PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, UserPromptSubmit, Stop, SubagentStop, TaskCompleted. TeammateIdle não suporta hooks de prompt/agente.

Hooks de Ferramenta MCP (v2.1.118+)

Hooks agora podem invocar uma ferramenta MCP diretamente via type: "mcp_tool", dispensando a necessidade de envolver um subprocesso Bash que chame o servidor.¹⁵²

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

Isso combina bem com servidores MCP que os usuários já têm configurados: qualquer ferramenta acessível por /mcp torna-se chamável por hook.

duration_ms em Hooks PostToolUse (v2.1.119+)

Entradas de hooks PostToolUse e PostToolUseFailure agora incluem duration_ms, o tempo de execução da ferramenta excluindo prompts de permissão e hooks PreToolUse.¹⁵² Útil para detecção de 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 de ferramentas via hookSpecificOutput.updatedToolOutput. A partir da v2.1.121, o mesmo campo funciona para qualquer hook PostToolUse — ferramentas embutidas (Bash, Read, Edit, Glob, Grep, etc.), ferramentas de subagent e ferramentas MCP. Casos de uso: redigir conteúdo sensível da saída de qualquer ferramenta, normalizar a estrutura para consumidores downstream, 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 do 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 previne exfiltração arbitrária de variáveis de ambiente por meio de valores de header. Hooks HTTP também são roteados pelo proxy de rede do sandbox quando o sandboxing está habilitado, aplicando a allowlist de domínios. Hooks HTTP não são suportados para 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 de workspace para hooks (v2.1.51+): Comandos de hook statusLine e fileSuggestion agora exigem aceitação de confiança do workspace antes de executar em modo interativo, fechando um potencial vetor de segurança.⁹⁸

Exemplos Práticos de Hooks

Auto-formatar arquivos TypeScript após 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 após mudanças no código:

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

Sistema de notificação personalizado:

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

Depuração de Hooks

Habilite o modo de depuração para solucionar problemas de hooks:

claude --debug

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

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

Hooks Escopados a Componentes (v2.1.0+)

Hooks podem ser definidos diretamente em Skills, subagents e slash commands usando frontmatter. Esses hooks são escopados 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 suportados: 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 de Longa Duração

Para sessões noturnas ou desacompanhadas do Claude Code, configure hooks para manter o Claude no rumo certo sem intervenção manual. O insight-chave: use hooks de linting e testes como guardrails que forçam 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 noturnas:

1. Verificação pré-flight: Use um hook Setup para verificar se o ambiente está pronto
2. Validação contínua: Hooks PostToolUse executam testes após cada alteração
3. Portão de conclusão: Hooks Stop verificam todos os critérios de aceitação antes que o Claude declare “concluído”
4. Notificação: Hooks Stop podem te notificar via Slack/Pushover quando o Claude termina ou fica travado

Combine com --dangerously-skip-permissions em um container em sandbox para execuções noturnas totalmente autônomas. O Claude continuará iterando até os testes passarem ou 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}"
      }
    }
  }
}

Variáveis de ambiente expandem usando a sintaxe ${VAR} com defaults opcionais: ${VAR:-default}.

Comandos de gerenciamento MCP

claude mcp list                      # View all configured servers
claude mcp get github                # Get specific server details
claude mcp remove github             # Remove a server
claude mcp reset-project-choices     # Reset project-scoped approvals
claude mcp add-from-claude-desktop   # Import from Claude Desktop
claude mcp add-json weather '{"type":"http","url":"..."}'  # Add from JSON

# Within Claude Code REPL
> /mcp                               # Interactive MCP management

Autenticação OAuth

Para servidores que requerem OAuth:

> /mcp
# Follow browser-based OAuth flow
# Tokens stored securely and auto-refreshed
# Use "Clear authentication" to revoke access

Usando recursos e prompts MCP

Recursos de referência:

@github:issue://123
@postgres:schema://users
@docs:file://api/authentication

Prompts MCP como slash commands:

/mcp__github__list_prs
/mcp__github__pr_review 456
/mcp__jira__create_issue "Bug title" high

Limites de output

O Claude Code limita o output MCP para evitar overflow de contexto: - Limite de aviso: 10.000 tokens - Máximo padrão: 25.000 tokens

Aumente se necessário:

export MAX_MCP_OUTPUT_TOKENS=50000

Servidores MCP populares

Padrões práticos de MCP

Workflow do GitHub:

> Review PR #456
> List all open issues assigned to me
> Create a bug issue for the authentication failure we found

Queries de banco de dados:

> What's our total revenue this quarter?
> Show the schema for the users table
> Find customers with no purchases in 90 days

Monitoramento de erros:

> What errors occurred in production today?
> Show the stack trace for error ABC123
> Which deployment introduced these errors?