Visual Studio Code e OpenCode su macOS

Per Windows c’è una guida a parte.

Quattro programmi lavorano insieme, e si installano in quest’ordine:

• Visual Studio Code, l’editor in cui si scrivono e si leggono i file del progetto
• Git, che tiene traccia delle versioni dei file e permette di tornare indietro
• OpenCode, l’agente di programmazione, che si installa dal terminale
• l’estensione di OpenCode, che apre la chat con l’agente dentro Visual Studio Code

0. Prima di iniziare

I nomi dei menu e dei pulsanti sono quelli dell’interfaccia in italiano. Visual Studio Code però parte in inglese: il capitolo 1 spiega come passare all’italiano, e per i passaggi più importanti il nome inglese è indicato fra parentesi.

I comandi da scrivere nel terminale conviene copiarli e incollarli da questa pagina: basta un carattere sbagliato perché non funzionino.

1. Visual Studio Code

Dal sito code.visualstudio.com il pulsante Download propone già la versione per macOS.

Il file scaricato ha un nome che comincia con “VSCode” e finisce con “.dmg”. Aperto con un doppio clic, mostra una finestra con l’icona di Visual Studio Code e quella della cartella delle applicazioni: l’icona di Visual Studio Code va trascinata su quella di Applications.

Il programma si apre dalla cartella Applicazioni o dal Launchpad, e non dalla finestra del file scaricato: altrimenti gira da un disco in sola lettura e non funziona correttamente. Al primo avvio macOS avverte che l’app è stata scaricata da internet: si risponde Apri.

Visual Studio Code può segnalare in basso a destra “Git non trovato”, con un pulsante Scarica GIT. L’avviso si può chiudere: Git si installa più avanti, in modo più semplice, come spiega il capitolo 4.

La lingua italiana

Al primo avvio Visual Studio Code propone, con una notifica in basso a destra, di installare la lingua italiana: si accetta e si riavvia quando richiesto.

Se la notifica non compare, si apre il pannello Extensions (l’icona con quattro quadrati nella barra a sinistra), si cerca “Italian Language Pack”, si installa quello della Microsoft e si riavvia.

2. La cartella di progetto

Visual Studio Code lavora prevalentemente su una cartella, non su un file singolo. La colonna di sinistra ne mostra il contenuto, il terminale si apre lì dentro e OpenCode legge e modifica i file che contiene. Aprire un file da solo, con un doppio clic, non basta.

Creare la cartella

Con il Finder si crea una cartella per i lavori del corso, per esempio dentro Documenti.

Nel nome conviene evitare spazi, lettere accentate e simboli, che complicano i comandi del terminale e gli indirizzi web: “lavori-corso” va bene, “Lavori Università” no.

Aprirla in Visual Studio Code

Dal menu File › Apri cartella… (File › Open Folder…) si sceglie la cartella e si conferma con Apri. La colonna di sinistra mostra il suo nome e, se presenti, i file che contiene.

Fidarsi della cartella

Una cartella appena aperta parte in Modalità con restrizioni, pensata per esaminare con prudenza il codice scritto da altri: molte estensioni restano disattivate, e quella di OpenCode può non avviarsi. Lo segnalano soltanto una striscia sottile in alto, facile da non notare, che comincia con “La Modalità con restrizioni è destinata all’esplorazione del codice sicuro”, e la scritta Modalità con restrizioni in basso a sinistra.

Per una cartella propria, o ricevuta dal docente, si fa clic su Gestisci (Manage) nella striscia e poi su Considera attendibile (Trust): la scelta resta valida anche le volte successive. Se la striscia è stata chiusa non ricompare, ma la scritta in basso a sinistra resta, e un clic su di essa apre la stessa finestra.

3. Il terminale

Il terminale è una finestra in cui si danno al computer istruzioni scritte, i comandi, invece di usare menu e pulsanti. Ogni comando sta su una riga e parte premendo Invio; il risultato compare sotto, come testo.

In Visual Studio Code si apre dal menu Terminale › Nuovo terminale (Terminal › New Terminal). Compare nella parte bassa della finestra, già posizionato nella cartella di progetto.

Un comando copiato da questa pagina si incolla nel terminale con Cmd+V e parte con Invio.

4. Git

Git tiene traccia delle versioni dei file del progetto e permette di tornare a uno stato precedente.

Su macOS fa parte degli strumenti per sviluppatori da riga di comando di Apple (Command Line Tools), e il modo più semplice per installarli è chiedere a macOS la versione di Git:

git --version

Se Git c’è già, il terminale risponde con un numero di versione, e il capitolo è finito. Se manca, macOS apre una finestra che propone di installare gli strumenti: si sceglie Installa, non Ottieni Xcode, che scaricherebbe un programma molto più grande.

Il pacchetto è grande e contiene più di quanto serve per Git, ma è la strada più diretta. Il pulsante Scarica GIT di Visual Studio Code porta invece al sito di Git, che propone Homebrew o MacPorts: programmi in più da installare, e Homebrew ha comunque bisogno degli stessi strumenti di Apple.

Finita l’installazione, Visual Studio Code va chiuso e riaperto, così si accorge che Git c’è. Il comando git --version ora risponde con un numero.

Il nome per Git

Ogni salvataggio registrato con Git, un commit, porta il nome e l’indirizzo email di chi l’ha fatto. Se non sono stati indicati, Git li ricava dal computer: il nome dall’account del Mac e un indirizzo inventato con il nome del computer. Conviene quindi indicarli, una volta sola. Prima il nome, scrivendo il proprio al posto di “Nome Cognome”:

git config --global user.name "Nome Cognome"

Poi un indirizzo email. Più avanti servirà un account su GitHub, il servizio che pubblica in rete i progetti gestiti con Git: conviene usare l’indirizzo con cui ci si iscriverà, o ci si è già iscritti.

git config --global user.email "nome@esempio.it"

5. OpenCode

Il comando è quello della documentazione della versione 1:

curl -fsSL https://opencode.ai/install | bash

Se alla fine compare l’avviso “No config file found for zsh”, manca il file di configurazione del terminale, “.zshrc”, che sui Mac nuovi non c’è. Senza quel file il terminale non trova OpenCode. Il comando seguente lo crea e lo rilegge:

echo 'export PATH="$HOME/.opencode/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

La guida si riferisce alla versione 1: la versione 2, uscita a fine settembre 2026, ha comandi in parte diversi e un’estensione non ancora stabile.

Questo è OpenCode per il terminale, quello che l’estensione avvia. L’app desktop di OpenCode è l’interfaccia grafica ma, al momento, non offre quello che può offrire Visual Studio Code.

Riavviare e verificare

Dopo l’installazione Visual Studio Code va chiuso e riaperto, e con lui il terminale: solo così il terminale trova il comando nuovo. Poi, in un nuovo terminale, il comando seguente risponde con il numero della versione, che deve cominciare con 1, per esempio “1.18.33”:

opencode --version

Se invece compare “command not found”, le soluzioni sono nel capitolo 7.

Il comando opencode, senza altro, apre l’interfaccia di OpenCode nel terminale, quella dell’immagine all’inizio del capitolo. È la stessa che l’estensione apre come chat, nel capitolo 6, quindi da qui non serve avviarla; se si apre per errore, si chiude con Ctrl+C, premuto due volte se nella casella c’è del testo.

6. L’estensione di OpenCode

Il pannello Estensioni (Extensions) si apre dall’icona con quattro quadrati nella barra a sinistra, oppure con Cmd+Maiusc+X.

Nella casella “Cerca le estensioni nel Marketplace” si scrive “opencode” e si sceglie opencode, pubblicata da SST, con oltre un milione di installazioni: è la prima dell’elenco. Si installa con il pulsante Installa nel pannello aperto a destra.

La chat con l’agente si apre con Cmd+Esc, oppure con la piccola icona di OpenCode che compare in alto a destra nel pannello attivo. Lavora sulla cartella aperta in Visual Studio Code. Al primo avvio OpenCode usa un modello gratuito, e si può scrivere subito una richiesta.

7. Se qualcosa non funziona

Il terminale non trova opencode

Il messaggio è command not found: opencode.

• chiudere e riaprire Visual Studio Code, e aprire un nuovo terminale: il terminale aperto prima dell’installazione non vede il comando nuovo
• se il problema resta, usare il comando che crea “.zshrc” (capitolo 5)

La chat non si apre

Se l’estensione segnala di non trovare OpenCode, per esempio “sulla porta …”, quasi sempre il terminale di Visual Studio Code non trova il programma.

• in un nuovo terminale, controllare che opencode --version risponda con un numero
• se non risponde, seguire le indicazioni qui sopra
• se risponde, chiudere e riaprire Visual Studio Code
• controllare che la cartella non sia in Modalità con restrizioni (capitolo 2)

Le estensioni non compaiono

Se il pannello Estensioni resta vuoto, o segnala un errore di rete, la causa può essere la data o l’ora del computer, quando sono diverse da quelle reali: i collegamenti sicuri con il Marketplace le controllano e rifiutano la connessione. Lo stesso problema può bloccare anche i comandi di installazione.

Si rimedia in Impostazioni di Sistema › Generali › Data e ora, attivando l’impostazione automatica di data e ora, e poi riaprendo Visual Studio Code.

È stata installata la versione 2

Se opencode --version risponde con un numero che comincia con 2, si reinstalla la versione 1 indicandola nel comando:

curl -fsSL https://opencode.ai/install | bash -s -- --version 1.18.33

Visual Studio Code non completa alcune operazioni

Se all’aggiornamento compare un errore o se alcune operazioni restano in sospeso per molto tempo, è probabile che il programma sia stato aperto dalla finestra del file scaricato, o da una cartella diversa da Applicazioni. Va chiuso, trascinato in Applicazioni e riaperto da lì.

Link utili

• Visual Studio Code, per scaricarlo
• Documentazione di OpenCode, versione 1
• Estensione opencode di SST, nel Marketplace
• Git per macOS, sul sito ufficiale