Série: Claude Code CLI: guia técnico — Parte 2: extensões, MCP e automação

Versão do conteúdo: outubro de 2026
Fontes: exclusivamente a documentação oficial da Anthropic (code.claude.com/docs e support.claude.com). A lista completa está em Fontes oficiais (Parte 3).
Aviso: o Claude Code é atualizado com frequência. Antes de usar este material como referência, confira as mudanças com /release-notes e a referência oficial do CLI. O claude --help não lista todas as flags.

---

📑 Índice da série

1. 🧠 O que é o Claude Code CLI (Parte 1)
2. 📦 Instalação e autenticação (Parte 1)
3. 🚪 Comandos de entrada (Parte 1)
4. ⌨️ Atalhos de teclado e prefixos (Parte 1)
5. ⚡ Slash commands essenciais (Parte 1)
6. 🔐 Modos de permissão (Parte 1)
7. 📄 Memória: CLAUDE.md e auto memory (Parte 1)
8. ⚖️ Configuração: settings.json (Parte 1)
9. 🪝 Hooks
10. 👥 Subagents
11. 🧩 Skills, comandos e plugins
12. 🔌 MCP no terminal
13. ⏪ Checkpoints e gestão de contexto
14. 🤖 Modo não interativo (-p) e CI
15. 🔀 Sessões em paralelo
16. ⏰ Automação agendada
17. 📱 Trabalho remoto e entre dispositivos (Parte 3)
18. ✅ O que só o CLI faz (Parte 3)
19. ❌ O que o CLI não faz (Parte 3)
20. 🤫 Recursos pouco conhecidos (Parte 3)
21. 🏆 Fluxo de trabalho recomendado (Parte 3)
22. ⚠️ Cuidados e limitações (Parte 3)
23. 📚 Fontes oficiais (Parte 3)

---

9. 🪝 Hooks

O que é: um comando seu (ou uma chamada HTTP, ferramenta MCP, prompt ou agente) que roda em pontos fixos do ciclo de vida da sessão. Ele não depende de o Claude decidir executá-lo. Hooks dos tipos prompt e agent usam um modelo para avaliar a situação, então não são determinísticos como command e http.

Para que serve: formatar código depois de cada edição, bloquear comandos perigosos, registrar todo comando executado, notificar o time, carregar contexto no início da sessão.

Eventos mais usados

SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, Stop, PreCompact, PostCompact. A documentação lista 33 eventos no total.

Exemplo: formatar após cada edição

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npm run format" }
        ]
      }
    ]
  }
}

Códigos de saída

Código	Efeito
0	Sucesso. Sem saída, o hook não tem decisão: a ação passa pelo fluxo normal de permissões (silêncio não aprova). Com JSON na saída, o hook pode decidir, por exemplo negar
2	Erro bloqueante em eventos que podem bloquear. Em PreToolUse, bloqueia a ferramenta e devolve o stderr ao Claude como motivo
Outros	Erro não bloqueante; a ação segue e aparece um aviso

Tipos de handler: command, http, mcp_tool, prompt e agent (este é experimental).

Exemplo: bloquear rm -rf com if e decisão em JSON

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# .claude/hooks/block-rm.sh  (chmod +x; exige jq)
COMMAND=$(jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q 'rm -rf'; then
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "Destructive command blocked by hook"
    }
  }'
else
  exit 0  # sem decisão; segue o fluxo normal de permissões
fi

O matcher restringe ao Bash e o if restringe a subcomandos rm *; só quando os dois casam o script é executado. Sem matcher, ou com "*", o grupo dispara em toda ocorrência do evento.

Onde definir hooks

Local	Escopo
~/.claude/settings.json	Todos os seus projetos
.claude/settings.json	O projeto, versionado no git
.claude/settings.local.json	O projeto, só para você
Settings gerenciado (managed)	A organização inteira
hooks/hooks.json de um plugin	Enquanto o plugin estiver ativo
Frontmatter de skill	Resto da sessão, depois que a skill é chamada
Frontmatter de subagent	Enquanto o subagent roda

• Hooks de níveis diferentes se somam: user, project e local acrescentam hooks sem remover os gerenciados. disableAllHooks não desliga hooks gerenciados.
• allowManagedHooksOnly (managed) bloqueia hooks de user, project, local e plugins.
• Hooks de settings, managed e plugins também rodam dentro de subagents; a entrada traz agent_id e agent_type.
• Sessões na nuvem não leem o ~/.claude/settings.json, então hooks de usuário não rodam lá.

Dicas:

• /hooks mostra os hooks configurados (só leitura).
• O matcher aceita texto exato ou regex. O campo if filtra usando a mesma sintaxe das regras de permissão.
• Timeout padrão: 600 s para command, http e mcp_tool; 30 s para prompt; 60 s para agent. Alguns eventos têm limites próprios, menores.
• Na maioria dos eventos, se o hook falhar ou estourar o tempo, a ação segue. Para bloquear nesse caso, use "onFailure": "block" em hooks command ou http (v2.1.295+; sem efeito em Stop, SubagentStop, TaskCompleted e TeammateIdle).
• Para reinjetar instruções depois de uma compactação, use um hook SessionStart com matcher compact.

Hook não fura deny: um PreToolUse que devolve "allow" não libera uma ação bloqueada por regra deny. Para limites rígidos, use o sistema de permissões.

---

10. 👥 Subagents

O que é: um assistente especializado que roda na sua própria janela de contexto, com prompt de sistema, ferramentas e permissões próprios. Ele devolve só um resumo, então logs e resultados de busca extensos não poluem a conversa principal.

Subagents nativos:

• Explore: busca rápida, só leitura.
• Plan: pesquisa no plan mode, só leitura.
• general-purpose: tarefas complexas, com todas as ferramentas.
• claude: catch-all para o que não se encaixa nos outros.
• statusline-setup e claude-code-guide: configuração da status line e dúvidas sobre o próprio Claude Code.

Criar o seu

Arquivo em .claude/agents/ (projeto) ou ~/.claude/agents/ (todos os projetos):

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. Give specific, actionable feedback.

Só name e description são obrigatórios.

• tools: allowlist de ferramentas. Se omitido, o subagent herda todas.
• disallowedTools: lista de ferramentas bloqueadas.
• Outros campos: model, permissionMode, skills, mcpServers, hooks, memory, isolation: worktree, maxTurns, background, effort, color, initialPrompt, omitClaudeMd.

Como invocar

• Automático: o Claude delega com base na description.
• Explícito: cite o subagent no prompt ou mencione com @.
• Sessão inteira: claude --agent code-reviewer.
• Definição temporária, só para a sessão:

claude --agents '{"debugger": {"description": "Debugs errors", "prompt": "You are an expert debugger."}}'

Recursos extras:

• /subtask <tarefa> cria um fork que herda a conversa inteira e reporta o resultado de volta na conversa. Para copiar a conversa para uma sessão em segundo plano, use /fork.
• Ctrl+B manda um subagent em execução para segundo plano.
• Subagents num modelo mais barato (como model: haiku para tarefas simples) reduzem custo.
• Para um subagent só de leitura, defina tools com ferramentas de leitura (como no exemplo acima). Apenas remover Edit/Write com disallowedTools não basta: ele mantém Bash e ferramentas MCP.

---

11. 🧩 Skills, comandos e plugins

Skills

O que é: um arquivo SKILL.md com instruções (e arquivos de apoio opcionais) que ensina um procedimento. O Claude carrega a skill quando ela é relevante, ou você chama com /nome.

Local	Escopo
~/.claude/skills/<nome>/SKILL.md	Você, em todos os projetos
.claude/skills/<nome>/SKILL.md	O time, via git
<plugin>/skills/<nome>/SKILL.md	Chamada como /plugin-name:skill-name

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---

Deploy $ARGUMENTS to production:
1. Run the test suite
2. Build the application
3. Push to the deployment target

• disable-model-invocation: true: só você pode chamar (ideal para deploy).
• user-invocable: false: some do menu / e só o Claude pode chamar.
• $ARGUMENTS recebe todos os argumentos; $0 é o primeiro, $1 o segundo (índice começa em zero).
• Arquivos em .claude/commands/ continuam funcionando e também viram /nome; a skill acrescenta arquivos de apoio e controle de invocação.
• /skills lista as skills; /skill-doctor (v2.1.252+) mostra o custo de contexto e o uso de cada uma.

Custo de contexto: a descrição de cada skill fica sempre no contexto (description + when_to_use são truncados em 1.536 caracteres na listagem). O conteúdo completo só carrega quando a skill é usada.

Skills que já vêm prontas: /code-review, /batch, /debug, /loop, /claude-api, /verify, /run, /simplify, /fewer-permission-prompts, entre outras.

Plugins

O que é: um diretório que empacota skills, agentes, hooks, servidores MCP e servidores LSP para instalar como uma unidade.

• /plugin abre o menu, com as abas Discover, Installed, Marketplaces, Errors e Stats. A aba Discover lista os plugins dos seus marketplaces.
• Ao abrir um plugin, os detalhes mostram uma estimativa de custo de contexto (Context cost) e o que ele vai instalar. Marketplaces locais ou próprios podem não fornecer esses dados.
• O marketplace oficial da Anthropic (claude-plugins-official) é adicionado na primeira sessão interativa no terminal, salvo bloqueio por política gerenciada.
• Pelo shell: claude plugin install <plugin>@<marketplace> (instala no escopo de usuário, a menos que você passe --scope).
• Escopos de instalação: usuário, projeto (via .claude/settings.json) ou local.
• A aba Installed agrupa plugins sem uso recente (Not used recently), para você desativar o que não usa.
• Sessões na nuvem (claude.ai/code) não carregam os plugins das suas configurações locais.

Atenção: um plugin ativo entra em todas as sessões, consome contexto e roda com as suas permissões. Revise antes de instalar.

---

12. 🔌 MCP no terminal

O MCP (Model Context Protocol) é um padrão aberto para conectar ferramentas de IA a fontes de dados externas.

Adicionar servidores

# Remoto via HTTP (recomendado para servidores remotos)
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Remoto com cabeçalho de autenticação
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

# Local via stdio: tudo depois de "--" vai para o comando do servidor
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

Escopos

Escopo	Onde fica	Quem vê
local (padrão)	~/.claude.json, na entrada do projeto	Só você, neste projeto
project	.mcp.json na raiz do repositório	O time, via git
user	~/.claude.json	Você, em todos os projetos

Escolha com -s ou --scope, por exemplo claude mcp add --transport http shared-server --scope project https://example.com/mcp.

Se o mesmo nome existir em mais de um lugar, vale a entrada inteira da fonte de maior precedência (os campos não se misturam): local → project → user → plugin → connectors do claude.ai. Servidores fornecidos pela organização via managedMcpServers (v2.1.259+) ficam acima de todos.

.mcp.json (compartilhado com o time)

{
  "mcpServers": {
    "notion": {
      "type": "http",
      "url": "https://mcp.notion.com/mcp"
    },
    "airtable": {
      "command": "npx",
      "args": ["-y", "airtable-mcp-server"],
      "env": { "AIRTABLE_API_KEY": "${AIRTABLE_API_KEY}" }
    }
  }
}

• ${VAR} e ${VAR:-padrão} são expandidos em command, args, env, url e headers. Assim o segredo fica no ambiente, não no git.
• Variáveis de credencial ficam vazias quando usadas em url e headers de servidores remotos. Exemplos: ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, AWS_BEARER_TOKEN_BEDROCK, HTTPS_PROXY e NPM_TOKEN. Use nomes próprios, como API_KEY.
• Servidores de escopo project pedem aprovação nas sessões interativas. Para refazer essas escolhas: claude mcp reset-project-choices.

Gerenciar

claude mcp list                     # lista servidores
claude mcp get <nome>               # detalhes de um servidor
claude mcp remove <nome>            # remove
claude mcp add-json <nome> '<json>' # adiciona a partir de JSON
claude mcp add-from-claude-desktop  # importa do Claude Desktop (macOS e WSL)
claude mcp serve                    # expõe o próprio Claude Code como servidor MCP
claude mcp login <nome>             # faz o login OAuth sem abrir o painel /mcp
claude mcp logout <nome>            # apaga as credenciais OAuth salvas

Dentro da sessão, /mcp mostra o status, faz login OAuth pelo navegador e liga ou desliga servidores por projeto. /mcp reconnect all reconecta todos os servidores com falha (v2.1.284+).

Limites e nomes

• A saída de uma ferramenta MCP gera aviso acima de 10.000 tokens e tem limite padrão de 25.000, ajustável com MAX_MCP_OUTPUT_TOKENS.
• MCP_TIMEOUT controla o timeout de inicialização (ex.: MCP_TIMEOUT=10000 claude, 10 s); MCP_TOOL_TIMEOUT, o de cada ferramenta. O campo timeout (em ms) no .mcp.json sobrepõe esse valor por servidor.
• Os schemas das ferramentas MCP são carregados sob demanda (tool search) por padrão, para economizar contexto.
• Ferramentas MCP seguem o padrão mcp__<servidor>__<ferramenta>; as de plugin, mcp__plugin_<plugin>_<servidor>__<ferramenta>. Use o nome completo em regras de permissão, tools de subagent e matchers de hook.

Segurança: a Anthropic não audita nem gerencia servidores MCP. Instale só os que você confia; um servidor que lê conteúdo da internet expõe você a prompt injection.

---

13. ⏪ Checkpoints e gestão de contexto

Checkpoints

O Claude Code cria um checkpoint automaticamente antes de cada prompt. Ele guarda as edições feitas pelas ferramentas de edição de arquivo do Claude.

• Abrir: /rewind (apelidos /checkpoint e /undo) ou Esc Esc com o campo vazio.
• Opções do menu: restaurar código e conversa, só a conversa, só o código, resumir a partir daqui, resumir até aqui. As opções de resumo comprimem o contexto sem mexer nos arquivos.
• Retenção: os 100 checkpoints mais recentes de cada sessão. Os snapshots são apagados cerca de 30 dias depois, conforme cleanupPeriodDays.
• Checkpoints sobrevivem a --resume e --continue.

O que o checkpoint NÃO desfaz:

• Efeitos de comandos Bash (rm, mv, cp etc.).
• Edições feitas por subagents.
• Mudanças feitas fora do Claude Code ou por outras sessões.
• Arquivos com symlink ou hard link.
• Ações remotas: banco de dados, APIs, deploys.

Checkpoint não substitui o git. Faça commits.

Gestão de contexto

Comando	O que faz
/context	Mostra o uso do contexto em grade colorida, com sugestões
/compact [instruções]	Resume a conversa, com foco opcional (ex.: /compact foque nas mudanças da API)
/clear	Começa uma conversa nova, com contexto vazio (apelidos /reset e /new)
/btw <pergunta>	Pergunta paralela que não entra no histórico
/autocompact 500k	Define a partir de quantos tokens a compactação automática dispara (auto volta ao padrão)

• Janela de contexto: 200 mil tokens no padrão. Modelos com janela nativa de 1 milhão (como Fable 5.1, Sonnet 5 em diante, Haiku 5.5 e Opus 4.7 em diante) usam 1M por padrão.
• Compactação automática vem ligada. Ela descarta primeiro saídas antigas de ferramentas e depois resume. Instruções detalhadas do início podem se perder.
• Para controlar o que sobrevive à compactação, adicione uma seção "Compact Instructions" no CLAUDE.md.
• CLAUDE_CODE_DISABLE_1M_CONTEXT=1 desliga a janela de 1M.

Como economizar contexto:

• Regras permanentes vão no CLAUDE.md, não na conversa.
• Investigações longas vão para subagents: só o resumo volta.
• Skills carregam o conteúdo só quando usadas.
• Use /clear entre tarefas sem relação.

---

14. 🤖 Modo não interativo (-p) e CI

claude -p "explique este erro" --output-format json
git diff | claude -p "revise este diff" --allowedTools "Read" "Grep"

Flags principais

Flag	O que faz
--output-format	Formato da saída: text (padrão), json ou stream-json. json traz result, session_id e total_cost_usd. stream-json exige --verbose
--input-format	Formato da entrada: text ou stream-json
--json-schema '<schema>'	Força saída estruturada (com --output-format json, vem em structured_output)
--max-turns <n>	Limita o número de turnos; sem limite por padrão
--max-budget-usd <valor>	Para quando o gasto estimado atingir o teto (só no modo -p)
--allowedTools / --disallowedTools	Libera ou bloqueia ferramentas com a sintaxe de regras, uma regra por argumento entre aspas: "Bash(git diff *)" "Read"
--tools	Restringe quais ferramentas nativas existem na sessão (ex.: "Bash,Edit,Read")
--permission-mode	Modo de permissão da execução (dontAsk é o mais seguro para CI)
--permission-prompts none	Nega pedidos de permissão em vez de esperar (v2.1.259+)
--append-system-prompt	Acrescenta instruções ao prompt de sistema; --system-prompt substitui
--bare	Pula hooks, skills, plugins, MCP, auto memory e CLAUDE.md; inicia mais rápido
-c / -r <id>	Continua ou retoma uma sessão também no modo -p

• Código de saída: 0 em sucesso, diferente de zero em falha. SIGTERM encerra com 143; prefira SIGINT para fechar o turno de forma limpa.
• A documentação avisa que --bare deve virar o padrão do -p numa versão futura.

Autenticação em CI

• No modo -p, ANTHROPIC_API_KEY é sempre usada quando presente.
• Com assinatura: gere o token com claude setup-token e use CLAUDE_CODE_OAUTH_TOKEN.
• Com --bare, o OAuth é ignorado: use ANTHROPIC_API_KEY ou apiKeyHelper.

GitHub Actions

• Configuração rápida: rode /install-github-app dentro do Claude Code. Exige repositório no github.com, gh autenticado e acesso de admin.
• Action oficial: anthropics/claude-code-action@v1, com o segredo ANTHROPIC_API_KEY ou CLAUDE_CODE_OAUTH_TOKEN.
• Sem prompt, responde a menções @claude em issues e PRs. Com prompt, roda automaticamente.
• claude_args repassa flags do CLI (ex.: --max-turns, --model).
• Quem dispara precisa ter permissão de escrita no repositório.

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: {% raw %}${{ secrets.ANTHROPIC_API_KEY }}{% endraw %}
    claude_args: "--max-turns 5"

GitLab CI/CD

Integração em beta, mantida pela GitLab. O job instala o Claude Code com o instalador nativo e roda claude -p com a variável mascarada ANTHROPIC_API_KEY.

Agent SDK

O modo -p é a interface de linha de comando do Agent SDK. Para saída estruturada, callbacks de aprovação e controle fino, use os pacotes oficiais em Python ou TypeScript.

---

15. 🔀 Sessões em paralelo

Git worktrees

claude --worktree feature-auth   # ou: claude -w feature-auth
claude -w "#1234"                # cria a partir de um PR (aspas por causa do #)

• Cria <repo>/.claude/worktrees/<nome> numa branch nova worktree-<nome>. Sem nome, o Claude gera um.
• Coloque .claude/worktrees/ no .gitignore.
• .worktreeinclude (sintaxe de gitignore) copia arquivos ignorados, como .env, para o worktree novo.
• worktree.baseRef: "fresh" (padrão, parte da branch principal) ou "head" (parte do HEAD atual).
• Ao sair de uma sessão sem nome e sem alterações, o worktree é removido. Nos demais casos, o Claude pergunta antes. Execuções -p não limpam: use git worktree remove.
• --tmux junto com --worktree abre o worktree numa sessão tmux.
• Subagents com isolation: worktree trabalham num worktree próprio.

/batch

/batch <instrução> pesquisa o código, divide o trabalho em 5 a 30 unidades independentes e mostra o plano. Depois da aprovação, roda um subagent em segundo plano por unidade, cada um no seu worktree, com testes.

/batch migre src/ de JavaScript para TypeScript

Sessões em segundo plano

• claude --bg "tarefa" inicia uma sessão em segundo plano (não combina com -p).
• /background (ou /bg) desanexa a sessão atual; /fork copia a conversa para uma nova sessão em segundo plano.
• claude agents abre o painel (agent view, em research preview). ← com o campo vazio desanexa; Enter ou → anexa.
• Pelo shell: claude attach, claude logs, claude stop, claude rm, claude respawn.
• As sessões rodam na sua máquina; uma sessão ociosa e desanexada encerra o processo depois de cerca de uma hora.

Agent teams (experimental)

• Desligado por padrão. Ative com CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.
• Um líder coordena vários "teammates" que trabalham em paralelo e conversam entre si.
• Não funciona no modo -p. Um time por sessão, sem times aninhados.
• Comece com 3 a 5 teammates. O consumo de tokens é bem maior que o de uma sessão única.

---

16. ⏰ Automação agendada

/loop: repetição dentro da sessão

/loop 5m verifique se o deploy terminou
/loop verifique o CI a cada 2 horas

• Unidades: s, m, h, d. A granularidade real é de 1 minuto (segundos são arredondados para cima).
• Sem intervalo, o Claude escolhe o ritmo entre 1 minuto e 1 hora. Sem prompt, usa .claude/loop.md ou ~/.claude/loop.md, se existir.
• Só dispara com o Claude Code aberto e ocioso. Tarefas recorrentes expiram em 7 dias; máximo de 50 por sessão.
• Esc para um loop de ritmo automático. CLAUDE_CODE_DISABLE_CRON=1 desliga o recurso.

/schedule: rotinas na nuvem

• Rotinas rodam na infraestrutura da Anthropic e continuam com o notebook fechado. Planos Pro, Max, Team e Enterprise; em research preview.
• Crie com /schedule no CLI ou em claude.ai/code/routines.
• Gatilhos: agenda (intervalo mínimo de 1 hora), chamada de API (HTTP POST com token) e eventos do GitHub.
• Limites por hora: 100 execuções agendadas por conta; 30 execuções por rotina, somando "Run now", chamadas de API e reexecuções avulsas; 100 chamadas de API por conta.

Qual usar

Opção	Onde roda	Intervalo mínimo	Precisa da máquina ligada?
/loop	Na sessão aberta	1 minuto	Sim, com a sessão aberta
Tarefa agendada do app desktop	Na sua máquina	1 minuto	Sim
/schedule (rotina)	Nuvem da Anthropic	1 hora	Não
GitHub Actions com schedule	Runner do GitHub	Conforme o cron do GitHub	Não

---

Continua na Parte 3: trabalho remoto, o que só o CLI faz, o que ele não faz, recursos pouco conhecidos, fluxo recomendado, cuidados e fontes oficiais.