Claude Code CLI: O Guia Completo

TL;DR: 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 centrais (configuração, permissões, hooks, MCP e subagents) e você desbloqueia uma produtividade multiplicadora. Escolha o tier 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 sempre ser executado.

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 criados pelo 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 centrais. 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 as operações
3. Sistema de hooks: habilita automação determinística
4. Protocolo MCP: estende as 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.
• Transfira o trabalho para a Camada de Delegação: subagents evitam o 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 ser executadas toda vez, 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 toolchain: 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 empresariais. Este guia destila essa experiência na referência completa que eu gostaria que existisse quando comecei. Cada recurso inclui a sintaxe real, exemplos de configuração reais e os casos extremos que pegam até usuários experientes de surpresa.

Como usar este guia

Esta é uma referência de mais de 5.000 linhas — você não precisa ler tudo de uma vez. 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 fornece um resumo escaneável de todos os principais comandos.

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 central (Core Layer): 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 rastreamento de decisões anteriores e a qualidade degrada. Esta camada custa dinheiro por token.

Camada de delegação (Delegation Layer): Subagents são gerados com contextos limpos, realizam trabalho focado e retornam resumos. Os resultados da exploração não inflam sua conversa principal; apenas as conclusões retornam. Direcione subagents para modelos mais baratos para exploração, ou use seu modelo principal em tudo se a qualidade importar mais que o custo.

Camada de extensão (Extension Layer): 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 tudo isso para distribuição.

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

Sumário

1. Como instalo o Claude Code?
2. Início rápido: sua primeira sessão
3. 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 os Hooks funcionam?
10. O que é MCP (Model Context Protocol)?
11. O que são Subagents?
12. O que é o modo de pensamento estendido?
13. Estilos de saída
14. Comandos slash
15. Como as Skills funcionam?
16. Sistema de Plugins
17. Como a memória funciona?
18. Imagens e entrada 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çado
23. Agentes remotos e em segundo plano [PREVIEW DE PESQUISA]
24. Claude no Chrome
25. Claude Code no Slack [PREVIEW DE PESQUISA]
26. Claude Code na Web [PREVIEW DE PESQUISA]
27. Otimização de desempenho
28. Como depuro problemas?
29. Implantação empresarial
30. Referência de atalhos de teclado
31. Boas práticas
32. Receitas de fluxo de trabalho
33. Guia de migração
34. Orientação por público-alvo
35. Cartão de referência rápida
36. Changelog
37. Referências

Como instalar o Claude Code?

Requisitos do sistema

O Claude Code funciona no macOS 10.15+, Ubuntu 20.04+/Debian 10+ e Windows 10+ através do WSL ou Git Bash. O sistema requer no mínimo 4 GB de RAM e uma conexão ativa com a internet.⁹⁹ A compatibilidade com 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 o Windows nativo. Alpine Linux e outros sistemas baseados em musl requerem pacotes adicionais:

apk add libgcc libstdc++ ripgrep
export USE_BUILTIN_RIPGREP=0

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 (descontinuada)

Nota: A partir da v2.1.15, instalações via npm exibem um aviso de descontinuaçã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 posteriormente.

Migração de uma instalação existente

Se você tem uma instalação mais 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 compensações:

Claude Console (cobrança via API)

Conecte-se à API da Anthropic diretamente pelo platform.claude.com (anteriormente console.anthropic.com). Crie uma conta, configure a cobrança e autentique-se pelo CLI. O Console oferece cobrança baseada em 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 desejam custos previsíveis.

Plataformas empresariais

AWS Bedrock, Google Vertex AI e Microsoft Foundry oferecem acesso de nível empresarial com relacionamentos de cobrança em nuvem existentes:

# 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

Para implantações empresariais atrás de proxies ou através 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, versão, 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 de trabalho comum para alternar entre contas ou organizações:

claude auth logout && claude auth login

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

Atualizações

O Claude Code atualiza automaticamente por padrão, verificando na inicialização e periodicamente durante as sessões. As atualizações são baixadas em segundo plano e aplicadas na próxima execução.

Desativar atualizações automáticas:

export DISABLE_AUTOUPDATER=1

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

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

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

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

1. Instale e inicie:

claude                           # Launch in current directory

2. Navegue até um projeto:

cd ~/my-project && claude        # Or launch from any git repo

3. Peça ao Claude para fazer algo:

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

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

/cost                            # Check token usage and cost
/compact                         # Free up context when it gets large
Alt+T                            # Toggle extended thinking for hard problems
Ctrl+C                           # Cancel current response

5. Continue depois:

claude -c                        # Resume your most recent session
claude --resume                  # Pick from session list

Dica avançada: 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 ação de maior impacto que você pode fazer para melhorar a qualidade.

Modos de interação principais

REPL interativo

Inicie o Claude Code sem argumentos para entrar no loop interativo de leitura-avaliação-impressão:

cd your-project
claude

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

Comece com um prompt inicial para direcionar a sessão:

claude "explain the authentication flow in this project"

Dica avançada: O REPL preserva o estado entre eventos de compactação. Quando o contexto fica muito grande, o Claude resume automaticamente a conversa mais antiga, 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 de impressão (-p) executa uma única consulta e encerra:

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

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

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

Para saída estruturada adequada para análise em scripts:

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

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

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

Para 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

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

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

Gerenciamento de sessões

As sessões persistem o histórico de conversas para continuação. A persistência de sessões é 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 PRs (v2.1.27+): Inicie uma sessão vinculada a um pull request específico:⁸¹

claude --from-pr 123                                    # By PR number
claude --from-pr https://github.com/org/repo/pull/123   # By URL

As sessões também se vinculam automaticamente a PRs quando você os cria via gh pr create durante uma sessão. Isso facilita retomar o trabalho em um PR específico posteriormente.

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 (ex.: 550e8400-e29b-41d4-a716-446655440000). Para nomeação de sessões legível por humanos, 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 de planejamento

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

Entrando no modo de planejamento:

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

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

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

Como funciona:

1. O Claude entra no modo de planejamento (automaticamente para tarefas complexas, ou via Shift+Tab)
2. Explora a base de 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 de planejamento com ExitPlanMode, apresentando o plano para sua revisão
5. Você aprova, solicita alterações ou rejeita

Ferramentas disponíveis no modo de planejamento: 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 aceitar edições automaticamente” (Shift+Tab) — começa do zero com contexto completo para o plano - “Sim, e aprovar edições manualmente” — preserva o contexto, você aprova cada alteração - “Sim, aceitar edições automaticamente” — preserva o contexto, o Claude executa sem aprovação por edição

Limpar o contexto automaticamente na aprovação é o fluxo de trabalho recomendado. Isso dá ao plano uma janela de contexto limpa, o que melhora significativamente a aderência ao plano — o Claude permanece no caminho certo por mais tempo sem a conversa antiga interferindo.

Quando usar o modo de planejamento: - Implementações de novos recursos com decisões arquiteturais - Refatorações em múltiplos arquivos onde você quer revisar a abordagem primeiro - Bases de código desconhecidas onde a exploração deve preceder a modificação - Qualquer tarefa onde múltiplas abordagens válidas existem e você quer contribuição

Dica avançada: Quanto mais tempo você passar no modo de planejamento, maior a probabilidade do Claude ter sucesso na implementação. O modo de planejamento é essencialmente exploração gratuita — sem chamadas de ferramentas arriscadas, sem edições desperdiçadas. Use-o generosamente.

Aprofundamento no sistema de configuração

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

Hierarquia de configuração

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

Referência completa do settings.json

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

{
  "$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-...                    # Direct API authentication
ANTHROPIC_AUTH_TOKEN=token                      # Custom authorization header
ANTHROPIC_CUSTOM_HEADERS="X-Key: val"           # Additional request headers

Configuração de modelo:

ANTHROPIC_MODEL=claude-opus-4-6                 # Override default model
ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-6    # Opus 4.6 (Feb 2026)
ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-5-20250929
ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5-20251001
CLAUDE_CODE_SUBAGENT_MODEL=sonnet               # Model for subagents
MAX_THINKING_TOKENS=10000                       # Enable extended thinking
CLAUDE_CODE_MAX_OUTPUT_TOKENS=4000              # Limit output length
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1          # Enable agent teams (v2.1.32+)

Configuração de provedores de nuvem:

CLAUDE_CODE_USE_BEDROCK=1                       # Use AWS Bedrock
CLAUDE_CODE_USE_VERTEX=1                        # Use Google Vertex AI
CLAUDE_CODE_USE_FOUNDRY=1                       # Use Microsoft Foundry
ANTHROPIC_BEDROCK_BASE_URL=https://...          # Custom Bedrock endpoint
CLAUDE_CODE_SKIP_BEDROCK_AUTH=1                 # Skip Bedrock auth (for gateways)
CLAUDE_CODE_SKIP_VERTEX_AUTH=1                  # Skip Vertex auth
AWS_BEARER_TOKEN_BEDROCK=token                  # Bedrock bearer token
VERTEX_REGION_CLAUDE_3_7_SONNET=us-west1        # Override Vertex region

Controle de comportamento:

DISABLE_AUTOUPDATER=1                           # Prevent automatic updates
DISABLE_TELEMETRY=1                             # Opt out of usage telemetry
DISABLE_ERROR_REPORTING=1                       # Disable Sentry
DISABLE_BUG_COMMAND=1                           # Disable /bug command
DISABLE_COST_WARNINGS=1                         # Hide cost warnings
DISABLE_PROMPT_CACHING=1                        # Disable prompt caching globally
DISABLE_PROMPT_CACHING_SONNET=1                 # Disable for Sonnet only
DISABLE_PROMPT_CACHING_OPUS=1                   # Disable for Opus only
DISABLE_NON_ESSENTIAL_MODEL_CALLS=1             # Skip non-critical API calls

Configuração de ferramentas:

BASH_DEFAULT_TIMEOUT_MS=30000                   # Bash command timeout (30s)
BASH_MAX_TIMEOUT_MS=600000                      # Maximum bash timeout (10min)
BASH_MAX_OUTPUT_LENGTH=50000                    # Bash output limit
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1     # Reset CWD after each bash
MCP_TIMEOUT=5000                                # MCP server startup timeout
MCP_TOOL_TIMEOUT=30000                          # MCP tool execution timeout
MAX_MCP_OUTPUT_TOKENS=25000                     # MCP output limit
SLASH_COMMAND_TOOL_CHAR_BUDGET=15000            # Slash command context limit

Rede e proxy:

HTTP_PROXY=http://proxy:8080                    # HTTP proxy
HTTPS_PROXY=https://proxy:8080                  # HTTPS proxy
NO_PROXY=localhost,example.com                  # Bypass proxy for domains
CLAUDE_CODE_CLIENT_CERT=/path/to/cert           # mTLS certificate
CLAUDE_CODE_CLIENT_KEY=/path/to/key             # mTLS private key
CLAUDE_CODE_CLIENT_KEY_PASSPHRASE=pass          # mTLS passphrase

Interface e terminal:

CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1            # Don't update terminal title
CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL=1             # Skip IDE extension install
CLAUDE_CODE_SHELL=/bin/zsh                      # Override shell detection
USE_BUILTIN_RIPGREP=1                           # Use included ripgrep (default)
CLAUDE_CONFIG_DIR=~/.myconfig                   # Custom config directory
IS_DEMO=1                                       # Hide sensitive UI elements[^37]
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1          # Disable background tasks and Ctrl+B[^46]
CLAUDE_CODE_TMPDIR=/path/to/tmp                 # Override temp directory[^50]
CLAUDE_CODE_DISABLE_1M_CONTEXT=1               # Disable 1M context window (use standard 200K)[^103]
CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=120000       # Plugin marketplace git timeout (default 120s, was 30s)[^105]
CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=1        # Remove built-in commit/PR instructions[^117]
CLAUDE_CODE_DISABLE_CRON=1                    # Stop scheduled cron jobs mid-session[^121]
CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=30000 # SessionEnd hooks timeout (default varies)[^123]

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

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

Identidade do chamador SDK (v2.1.51+):

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

Depuração:

ANTHROPIC_LOG=debug                             # Enable API request logging

Qual modelo devo escolher?

Escolher o modelo certo para cada tarefa impacta significativamente tanto o custo quanto a qualidade. O Claude Code oferece troca flexível de modelo em múltiplos níveis.

Modelos disponíveis

Opus 4.6 (5 de fevereiro de 2026): O modelo flagship mais recente com janela de contexto de 1M tokens, output máximo de 128K, pensamento adaptativo e agent teams.⁸⁶ Mesmo preço do Opus 4.5 ($5/$25 por MTok). A partir da v2.1.75 (13 de março de 2026), a janela de contexto de 1M está habilitada por padrão para planos Max, Team e Enterprise — o sufixo [1m] não é mais necessário para esses planos.¹²⁴ A partir da v2.1.77 (17 de março de 2026), o limite padrão de tokens de output do Opus 4.6 foi aumentado para 64K tokens, com um limite máximo de 128K tokens.¹²⁶ Contexto longo (>200K de input) em uso exclusivo via API ainda custa $10/$37.50 por MTok. Model ID: claude-opus-4-6.¹

Sonnet 4.6 (17 de fevereiro de 2026): O novo modelo equilibrado que substitui o Sonnet 4.5 como padrão no claude.ai e no Claude Cowork.¹⁰⁰ Mesmo preço do Sonnet 4.5 ($3/$15 por MTok). Desempenho aprimorado em busca agêntica consumindo menos tokens. Suporta pensamento estendido, pensamento adaptativo e janela de contexto de 1M tokens (beta). Output máximo de 64K (limite superior aumentado para 128K na v2.1.77).¹²⁶ Data de corte do conhecimento: agosto de 2025 (confiável), janeiro de 2026 (dados de treinamento). Model ID: claude-sonnet-4-6. O Sonnet 4.5 agora é um modelo legado.¹⁰⁰

Por que essas diferenças de preço importam: Uma sessão típica de codificação consome 50K-200K tokens de input e 10K-50K tokens de output. Com o Haiku, isso custa $0,10-$0,45 por sessão. Com o 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. Lida bem com a maioria das tarefas de codificação: implementar funcionalidades, corrigir bugs, escrever testes, revisão de código. Use como seu padrão. O Sonnet 4.6 (fevereiro de 2026) oferece busca agêntica aprimorada e melhor eficiência de tokens em comparação ao Sonnet 4.5, com suporte a pensamento adaptativo e a janela de contexto de 1M em beta.¹⁰⁰

Opus: Reserve para raciocínio genuinamente complexo: decisões arquiteturais, debugging difícil, compreensão de sistemas complexos, análise de segurança. O Opus 4.6 (fevereiro de 2026) é um avanço significativo: ele planeja com mais cuidado, sustenta tarefas agênticas por mais tempo, opera de forma mais confiável em codebases grandes e identifica melhor seus próprios erros durante a revisão de código.⁸⁶ Possui uma janela de contexto de 1M tokens em beta e introduz pensamento adaptativo que determina automaticamente a profundidade do raciocínio. Segundo a Anthropic, no Terminal-Bench 2.0, o Opus 4.6 alcança a maior pontuação de codificação agêntica da indústria. No GDPval-AA (trabalho de conhecimento economicamente valioso), a Anthropic relata que ele supera o GPT-5.2 por ~144 pontos Elo.⁸⁶ Nota: Usuários com assinatura Pro têm acesso ao Opus como parte de sua assinatura.²⁰

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

Trocando de modelo

Durante a sessão:

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

Na inicialização:

claude --model opus

Via variável de ambiente:

export ANTHROPIC_MODEL=opus

No settings.json:

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

Para subagents especificamente:

export CLAUDE_CODE_SUBAGENT_MODEL=haiku

Contexto estendido

Para codebases grandes ou sessões longas, habilite o contexto de 1M tokens:

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

Ou durante uma sessão:

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

A partir da v2.1.75 (13 de março de 2026), o Opus 4.6 usa contexto de 1M por padrão para planos Max, Team e Enterprise — sem necessidade do sufixo [1m].¹²⁴ O sufixo [1m] ainda é necessário para o Sonnet e para usuários exclusivos de API.

O Opus 4.6 é o primeiro modelo da classe Opus com suporte nativo a contexto de 1M. Ele alcança 76% de precisão na variante de 8 agulhas do MRCR v2 com 1M (concorrentes pontuam ~18,5%), tornando-o o modelo mais forte para recuperação em contexto longo.⁸⁶

O contexto estendido custa mais por token (2x no input, 1,5x no output quando >200K tokens de input). Para o Sonnet com [1m], use quando você realmente precisar, não como padrão.

Verificando o modelo atual

> /status

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

Rótulos do seletor de modelo (v2.1.51+): O seletor /model agora exibe rótulos legíveis (por exemplo, “Sonnet 4.6”) em vez de IDs brutos de modelo para versões fixadas, com dicas de atualização quando versões mais recentes estão disponíveis.¹⁰⁵

Modo rápido (v2.1.36+)

O modo rápido fornece output significativamente mais rápido do mesmo modelo; ele não troca para um modelo mais barato. Alterne durante uma sessão com /fast.⁹³

> /fast            # Toggle fast mode on/off

Preços (modo rápido do Opus 4.6):

O preço do modo rápido se aplica a toda a janela de contexto, incluindo requisições acima de 200K tokens de input — não há sobretaxa adicional de contexto longo no modo rápido.¹ O preço do modo rápido é cumulativo com prompt caching e multiplicadores de residência de dados, mas NÃO com preços de contexto longo. O modo rápido não está disponível com a API Batch.

Quando usar o modo rápido: - 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 o modo rápido: - Tarefas agênticas de longa duração (o custo acumula rápido com taxas 6x) - Trabalho de subagents em segundo plano (ninguém está esperando pelo output) - Sessões com orçamento limitado

O modo rápido do Opus 4.6 agora inclui a janela completa de contexto de 1M (v2.1.50+). Anteriormente, o modo rápido era limitado ao contexto padrão; agora você tem a mesma capacidade de 1M tokens na velocidade do modo rápido.¹⁰³

Dica avançada: O modo rápido combina bem com o híbrido opusplan: use o modo rápido durante a fase de execução do Sonnet para iteração rápida, mantendo as taxas padrão para o planejamento com Opus. Note que /fast requer que /extra-usage esteja habilitado primeiro (correção da v2.1.37).⁹³

Quanto custa o Claude Code?

Entender e controlar custos é essencial para um uso sustentável do Claude Code. Veja também Seleção de modelo para capacidades dos modelos e Frameworks de decisão para escolher o modelo certo para cada 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

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 nas taxas padrão da API.²¹

Preços de tokens da API (fevereiro de 2026)¹⁸⁶

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

Preços para contexto longo (>200K tokens de entrada):

O limite de 200K é baseado no total de tokens de entrada (incluindo leituras/escritas de cache). Quando excedido, a Anthropic cobra todos os tokens na taxa de contexto longo.¹

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

Prompt caching reduz significativamente os custos de entrada repetida: escritas no cache custam 1,25× do preço base (cache de 5 min) ou 2× (cache de 1 hora), mas leituras do 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%.

API em lote oferece descontos de 50% com retorno em 24 horas para tarefas não urgentes, como suítes de testes durante a noite.

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 do mesmo IP/rede são explicitamente suportadas - As contas são completamente separadas; não há transferência de chats ou projetos entre elas

O que é proibido (conforme a Política de Uso): - Criar contas para evitar banimentos após ser banido - Coordenar atividades maliciosas entre contas para evitar detecção - Usar múltiplas contas para contornar limites de taxa ou créditos do plano gratuito

Nota do mundo real: Em janeiro de 2026, o usuário avançado Jeffrey Emanuel (@doodlestein) teve 22 contas Max sinalizadas automaticamente e banidas temporariamente. O funcionário da Anthropic, Thariq (@trq212), resolveu a situação em 4 horas após confirmar o uso legítimo. Se você está usando o Claude Code extensivamente para projetos de trabalho e pessoais em múltiplas contas, isso é exatamente para o 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

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

Gestão de custos para equipes

TPM/RPM recomendados por tamanho de equipe:

Taxas ocultas de ferramentas

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

Esses custos se acumulam em loops de agentes. Um ciclo de depuração de 100 iterações com Bash custa aproximadamente 24.500 tokens de entrada extras apenas em overhead.

Estratégias para economizar

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

Monitorando o uso

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

Uso de tokens em segundo plano

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

Normalmente menos de $0,04 por sessão.

API de Analytics do Claude Code (Team/Enterprise)⁵³

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

Endpoint: GET /v1/organizations/usage_report/claude_code

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

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

Frameworks de decisão

Saber que os recursos existem não é suficiente. Você precisa saber quando usar cada um. Estas árvores de decisão transformam conhecimento em ação.

Qual modelo devo usar?

START → Is the task simple? (file search, quick question, formatting)
         │
         ├── YES → Use Haiku
         │         Cost: ~$0.03/task
         │         Speed: Fastest
         │
         └── NO → Does it require deep reasoning?
                  (architecture, complex debugging, security analysis)
                  │
                  ├── YES → Use Opus 4.6
                  │         Cost: ~$2.00/task
                  │         Quality: Highest (1M context, adaptive thinking)
                  │
                  └── NO → Use Sonnet (default)
                           Cost: ~$0.75/task
                           Balance: Best overall

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

Command vs Skill vs Subagent vs Agent Team?

Do you want explicit control over when it runs?
│
├── YES → Use Slash Command
│         Example: /deploy, /test, /security-review
│         You invoke it. You control timing.
│
└── NO → Should the expertise apply automatically based on context?
         │
         ├── YES → Use Skill
         │         Example: Security patterns, domain rules, code standards
         │         Claude recognizes context and applies expertise.
         │
         └── NO → Does the work need isolated context?
                  │
                  ├── YES → Is there one subtask or many parallel subtasks?
                  │         │
                  │         ├── ONE → Use Subagent (Task tool)
                  │         │         Example: Deep exploration, parallel analysis
                  │         │         Prevents context bloat in main conversation.
                  │         │
                  │         └── MANY → Use Agent Team (v2.1.32+)
                  │                   Example: 5 agents reviewing different modules simultaneously
                  │                   Opus coordinates; each agent works independently.
                  │
                  └── NO → Just prompt directly
                           Not everything needs abstraction.

Hook vs Prompt?

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

Quando usar Extended Thinking?

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

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

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

Qual superfície de execução?

Where should this work happen?
│
├── Requires YOUR local files and tools
│   │
│   ├── Interactive, iterative work → Main REPL session
│   ├── One-shot scripted task → claude -p "prompt" (print mode)
│   ├── CI/CD automation → claude -p --json (non-interactive + structured output)
│   └── Parallel isolated tasks → Subagents via Task tool
│
├── Requires SOMEONE ELSE'S environment
│   │
│   └── Remote codebase or server → Background agent (cloud)
│
└── Doesn't require any environment
    │
    ├── Research or analysis → Subagent with Explore type
    └── Web content extraction → WebFetch / WebSearch tools

Agent Teams vs Subagents vs Sessões Paralelas

Do you need multiple agents working on related subtasks?
│
├── YES → Are the subtasks independent (no shared state)?
│         │
│         ├── YES → Can they share the same codebase?
│         │         │
│         │         ├── YES → Use Agent Team (v2.1.32+)
│         │         │         Opus coordinates. Agents share repo access.
│         │         │         Example: "Review auth, API, and DB modules in parallel"
│         │         │
│         │         └── NO → Use Parallel Sessions (separate terminals)
│         │                  Each has its own working directory.
│         │                  Example: "Fix repo-A and repo-B simultaneously"
│         │
│         └── NO → Use Sequential Subagents
│                  Results from one feed into the next.
│                  Example: "Explore → Plan → Implement"
│
└── NO → Use Single Subagent or Main REPL

Qual tipo de Hook?

What kind of automation do you need?
│
├── Run a shell command at a specific event?
│   │
│   └── Use Command Hook
│       Trigger: PreToolUse, PostToolUse, Notification, Stop, SubagentStop
│       Example: "Run prettier after every file edit"
│       Config: hooks.PostToolUse[].command = "prettier --write $FILE"
│
├── Modify Claude's system prompt based on context?
│   │
│   └── Use Prompt Hook (v2.1.35+)
│       Trigger: Same events
│       Example: "Inject project rules when working in /src/auth/"
│       Config: hooks.PreToolUse[].prompt = "When editing auth files..."
│
└── Have Claude make a judgment call before proceeding?
    │
    └── Use Agent Hook (v2.1.35+)
        Trigger: Same events
        Example: "Evaluate if this bash command is safe before running"
        Config: hooks.PreToolUse[].agent = { prompt: "Is this safe?" }

Quando usar /fast?

Is response speed more important than depth right now?
│
├── YES → Use /fast
│         Same Opus 4.6 model, faster output
│         Good for: quick questions, simple edits, code explanations,
│                   file searches, formatting tasks
│
└── NO → Stay in normal mode
         Good for: architecture decisions, complex debugging,
                   security reviews, multi-file refactors,
                   anything requiring deep reasoning

/fast alterna o modo rápido para a sessão atual. Ele usa o mesmo modelo (Opus 4.6) com velocidade de saída otimizada — NÃO muda para um modelo mais barato.

Como funciona o sistema de permissões?

O sistema de permissões do Claude Code oferece controle granular sobre quais operações podem ser executadas. Entendê-lo é essencial tanto para segurança quanto para eficiência no fluxo de trabalho. Veja também Implantação corporativa para configurações gerenciadas que aplicam permissões em toda a organização.

Níveis de permissão

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

Capacidades da ferramenta LSP (v2.0.74+): A ferramenta LSP fornece inteligência de código similar a uma IDE: - Ir para definição: Navegar até onde um símbolo é definido - Encontrar referências: Listar todos os usos de um símbolo no codebase - 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 servidor de linguagem esteja disponível (normalmente instalado com seu toolchain)

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

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

Modos de permissão

Modo YOLO (v2.0.68+): Para operação totalmente autônoma, use a flag --dangerously-skip-permissions. A flag aprova tudo automaticamente: edições de arquivo, comandos bash, todas as chamadas de ferramentas. A palavra “dangerous” é intencional. Use em ambientes isolados ou quando você confia totalmente no codebase.⁶¹

claude --dangerously-skip-permissions

Defina o modo via CLI:

claude --permission-mode acceptEdits

Alterne durante a sessão:

Shift+Tab  # Alterna entre os modos

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: Os padrões Bash correspondem apenas por prefixo, não por 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 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 com curinga mcp__server__* para permitir ou negar todas as ferramentas de um servidor MCP específico.³⁹ A sintaxe com 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 adjacentes.

Modo sandbox

Habilite isolamento de sistema de arquivos e rede:

> /sandbox

Ou configure nas configurações:

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"],
    "network": {
      "allowUnixSockets": ["~/.ssh/agent-socket"],
      "allowLocalBinding": true
    }
  }
}

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

Dica avançada: O modo sandbox é excelente para executar o Claude em codebases não confiáveis. Habilite-o ao explorar projetos desconhecidos ou quando quiser uma camada extra de proteção. Testes internos da Anthropic mostraram que o sandbox reduz as solicitações de permissão em 84%.⁴⁵ O sandbox usa primitivas do sistema operacional (seatbelt do macOS, bubblewrap do Linux) para isolamento de sistema de arquivos e rede, então mesmo uma injeção de prompt bem-sucedida fica totalmente contida. A Anthropic disponibilizou o runtime do sandbox como código aberto para equipes que constroem seus próprios agentes.⁸⁹

Notas de segurança (v2.1.34+): Comandos excluídos do sandbox via sandbox.excludedCommands ou dangerouslyDisableSandbox podiam anteriormente contornar a regra de permissão de Bash quando autoAllowBashIfSandboxed estava habilitado; isso foi corrigido na v2.1.34.⁹⁴ A partir da v2.1.38, gravações em .claude/skills são bloqueadas no modo sandbox, impedindo que injeção de prompt modifique definições de skills.⁹⁵ A v2.1.77 adiciona uma configuração allowRead no sistema de arquivos do sandbox para reabilitar 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.¹²⁶

Como os Hooks Funcionam?

Hooks executam comandos shell determinísticos em pontos específicos do fluxo de trabalho do Claude Code. Diferente de pedir ao Claude para realizar ações, hooks garantem a execução independentemente do comportamento do modelo. São essenciais para aplicar 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 rode o Prettier após editar arquivos” funciona às vezes. Porém, o Claude pode esquecer, priorizar velocidade ou decidir que a mudança é “pequena demais.” Hooks garantem a execução: cada Edit ou Write aciona seu formatador, toda vez, sem exceções. Para conformidade, segurança e padrões de equipe, determinístico supera probabilístico.⁷

Eventos Disponíveis

Configuração de Hooks

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

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

Matchers

O campo matcher determina quais ferramentas acionam um hook:

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

Protocolo de Entrada/Saída de Hooks

Hooks recebem JSON 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 os 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 precisar 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 verbose (Ctrl+O). Para UserPromptSubmit e SessionStart, stdout é adicionado ao contexto. - 2: Erro bloqueante: a operação para. Stderr se torna a mensagem de erro enviada ao Claude. - 1, 3, etc.: Erro não bloqueante: a operação continua. Stderr exibido como aviso no modo verbose.

Para controle avançado, hooks podem gerar JSON como saída:

{
  "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 depreciados para PreToolUse. Use hookSpecificOutput.permissionDecision e hookSpecificOutput.permissionDecisionReason no lugar. Outros eventos (PostToolUse, Stop, etc.) ainda usam decision de nível superior.⁹⁶

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, email, Pushover) que não devem desacelerar a sessão - Registro e telemetria que podem rodar em segundo plano - Pós-processamento não crítico (analytics, backups)

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

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

Além dos hooks de comando shell (type: "command"), o Claude Code suporta dois tipos de hook com 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 que hooks de comando (retornam JSON com decision e reason). 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") criam um subagent com acesso a ferramentas (Read, Grep, Glob) para verificação em múltiplos turnos. Use-os quando a verificação requer inspecionar arquivos reais ou saída de testes:

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

Use $ARGUMENTS como placeholder para a entrada JSON do hook. Ambos os tipos 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.

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 evita a 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 lista de domínios permitidos. 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 em hooks (v2.1.51+): Comandos de hook statusLine e fileSuggestion agora exigem aceitação de confiança do workspace antes de serem executados no 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 nos 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

Ative o modo de depuração para solucionar problemas em hooks:

claude --debug

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

Exibição da origem do hook (v2.1.75+): Quando um hook requer 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 com Escopo de Componente (v2.1.0+)

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

Skill com hooks incorporados:

---
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 para skills e slash commands) garante que o hook execute 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 autônomas do Claude Code, configure hooks para manter o Claude no caminho certo sem intervenção manual. O ponto-chave: use hooks de linting e testes como barreiras 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é-voo: Use um hook Setup para verificar se o ambiente está pronto
2. Validação contínua: Hooks PostToolUse executam testes após cada mudança
3. Portão de conclusão: Hooks Stop verificam todos os critérios de aceitação antes que o Claude declare “pronto”
4. Notificação: Hooks Stop podem notificar você via Slack/Pushover quando o Claude finalizar ou ficar travado

Combine com --dangerously-skip-permissions em um contêiner isolado 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 estende 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 no 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 ao seu conjunto de ferramentas existente.

Por que MCP importa 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 no GitHub, verificar erros no Sentry e interagir com qualquer API que sua equipe usa, tudo a partir de solicitações em linguagem natural. O protocolo padroniza como ferramentas de IA se conectam a serviços externos, prevenindo dependência de fornecedor. Veja Frameworks de Decisão para orientação sobre quando usar MCP vs 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 gerencia a renovação 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

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

O Claude Code agora pode usar conectores MCP configurados na sua conta claude.ai. Isso conecta o ambiente web e o CLI: servidores MCP que você configurou pela interface do claude.ai ficam automaticamente disponíveis no Claude Code sem precisar reconfigurá-los localmente.¹⁰²

Desativar: Defina ENABLE_CLAUDEAI_MCP_SERVERS=false no seu ambiente ou no bloco env do settings.json para impedir que servidores MCP do claude.ai sejam carregados.¹¹¹

MCP Tool Search (v2.1.7+)

À medida que os 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 descrições de ferramentas dinamicamente apenas quando necessário, uma forma de lazy loading para ferramentas de IA.⁵⁴

Impacto no desempenho: Benchmarks internos mostram melhorias drásticas na 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 ativar a busca de ferramentas - false - Sempre desativar (carregar todas as descrições de ferramentas antecipadamente) - auto:N - Ativar quando as ferramentas excederem N% do contexto (0-100)

Dica avançada: Com Tool Search ativado, você pode conectar a muito 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.

MCP Elicitation (v2.1.76+)

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

Integração com hooks: Dois novos eventos de hook — Elicitation (antes do diálogo aparecer) e ElicitationResult (após o usuário responder) — permitem interceptar, validar ou sobrescrever respostas de elicitação programaticamente. Isso possibilita fluxos de trabalho corporativos onde prompts de servidores MCP são pré-preenchidos ou restringidos por política.

Assistente Interativo de Configuração MCP

Execute claude mcp add sem argumentos para iniciar uma interface passo a passo para adicionar servidores MCP. O assistente guia você pela seleção do 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 (descontinuado, 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

No Windows é necessário 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 sobrescreve projeto, que sobrescreve usuário):

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 são expandidas usando a sintaxe ${VAR} com valores padrão 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

Referenciar recursos:

@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 Saída

O Claude Code limita a saída MCP para evitar estouro 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

Fluxo de trabalho com GitHub:

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

Consultas ao 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 Corporativa

Administradores de sistema podem impor 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 lista de bloqueio 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 os 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 é renderizada dentro do Claude. Embora os MCP Apps atualmente apareçam na interface web do claude.ai, as extensões do protocolo MCP subjacentes são relevantes para o ecossistema MCP do Claude Code à medida que os servidores adotam as novas capacidades interativas.

Plataforma API: Code Execution Tool v2 (Janeiro de 2026)

A Anthropic lançou a v2 do Code Execution Tool em beta público, substituindo o sandbox original exclusivo para Python por execução de comandos Bash e manipulação direta de arquivos.⁷⁹ Principais mudanças: - Executar comandos Bash (não apenas Python) em containers isolados - Escrever e executar código em qualquer linguagem - Chamada programática de ferramentas (também em beta público): o Claude pode chamar ferramentas de dentro da execução de código, reduzindo latência e uso de tokens em fluxos de trabalho com múltiplas ferramentas

A ferramenta v2 afeta principalmente usuários da API, mas sinaliza a direção para as capacidades de execução em nuvem do Claude Code.

O que são subagents?

Subagents são instâncias especializadas de Claude que lidam com tarefas complexas de forma independente. Eles são um dos recursos mais poderosos do Claude Code e um dos menos compreendidos. Dominar subagents expande drasticamente o que você pode realizar. Consulte Frameworks de decisão para orientação sobre Agent Teams vs Subagents vs Sessões Paralelas.

Por que subagents existem: A conversa principal do Claude Code tem uma única janela de contexto. Tudo o que você discute, cada arquivo que Claude lê, cada saída de ferramenta: tudo isso consome contexto. Em sessões longas, o contexto se esgota, Claude perde o controle de decisões anteriores e o desempenho degrada. Subagents resolvem isso isolando o trabalho: resultados de exploração não inflam sua conversa principal, apenas o resumo retorna. Claude também pode executar até 10 subagents em paralelo, permitindo trabalho concorrente que seria impossível sequencialmente.²

Como subagents funcionam

Quando Claude encontra uma tarefa que se beneficia de atenção focada (exploração profunda, análise em múltiplas etapas, trabalho especializado), ele pode criar um subagent. O subagent:

1. Inicia com um contexto limpo (sem poluição da conversa principal)
2. Tem acesso a ferramentas especificadas
3. Opera com um modelo específico (frequentemente mais barato/rápido)
4. Retorna resultados para a conversa principal

A arquitetura previne estouro de contexto enquanto habilita fluxos de trabalho complexos.

Tipos de subagents integrados

Explore (rápido, somente leitura): - Modelo: Haiku (ultra-rápido) - Modo: Estritamente somente leitura - Ferramentas: Glob, Grep, Read e comandos bash seguros (ls, git status, git log, git diff, find, cat, head, tail) - Níveis de profundidade: Rápido, Médio, Muito detalhado - Use para: Exploração de codebase, encontrar arquivos, entender estrutura

General-purpose (uso geral): - Modelo: Herda da conversa principal - Modo: Leitura/escrita completa - Ferramentas: Todas as ferramentas disponíveis - Use para: Tarefas complexas de pesquisa + modificação

Plan (planejamento): - Modelo: Herda da conversa principal (ou Opus com opusplan) - Modo: Somente leitura - Ferramentas: Read, Glob, Grep, Bash - Use para: Planejar implementações complexas antes da execução

Acionando subagents

Claude delega automaticamente para subagents com base no tipo de tarefa. Você também pode solicitá-los explicitamente:

> Use the explore agent to find all authentication-related files

> Have a subagent analyze the database schema thoroughly

> Spawn an agent to research how error handling works in this codebase

Dica avançada: Para tarefas complexas, solicite explicitamente a delegação para subagents. “Use an explore agent to find…” previne inchaço de contexto na sua conversa principal.

Criando subagents personalizados

Defina subagents em .claude/agents/ (projeto) ou ~/.claude/agents/ (pessoal):

---
name: security-reviewer
description: Expert security code reviewer. Use PROACTIVELY after any code changes to authentication, authorization, or data handling.
tools: Read, Grep, Glob, Bash
model: opus
permissionMode: plan
---

You are a senior security engineer reviewing code for vulnerabilities.

When invoked:
1. Identify the files that were recently changed
2. Analyze for OWASP Top 10 vulnerabilities
3. Check for secrets, hardcoded credentials, SQL injection
4. Report findings with severity levels and remediation steps

Focus on actionable security findings, not style issues.

Campos de configuração:

Restringindo subagents que podem ser criados (v2.1.33+, renomeado v2.1.63): O campo tools suporta a sintaxe Agent(agent_type) para limitar quais tipos de subagent um agent pode criar. Por exemplo, tools: Read, Grep, Agent(Explore) permite que o agent use Read e Grep diretamente, mas só delegue para subagents do tipo Explore. A restrição impede delegação excessiva em agents com restrições. Nota: Na v2.1.63, o Tool Task foi renomeado para Agent. Referências existentes Task(...) em configurações e definições de agents ainda funcionam como aliases compatíveis.¹¹³

Subagents definidos via CLI (v2.1.32+)

Defina subagents como JSON na inicialização para testes rápidos ou automação. Eles existem apenas durante a sessão e não são salvos em disco:⁹⁶

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality and security.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

A flag --agents aceita JSON com os mesmos campos de frontmatter dos subagents baseados em arquivo: description, prompt, tools, disallowedTools, model, permissionMode, mcpServers, hooks, maxTurns, skills e memory.

Gerenciando subagents

> /agents                    # Gerenciamento interativo
> /agents create             # Criar novo subagent
> /agents edit               # Modificar existente
> /agents delete             # Remover subagent
> /agents list               # Visualizar todos

Listagem via CLI (v2.1.50+): Liste todos os agents configurados pela linha de comando sem iniciar uma sessão interativa:

claude agents                # Mostra agents agrupados por origem (integrados, usuário, projeto, plugin)

Controle remoto (v2.1.51+): O subcomando claude remote-control disponibiliza seu ambiente local para builds externos, permitindo que todos os usuários acessem as capacidades do ambiente local remotamente:¹⁰⁵

claude remote-control                      # Começar a servir o ambiente local
claude remote-control --name "My Project"  # Título personalizado da sessão visível em claude.ai/code (v2.1.69+)[^117]

Executando agents em segundo plano

Para tarefas de longa duração:

> Run a thorough security review in the background

> /agents  # Check status of running agents

Recupere os resultados depois com o ID do agent.

Padrões avançados

Subagents encadeados:

> First use the code-analyzer subagent to find performance issues, then use the optimizer subagent to fix them

Exploração paralela:

> Have three explore agents search in parallel:
> 1. Authentication code
> 2. Database models
> 3. API routes

Agents resumíveis: Agents podem ser retomados com seu ID para continuar trabalhos anteriores:

> Resume agent abc123 and continue the analysis

Subagents assíncronos (dezembro de 2025)

Subagents assíncronos permitem multitarefa e execução paralela para projetos em grande escala:

> Run security review in the background while I continue frontend work
> /tasks                    # Check status of running agents

Agents assíncronos retornam resultados via o TaskOutputTool unificado, permitindo fluxos de trabalho eficientes em estilo pipeline.

Resiliência a negação de permissão (v2.1.0+)

A partir da v2.1.0, subagents continuam funcionando após negações de permissão em vez de parar completamente. Quando um subagent encontra uma barreira de permissões, ele tenta abordagens alternativas automaticamente. A mudança torna fluxos de trabalho autônomos mais resilientes e reduz a necessidade de intervenção humana.⁴⁷

Agent Teams (fevereiro de 2026, prévia de pesquisa)

Agent Teams coordenam múltiplas instâncias de Claude Code trabalhando juntas. Uma sessão atua como o líder da equipe, criando companheiros de equipe que trabalham independentemente em suas próprias janelas de contexto, comunicando-se diretamente entre si via uma caixa de mensagens e lista de tarefas compartilhadas.⁸⁶⁹¹

Diferentemente de subagents (que executam dentro de uma única sessão e apenas reportam ao chamador), companheiros de equipe são sessões independentes completas que podem trocar mensagens entre si, questionar as descobertas uns dos outros e se auto-coordenar.

Ativar:

// settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Ou via variável de ambiente: export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Arquitetura:

Modos de exibição:

Configure nas configurações: "teammateMode": "in-process" ou "tmux". Ou por sessão: claude --teammate-mode in-process.

Controles principais: - Shift+Down: Alternar entre companheiros de equipe (modo in-process; volta ao líder após o último companheiro) - Shift+Tab: Ativar modo delegação (restringe o líder apenas à coordenação, sem alterações de código) - Ctrl+T: Alternar lista de tarefas compartilhada - Enter no companheiro: Ver a sessão dele; Escape para interromper o turno

Quando usar agent teams vs subagents:

Melhores casos de uso: - Pesquisa e revisão (múltiplas perspectivas simultaneamente) - Novos módulos/funcionalidades (companheiros cada um responsável por partes separadas) - Debugging com hipóteses concorrentes (testar diferentes teorias em paralelo) - Coordenação entre camadas (frontend, backend, testes cada um sob responsabilidade de um companheiro diferente)

Aprovação de plano para companheiros: Para tarefas complexas ou arriscadas, exija que companheiros planejem antes de implementar. O companheiro trabalha em modo de planejamento somente leitura até que o líder revise e aprove sua abordagem:

Spawn an architect teammate to refactor the authentication module.
Require plan approval before they make any changes.

O líder toma decisões de aprovação de forma autônoma. Influencie seu julgamento com critérios: “only approve plans that include test coverage” ou “reject plans that modify the database schema.”

Exemplos de prompts:

Create an agent team to review PR #142. Spawn three reviewers:
- One focused on security implications
- One checking performance impact
- One validating test coverage

Spawn a team with 4 teammates to refactor these modules in parallel.
Use Sonnet for each teammate.

Armazenamento: Configurações de equipes ficam em ~/.claude/teams/{team-name}/config.json (array de membros com nome, ID do agent, tipo do agent). Listas de tarefas em ~/.claude/tasks/{team-name}/. Tarefas suportam dependências: tarefas bloqueadas são desbloqueadas automaticamente quando suas dependências são concluídas.⁹¹

Integração com hooks: Use hooks TeammateIdle (código de saída 2 para enviar feedback e manter o companheiro trabalhando) e TaskCompleted (código de saída 2 para impedir conclusão) para impor gates de qualidade nos companheiros.

Limitações (experimental): - Sem retomada de sessão para companheiros in-process (/resume não os restaurará) - Uma equipe por sessão; sem equipes aninhadas - Companheiros não podem criar suas próprias equipes - Painéis divididos requerem tmux ou iTerm2 (não suportado no terminal do VS Code, Windows Terminal ou Ghostty) - Todos os companheiros iniciam com o modo de permissão do líder - Intensivo em tokens: cada companheiro é uma instância separada de Claude

Agent Skills (dezembro de 2025)

Agent Skills são pastas organizadas de instruções, scripts e recursos que agents descobrem e carregam dinamicamente.³¹ Eles fornecem expertise de domínio componível e portátil:

.claude/skills/
├── security-review/
│   ├── skill.md           # Instructions and prompts
│   ├── checklist.md       # Security checklist
│   └── common-vulns.sh    # Detection scripts
└── performance-audit/
    ├── skill.md
    └── profiling-guide.md

Skills diferem de comandos: comandos são invocados explicitamente, enquanto skills são ativados automaticamente com base no contexto da tarefa. O Claude Agent SDK (renomeado de Claude Code SDK) fornece o framework para construir agents personalizados com suporte a skills.³²

O que é o modo de pensamento estendido?

O pensamento estendido dá ao Claude mais tempo para raciocinar sobre problemas complexos antes de responder. É particularmente valioso para decisões arquiteturais, depuração de problemas difíceis e tarefas que exigem análise cuidadosa.

Estado atual (março de 2026)

O pensamento estendido agora está habilitado por padrão com um orçamento de 31.999 tokens.⁷⁰ A Anthropic fez essa mudança porque o pensamento estendido melhora significativamente o desempenho em tarefas complexas de planejamento e raciocínio.

Níveis de esforço (v2.1.68+, simplificado na v2.1.72): Opus 4.6 usa por padrão esforço médio para assinantes Max e Team — o equilíbrio ideal entre velocidade e profundidade. O nível de esforço é exibido no logotipo e no spinner com símbolos simplificados: ○ (baixo), ◐ (médio), ● (alto).¹²¹ A palavra-chave “ultrathink” foi reintroduzida para ativar o modo de esforço alto. Outros gatilhos em linguagem natural (“think”, “think hard”, “think harder”) continuam obsoletos — use MAX_THINKING_TOKENS ou /config em vez disso.⁷⁰¹¹⁶

Nota: Opus 4 e Opus 4.1 foram removidos do Claude Code na API própria (v2.1.68). Usuários que tinham esses modelos fixados foram migrados automaticamente para Opus 4.6.¹¹⁶

Modelos compatíveis

• Claude Opus 4.6 (também suporta pensamento adaptativo, que determina automaticamente a profundidade do raciocínio)
• Claude Sonnet 4.6 (também suporta pensamento adaptativo)
• Claude Opus 4.5
• Claude Sonnet 4.5
• Claude Haiku 4.5

Controlando o pensamento estendido

Alternância rápida durante a sessão:

Press Alt+T to toggle thinking on/off

Nota: a Anthropic alterou o atalho de alternância do pensamento de Tab para Alt+T para evitar ativações acidentais.³⁹

Via /config: Navegue até /config → Extended Thinking para habilitar/desabilitar ou ajustar o orçamento.

Variável de ambiente (permanente):

# Set custom budget (default is 31,999)
export MAX_THINKING_TOKENS=8000
claude

# Double the default for complex tasks
export MAX_THINKING_TOKENS=63999
claude

Desabilitar para economizar custos: Para tarefas mais simples onde o raciocínio profundo não é necessário, você pode reduzir custos desabilitando o pensamento em /config ou diminuindo o orçamento:

export MAX_THINKING_TOKENS=8000  # Reduce from default 31,999

Orçamentos de tokens de pensamento

Consideração de custo: a Anthropic cobra tokens de pensamento como tokens de saída. O orçamento padrão de 31.999 funciona bem para a maioria das tarefas, mas para operações simples você pode economizar custos reduzindo o orçamento ou desabilitando o pensamento por completo.

Como funciona

Quando o pensamento está habilitado, o Claude realiza um raciocínio interno que influencia a resposta, mas não aparece na saída. O Claude Code criptografa o pensamento e o retorna em um campo signature para verificação.

Em conversas de múltiplos turnos com uso de ferramentas, os blocos de pensamento devem ser passados de volta para a API para preservar a continuidade do raciocínio. O Claude Code lida com isso automaticamente.

Quando considerar desabilitar/reduzir

O pensamento estendido agora é o padrão, mas considere reduzir o orçamento ou desabilitar para: - Edições simples de arquivos - Refatoração de rotina - Perguntas rápidas - Formatação de código - Operações de alto volume onde os custos se acumulam

Comportamento de cache

O Claude Code preserva o cache do prompt de sistema quando os parâmetros de pensamento mudam. Alterar o orçamento de pensamento ou o status de habilitação entre turnos invalida o cache de mensagens.

Estilos de saída

Os estilos de saída personalizam como o Claude apresenta informações, o que é útil para aprendizado, documentação ou preferências específicas de equipe.¹⁹

Estilos integrados

Configurando o estilo de saída

> /output-style Explanatory
> /output-style Learning

Ou via configurações:

{
  "outputStyle": "Explanatory"
}

Estilos de saída personalizados

Crie em .claude/styles/:

# my-style

## Instructions
- Always explain the WHY behind each decision
- Include relevant documentation links
- Format code examples with comments
- End with a "What to do next" section

## Format
Use markdown headers for organization.
Keep explanations under 200 words per section.

Invoque com /output-style my-style.

Obsoleto (v2.1.73+): /output-style está obsoleto. Use /config para gerenciar estilos de saída em vez disso.¹²²

Comandos Slash

Os comandos slash oferecem acesso rápido aos recursos do Claude Code e permitem criar fluxos de trabalho personalizados. São mais rápidos do que digitar prompts completos para operações comuns.

Referência de comandos integrados

Criação de comandos personalizados

Crie comandos reutilizáveis em .claude/commands/ (projeto) ou ~/.claude/commands/ (pessoal):

---
description: Security-focused code review
allowed-tools: Read, Grep, Glob
model: claude-sonnet-4-5
---

Review this code for security vulnerabilities:

1. Injection attacks (SQL, command, XSS)
2. Authentication and authorization flaws
3. Sensitive data exposure
4. Insecure dependencies

Focus on actionable findings with specific line references.

Salve como .claude/commands/security-review.md e invoque com /security-review.

Opções de frontmatter dos comandos

---
description: Brief description for /help
allowed-tools: Read, Edit, Bash(npm:*)
model: opus
argument-hint: [arg1] [arg2]
disable-model-invocation: false
---