Usando o Claude Code no VS Code: configuração, atalhos e dicas (2026)

reverificado com a documentação oficial em code.claude.com/docs/en/vs-code (acesso em 10/08/2026).

Esclarecimento rápido: o que significa 'claude code vs code'?

Se você digitou 'claude code vs code' esperando uma comparação direta contra outra ferramenta, veio à página errada. Aqui 'vs code' = Visual Studio Code, então a pergunta de verdade é como usar o Claude Code integrado dentro do VS Code - e não um confronto. (Procurando mesmo por uma comparação? Comece por o que é o Claude Code para dominar o básico primeiro.)

Mais uma confusão comum: este artigo é sobre a extensão oficial 'Claude Code' (publisher anthropic.claude-code, ícone Spark ✱, com diff/plan/checkpoint), não a antiga extensão de chat na barra lateral 'Claude AI' que muitos guias mostram. São produtos completamente diferentes. A extensão oficial entende todo o seu workspace, edita vários arquivos de uma vez e devolve um diff para você revisar; as extensões de chat mais antigas são, na maior parte, uma caixinha de perguntas e respostas ao lado do código. Se um guia nunca menciona o ícone Spark, o diff review ou o plan mode, quase certamente está falando de outro produto.

O que você precisa primeiro (requisitos)

Antes de instalar, confira três coisas para não perder tempo:

• Uma versão recente do VS Code - a documentação oficial indica a versão >= 1.94.0. Verifique em Help -> About e atualize antes se a sua for muito antiga.
• Um plano Claude pago: Pro, Max, Team ou Enterprise (ou acesso pelo Claude Console). Esse é um requisito obrigatório.
• Sem chave de API, sem versão gratuita. A extensão faz login com a sua conta Claude, em vez de uma chave colada como em algumas outras ferramentas. Se você ainda não tem um plano, não vai conseguir usá-la - essa é uma diferença real em relação a algumas extensões de IA de terceiros que deixam você plugar a sua própria chave de API.

Vou ser sincera sobre a limitação: como depende de um plano pago, essa não é a opção para quem espera usar de graça. O lado bom é que você nunca administra cotas de API nem toma um susto com uma conta de tokens - o uso fica dentro da sua assinatura. Se estiver em dúvida entre os planos, escolha pela frequência de uso: o Pro dá e sobra para experimentar ou aprender, enquanto o Max compensa o preço se você fica na ferramenta o dia todo.

Ainda não sabe bem o que é o Claude Code ou até onde ele vai? Leia a introdução ao Claude Code e depois volte aqui para instalar a extensão.

Como instalar a extensão Claude Code para o VS Code (passo a passo)

A coisa toda leva cerca de dois minutos. Quatro passos:

1. Abra a aba de extensões com Ctrl+Shift+X (Windows/Linux) ou Cmd+Shift+X (macOS). Digite 'Claude Code' na busca, escolha a extensão do publisher Anthropic (não confunda com as outras extensões 'Claude AI') e clique em Install.
2. Abra o painel do Claude Code clicando no ícone Spark ✱. Ele aparece na barra de ferramentas do editor (canto superior direito com um arquivo aberto), na Activity Bar à esquerda ou na barra de status embaixo. Dica: você precisa de pelo menos um arquivo aberto para o ícone aparecer com clareza.
3. Faça login: clique em Sign in e o VS Code abre o navegador para autenticar com a sua conta Claude. Volte ao VS Code e o painel está pronto.
4. Envie um prompt de teste: tente algo simples como 'explique o que este arquivo faz' para confirmar que tudo funciona. Se o Claude responder e reconhecer o arquivo aberto, a instalação está boa.

Um hábito que vale começar já: depois de instalar, abra a pasta do projeto de verdade (não um arquivo solto) para o Claude enxergar todo o contexto do workspace. No Windows, se você trabalha com WSL, abra o projeto no modo WSL do VS Code como de costume e então chame o painel - a extensão roda tranquilamente nesse ambiente.

Essa extensão não se limita ao VS Code puro - ela também instala em Cursor, Kiro e builds baseados no Open VSX, com os mesmos passos. Se você também quer o comando claude no terminal, veja o guia completo de instalação do Claude Code CLI (a extensão e a CLI se complementam, mais sobre isso abaixo).

A interface e os recursos principais dentro do VS Code

Comparada a digitar comandos no terminal, a extensão oferece uma interface bem mais visual. Aqui estão os recursos que valem a pena:

• Diff review lado a lado: sempre que o Claude edita um arquivo, a mudança aparece como um diff lado a lado, em verde e vermelho bem nítidos. Você revisa uma mudança por vez, aceita ou rejeita cada uma individualmente e pode até editar direto no diff antes de aceitar. É um mundo de diferença em relação a colar código de um chat e mesclar na mão - você sempre vê exatamente o que está prestes a mudar e pode bloquear linha por linha. Esse é o motivo mais forte para trabalhar no VS Code.
• Plan mode: no plan mode, o Claude abre um plano em Markdown para você ler e comentar inline antes de ele tocar em qualquer código. Cai muito bem em tarefas grandes: você revisa a direção, ajusta alguns pontos do plano e só então deixa rodar - chega de assistir a IA avançar em uma dúzia de arquivos de uma vez. Para se aprofundar no fluxo de planejamento, veja os 10 primeiros passos para iniciantes.
• @-mention para adicionar contexto a um prompt: @file#5-10 (só as linhas 5-10), @folder/ (uma pasta inteira), @terminal:name (puxa a saída do terminal) e @browser (controla o Chrome). Em vez de copiar e colar, você aponta o Claude direto para o que ele precisa ver. Ao depurar, por exemplo, @file#40-72 mantém o Claude exatamente na função quebrada, em vez de ler um arquivo de mil linhas - mais preciso e mais econômico em tokens.
• Checkpoint / Rewind: reverte as mudanças de arquivo para um estado anterior se o Claude for pelo caminho errado - uma rede de segurança, para você não depender só de git stash ou do Ctrl+Z passo a passo.
• Histórico de sessões + várias abas: rode várias sessões em paralelo e volte a conversas antigas, prático quando você está fazendo malabarismo com vários fios - uma aba no meio de um refactor, outra para uma pergunta rápida de API.
• Permission mode: ali mesmo na caixa de prompt, escolha Manual (aprovar cada ação na mão), Plan (só planejar) ou editar automaticamente. Mantenha cauteloso num repositório desconhecido e afrouxe quando ganhar confiança. Você pode definir um padrão de largada pelo initialPermissionMode nas configurações.

Atalhos de teclado do Claude Code no VS Code

Aqui está a tabela completa de atalhos (da documentação oficial) que a maioria dos guias deixa de fora:

Esqueceu algum? Abra a Command Palette (Ctrl/Cmd+Shift+P) e digite 'Claude Code' para ver todos os comandos. Para um resumo que dá para imprimir, veja o cheat sheet do Claude Code.

Dicas para aproveitar ao máximo o Claude Code no VS Code

Qualquer um consegue instalar, mas rodar com fluidez pede alguns truques. Estes são os que eu uso todo dia:

• Mova o painel para a barra lateral secundária: assim o Claude fica ao lado do código em vez de cobrir o editor. É só arrastar o ícone Spark para a borda direita - ver o diff e o código ao mesmo tempo fica bem mais fácil.
• Escreva um CLAUDE.md como a sua 'memória do projeto': esse é o maior ganho de qualidade de todos. Coloque convenções, stack e comandos de teste nesse arquivo para o Claude não ter que adivinhar. Veja como escrever um CLAUDE.md sólido.
• Use @terminal em vez de copiar e colar erros: rode o comando que falhou no terminal integrado e o @terminal joga a saída inteira no seu prompt - mais rápido e com mais contexto do que colar na mão.
• Alterne o useTerminal: se você prefere uma pegada de CLI, ligue isso nas configurações; se quer uma GUI pura, desligue.
• Considere autosave e respectGitIgnore: para manter os diffs limpos e evitar que o Claude leia lixo ou arquivos sensíveis por acidente.
• Acompanhe o seu custo: digite /usage para checar o consumo e /compact para comprimir o contexto quando um chat lota - isso mantém o Claude focado e economiza tokens.
• Mantenha uma statusline arrumada: personalize para ver o modelo atual e o custo num relance - veja o guia de personalização da statusline.

Um hábito que vale construir: antes de passar uma tarefa grande, gaste 30 segundos deixando claro o objetivo e as restrições no prompt (ou guarde no CLAUDE.md) e então ligue o plan mode para revisar a direção antes de deixar editar. Custa um tempinho extra, mas reduz bastante a frequência com que o Claude se desvia do alvo, poupando rewinds. Num repositório grande, combine com @folder/ para o módulo em que você está trabalhando, em vez de jogar o projeto inteiro nele - o Claude mantém o foco, a saída sai mais limpa e custa menos tokens.

Extensão vs CLI - qual usar?

Uma pergunta comum: depois de ter a extensão, você ainda precisa da CLI? Comparação rápida:

Observação importante: a extensão não adiciona o comando claude ao seu PATH, então, para digitar claude no terminal integrado, você precisa instalar a CLI standalone à parte. Conselho prático: use as duas - a GUI para revisar diffs e planos, a CLI para ações rápidas - e elas compartilham o mesmo histórico, então dá para fazer claude --resume e retomar uma sessão. Os detalhes completos de instalação da CLI estão no guia completo de instalação do Claude Code.

Problemas comuns e como resolver

Alguns problemas frequentes e soluções rápidas:

• Cmd+Esc não funciona no macOS Tahoe: esse atalho costuma ser capturado pelo Game Overlay. Vá em System Settings -> Keyboard -> Keyboard Shortcuts -> Game Controllers e desmarque o item que o está usando, ou remapeie o Claude Code: Focus input para outra combinação nos atalhos de teclado do VS Code.
• Sem ícone Spark ✱: confira na ordem - você tem pelo menos um arquivo aberto? O VS Code está >= 1.94.0? Tente Reload Window (Command Palette), desative temporariamente outras extensões de IA em conflito e habilite o workspace trust para a pasta do projeto.
• 'Please run /login': tente Reload Window, ou feche o VS Code e reabra o projeto com code . pelo terminal para ele pegar a sessão logada certa.
• O Claude não responde: confira sua rede, abra uma nova sessão ou teste a CLI para isolar se o problema é da extensão ou da sua conta. Se o chat ficou muito longo, digite /compact para comprimir o contexto e tente de novo.
• Os diffs não aparecem ou se aplicam no lugar errado: confirme que o arquivo está salvo e não está sendo sobrescrito por outra extensão (um formatador rodando ao salvar). Use um autosave controlado e desative temporariamente o format-on-save enquanto revisa um diff grande.

Esbarrou em algo que não está nesta lista? Veja o apanhado de erros comuns do Claude Code e como corrigi-los.

Suba de nível com skills e subagents prontos

A extensão fica muito mais forte quando o seu Claude Code já tem um conjunto de skills, subagents e workflows, em vez de você montar tudo do zero. Se quer andar rápido, uma opção é o kit AgentKit para o Claude Code - um conjunto empacotado de skills e agents para trabalho de dev e marketing; você pode experimentar o AgentKit (20% de desconto pelo link) para ver se ele encaixa no seu fluxo. Não é obrigatório: a extensão de fábrica já basta sozinha, e um kit é só um jeito opcional de ir mais rápido.

Perguntas frequentes (FAQ)

O Claude Code no VS Code é gratuito?

Não. A extensão instala de graça, mas para usá-la você precisa de um plano Claude pago (Pro, Max, Team ou Enterprise) ou acesso pelo Claude Console. Não há versão gratuita e você não pode usá-la com uma chave de API.

Preciso de um plano Pro?

Você precisa de pelo menos um plano pago; o Pro é o nível mais baixo que serve para uma pessoa. O Max combina com uso intenso, enquanto Team e Enterprise são para grupos.

Qual a diferença para a extensão 'Claude AI', o Cline ou o Continue?

A extensão 'Claude Code' é o build oficial da Anthropic (publisher anthropic.claude-code), com diff review, plan mode, checkpoints e @-mention ligados à sua conta Claude. Extensões como o antigo chat 'Claude AI', o Cline e o Continue são produtos diferentes, que funcionam e se sentem de outro jeito.

Dá para usar no Cursor?

Sim. A extensão Claude Code instala no Cursor, no Kiro e em editores baseados no Open VSX, com os mesmos passos do VS Code.

Preciso instalar a CLI separadamente?

Não necessariamente. A extensão já traz uma CLI para o painel. Você só precisa da CLI standalone se quiser digitar o comando claude no terminal integrado, já que a extensão não adiciona o claude ao seu PATH.

Funciona no Windows/WSL?

Sim. A extensão roda no Windows, macOS e Linux; para WSL, abra o projeto no modo WSL do VS Code como de costume e então use o painel do Claude Code.

Conclusão e próximos passos

É isso: o Claude Code rodando bem dentro do VS Code - instale a extensão oficial, faça login com um plano pago e apoie-se no diff/plan/checkpoint, no @-mention e nos atalhos para codar mais rápido. Próximo passo: se você está só começando, leia os 10 primeiros passos para iniciantes; se também quer a linha de comando, veja o guia completo de instalação do Claude Code CLI. Bom código!