Il tuo progetto diventa un'app del Mac

Cos'è e perché conta

Con Claude ti sei fatto uno strumento tuo, e ogni mattina è lo stesso rito: apri il terminale, lanci il server (il programma che fa girare l'app sul tuo computer), cerchi la scheda giusta nel browser. E se chiudi il terminale per sbaglio, si spegne tutto.

app-it è un progetto gratuito e open source (licenza MIT) che si aggiunge a Claude Code e trasforma quel progetto in un'app del Mac, con icona nel Dock e finestra sue. Doppio clic: l'app accende il server da sola e apre una finestra nativa (WebKit, il motore di Safari). Con ⌘Q spegni anche il server e liberi la porta (il numero, tipo 5173, su cui risponde).

Non riscrive la tua app: aggiunge qualche file e ti lascia un resoconto per tornare indietro. È un progetto non ufficiale di uno sviluppatore indipendente, non di Anthropic. Ed è per uso tuo: non serve a pubblicare l'app sull'App Store o a venderla.

1. Cosa ti serve prima

• Un Mac. In pratica app-it è solo per macOS: il ramo per Windows è ancora sperimentale e non lo consiglio.
• Gli Xcode Command Line Tools, gli strumenti di sviluppo di Apple, che servono a costruire la finestra. Se non li hai: nel Terminale scrivi xcode-select --install.
• Quello che il tuo progetto usa già per partire, installato e funzionante: per esempio Node e le sue dipendenze (npm install già fatto). app-it non installa niente al posto tuo.
• Claude Code, aperto nella cartella del progetto.

La prova più semplice: se oggi lanci il progetto a mano dal terminale e funziona, sei pronto. Se a mano non parte, app-it non lo aggiusta: prima sistema quello.

2. Aggiungilo a Claude Code

app-it è un plugin, cioè un pacchetto di istruzioni e script per Claude Code. Non sta nel marketplace ufficiale di Anthropic ma in quello del progetto, su GitHub: prima aggiungi quello, poi installi il plugin. Dentro una sessione di Claude Code:

1. Scrivi /plugin marketplace add Christian-Katzmann/app-it. Aggiungi il catalogo del progetto (il repository è github.com/Christian-Katzmann/app-it).
2. Scrivi /plugin install app-it@app-it. Non installa subito: ti apre la scheda del plugin con quello che aggiunge. Leggila, poi scegli dove installarlo (per te, in tutti i progetti, va benissimo).
3. Se Claude Code te lo chiede, scrivi /reload-plugins. Dal terminale gli stessi passi sono claude plugin marketplace add e claude plugin install.

Vale per ogni plugin di terzi: leggi cosa installi, perché può far girare script sul tuo computer. Il codice di app-it è pubblico e il progetto dice di non caricare niente online e di non raccogliere dati.

3. Lancia /app-it sul progetto

Apri Claude Code nella cartella del progetto e scrivi /app-it (il nome completo è /app-it:app-it). Guarda il progetto, sceglie come costruire l'app, la costruisce, la installa e la prova. Io gli scrivo così:

/app-it
Trasforma questo progetto in un'app del Mac con la sua icona.
Non toccare la logica dell'app.
Alla fine spiegami il resoconto in parole semplici: che tipo di progetto hai trovato, su che porta gira, che icona hai usato, quali file hai aggiunto e come si toglie tutto.
Dimmi anche cosa devo controllare io a mano.

L'ultima riga conta: Claude verifica da solo che il server risponda e che ⌘Q lo spenga, ma la finestra e l'icona nel Dock le guardi tu.

Cosa aggiunge al tuo progetto

• Una cartella scripts/ con gli script per costruire, installare e chiudere l'app, e il file scripts/app-it.config.json con nome, porta e comando di avvio.
• Un'icona in assets/, quella che trova nel progetto oppure una provvisoria generata sul tuo Mac.
• Nel package.json, i comandi desktop:build, desktop:install, desktop:quit, desktop:doctor e desktop:verify.
• docs/desktop-launcher.md, le istruzioni brevi, e docs/desktop-launcher.app-it-report.md, il resoconto con ogni modifica.

4. Usala ogni giorno

• Primo avvio: se macOS non la apre, clic destro sull'icona, Apri, e conferma. Il primo avvio è più lento, perché il server deve partire da zero.
• Chiudere la finestra con ⌘W o con il pallino rosso non spegne il server: resta acceso, così la volta dopo si riapre subito. Per spegnere tutto e liberare la porta serve ⌘Q, oppure Esci dal menu dell'icona nel Dock.
• Se la porta preferita è occupata, di solito l'app ne prende una libera poco più in alto e la segna nel file ~/Library/Application Support/app-it/<nome-app>/server.port.
• L'app fa girare il server dalla cartella del progetto, e si ricorda dove sta. Se sposti o cancelli quella cartella, l'app smette di funzionare: rimettila dov'era, oppure rifai /app-it nel posto nuovo.

Un trucco: trascina la cartella ~/Applications/App It/ a destra nel Dock. Diventa una pila, e ogni app che crei dopo ci compare da sola. Per un controllo, o per cambiare icona:

Controlla l'app che hai creato con app-it.
Lancia npm run desktop:doctor e dimmi in parole semplici: su che porta gira davvero il server, se l'icona installata è quella giusta e se c'è qualcosa da sistemare.
Poi usa come icona questa immagine: [percorso dell'immagine], ricostruisci e reinstalla l'app.
Non toccare il codice dell'app.

5. Quando l'app è finita: app-it-static

app-it tiene acceso il server di sviluppo: comodo finché ci lavori, ma pesa sulla memoria del Mac. Per uno strumento finito c'è un fratello più leggero nello stesso marketplace, app-it-static: costruisce l'app una volta (la build, la versione finale dei file) e serve quella. Stessa finestra, stessa pila nel Dock.

Si installa con /plugin install app-it-static@app-it e si lancia con /app-it-static. Il limite da sapere: mostra una fotografia della build. Se poi cambi il codice, l'app non lo vede finché non lanci npm run desktop:rebuild.

/app-it-static
Questo progetto è finito: voglio un'app del Mac leggera che serva la build, senza server di sviluppo.
Prima di partire dimmi che comando di build userai e in che cartella finisce il risultato, e aspetta il mio ok.

In più: un'app già online, come un Artifact di Claude

app-it può anche mettere in una finestra del Dock un indirizzo web, come un Artifact di Claude pubblicato. La finestra carica il link, entri con il tuo account e l'uso resta sul tuo piano. Dai a Claude il link pubblicato, non il codice copiato.

6. Come tornare indietro

Tutto quello che app-it aggiunge si può togliere, e il resoconto dice cosa. Fallo fare a Claude partendo da lì, guardando prima l'elenco.

Voglio togliere app-it da questo progetto.
Leggi docs/desktop-launcher.app-it-report.md e mostrami l'elenco di file, cartelle e righe del package.json che app-it ha aggiunto, più l'app installata in ~/Applications/App It/.
Prima spegni l'app con npm run desktop:quit.
Non cancellare niente finché non ti do l'ok, e non toccare il codice dell'app.

Gli errori più comuni

• Lanciare /app-it su un progetto che a mano non parte. Se la finestra mostra un errore del server, di solito è il progetto: sistemalo dal terminale, poi ricostruisci l'app.
• Chiudere con il pallino rosso e pensare di aver spento tutto. Il server resta acceso: per spegnerlo serve ⌘Q.
• Spostare o rinominare la cartella del progetto dopo aver creato l'app. L'app la cerca dov'era.
• Mandare il file .app a un amico come se fosse un'app vera. È firmata solo per il tuo Mac, non è notarizzata da Apple, e senza la cartella del progetto e il suo server non funziona.

Checklist

• Il progetto parte a mano dal terminale
• Gli Xcode Command Line Tools sono installati (xcode-select --install)
• Ho letto la scheda del plugin app-it prima di installarlo
• Claude mi ha spiegato il resoconto di app-it e cosa controllare a mano
• La finestra mostra la mia app e nel Dock c'è la sua icona
• ⌘Q spegne il server e libera la porta
• La cartella ~/Applications/App It/ è nel Dock

Domande frequenti