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

Resumo: Claude Code é um CLI agêntico que lê sua base de código, executa comandos e modifica arquivos através de um sistema em camadas de permissões, hooks, integrações MCP e subagents. Domine cinco sistemas principais (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 com Opus se qualidade for sua única variável. Use hooks (não prompts) para tudo que deve ser executado sempre.

Claude Code opera como um sistema agêntico, não como uma interface de chat com conhecimento de programação. O CLI lê sua base de código, executa comandos, modifica arquivos, gerencia fluxos de trabalho git, conecta-se a serviços externos via MCP e delega tarefas complexas a subagents especializados. Tudo flui através de uma interface de linha de comando que se integra à forma como desenvolvedores realmente trabalham. Em fevereiro de 2026, 4% dos commits públicos no GitHub (~135.000 por dia) são de autoria do Claude Code — um crescimento de 42.896× em 13 meses desde o preview de pesquisa — e 90% do código da própria Anthropic é escrito por IA.¹¹⁰

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

1. Hierarquia de configuração: controla o comportamento
2. Sistema de permissões: controla operações
3. Sistema de hooks: habilita automação determinística
4. Protocolo MCP: estende capacidades
5. Sistema de subagents: lida com tarefas complexas de múltiplas etapas

Principais conclusões

• Cinco sistemas determinam sua eficácia: hierarquia de configuração, permissões, hooks, MCP e subagents controlam tudo, do comportamento à automação.
• Delegue 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 devem rodar sempre, independentemente do comportamento do modelo.
• Escalonamento de modelos economiza custo sem sacrificar qualidade: direcione a exploração de subagents para modelos mais baratos e reserve Opus para raciocínio arquitetural genuíno — ou padronize com Opus se qualidade for sua única variável.
• MCP conecta Claude à sua cadeia de ferramentas: bancos de dados, GitHub, Sentry e mais de 3.000 integrações estendem o Claude além da leitura de arquivos e comandos bash.

Passei meses levando o Claude Code ao limite em bases de código de produção, pipelines de CI/CD e implantações corporativas. 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 reais e os casos extremos que pegam até usuários experientes de surpresa.

Escolha seu caminho

Como usar este guia

Esta é uma referência com mais de 5.000 linhas — você não precisa ler tudo do início ao fim. Comece pelo ponto que se encaixa no seu nível de experiência:

Use Ctrl+F / Cmd+F do seu navegador para buscar flags, comandos ou chaves de configuração específicas. O Cartão de Referência Rápida no final oferece um resumo escaneável de todos os principais comandos.

Deep dives relacionados

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

Início rápido em 60 segundos

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

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

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

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

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

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

Pré-requisitos: Node 18+ (para o caminho via npm), macOS / Linux / Windows 10+. Uma assinatura Claude Pro, Max, Team ou Enterprise, ou uma chave API Anthropic pay-per-token, cobre o uso. Veja Como instalar o Claude Code? para especificidades de plataforma, troubleshooting e o caminho do binário nativo (padrão desde a v2.1.113).

Como o Claude Code funciona: o modelo mental

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

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

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

Camada de Delegação: subagents são iniciados com contextos limpos, fazem trabalho focado e retornam resumos. Os resultados da exploração não inflam sua conversa principal; apenas as conclusões retornam. Direcione subagents para tiers de modelo mais baratos para exploração, ou use seu modelo principal o tempo todo se a qualidade importa mais do 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 expertise de domínio que o Claude aplica automaticamente. Plugins empacotam todos esses para distribuição.

O insight-chave: a maioria dos usuários trabalha inteiramente na Camada Core, vendo o contexto inflar e os custos subirem. Power users empurram a exploração e o trabalho especializado para a Camada de Delegação, mantêm a Camada de Extensão configurada para seu workflow, e usam a Camada Core apenas para orquestração e decisões finais.

Sumário

1. Como instalar o Claude Code?
2. Início rápido: sua primeira sessão
3. Modos de interação principais
4. Sistema de configuração em profundidade
5. Qual modelo devo escolher?
6. Quanto custa o Claude Code?
7. Frameworks de decisão
8. Como funciona o sistema de permissões?
9. Como funcionam os hooks?
10. O que é MCP (Model Context Protocol)?
11. O que são subagents?
12. O que é o modo de pensamento estendido?
13. Output styles
14. Slash commands
15. Como funcionam as skills?
16. Sistema de plugins
17. Como funciona a memória?
18. Entrada de imagens e multimodal
19. Modo de voz
20. Como funciona a integração com Git?
21. Como uso o Claude Code na minha IDE?
22. Padrões de uso avançados
23. Agents remotos e em background [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 faço debug de problemas?
29. Implantação corporativa
30. Referência de atalhos de teclado
31. Boas práticas
32. Receitas de workflow
33. Guia de migração
34. Orientação por público
35. Cartão de referência rápida
36. Changelog
37. Referências

Como instalar o Claude Code?

Requisitos do sistema

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

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

apk add libgcc libstdc++ ripgrep
export USE_BUILTIN_RIPGREP=0

Matriz de suporte de plataformas

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

Consulta rápida — todos os métodos, todos os comandos, verificação de versão em uma única tela. As subseções abaixo cobrem detalhes específicos por método e solução de problemas.

Desde a v2.1.113, o CLI canônico inicia um binário nativo do Claude Code por meio de uma dependência opcional específica para cada plataforma, em vez do JavaScript incluído — use o instalador nativo para a distribuição testada. O caminho via npm ainda funciona, mas recebe o aviso de depreciação adicionado pela primeira vez na v2.1.15.

Métodos de instalação

Instalação nativa (recomendada)

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

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

# Homebrew alternative
brew install --cask claude-code

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

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

Para instalação de uma versão específica:

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

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

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

Instalação via NPM (depreciada)

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

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

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

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

Migração de uma instalação existente

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

claude install

Opções de autenticação

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

Claude Console (cobrança via API)

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

Assinatura Claude Pro ou Max

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

Plataformas corporativas

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

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

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

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

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

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

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

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

Verificação

claude doctor

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

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

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

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

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

claude auth logout && claude auth login

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

Atualizações

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

Desativar auto-atualizações:

export DISABLE_AUTOUPDATER=1

Ou no settings.json:

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

Atualização manual:

claude update

Desinstalação

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

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

Instalação nativa (Windows PowerShell):

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

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

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

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

1. Instale e inicie:

claude                           # Inicia no diretório atual

2. Navegue até um projeto:

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

3. Peça ao Claude para fazer algo:

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

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

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

5. Continue depois:

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

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

Modos principais de interação

REPL interativo

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

cd your-project
claude

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

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

claude "explain the authentication flow in this project"

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

Modo não-interativo

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

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

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

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

Para saída estruturada adequada para parsing em scripts:

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

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

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

Para processamento em tempo real de saída em streaming:

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

Opções de formato de saída:

Códigos de saída:

Controlando o comportamento agêntico no modo -p:

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

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

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

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

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

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

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

Gerenciamento de sessão

As sessões preservam o histórico de conversas para continuação. A persistência de sessão é essencial para trabalhos complexos com múltiplas sessões:

# Continue most recent session
claude -c

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

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

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

Sessões vinculadas a PR (v2.1.27+, expandido em v2.1.119+): Inicie uma sessão vinculada a um pull ou merge request específico. A partir da v2.1.119, --from-pr aceita URLs de MR do GitLab, PR do Bitbucket e PR do GitHub Enterprise, além de github.com:⁸¹¹⁵⁹

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

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

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

Sessões nomeadas: Nomeie sessões na inicialização ou durante uma sessão:

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

# Name current session
> /rename auth-refactor

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

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

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

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

Modo plano

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

Entrando no modo plano:

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

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

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

Como funciona:

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

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

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

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

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

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

Mergulho profundo no sistema de configuração

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

Hierarquia de configuração

Dica de especialista: Use .claude/settings.local.json para preferências pessoais em projetos compartilhados (adicione-o ao .gitignore). Use .claude/settings.json para configuração de toda a equipe que será versionada no controle de código.

Referência completa do settings.json

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

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-4-5-20250929",
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(npm run:*)",
      "Bash(git:*)",
      "Bash(make:*)",
      "Edit(src/**)",
      "Write(src/**)",
      "mcp__github"
    ],
    "deny": [
      "Read(.env*)",
      "Read(secrets/**)",
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Edit(package-lock.json)",
      "Edit(.git/**)"
    ],
    "ask": [
      "WebFetch",
      "Bash(curl:*)",
      "Bash(docker:*)"
    ],
    "additionalDirectories": [
      "../shared-lib",
      "../docs"
    ],
    "defaultMode": "acceptEdits"
  },
  "env": {
    "NODE_ENV": "development",
    "DEBUG": "app:*"
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$FILE_PATH\""
          }
        ]
      }
    ]
  },
  "sandbox": {
    "enabled": false,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"]
  },
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  },
  "includeCoAuthoredBy": true,
  "cleanupPeriodDays": 30,
  "outputStyle": "Explanatory",
  "language": "en",
  "respectGitignore": true,
  "showTurnDuration": true,
  "plansDirectory": ".claude/plans",
  "spinnerVerbs": ["Thinking", "Processing", "Analyzing"],
  "spinnerTipsOverride": {
    "tips": ["Custom tip 1", "Custom tip 2"],
    "excludeDefault": true
  },
  "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
  }
}

Referência de variáveis de ambiente

Autenticação e API:

ANTHROPIC_API_KEY=sk-ant-...                    # Autenticação direta via API
ANTHROPIC_AUTH_TOKEN=token                      # Cabeçalho de autorização personalizado
ANTHROPIC_CUSTOM_HEADERS="X-Key: val"           # Cabeçalhos de requisição adicionais

Configuração de modelo:

ANTHROPIC_MODEL=claude-opus-4-7                 # Sobrescreve o 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 o tamanho da saída
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1          # Habilita 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 personalizado do Bedrock
ANTHROPIC_BEDROCK_SERVICE_TIER=priority         # Tier de serviço do Bedrock (v2.1.122+): 'default', 'flex' ou 'priority'; enviado como cabeçalho X-Amzn-Bedrock-Service-Tier[^162]
CLAUDE_CODE_SKIP_BEDROCK_AUTH=1                 # Pula autenticação do Bedrock (para gateways)
CLAUDE_CODE_SKIP_VERTEX_AUTH=1                  # Pula autenticação do Vertex
AWS_BEARER_TOKEN_BEDROCK=token                  # Bearer token do Bedrock
VERTEX_REGION_CLAUDE_3_7_SONNET=us-west1        # Sobrescreve a região do Vertex

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 rigoroso que DISABLE_AUTOUPDATER)[^160]
DISABLE_TELEMETRY=1                             # Recusa telemetria de uso
DISABLE_ERROR_REPORTING=1                       # Desabilita Sentry
DISABLE_BUG_COMMAND=1                           # Desabilita o comando /bug
DISABLE_COST_WARNINGS=1                         # Oculta avisos de custo
DISABLE_PROMPT_CACHING=1                        # Desabilita prompt caching globalmente
DISABLE_PROMPT_CACHING_SONNET=1                 # Desabilita apenas para Sonnet
DISABLE_PROMPT_CACHING_OPUS=1                   # Desabilita apenas para Opus
DISABLE_NON_ESSENTIAL_MODEL_CALLS=1             # Pula chamadas não críticas à API
ENABLE_PROMPT_CACHING_1H=1                      # Adesão ao TTL de prompt cache de 1 hora (v2.1.108+, API/Bedrock/Vertex/Foundry)
ENABLE_PROMPT_CACHING_1H_BEDROCK=1              # Alias depreciado para o anterior; v2.1.108+ ainda o aceita no Bedrock mas registra um aviso de depreciaçã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 (desabilitado por padrão na v2.1.119+ para evitar cabeçalho beta não suportado). Valores válidos: true, false, auto, auto:N[^160]
CLAUDE_CODE_HIDE_CWD=1                          # Oculta o diretório de trabalho no logo de inicialização (v2.1.119+)[^160]
CLAUDE_CODE_FORK_SUBAGENT=1                     # Habilita subagents em fork em builds externos (v2.1.117+)[^160]

Configuração de ferramentas:

BASH_DEFAULT_TIMEOUT_MS=30000                   # Timeout de comando 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                  # Ignora 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 o título do terminal
CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL=1             # Pula instalação da extensão de IDE
CLAUDE_CODE_SHELL=/bin/zsh                      # Sobrescreve detecção de shell
USE_BUILTIN_RIPGREP=1                           # Usa o ripgrep incluído (padrão)
CLAUDE_CONFIG_DIR=~/.myconfig                   # Diretório de configuração personalizado
IS_DEMO=1                                       # Oculta elementos sensíveis da UI[^37]
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1          # Desabilita 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               # Desabilita janela de contexto de 1M (usa o padrão de 200K)[^103]
CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=120000       # Timeout de git do 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 jobs cron agendados no meio da sessão[^121]
CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=30000 # Timeout de hooks SessionEnd (padrão varia)[^123]
CLAUDE_CODE_USE_POWERSHELL_TOOL=1             # Habilita ferramenta PowerShell do Windows em Linux/macOS (requer pwsh no PATH; v2.1.111+)[^153]
CLAUDE_CODE_ENABLE_AWAY_SUMMARY=1             # Força Session Recap quando telemetria está desabilitada (v2.1.108+)[^153]
OTEL_LOG_RAW_API_BODIES=1                     # Emite corpos completos de requisição/resposta da API como eventos de log OTel (v2.1.111+)[^153]
TRACEPARENT=00-...                            # W3C Trace Context parent (v2.1.110+, SDK/headless)[^153]
TRACESTATE=vendor=value                       # W3C Trace Context state (v2.1.110+, SDK/headless)[^153]

Exportadores OpenTelemetry + controle de campos sensíveis:¹⁶³

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

Atributos de span de requisição LLM na v2.1.121+: stop_reason, gen_ai.response.finish_reasons e user_system_prompt agora são emitidos em spans de requisição LLM. user_system_prompt é controlado por OTEL_LOG_USER_PROMPTS=1 já que pode conter PII.¹⁶¹

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

Controle de API / Modelo:¹⁶³

CLAUDE_CODE_EXTRA_BODY='{...}'                # Injeta campos extras no body de chamadas à API; v2.1.113 corrigiu erros 400 com output_config.effort em chamadas Vertex/subagent
CLAUDE_CODE_MAX_CONTEXT_TOKENS=200000         # Sobrescreve max context tokens (variável pré-existente; v2.1.98 corrigiu o tratamento de DISABLE_COMPACT quando ambas estão definidas)
CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS=25000 # Sobrescreve o limite padrão de tokens em 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                   # Habilita cabeçalhos beta da API; v2.1.78 corrigiu ignore silencioso 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 diretório literal '~' em alguns shells)
CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 # Preserva cache do marketplace de plugins quando git pull falha (compatível com offline; v2.1.90+)
CLAUDE_CODE_MCP_SERVER_NAME=server1           # Repassado a scripts headersHelper do MCP para que um helper possa atender múltiplos servidores (v2.1.85+)
CLAUDE_CODE_MCP_SERVER_URL=https://...        # Repassado a scripts headersHelper do MCP junto com o nome (v2.1.85+)

Shell / IDE:¹⁶³

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

Empresarial / autenticação:¹⁶³

CLAUDE_CODE_PROXY_RESOLVES_HOSTS=1            # Adesão à resolução de DNS pelo proxy (v2.0.55 mudou isso de padrão-ativado para opt-in)
CLAUDE_CODE_API_KEY_HELPER_TTL_MS=300000      # TTL para chaves API geradas dinamicamente via apiKeyHelper (refresh de apiKeyHelper adicionado na v0.2.74 com padrão de 5 min; variável de ambiente adicionada na 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 chamador SDK (v2.1.51+):

CLAUDE_CODE_ACCOUNT_UUID=uuid                  # Fornece UUID da conta de forma síncrona para chamadores SDK
CLAUDE_CODE_USER_EMAIL=[email protected]        # Fornece email do usuário para chamadores SDK
CLAUDE_CODE_ORGANIZATION_UUID=uuid             # Fornece UUID da organização para chamadores SDK

Depuração:

ANTHROPIC_LOG=debug                             # Habilita logging de requisições à API

Qual modelo 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 tokens com preço padrão — sem premium de contexto longo. Saída máxima de 128K, apenas thinking adaptativo (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.¹⁵² Knowledge cutoff confiável: janeiro de 2026. Training data cutoff: 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, atinge 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 aproximadamente 1×–1,35× contagens de tokens para o mesmo texto; aumente a margem de max_tokens e os gatilhos de compactação.¹⁵² Vision 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 por 12,7 sobre a baseline amplamente citada do GPT-5-Codex e o SWE-bench Pro por 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 múltiplos 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 pelo 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 thinking adaptativo está desligado por padrão; requisições sem o campo thinking rodam sem thinking.
• Definir temperature, top_p ou top_k para 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 (necessário se seu produto fizer streaming de thinking para usuários).

Task budgets (header beta task-budgets-2026-03-13) permitem que você indique ao modelo um alvo de tokens em todo um 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 originalmente lançado em 5 de fevereiro de 2026.⁸⁶¹⁵¹ A partir da v2.1.117 (22 de abril de 2026), assinantes Pro e Max passam a ter 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 em claude.ai e Claude Cowork.¹⁰⁰ Mesmo preço do Sonnet 4.5 ($3/$15 por MTok). Desempenho aprimorado de busca agêntica enquanto consome menos tokens. Suporta extended thinking, thinking adaptativo e uma janela de contexto de 1M tokens (beta). Saída máxima de 64K (limite superior de 128K na v2.1.77).¹²⁶ Knowledge cutoff: agosto de 2025 (confiável), janeiro de 2026 (training data). Model ID: claude-sonnet-4-6.

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

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

Quando usar cada modelo

Haiku: Use para subagents fazendo exploração, buscas simples em arquivos, perguntas rápidas. É ~5x 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 cavalo de batalha para o 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 ao Sonnet 4.5, com suporte a thinking adaptativo e janela de contexto de 1M com preço padrão.¹⁰⁰ A partir do Opus 4.7 (16 de abril de 2026), Claude Code tem como padrão o Opus 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 Sonnet quando você precisar de tokens mais baratos, latência mais rápida ou economia em subagents.

Opus: O nível carro-chefe 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 compensa: decisões arquiteturais, debugging complicado, entendimento de sistemas complexos, análise de segurança, trabalho agêntico de longo horizonte. Opus 4.7 resolve 3× mais tarefas de produção no SWE-Bench que o Opus 4.6, atinge 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 por padrão esforço xhigh 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 requerer --enable-auto-mode; outros planos/provedores têm disponibilidade específica do plano e controlada pelo administrador.¹⁵³ Contexto de 1M com preço padrão — sem premium de contexto longo. Mudanças de comportamento que vale conhecer: o Opus 4.7 segue instruções mais literalmente, calibra o tamanho da resposta com 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 modelos

Durante a sessão:

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

No início:

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

claude --model sonnet[1m]
claude --model opus[1m]           # Opus 4.7 com contexto de 1M

Ou dentro de uma sessão:

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

Opus 4.7, Opus 4.6 e Sonnet 4.6 incluem a janela completa de contexto de 1M tokens com preço padrão — sem premium de contexto longo.¹⁵⁵ Uma requisição de 900K tokens é cobrada à mesma taxa por token de uma requisição de 9K tokens. Os descontos de prompt caching e batch processing aplicam-se em taxas padrão em toda a janela de contexto.

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

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

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 modelos (v2.1.51+): O seletor /model agora mostra rótulos legíveis por humanos (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 troca para um modelo mais barato. Alterne durante uma sessão com /fast.⁹³

> /fast            # Liga/desliga o fast mode

Preço (Opus 4.6 fast mode):

Fast mode é research preview, apenas Opus 4.6, e entrega saída ~2,5× mais rápida a 6× do preço base.¹⁵⁶ Habilitar /fast automaticamente troca a sessão para Opus 4.6 se você estava em outro modelo; desabilitar /fast deixa você no Opus 4.6 até trocar via /model. Fast mode não está disponível no Opus 4.7, Sonnet, Haiku, ou via Bedrock/Vertex/Foundry. Requer extra usage habilitado e, para Team/Enterprise, habilitação de 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 em uma lista de tarefas similares sequencialmente

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

O fast mode do Opus 4.6 inclui a janela completa de contexto de 1M (v2.1.50+). O preço do fast mode é fixo em todo o contexto de 1M — sem sobretaxa adicional para contexto longo.¹⁰³¹⁵⁶

Dica de especialista: Fast mode não combina com opusplan (opusplan já mistura Opus e Sonnet; fast mode afeta apenas o Opus 4.6). Use fast mode diretamente quando a latência importa mais que o custo, e desabilite-o para trabalho autônomo ou em batch. /fast requer extra usage; admins de Team/Enterprise podem precisar habilitá-lo primeiro (correção da 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 trade-off entre velocidade/inteligência. Use /effort durante uma sessão:

> /effort              # abre um slider interativo (setas + Enter)
> /effort xhigh        # define diretamente

Claude Code agora usa por padrão o esforço xhigh para Opus 4.7. xhigh é exclusivo do Opus 4.7 — outros modelos retornam 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 a correspondência de intenção e a segurança. Nota (v2.1.111+): a flag --enable-auto-mode foi removida; inicie uma sessão em Auto Mode com --permission-mode auto. Auto Mode não está disponível no Pro; 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 personalizadas sem perder os padrões (v2.1.118+). Versões anteriores tornavam autoMode.allow, autoMode.soft_deny e autoMode.environment excludentes: defina sua própria lista e perca as regras de segurança integradas. O sentinela $defaults resolve isso — ele se expande inline para a lista integrada exatamente na posição em que você o coloca, permitindo que você adicione regras personalizadas em torno delas:¹⁵⁹

// .claude/settings.json
{
  "autoMode": {
    "allow": [
      "Bash(npm test:*)",        // suas adições, prefixadas
      "$defaults",                // lista allow integrada inserida aqui
      "Bash(git push:origin/feature/*)"  // anexada após
    ]
  }
}

Opt-in “Não pergunte novamente” (v2.1.118+). O prompt de opt-in do Auto Mode agora oferece uma opção “Não pergunte novamente”, para que usuários frequentes possam suprimir o explicador sem precisar scriptar uma flag.¹⁵⁹

Novos comandos na v2.1.105–v2.1.114¹⁵³¹⁵⁷

Recap de sessão (v2.1.108+)

Um novo recurso em nível de sessão que apresenta o contexto quando você retorna a uma sessão pausada. Habilitado por padrão e com opção de desativação via /config ou CLAUDE_CODE_ENABLE_AWAY_SUMMARY=0. O modelo também pode invocar slash commands integrados (/init, /review, /security-review) via a ferramenta Skill — estende o padrão subagent/skill.¹⁵³

Push notifications (v2.1.110+)

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

Ferramenta Windows PowerShell (v2.1.111+, rollout)

Claude Code está fazendo rollout de uma ferramenta PowerShell nativa do Windows. No Linux/macOS, habilite-a com CLAUDE_CODE_USE_POWERSHELL_TOOL=1 (requer pwsh no PATH). No Windows, a mesma variável controla 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 os 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 para operadores que equipes já recebem em 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 acionam 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 do Claude Code a traces distribuídos. Combine com OTEL_LOG_RAW_API_BODIES=1 (v2.1.111+) para emitir corpos completos de requisição/resposta da API como eventos de log do OpenTelemetry para debugging.¹⁵³

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

A v2.1.113 muda como o CLI é iniciado: claude agora gera um binário nativo do Claude Code via uma dependência opcional por plataforma em vez de rodar JavaScript empacotado. Os comandos de instalação e atualização permanecem os mesmos, e as 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 rolagem de viewport em fullscreen:

Ativados por padrão. Não é necessária configuração de keybinding.

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

Subagents que travam no meio do streaming agora falham com um erro claro após 10 minutos em vez de ficarem pendurados 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 da v2.1.114¹⁵⁷

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

Quanto Custa o Claude Code?

Entender e controlar custos é essencial para o uso sustentável do Claude Code. Veja também Seleção de Modelo para capacidades de modelo 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.²¹

Preço por token da API (abril de 2026)¹¹⁵¹

Para usuários cobrados via API, preço 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 incluem 1M nas 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. Modelos legados Opus 4.5 e anteriores mantêm suas estruturas de preço originais.

Preço de residência de dados: Especificar inferência somente nos EUA via inference_geo adiciona um multiplicador de 1,1× sobre todo o preço de tokens, incluindo leituras e gravações de cache (modelos Opus 4.6+).¹⁵⁵

Prompt caching reduz significativamente os custos repetidos de entrada: gravações em 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 descontos de 50% com prazo de 24 horas para tarefas não urgentes, como conjuntos de testes noturnos.

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 servem 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 a partir do mesmo IP/rede são explicitamente suportadas - As contas são completamente separadas; não há 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 tier gratuito

Nota do mundo real: Em janeiro de 2026, o power user Jeffrey Emanuel (@doodlestein) teve 22 contas Max sinalizadas automaticamente e temporariamente banidas. O funcionário da Anthropic Thariq (@trq212) resolveu isso 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: Entre em contato com 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 de custo: Usar Haiku para subagents de exploração e Sonnet para implementação normalmente reduz custos em 40-50% comparado a usar Sonnet para tudo.

Gerenciamento de custos da equipe

TPM/RPM recomendado por tamanho da equipe:

Taxas ocultas de ferramentas

Além do preço por token, algumas ferramentas incorrem em cobranças separadas:¹⁶

Esses valores se acumulam em loops de agente. Um ciclo de debug de 100 iterações com Bash custa ~24.500 tokens de entrada extras só em overhead.

Estratégias de economia de custo

1. Use Haiku para subagents: A maior parte da exploração não precisa de Sonnet
2. Ative prompt caching: Padrão, mas verifique se não está desativado
3. Defina turnos máximos: claude --max-turns 5 previne conversas descontroladas
4. Use o modo plan 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 uso

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

Uso de tokens em segundo plano

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

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 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 do desenvolvedor (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 dentro de 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. Compreendê-lo é essencial tanto para a segurança quanto para a eficiência do fluxo de trabalho. Veja também Implantação Empresarial para configurações gerenciadas que aplicam permissões em toda a organização.

Camadas de permissões

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

Recursos da ferramenta LSP (v2.0.74+): A ferramenta LSP fornece inteligência de código semelhante à de uma IDE: - Ir para definição: Pular para onde um símbolo é definido - Encontrar referências: Listar todos os usos de um símbolo em toda a base de 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 (geralmente instalado com seu toolchain)

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

Na primeira vez que uma ferramenta de modificação é executada, o Claude Code solicita aprovação. As aprovações persistem durante a sessão, a menos que configuradas explicitamente de outra forma.

Modos de permissão

Modo Auto (v2.1.85+): Uma substituição mais segura para --dangerously-skip-permissions. Um modelo classificador separado (Sonnet 4.6) revisa cada ação antes da execução, verificando se ela corresponde à intenção do usuário e é 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

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

Disjuntor (circuit breaker): 3 bloqueios consecutivos ou 20 no total em uma sessão pausa e retorna ao prompt 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 a seguir. 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 “perigoso” é 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 das regras de permissão

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

Padrões de comandos Bash:

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

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

Limitação importante: padrões Bash correspondem apenas a prefixos, não a regex. Um padrão como Bash(curl http:*) não 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ções em arquivos:

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

Sintaxe de caminhos: - Caminhos relativos: Edit(src/**) - relativo ao diretório de trabalho - Absoluto a partir do arquivo de configurações: Edit(/build/**) - relativo à 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

Habilita isolamento de filesystem e 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 filesystem restrito ao diretório do projeto - Acesso à rede controlado - Certos comandos excluídos das restrições do sandbox - Comandos Bash aprovados automaticamente se autoAllowBashIfSandboxed for true

Dica de especialista: o modo sandbox é excelente para executar o Claude em bases de código não confiáveis. Habilite-o ao explorar projetos desconhecidos ou quando quiser uma camada extra de proteção. Testes internos da Anthropic descobriram que o sandboxing reduz os prompts de permissão em 84%.⁴⁵ O sandbox usa primitivas de nível de SO (macOS seatbelt, Linux bubblewrap) para isolamento de filesystem e rede, então mesmo uma injeção de prompt bem-sucedida fica totalmente contida. A Anthropic disponibilizou como open source o runtime do sandbox para equipes que estão construindo 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 “ask” do Bash quando autoAllowBashIfSandboxed estava habilitado; isso foi corrigido na v2.1.34.⁹⁴ A partir da v2.1.38, escritas em .claude/skills são bloqueadas no modo sandbox, impedindo que injeções de prompt modifiquem definições de skills.⁹⁵ v2.1.77 adiciona uma configuração allowRead no filesystem do sandbox para reabilitar 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 agentes em .claude/ (v2.1.121+): --dangerously-skip-permissions não solicita mais para escritas em .claude/skills/, .claude/agents/ e .claude/commands/.¹⁶¹

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

• sandbox.network.deniedDomains bloqueia hosts específicos mesmo quando um curinga mais amplo allowedDomains permitiria. Use a lista de bloqueio para cortar pastebins, drops de arquivos ou hosts conhecidos como ruins sem reescrever toda a sua política de allow.
• Regras de deny para comandos wrapper. Regras de deny do 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 de 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 roteia pelo caminho normal de permissão.
• Proteção de remoção no macOS. Regras de allow Bash(rm:*) agora tratam /private/etc, /private/var, /private/tmp e /private/home como alvos perigosos de remoção. /var, /etc e /tmp são symlinks para /private/, então o formato anterior da regra deixava passar 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?

Configuração MCP enterprise

Administradores de sistema podem aplicar políticas MCP via managed-mcp.json:

{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverName": "sentry" },
    { "serverCommand": ["npx", "-y", "@approved/server"] }
  ],
  "deniedMcpServers": [
    { "serverName": "dangerous-server" }
  ]
}

Localização: - macOS: /Library/Application Support/ClaudeCode/managed-mcp.json - Linux: /etc/claude-code/managed-mcp.json - Windows: C:\ProgramData\ClaudeCode\managed-mcp.json

A denylist tem precedência absoluta. Comandos devem corresponder exatamente, incluindo a ordem dos argumentos.

MCP Apps (janeiro de 2026)

A Anthropic lançou os MCP Apps, uma extensão do Model Context Protocol que habilita UIs interativas de ferramentas diretamente dentro da interface do Claude.⁷⁸ MCP Apps permitem que usuários visualizem, editem e interajam com conteúdo de serviços externos sem sair do Claude, incluindo Asana, Box, Canva, Figma, Hex, monday.com e Slack. Qualquer servidor MCP pode fornecer uma UI interativa que renderiza dentro do Claude. Embora os MCP Apps atualmente apareçam na interface web do claude.ai, as extensões subjacentes do protocolo MCP são relevantes para o ecossistema MCP do Claude Code à medida que servidores adotam as novas capacidades interativas.