Ao final deste capítulo, você terá o Claude Code instalado, autenticado e funcionando no seu terminal e, se quiser, dentro do seu editor. Também saberá onde ficam os arquivos de configuração e como resolver os problemas de instalação mais frequentes. Ainda não vamos conversar com a ferramenta nem aprender comandos; o objetivo aqui é chegar à primeira execução bem-sucedida.
Pré-requisitos
O Claude Code é uma ferramenta de linha de comando distribuída como um pacote do Node.js. Por isso, a primeira exigência é ter o Node.js na versão dezoito ou superior. Para conferir, abra o terminal e digite node seguido de traço traço version. Se o número exibido começar com dezoito ou mais, você está pronto. Se for menor, ou se o comando não existir, instale uma versão recente. A forma mais prática é usar um gerenciador de versões como o nvm, que permite instalar e alternar versões do Node sem privilégios de administrador.
Quanto ao sistema operacional, macOS e Linux funcionam nativamente. No Windows, o caminho recomendado é o WSL, sigla para Windows Subsystem for Linux, que executa uma distribuição Linux dentro do Windows. Instale o WSL pela loja da Microsoft ou com o comando wsl traço traço install em um PowerShell como administrador, escolha uma distribuição como o Ubuntu e faça toda a instalação do Node e do Claude Code dentro dela. Existe suporte nativo ao Windows por meio do Git para Windows, mas o WSL continua sendo a experiência mais estável e é a que usaremos neste livro.
Você também precisa de uma conta. Há duas opções, e falaremos da diferença entre elas daqui a pouco: uma assinatura do Claude, nos planos Pro ou Max, ou uma conta na Anthropic Console com faturamento configurado para uso de API.
Instalação via npm
Com o Node pronto, a instalação é um único comando:
- Ouça o áudio com a tela desligada
- Ganhe Certificado após a conclusão
- + de 5000 cursos para você explorar!
Baixar o aplicativo
npm install -g @anthropic-ai/claude-codeLendo em voz alta: npm install, a opção g de global, e o nome do pacote, que é arroba anthropic traço ai barra claude traço code. A opção global faz o comando claude ficar disponível em qualquer pasta. Um aviso importante: não use sudo na frente desse comando. Instalar pacotes globais como administrador causa problemas de permissão depois, e veremos como corrigir isso na seção de erros. Se você usa nvm, não precisará de sudo em nenhum momento.
A Anthropic também oferece um instalador nativo, que não depende do Node e é executado com um script baixado via curl. Se optar por ele, copie o endereço apenas da documentação oficial da Anthropic e, de preferência, baixe o script em um arquivo e leia o conteúdo antes de executá-lo: encadear curl direto no shell roda código de terceiros com as suas permissões de usuário. Ele é uma alternativa válida, mas neste livro seguiremos com o npm, por ser o caminho mais conhecido por desenvolvedores.
Autenticação: assinatura ou chave de API
Entre na pasta de qualquer projeto seu e digite apenas claude. Na primeira execução, a ferramenta pergunta como você quer entrar e abre o navegador para concluir o login. Existem dois caminhos.
O primeiro é entrar com a conta do Claude, a mesma usada no aplicativo e no site. Nesse caso, o uso do Claude Code é coberto pela sua assinatura Pro ou Max. Você paga um valor fixo por mês e tem limites de uso que se renovam em janelas de poucas horas, normalmente cinco, somados a limites semanais. Vale lembrar que os planos diferem também nos modelos disponíveis: o Pro costuma liberar apenas os modelos Sonnet, enquanto o Max amplia os limites e dá acesso aos modelos maiores. Como esses valores mudam com frequência, confirme os limites e os modelos do seu plano na página oficial de preços antes de decidir. É o caminho mais simples e previsível para quem está começando.
O segundo é entrar com a Anthropic Console, a plataforma para desenvolvedores. Aqui a cobrança é por consumo: cada sessão gera custo em função da quantidade de texto enviado e recebido, e você precisa ter créditos ou um cartão cadastrado. Esse caminho serve para times, para automações e para quem já usa a API em outros produtos. Você também pode definir a variável de ambiente ANTHROPIC_API_KEY com uma chave de API; na primeira vez o Claude Code mostra a chave detectada e pede sua confirmação para usá-la, em vez de abrir o navegador. Trate essa chave como uma senha: nunca a coloque em arquivos versionados no Git nem em capturas de tela, e revogue-a na Console se suspeitar de vazamento.
Na prática, a diferença é esta: assinatura tem custo fixo e limite de uso; chave de API tem custo variável e sem teto além do que você configurar na Console. Por isso, se escolher a chave de API, defina antes um limite de gasto mensal e alertas de cobrança na Console, porque uma sessão longa em um projeto grande pode consumir bem mais do que você espera. Se mudar de ideia depois, o comando barra login dentro de uma sessão permite trocar de conta.
Verificando, atualizando e desinstalando
Para confirmar que tudo está no lugar, execute claude traço traço version. Deve aparecer o número da versão instalada. Um comando ainda mais útil é claude doctor, que verifica o método de instalação, a versão do Node, o caminho do executável e avisa se algo está errado.
O Claude Code se atualiza sozinho em segundo plano na maioria dos casos. Se quiser forçar, use claude update ou repita o comando de instalação do npm, que sobrescreve a versão anterior. Para desinstalar, execute npm uninstall com a opção g e o nome do pacote. Se quiser apagar também o histórico e as configurações pessoais, remova a pasta ponto claude e o arquivo ponto claude ponto json que ficam na sua pasta de usuário. Atenção: essa remoção é definitiva e leva embora todo o histórico de conversas e as credenciais salvas, então faça uma cópia de segurança dessas duas coisas antes, caso pretenda reinstalar depois.
Integração com VS Code e JetBrains
O terminal é suficiente para tudo o que faremos no livro, mas as extensões para editores adicionam conforto. No Visual Studio Code, procure por Claude Code no marketplace de extensões e instale. Há um atalho: se você abrir o terminal integrado do VS Code e executar claude, a extensão é instalada automaticamente. O mesmo vale para editores derivados, como Cursor e Windsurf.
O que a extensão acrescenta em relação ao terminal puro: as alterações propostas aparecem como diff visual dentro do editor, em vez de texto colorido no terminal; o trecho de código selecionado é enviado como contexto para a conversa; um atalho de teclado, Command mais Escape no Mac ou Control mais Escape no Windows e Linux, abre o Claude Code sem sair do editor; e os arquivos abertos são referenciados com número de linha. As versões mais recentes também oferecem um painel gráfico de conversa ao lado do código.
Nas IDEs da JetBrains, como IntelliJ IDEA, PyCharm, WebStorm e GoLand, o processo é semelhante: abra as configurações, vá em Plugins, busque por Claude Code e instale. Será preciso reiniciar a IDE. Os recursos são os mesmos: diff no editor, seleção como contexto e atalho de teclado. Uma observação para usuários de WSL: a IDE roda no Windows enquanto o Claude Code roda no Linux, então configure a IDE para usar o terminal do WSL, ou a integração não encontrará o executável.
Onde ficam as configurações
Você não precisa editar nada agora, mas vale saber onde as coisas moram. Há dois níveis principais. O nível do usuário fica na pasta ponto claude, dentro da sua pasta pessoal. Ali está o arquivo settings ponto json com preferências que valem para todos os projetos, além do histórico de sessões e de outros dados da ferramenta.
O nível do projeto fica em uma pasta ponto claude na raiz do repositório. Dentro dela, o arquivo settings ponto json guarda configurações compartilhadas com o time, e por isso costuma ser versionado no Git. Existe ainda um settings ponto local ponto json para ajustes só seus, que o Claude Code adiciona automaticamente ao gitignore. Essa mesma pasta abrigará, mais adiante, comandos personalizados e agentes.
Além disso, na raiz do projeto costuma existir um arquivo chamado CLAUDE ponto md, com instruções que a ferramenta lê ao iniciar. O que colocar nesses arquivos, como funcionam as permissões e como organizar o contexto são assuntos dos capítulos cinco e seis. Por enquanto, basta reconhecer esses nomes quando aparecerem.
Resolvendo os erros mais comuns
- Erro de permissão ao instalar, com a sigla EACCES. Acontece quando o npm tenta escrever em uma pasta do sistema. Não resolva com sudo. Em vez disso, instale o Node via nvm, ou configure o npm para usar uma pasta dentro do seu diretório pessoal com o comando npm config set prefix apontando para algo como til barra ponto npm traço global, e adicione a subpasta bin ao seu PATH.
- Comando claude não encontrado. A instalação funcionou, mas a pasta de binários globais do npm não está no PATH. Execute npm config get prefix, adicione o caminho retornado seguido de barra bin ao arquivo de inicialização do seu shell e reabra o terminal.
- Versão do Node antiga. A mensagem costuma citar sintaxe não suportada ou exigir a versão dezoito. Instale uma versão recente com nvm e confirme com node traço traço version.
- No WSL, o npm aponta para o Node do Windows. Se o comando which npm retornar um caminho começando com barra mnt barra c, você está usando o Node instalado no Windows a partir do Linux, o que gera erros estranhos. Instale o Node dentro da distribuição Linux com nvm e confira novamente.
- O navegador não abre no login. Comum no WSL e em servidores remotos. O terminal exibe um link; copie e cole no navegador do Windows ou de outra máquina, conclua o login e volte ao terminal.
- Falha de rede em ambiente corporativo. Proxies e firewalls podem bloquear a conexão com a API. Configure as variáveis HTTPS_PROXY e HTTP_PROXY, ou peça ao time de infraestrutura para liberar o domínio da Anthropic.
Quando nada disso resolver, claude doctor é o primeiro diagnóstico, e a saída dele é o que você deve levar para a documentação oficial ou para um colega.
Recapitulando
Neste capítulo você instalou o Node.js na versão dezoito ou superior, preparou o WSL se estiver no Windows, instalou o Claude Code com npm sem usar sudo e fez o login escolhendo entre assinatura, com custo fixo, e chave de API, com custo por consumo. Aprendeu a verificar a instalação com claude doctor, a atualizar e a desinstalar, a adicionar a extensão ao VS Code e às IDEs JetBrains, e a reconhecer a pasta ponto claude e os arquivos settings ponto json e CLAUDE ponto md. Por fim, viu como resolver os erros de permissão, PATH, versão do Node e WSL mais frequentes. Seu ambiente está pronto para uso.
