Instalei o Claude Code pelo npm e agora? O que acontece no primeiro comando

O tutorial de instalação sempre acaba no mesmo lugar: o npm install termina, aparece o cursor piscando e acabou o post

Aí você roda o agente pela primeira vez e ele começa a te perguntar coisa antes de escrever uma linha de código

Este post pega exatamente esse pedaço que fica de fora: o que aparece na tela da primeira sessão, do prompt de login até a pergunta de confiança da pasta, e como saber que a instalação ficou realmente de pé

Só com o que a documentação oficial confirma, sem passo chutado 🙂

Antes de abrir o agente: o que precisa estar de pé

Antes de rodar qualquer coisa, vale conferir se a máquina bate com os requisitos oficiais

Nada de PC da Nasa aqui, a régua é baixa:

• macOS 10.15+, Ubuntu 20.04+/Debian 10+ ou Windows 10+ (no Windows, com WSL 1, WSL 2 ou Git for Windows)
• 4GB+ de RAM
• Node.js 18+ (tem uma ressalva do pacote npm aqui, já te conto)
• conexão com a internet
• shell Bash, Zsh, PowerShell ou CMD

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

E a ressalva do Node, pra não te pegar de surpresa no meio do install: a partir da versão 2.1.198, o pacote npm exige Node.js 22 ou superior

Só que em Node mais antigo o npm apenas imprime o aviso EBADENGINE e a instalação conclui do mesmo jeito, porque o pacote baixa um binário nativo que não usa o Node em tempo de execução

Ou seja: o requisito de sistema do Claude Code continua sendo Node.js 18+, e o 22+ é exigência declarada pelo pacote npm, que na prática não trava a instalação

A instalação via npm cobre estas plataformas: darwin-arm64, darwin-x64, linux-x64, linux-arm64, linux-x64-musl, linux-arm64-musl, win32-x64 e win32-arm64

Se você ainda não passou por essa parte, o caminho de instalar o Claude Code pelo npm está detalhado em outro post aqui do blog

E tem um requisito que não é de máquina, é de conta: o login aceita assinatura Claude Pro ou Max (conta Claude.ai), Claude for Teams ou Enterprise (conta Claude.ai convidada pelo admin) ou credenciais do Claude Console

Se você não tem nenhuma dessas na mão, o agente para no login e não passa dali, beleza?

Passo a passo da primeira sessão do Claude Code

A sequência abaixo é a ordem real das telas na primeira vez que tu abre o agente dentro de uma pasta

Cada passo vem com o tropeço mais comum, porque a maioria dos perrengues acontece por pressa, não por bug

1. Confirme que a instalação existe

O comando de instalação global via npm é este:

npm install -g @anthropic-ai/claude-code

A versão mais recente publicada do pacote no npm hoje é a 2.1.226

O erro comum deste passo: rodar o install de novo achando que resolve tudo, quando o problema real vai aparecer só lá na frente, no login

2. Entre na pasta do projeto e rode o agente

A sessão interativa começa com um comando só, dentro do diretório do projeto:

cd meu-projeto
claude

O erro comum deste passo: rodar claude de qualquer lugar, tipo da home do usuário

O diretório onde tu roda o comando é o diretório de trabalho da sessão, então isso importa MUITO

3. Faça o login

No primeiro uso o Claude Code pede login

Para conta de assinatura Claude ou Console, a autenticação é concluída no navegador

Dois detalhes que pegam gente desprevenida:

• se a variável de ambiente ANTHROPIC_API_KEY estiver definida, ele pula o prompt de login e pede aprovação da chave no lugar
• no primeiro login é criado automaticamente um workspace Claude Code no Console, pra rastreio centralizado de custo

O erro comum deste passo: ter uma ANTHROPIC_API_KEY esquecida no ambiente e não entender por que a tela de login que você viu no tutorial não apareceu

4. Responda ao prompt de confiança da pasta

Ao abrir o Claude Code numa pasta pela primeira vez, ele exibe a pergunta Do you trust the files in this folder?

Por que ele pergunta isso? Porque ele pode ler, escrever ou executar arquivos do diretório onde foi iniciado

A escrita fica confinada à pasta onde você rodou o comando e às subpastas dela

A leitura pode sair desse escopo, ou seja, ele consegue ler arquivos fora do diretório de trabalho, mas não escreve lá

O erro comum deste passo: passar batido no prompt sem olhar em qual pasta você está

Se você respondeu confiando na pasta errada, o escopo de escrita é o da pasta errada 😛

Dá pra listar diretórios confiáveis no arquivo de configuração e, com o diretório listado, ele não pergunta de novo

5. Entenda o modo de permissão padrão

No modo padrão, o Claude pede aprovação antes de cada alteração

É chato no começo e é exatamente o que te salva de um rm -rf da vida rodando sozinho

O atalho Shift+Tab cicla entre os modos

Além do padrão existem o acceptEdits, que aprova automaticamente edições de arquivo (e um conjunto fixo de comandos Bash de sistema de arquivos como mkdir, touch, rm, mv, cp e sed em caminhos do diretório de trabalho), e o plan, em que o Claude propõe mudanças sem editar nada

O erro comum deste passo: aprovar um caminho de arquivo com Yes, don't ask again achando que liberou a pasta inteira

Não liberou

Ao aprovar assim, o Claude Code escapa os caracteres de padrão gitignore daquele caminho e gera uma regra que casa apenas com o caminho literal aprovado

Tome cuidado com essa expectativa, é fonte de confusão fácil

6. Rode o /init

Já dentro da sessão, digita /init e manda ver

Ele gera um arquivo CLAUDE.md na raiz do projeto com as convenções do código, e esse arquivo é lido automaticamente no início de toda sessão

O erro comum deste passo: pular o /init e depois reclamar que o agente não segue o padrão do projeto

O contexto que você não escreve é contexto que ele não tem

Comandos que valem a pena conhecer já na primeira sessão

Digitar / abre a lista completa de comandos

E / seguido de letras filtra a lista, então não precisa decorar nada

Esses aqui resolvem quase tudo no primeiro dia, e todos são digitados DENTRO da sessão:

Guarda esse /doctor aí, porque ele tem um irmão que roda fora da sessão e eu explico a diferença logo abaixo

Se eu tivesse que escolher dois pra rodar logo depois do login, seriam /status e /init

Um te diz que está tudo respondendo, o outro dá contexto pro agente trabalhar melhor

Deu problema na primeira sessão? Sintomas e o que checar

A primeira sessão costuma travar em quatro pontos, e todos têm sintoma bem reconhecível

Aviso EBADENGINE na hora do install:

Como falei lá em cima, a partir da versão 2.1.198 o pacote npm exige Node.js 22 ou superior

Em Node antigo o npm apenas imprime o aviso EBADENGINE e a instalação conclui, porque o pacote baixa um binário nativo que não usa o Node em tempo de execução

Ou seja: aviso amarelo assustador, instalação viva

O login abre o navegador e nunca fecha:

Se o callback em localhost estiver bloqueado (SSH remoto, devcontainer ou firewall restritivo), o fluxo automático não completa

Existe caminho manual: copiar a URL impressa no terminal, fazer login em qualquer navegador e colar o código de volta no terminal

Problema com chave de API:

Três causas comuns:

• a chave foi exportada em outro shell
• o Claude Code ainda não foi instruído a confiar na chave
• a chave é do Console, mas a organização exige login por SSO

Falha de acesso ao modelo:

Pode significar que a conta existe, mas não tem acesso ao modelo requisitado

Em assentos Enterprise, o caminho é confirmar assento ativo nas configurações de admin da organização

/doctor ou claude doctor? A diferença é ONDE tu digita:

O diagnóstico tem duas portas de entrada, e essa é a confusão mais comum de todas

Se a sessão abre normal, o /doctor é comando de barra: tu digita dentro do Claude Code e ele diagnostica problemas de instalação e configuração

Se a sessão nem abre (que é justamente o cenário dos quatro sintomas acima), o de dentro não te serve, e aí vale este:

claude doctor

Esse tu roda no shell normal, fora de uma sessão do Claude

Ele imprime um relatório de diagnóstico que pode ser anexado a um ticket de suporte, o que economiza um vai e volta enorme

Um aviso sobre o npm: a instalação que você acabou de fazer está depreciada

Se liga nisso, porque muda o teu caminho daqui pra frente

A documentação oficial marca a instalação via npm como depreciada e recomenda o instalador nativo:

curl -fsSL https://claude.ai/install.sh | bash

Sem drama: o comando pra iniciar a sessão continua sendo claude, e tudo que está neste post continua valendo do mesmo jeito

A diferença é que o caminho recomendado hoje é o instalador nativo, não o pacote global do npm

Se tu já instalou pelo npm e está funcionando, segue o baile

Mas quando for instalar em outra máquina, já vai pelo recomendado, é o caminho que a documentação aponta …

Próximo passo depois da primeira sessão

A instalação está de pé quando três coisas aconteceram: o login concluiu, o prompt de confiança da pasta foi respondido e o /status responde dentro da sessão

Se esses três bateram, para de mexer, está funcionando 😀

O próximo passo concreto é rodar o /init pra gerar o CLAUDE.md na raiz, porque é ele que dá contexto do projeto em toda sessão nova

E quando a aprovação por ação começar a incomodar (e vai começar), o ajuste é nas permissões: listar diretórios confiáveis nas settings e definir o modo padrão de novas sessões locais em permissions.defaultMode

Depois disso o assunto deixa de ser instalação e vira rotina de trabalho, que é onde o fluxo completo de um projeto começa a fazer sentido

Bora rodar o primeiro claude de verdade?

até o próximo post! =)