Integração com VS Code

📚 Navegação da Série: O artigo anterior 07 Primeiro Uso levou você a executar o primeiro exemplo no terminal. Este artigo traz o Claude Code para o VS Code — as mesmas capacidades, mas com a jogabilidade de uma interface gráfica.

Ao começar a usar a extensão do VS Code, era muito fácil cometer um erro bem estúpido.

O Claude Code que rodava tão bem no terminal, após instalar a extensão, você quer testar a interface gráfica, abre uma pasta vazia e, por mais que procure, não consegue encontrar o "Ícone Spark" (o ícone em forma de faísca na barra de ferramentas, o identificador de entrada do Claude Code na IDE) mencionado no site oficial. Neste momento, é muito fácil achar que instalou errado, desinstala, reinstala, reinicia, limpa o cache, perde uns vinte minutos e, finalmente, ao ler a documentação, descobre — aquele ícone só aparece quando você abre um arquivo específico, abrir apenas a pasta não é suficiente. Procurar o ícone de frente para um workspace vazio é procurar para sempre.

Simplificando, a integração com o VS Code não é difícil, mas ela e o terminal têm lógicas de interação diferentes. Algumas suposições farão você ficar preso no primeiro passo. Este artigo aponta esses problemas antecipadamente para você.

Depois de ler este artigo, você obterá:

• Os passos completos para instalar a extensão Claude Code no VS Code (incluindo forks como Cursor), além da lista de verificação de "ícone não encontrado"
• Como usar o diff lado a lado (revisão de alterações linha por linha), as menções com @ e a revisão de plano, as três vantagens exclusivas da interface gráfica
• Uma tabela de comparação de "qual usar: extensão vs CLI", além de um conjunto de atalhos comuns

---

01 Entenda primeiro: Qual é a relação entre a extensão e a CLI

"Eu já sei usar o claude no terminal, eu ainda preciso instalar a extensão?" Conclusão primeiro: A extensão não substitui a CLI, ela coloca uma camada de interface gráfica por fora. A instalação da extensão também trará a CLI, as duas compartilham a mesma configuração ~/.claude/settings.json; o histórico da conversa pode ser recuperado, mas não sincroniza em tempo real — se você conversar até a metade na extensão, e depois rodar claude --resume no terminal, você pode continuar ativamente essa conversa.

Analogia: A mesma cozinha com duas janelas de pedidos. A CLI é gritar o pedido pela janela da cozinha — rápido, completo, você pode pedir qualquer coisa; a extensão é o garçom do restaurante, ajudando você a fazer o menu ilustrado e visualizar o andamento dos pedidos de forma mais intuitiva, mas há alguns "menus ocultos" que você só pode pedir através da janela. A cozinha é a mesma, os pratos são idênticos.

Afinal de contas, quando usar qual? O site oficial forneceu uma comparação de recursos, resumida aqui:

Recurso	CLI (Terminal)	Extensão VS Code
Comandos e skills	Todos	Subconjunto (digite / para ver os disponíveis)
Configuração do servidor MCP	Completa	Parcial (adicione com a CLI, gerencie com /mcp no painel)
Checkpoints (pontos de verificação)	Suportado	Suportado
Atalho bash !	Suportado	Não Suportado
Autocompletar com Tab	Suportado	Não Suportado
Diff lado a lado, contexto por seleção de código	Requer conexão com a IDE	Nativo, pronto para uso

Em resumo: Para tarefas como escrever código e revisar alterações, onde você "lida com arquivos", a extensão é obviamente melhor; atalhos bash como !ls e o autocompletar com Tab estão apenas na CLI. O uso comum é ter a força de trabalho principal aberta na extensão, e se precisar rodar comandos em lote ou usar comandos não disponíveis na extensão, digite claude diretamente no terminal integrado — o histórico é contínuo, a troca é perfeita.

💡 Resumo em uma frase: A extensão e a CLI são duas faces do mesmo motor, compartilham histórico e configuração, você pode alternar livremente dependendo da tarefa, não precisa escolher entre uma ou outra.

---

02 Instalação: Três posturas, mais solução de problemas se o ícone não aparecer

Olhe para a versão antes de instalar

Requisito rígido oficial: VS Code versão 1.98.0 ou superior, não será instalada ou não funcionará se a versão for inferior a esta (clique em "Ajuda → Sobre" para ver o número da versão). Ao abrir a extensão pela primeira vez, ela pedirá que você faça login na sua conta Anthropic; para empresas que usam fornecedores terceiros como Bedrock, Vertex AI, o método de configuração é diferente, isso é abordado separadamente no final.

Três formas de instalação

Método um: Pesquisar no Marketplace do aplicativo (O mais seguro, recomendado para iniciantes)

No VS Code, pressione Cmd+Shift+X (Mac) ou Ctrl+Shift+X (Windows/Linux) para abrir a exibição Extensões, pesquise por Claude Code e clique em Instalar.

A imagem acima mostra como é a pesquisa por Claude Code na visão de extensões: A linha na caixa vermelha "Claude Code para VS Code" da Anthropic com um selo de verificação azul é a oficial, tenha certeza disso e clique nela para instalar.

Existe aqui uma armadilha mais fácil para iniciantes: pesquisar por Claude Code fará surgir várias extensões com nomes parecidos, preste atenção naquela cujo autor seja a Anthropic e não instale algo falso de terceiros.

Método dois: Instalação direta por link

Com o VS Code aberto, clicar no link vscode:extension/anthropic.claude-code saltará diretamente para a página de instalação da extensão (no Cursor troque vscode: por cursor:).

Método três: Editores não convencionais / Quando não instala

A extensão também pode ser instalada em forks do VS Code (Cursor, Devin Desktop, Kiro etc.) — busque Claude Code na exibição de extensões deles, ou instale pelo registro Open VSX. Caso não consiga instalar de jeito nenhum, não quebre a cabeça, a solução de contorno oficial é executar o claude diretamente no terminal integrado.

Dica para a China: A instalação, a autorização de login e o trabalho subsequente do Claude requerem conexão com os serviços da Anthropic, portanto, usar proxy para acessar a internet é necessário durante todo o processo, de maneira idêntica à versão de terminal.

Ícone não encontrado após a instalação? Use esta lista de verificação

Esta foi a armadilha do início. Após a instalação, a extensão não exibe um pop-up por padrão, você tem que chamar o painel sozinho. O caminho mais rápido: abra primeiro um arquivo específico e, em seguida, clique no Ícone Spark (um ícone em forma de faísca) na barra de ferramentas no canto superior direito do editor.

A imagem acima marca as localizações das três entradas: o Ícone Spark no canto superior direito do editor (②, o mais rápido, mas só aparece quando o arquivo está aberto), o Spark na barra de atividades (①, sempre presente) e o ✱ Claude Code na barra de status (③, também acessível sem arquivos abertos).

A chave é apenas uma: O Ícone Spark só aparece quando você abriu um arquivo, abrir apenas a pasta não é o suficiente. Se você ainda não conseguir vê-lo, verifique nesta ordem, de acordo com o site oficial:

Fenômeno	Ação de Verificação
Sem ícone no canto superior direito do editor	Abra primeiro um arquivo (não apenas a pasta)
O arquivo está aberto e ainda não aparece	Confirme que o VS Code ≥ 1.98.0 (Ajuda → Sobre)
A versão também é suficiente	Execute Developer: Reload Window na Paleta de Comandos para recarregar a janela
Recarregar também não funcionou	Desative temporariamente outras extensões de IA (Cline, Continue, etc.), pode haver conflito
Workspace está no "Modo Restrito"	Extensões não funcionam em modo restrito, é preciso confiar no workspace

Se não conseguir encontrar o ícone Spark de jeito nenhum, restam duas portas alternativas:

• Na barra de atividades (a barra vertical de ícones na extrema esquerda), há o ícone Spark — ele está sempre lá, ao clicar abrirá a lista de sessões.
• Na barra de status (canto inferior direito da janela), há o ✱ Claude Code — este também pode ser clicado mesmo se nenhum arquivo estiver aberto, costuma ser mais prático para não ter que se preocupar se há algum arquivo aberto. Você também pode acessar a paleta de comandos (Cmd+Shift+P / Ctrl+Shift+P) e digitar Claude Code.

A primeira vez que você clicar no painel aparecerá a tela de login, clique em Fazer Login e conclua a autorização no navegador. (Se a variável ANTHROPIC_API_KEY estiver definida e ainda for solicitado a fazer login, o mais provável é que o VS Code não tenha herdado as variáveis de ambiente do terminal. A solução oficial é iniciar o VS Code a partir do terminal com code . para trazer as variáveis de ambiente com ele.)

💡 Resumo em uma frase: Procure pelo autor Anthropic ao instalar a extensão. O ícone Spark requer que um arquivo esteja aberto para aparecer. Se você não conseguir achá-lo, abra um arquivo, e se não der certo, use a porta da barra de status no canto inferior direito.

---

03 Visão Diff: Compare as alterações frente a frente, veja claramente e, em seguida, acene com a cabeça

Esta é a característica que fez muitos se apaixonarem cedo pela extensão. No terminal, os diffs ao alterar os arquivos são feitos de caracteres de texto. Se o arquivo for muito grande ou houver muitas alterações, fica difícil olhar. A extensão levou esta tarefa para a visão diff nativa do VS Code — onde os acréscimos e exclusões são destacados em vermelho e verde, dando a mesma sensação que você tem ao visualizar um Git diff normal.

Analogia: A visualização em "Modo de Revisão" antes de assinar o contrato. A outra parte manda de volta o contrato modificado com o rascunho original à esquerda e a versão modificada à direita. Todas as edições são marcadas de forma limpa — você não assina às cegas, você lê item por item e só então escreve. O Claude funciona assim ao fazer edições; as exibe, solicita permissão e você tem três opções: aceitar, rejeitar ou instruí-lo a alterar de outra maneira.

Além disso, há um detalhe que muitas vezes é ignorado até se usar a funcionalidade: antes de aceitar, você pode editar diretamente as recomendações do Claude na visão diff. Ao alterar, ele sabe que "você tocou ali" e não prosseguirá com a versão antiga. Por exemplo: pedir que ele refatore uma função de 200 linhas. Ele pode alterar sete ou oito partes diferentes; se ao passar o olho pelo diff, você perceber que uma avaliação de borda ficou de trás para frente, conserte você mesmo no lado direito e, em seguida, aceite — isso te poupará de uma rodada de idas e vindas.

💡 Resumo em uma frase: A visão diff coloca todas as mudanças diante de você. Veja claramente, edite na hora e, por fim, decida se vai aceitar ou não. Muito mais seguro que os diffs em formato texto no terminal.

---

04 A menção com @ e a Seleção de Código: Alimente o contexto com precisão

O maior desperdício de tempo ao fazer o Claude trabalhar, é quando ele "não sabe a qual trecho de código você se refere" e acaba adivinhando, andando em círculos. A extensão possui dois truques para alimentar o contexto de maneira muito rápida e precisa.

Truque número um: Menção de arquivo / pasta usando @

Escreva @ seguido pelo nome do arquivo ou da pasta dentro da caixa de prompt, e o Claude lerá esses conteúdos. A funcionalidade oferece correspondência vaga; você não precisa inserir o nome completo:

> Por favor, explique a lógica por trás do @auth (Ele irá corresponder a auth.js, AuthService.ts, etc., automaticamente)
> O que tem no @src/components/? (Não se esqueça da barra / no final de uma pasta)

Analogia: Mandar os arquivos no grupo de chat antes da reunião. Ao invés de uma descrição verbal do tipo "aquele arquivo relacionado ao login," é melhor usar um @ e jogar diretamente o arquivo para ele; você poupa o esforço de ele ficar caçando no projeto inteiro — e de errar a busca. Para os PDFs super grandes, você pode até informar para ele ler apenas páginas específicas (ex: páginas 1-10), em vez de ler o documento completo.

Truque número dois: Selecione o código, ele vê automaticamente

Este truque é mais fácil do que o @: selecione um código diretamente no editor; o Claude automaticamente o verá, a caixa de entrada embaixo mostrará: "XX linhas selecionadas". Caso você pergunte diretamente "por que isso aqui daria erro?", ele saberá a qual trecho você se refere.

Alguns dos macetes complementares frequentemente usados:

• Insira citações com os números de linhas: Pressione a tecla Option+K / Alt+K para injetar o caminho associado com o número de linhas referido automaticamente, como @app.ts#5-10 (Requer que o editor esteja em foco).
• Oculte temporariamente sua seleção de código dele: Clique no "indicador de seleção" na parte inferior da caixa de prompt para alternar, quando surgir aquele símbolo de “um olho com uma barra transversal,” o que você está selecionando ficará oculto do Claude — a seleção será apenas para fins de cópia.
• Arraste o arquivo como anexo: Arraste um arquivo direto no espaço de prompt e certifique-se de apertar Shift ao soltar; exclua o seu anexo via a tecla × no anexo.

Por exemplo, rastreando a fonte de um bug de estilo CSS com cinco ou seis camadas de aninhamento. Após selecionar aquela provável regra suspeita e então perguntar: "por que isso aqui não tem efeito?", o Claude achará o erro gerador dentro de poucos passos, notando, por ex., que é o overflow: hidden do elemento pai cortando o elemento filho — só usando texto para descrever aquele aninhamento, daria muito trabalho de digitar.

⚠️ O texto selecionado e o arquivo atualmente aberto serão enviados ao Claude com o prompt por padrão. Para arquivos confidenciais como o .env, a sugestão oficial é adicionar uma regra de rejeição Read para o caminho, e caso coincida, a leitura não alcançará o Claude (sujeito à documentação oficial).

💡 Resumo em uma frase: Use a menção com @ para alimentar os arquivos e a seleção de código para alimentar o contexto automaticamente — elimine diretamente o maior custo de adivinhação sobre "a qual trecho você se refere".

---

05 A Revisão via Plano (Plan Review): Deixe ele entregar o plano primeiro, você aprova e ele age

Esta seção é provavelmente a área em que a extensão tem o maior aumento de experiência em comparação com o terminal. Começando com os modos de permissão: clicar no indicador de modo na parte inferior da caixa de prompt pode alterar o modo de atuação do Claude Code, que tem estas opções:

Modo	O comportamento do Claude	Quando usar
Modo Normal (Padrão)	Interroga você e solicita sua permissão antes de cada operação	Em tarefas não familiares ou se quiser controle total passo a passo
Plan Mode (Modo Plano)	Ele descreverá primeiro como pretende agir; só vai trabalhar com a sua aprovação final	Alterações massivas, múltiplos arquivos, ou se deseja ver o roteiro
Modo Aceitar Automaticamente	Modificará diretamente sem fazer perguntas sucessivas a cada passo	Tarefas repetitivas e de pequena escala que são confiáveis

Além disso, há um quarto nível, bypassPermissions (ignorar todas as verificações de permissão), que exige a ativação de allowDangerouslySkipPermissions nas configurações, aplicável apenas em ambientes sandbox completamente isolados, não recomendado para uso diário.

Analogia: Se o estagiário pergunta ou não antes de agir. O Modo Normal é "perguntar em cada passo", o Aceitar Automaticamente é "deixar ele trabalhar livremente" — O Modo Plano é o mais especial, é como se o estagiário lhe entregasse um rascunho de "aqui está como planejo fazer" para você revisar, e ele só age quando você concordar.

O Modo Plano tem um benefício no VS Code que o terminal não pode oferecer: o Claude abrirá automaticamente o plano como um documento Markdown completo, e você pode adicionar anotações embutidas nele. Ao não ser meramente vago nas respostas como "o segundo passo está errado", você pode diretamente escrever ao lado da linha "Passo 2": "Não toque no banco de dados aqui, adicione cache de memória primeiro", e ele absorverá sua opinião antes de agir — muito mais preciso do que apenas um retrabalho verbal.

A imagem acima mostra o documento de plano em Markdown aberto no Modo Plano: o Claude lista cada passo, você anota (por exemplo: "Não mexer no banco de dados, adicione cache de memória primeiro") ao lado da linha "Passo 2", e quando você aprova, ele internaliza essa solicitação ao começar o trabalho.

Gostaria de torná-lo o padrão? Altere o parâmetro claudeCode.initialPermissionMode nas configurações para plan. Um hábito seguro é sempre usar o Modo Plano primeiro para "múltiplos arquivos, ou alterações de mais de 50 linhas". Aqui a comum lição aos iniciantes: por conveniência, deixar no Modo Aceitar Automaticamente a todo momento e pedir que ele adicione logs a um módulo. Ele pode, por acaso, também "otimizar" a ordem das importações em vários arquivos e depois você gastará dez minutos para descobrir onde ele tocou. Toda e qualquer ampla mutação deve ir com o Modo Plano para limitar ele nas etapas de solução antecipadamente, o que será na verdade de grande economia!

💡 Resumo em uma frase: Modo Plano = Analise o plano antes da ação, sendo possível fazer anotações passo a passo no plano Markdown — mude para este modo em alterações grandes de múltiplos arquivos e previna retrabalhos imensos!

---

06 Mão na Massa: Execute todo o fluxo da interface gráfica em 10 minutos

Esta seção começará do zero com o passo-a-passo, e em cada um será descrito "o que você verá na tela", permitindo que você avalie de forma autêntica se aprendeu ou instalou corretamente.

Passo 0: Crie um projeto mínimo de ensaio

Não precisa de um projeto real, uma pasta vazia contendo um arquivo basta. No terminal, rode:

mkdir vscode-claude-demo && cd vscode-claude-demo
printf 'def greet(name):\n    return "Hello " + name\n\nprint(greet("world"))\n' > demo.py
code .

Expectativa: O VS Code abrirá esta pasta, no gerenciador de recursos lateral à esquerda, o script / arquivo demo.py estará visível. (Se você não instalou o utilitário de comando code, abra a pasta manualmente.)

Passo 1: Abra o painel do Claude e faça login

Clique para abrir o demo.py (lembre-se, é essencial que um arquivo seja aberto para isto), clique no Ícone Spark no canto superior direito. Se aparecer a tela de login pela primeira vez, clique em Fazer Login e conclua a autorização no navegador.

Expectativa: O painel de bate-papo do Claude Code aparecerá do lado direito e o topo não mostrará mais "Não Fez Login".

Passo 2: Selecione código + peça para modificar, e olhe o diff embutido

Selecione as duas linhas contendo a função greet no arquivo demo.py, o texto da caixa de entrada inferior deve exibir "2 linha(s) selecionadas". Nesse instante, digite:

Ajude na edição ao modelo pra conversões dele pro estilo uso das de f-strings no python e adicione por anotações de tipos

Expectativa: O Claude não lhe perguntará "qual função" (demonstrando que o contexto selecionado foi percebido), acionando imediatamente a comparação diff lado a lado — O lado direito vai mudar return "Hello " + name para os termos return f"Hello {name}" e anotará propriedades de tipos. Logo abaixo, as opções Aceitar / Rejeitar vão surgir. Olhe tudo com exatidão e aperte em Aceitar.

Passo 3: Tente o Modo Plano uma vez

Mude o indicador na parte inferior do prompt para ativar o modo Plan Mode e envie uma requisição maior:

Adicione suporte aos argumentos pela linha de comando nesse respectivo documento, permitindo que o usuário insira o nome através do terminal.

Expectativa: O Claude não modificará o documento do projeto; ele primeiro apresentará uma listagem de plano, em formato de relatório Markdown de como efetuará os procedimentos (Por exemplo incluir o argparse). O usuário deverá conferir, ou adicionar comentários à linha referente e o mesmo irá atuar perante sua resposta. Chegado aqui, o diff embutido, menção por seleção, e revisão pelo modo plano foram usados em seus núcleos práticos.

---

07 Dica Rápida para Favoritos: Seus atalhos comuns e como "Alternar pro CLI"

Um agrupamento de atalhos comuns (Fontes oficiais, diferenças de sistema operacional observadas):

Ação / Operação	Atalhos / Combinação	Explicação
Alternar O Foco (Editor ↔ Claude)	Cmd+Esc / Ctrl+Esc	Alterna a região ativa dependendo da localização da caixa de digitação/cursor!
Abrir a conversa em Nova Aba	Cmd+Shift+Esc / Ctrl+Shift+Esc	Trabalhar com múltiplas conversas abertas e ativas em paralelo!
Inserção da Citação / Referência @	Option+K / Alt+K	Requer que o editor de código esteja com o foco no modo.
Reabertura da última conversa fechada	Cmd+Shift+T / Ctrl+Shift+T	Está habilitado de fábrica
Iniciar Nova Conversa	Cmd+N / Ctrl+N	Desativado de fábrica; Habilite-o ativando enableNewConversationShortcut nas Opções.

MacOS Tahoe+ possui um erro comum: O sistema da interface 'Game Controller' de "Overlays" capta a tecla de comando padrão do Cmd+Esc. Retire sua ação ao Configurar nas Preferências: Sistema -> Atalhos Teclado -> Ajustes de Game Controllers, para retirar sua caixa ativada, ou então defina o seu atalho Claude Code: Focus input para outras teclas de teclado.

Você quer ter o charme das interfaces antigas baseadas na linha de comando (CLI)? Dê acesso ou inicie seu Terminal Integrado (Comando: Cmd+` ou Ctrl+`) e faça o acionamento em: claude. — O CLI ligará ao VS Code em integração nativa e perfeitamente automática, visualizando com nitidez os Diff (se optar pelo Terminal via janelas externas/separadas aciona com /ide). Ou ligue o setting na configuração Use Terminal (useTerminal) ativando sua largada pelo terminal no modo padrão pela sua extensão.

Operadores trabalhando via serviços 3rd Party: (Modelos da Vertex AI / Bedrock / Foundry): Selecione para ativação as opções da sua extensão para (Inibir e desativar o PopUp por Auth/Login) (disableLoginPrompt) ; O próximo passo o realize nas parametrizações descritas das Documentações fornecidas com base nessas origens, atualizando em .claude/settings.json (Consulte suas descrições na página oficial destas instâncias).

💡 Resumo em uma frase: Focar a troca via Cmd+Esc de maneira frequente; inserir a menção no uso com o atalho Option+K, e se desejar pelo bash, chame pela execução do comando claude ou pela marcação em useTerminal — A extensão gráfica e as operações nos comandos CLI, trocam entre si!

---

08 Resumo

Este artigo trouxe os recursos da CLI do Claude para a extensão (GUI) do VS Code. Baseado nas seguintes vertentes:

• As integrações (A Extensão) Não é a substituta direta ou eliminatória do Console/CLI: O mecanismo, o sistema principal e compartilhamentos de configurações e memória estão sendo o mesmo da CLI original! Usaremos o modelo das UI de interface durante as tarefas operacionais de "Código", e trocaremos ao Terminal e Consoles caso funções exclusivas do ambiente nativo da CLI requeiram de tais!
• Sua Primeira Fase na Instalação é descobrir se O ícone está onde e como (O Spark): Identifique ser a publicação de Origem Anthropic. O fato sobre O "Ícone Faísca (Spark)" é as suas aparições estarem atreladas às aberturas apenas ocorrendo na exata hora com Arquivo também estando aberto, O modo onde as ausências apareçam, atente à ir via pela barrar lateral inferior direito de sua base na barra Status.
• As Três vantagens gráficas via as janelas UI de Interação (Interface): Pela tela de Side-By-Side (Visão de Diffs); Onde podes certificar acertos de antemão ou modificar e acenar por lá os erros (Inline); Os Comandos de Chamadas (Mentions @) / Além a exatidões nas áreas ou escopos selecionadas via (Snippets Selects); A sua planificação em Modo Revisar os Planos(Visualização para Soluções, e com notas diretamente às linhas na tela do Markdown)!

Ao atingir toda operação nestes fluxos, terá os manuseios via o lado a lado no visual, O ato em abastecer e inserir as posições precisas e contexto e além as planificações ante das Grandes e vastas aplicações / alterações via a Review! Toda rotina e codificação ficarão suportados estavelmente em bases firmes em sua utilização no dia a dia.

---

A próxima documentação foca no 09 Integração ao Ecossistema JetBrains — Se seu trabalho principal e forte forem nas raízes da IntelliJ IDEA, Ou Python/PyCharm e na familia destas linhas e plataformas, existe igualmente os modos nativos em "Plugin Oficial Claude Code". E iremos avaliar na similaridades em como ele é se aproxima / reflete em comparação as Extensões de UI / VS Code e quais detalhes de seu software estarão configurados aos da base exclusivas dos Operadores de JetBrains.

---

Leitura Recomendada

• Modo de Voz (Voice): Falar e ditar os prompts de comando no lugar de digitar
• Navegador da Web e Modelos na Nuvem: Levando e Embutindo O Claude no seu Web Browser ou Telefone e Smartphone
• As Imagens e Modos Multimodais: Basta lançar uma captura/Imagem de tela na Janela e toda compreenção das operações acontecerá!