Come configurare Claude Code su Mac, Windows e Linux

In breve: Per installare Claude Code ti servono tre cose: Node.js 18 o superiore, un account Anthropic e un terminale. Su Mac e Linux funziona subito. Su Windows serve WSL2. Si installa con un singolo comando:

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

Poi entri nella cartella del progetto, digiti claude, autentichi il tuo account e sei operativo. In questa guida trovi ogni passaggio nel dettaglio, i problemi più comuni e come li risolvi.

Ho scritto un articolo completo su cos'è Claude Code e perché vale la pena usarlo. Se non lo hai ancora letto, ti consiglio di partire da lì per capire il contesto. Questo articolo è la parte pratica: il come. Niente teoria, solo i passaggi per andare da zero a operativo nel tempo di un caffè.

Configurare Claude Code è più semplice di quanto sembri, ma ci sono un paio di dettagli che possono farti perdere mezz'ora se non li conosci. Li ho scoperti sulla mia pelle e te li risparmio.

Cosa serve prima di iniziare?

Tre prerequisiti. Nessuno è complicato, ma se ne manca uno non parti.

Node.js 18 o superiore. Claude Code si installa tramite npm, il gestore di pacchetti di Node.js. Se non hai Node.js installato, vai su nodejs.org e scarica la versione LTS. Se lo hai già, verifica la versione:

node --version

Se il numero che esce inizia con 18, 20, 22 o superiore, sei a posto. Se è inferiore a 18, devi aggiornare. Il modo più pulito per gestire le versioni di Node.js è usare nvm (Node Version Manager), che ti permette di installare e alternare tra versioni diverse senza conflitti. Ma se vuoi fare in fretta, basta scaricare l'ultima LTS dal sito ufficiale e installarla sopra quella vecchia.

Un account Anthropic. Ti serve per autenticarti la prima volta che lanci Claude Code. Puoi crearlo gratuitamente su anthropic.com. Il piano gratuito ha limiti stretti ma è sufficiente per completare la configurazione e fare le prime prove. Per lavorarci seriamente ti consiglio Claude Pro a 20 dollari al mese, ma per oggi basta l'account.

Un terminale. Su Mac hai Terminal o iTerm2. Su Linux hai il terminale del tuo desktop environment. Su Windows la situazione è un po' diversa e ne parliamo tra poco. Il punto è che Claude Code vive nel terminale: non è un'app con un'interfaccia grafica, non è un'estensione di VS Code (anche se esiste pure quella). È un programma da riga di comando, e per usarlo devi avere confidenza minima con il terminale. Se sai fare cd per spostarti tra cartelle e ls per vedere i file, hai tutto quello che ti serve.

Come si installa Claude Code?

Un comando. Non sto scherzando, è davvero un comando solo:

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

Il flag -g lo installa globalmente, così puoi lanciarlo da qualsiasi cartella del tuo sistema. L'installazione dura una manciata di secondi.

Mac e Linux

Su Mac e Linux non c'è praticamente nulla da configurare. Apri il terminale, lanci il comando di installazione e funziona. Se incontri errori di permessi su Mac con il comando npm globale, hai due opzioni: mettere sudo davanti al comando (la via veloce) oppure configurare nvm per gestire Node.js senza permessi di root (la via pulita). Ti consiglio la seconda se pensi di lavorare con Node.js regolarmente.

Windows

Su Windows la situazione è diversa. Claude Code non gira nativamente su Windows: serve WSL2, il Windows Subsystem for Linux. È il sottosistema che ti permette di eseguire un ambiente Linux completo dentro Windows, ed è il modo in cui qualsiasi sviluppatore serio lavora su Windows nel 2026.

Se non hai WSL2, aprilo PowerShell come amministratore e lancia:

wsl --install

Questo installa WSL2 con Ubuntu come distribuzione predefinita. Dopo il riavvio del PC, apri Ubuntu dal menu Start, crea il tuo utente Linux e da lì installi Node.js e Claude Code esattamente come faresti su una macchina Linux nativa. Tutto il resto della guida vale identicamente: una volta dentro WSL2, sei su Linux a tutti gli effetti.

Un consiglio per chi è su Windows: usa Windows Terminal (lo trovi nel Microsoft Store, gratuito) come app per il terminale. Ti permette di avere tab multiple con WSL, PowerShell e CMD nella stessa finestra, e l'esperienza è enormemente migliore del terminale predefinito.

Il primo avvio

Installato Claude Code, spostati nella cartella del progetto su cui vuoi lavorare e lancia claude:

cd il-tuo-progetto
claude

La prima volta succedono due cose. Prima ti chiede di autenticarti: si apre il browser, fai login con il tuo account Anthropic, autorizzi l'accesso e torni al terminale. Tutta la procedura dura trenta secondi e non dovrai ripeterla.

Poi Claude Code scansiona il progetto. Legge la struttura delle cartelle, i file di configurazione, il package.json se è un progetto Node, il README.md se esiste. Si costruisce un contesto del tuo codebase. Non manda tutti i file al cloud: legge la struttura locale e carica nel contesto solo quello che serve per rispondere alle tue richieste.

Da questo momento sei in una conversazione. Scrivi quello che vuoi fare in linguaggio naturale e Claude Code agisce. Ma prima di agire sui file, ti chiede il permesso. Vedi una schermata che dice qualcosa come "Vorrei modificare il file X, creare il file Y ed eseguire il comando Z. Approvi?". Questo sistema di permessi è importante: significa che l'agente non tocca nulla senza il tuo consenso esplicito. Col tempo puoi configurare le regole per approvare automaticamente certe azioni, ma all'inizio il default prudente è quello giusto.

Come configuro il mio ambiente?

Qui è dove la configurazione di Claude Code diventa personale. Ci sono tre file che fanno la differenza tra un'esperienza generica e un ambiente ottimizzato per il tuo modo di lavorare.

Il file CLAUDE.md. Lo metti nella root del progetto e contiene le istruzioni di contesto per Claude Code. Pensa a un briefing: "Questo è un progetto Next.js con TypeScript, usa Tailwind per il CSS, i componenti sono in /components, le API in /app/api. Quando crei nuovi componenti segui il pattern degli esistenti." Claude Code legge questo file a ogni avvio e lo usa come base per tutte le decisioni. È la singola cosa che migliora di più la qualità delle risposte, perché trasforma l'agente da generico a specializzato sul tuo progetto. Io ne ho uno in ogni progetto su cui lavoro.

Il file .claude/settings.json. Contiene le preferenze di Claude Code per quel progetto: quali comandi può eseguire senza chiedere permesso, quali cartelle ignorare, impostazioni specifiche. Si crea automaticamente la prima volta che approvi un'azione con l'opzione "sempre per questo progetto", ma puoi anche editarlo a mano se preferisci avere il controllo totale.

Le custom skills. Sono istruzioni riutilizzabili che puoi creare nella cartella .claude/skills/ del progetto. Io le uso per operazioni che ripeto spesso: creare un nuovo articolo per il blog con la struttura giusta, generare un componente React che segue le convenzioni del progetto, preparare una pull request con il formato che voglio. Sono file markdown che descrivono il compito, e Claude Code li legge quando li invochi. Se c'è qualcosa che fai più di tre volte, fanne una skill.

I problemi più comuni

Ho configurato Claude Code su diverse macchine e ho aiutato altre persone a farlo. Questi sono i problemi che escono più spesso.

Versione di Node.js troppo vecchia. Il sintomo è un errore criptico durante l'installazione o al primo avvio. La soluzione è aggiornare Node.js alla versione 18 o superiore. Controlla con node --version e se sei sotto, aggiorna.

Errori di permessi npm su Mac. Quando lanci npm install -g e ottieni un errore "EACCES permission denied", significa che npm non ha i permessi per scrivere nella cartella globale. La soluzione rapida è usare sudo, quella corretta è installare nvm e reinstallare Node.js attraverso di esso. Con nvm non avrai mai più problemi di permessi.

WSL non configurato su Windows. Se lanci Claude Code dal prompt di Windows (CMD o PowerShell) non funzionerà. Devi essere dentro una sessione WSL. Installa WSL2, apri Ubuntu e lavora da lì. Tutto il tuo workflow di sviluppo ne beneficerà, non solo Claude Code.

Problemi di autenticazione. Se il browser non si apre automaticamente durante il login, Claude Code ti mostra un URL da copiare e incollare manualmente. Se l'autenticazione fallisce, verifica di avere un account Anthropic attivo e che il browser non blocchi i popup. In casi rari, firewall aziendali o VPN possono interferire: prova disattivandoli temporaneamente. Trovi dettagli aggiuntivi nella documentazione ufficiale di Claude Code.

Se hai seguito tutti i passaggi, a questo punto hai Claude Code installato, configurato e pronto per lavorare. Il passo successivo è usarlo su un progetto reale, e lì la differenza la fa la pratica. Il mio consiglio è partire con richieste semplici e specifiche: "aggiungi un bottone qui", "correggi questo errore", "scrivi un test per questa funzione". Man mano che capisci come ragiona, puoi dargli compiti più ampi e ambiziosi. Trovi altri articoli su Claude Code e sugli strumenti AI nel blog.