Forma, un coach privato di alimentazione e allenamento
Mi capitava di stare in cucina a indovinare i grammi della pasta, o di tornare da un allenamento e aprire tre app diverse per ricostruire la giornata. I pasti restavano a metà in un’app di note, e stimare calorie e macro a mano era noioso. Volevo qualcosa che si adattasse al mio calendario, e che tenesse i dati di salute su un’infrastruttura mia.
Ho costruito Forma, un coach privato in Grok Bot, con una dashboard sul mio Cloudflare e un’app che legge Apple Health. Gli mando una foto del pranzo e mi torna una stima, gli chiedo cosa mangiare prima del tennis, e la sera do un’occhiata alla dashboard.
Ora ho pubblicato un template del bot. Lo puoi installare sul tuo account e usarlo allo stesso modo, con i tuoi dati sul tuo Cloudflare. Spiego cos’è, come si installa, come si mette in piedi la dashboard e Forma Sync, e dove restano i dati.
Cos’è Forma
Forma è un coach privato di alimentazione e allenamento. Gli parli in chat, in italiano o nella lingua che scegli alla prima conversazione.
Ti tiene il diario dei pasti. Puoi mandare una foto del piatto, un menu, uno scontrino, oppure descrivere quello che hai mangiato. Forma stima calorie, proteine, grassi, carboidrati e fibre, e marca le stime come tali. Se correggi un pasto, aggiorna la voce esistente, senza crearne una seconda.
Prepara piani pasti e una lista della spesa, con un budget che gli dici tu. Propone allenamenti adatti al tuo calendario. Puoi attivare dei promemoria per i pasti: restano in pausa finché non glielo chiedi tu. Per i piani e i record di decisione può usare una knowledge base a tua scelta.
I target giornalieri sono dinamici. Quando la dashboard e l’app di sync sono collegate, le calorie del giorno seguono la spesa energetica misurata da Apple Health. Proteine, grassi, carboidrati e fibre li imposti tu, oppure Forma calcola dei valori provvisori, da far confermare a un professionista. I riferimenti di partenza, come esempio e non come prescrizione, sono circa 1,6-2 g di proteine per chilo di peso, grassi al 25-30% delle calorie, e 30 g di fibre.
Come iniziare
Il template del bot si installa da Grok Bot: Forma su Grok Bot.
Alla prima conversazione Forma ti guida, una domanda alla volta:
- Come vuoi chiamarlo, e in che lingua deve scrivere.
- Il profilo: data di nascita, altezza, peso, obiettivo.
- Vincoli alimentari e, se ce l’hai, il piano di un nutrizionista.
- Allenamento, eventuali limiti fisici, e se usi un’app come Hevy.
- Integratori.
- Orari abituali dei pasti.
- Dove fai la spesa, il budget, per quante persone.
- Una knowledge base, se vuoi usarla.
- Il calendario, in sola lettura.
- L’email, anch’essa in sola lettura.
Poi salva il profilo, calcola i target provvisori e crea le routine dei promemoria, lasciandole in pausa. Il diario parte dal primo pasto che gli mandi.
Quando la dashboard è pronta, gli dai l’indirizzo del sito e salvi INGEST_SECRET come secret del bot, mai nel testo della chat.
La dashboard sul tuo Cloudflare
Il diario e i dati di Salute stanno su un sito tuo, servito da un Worker Cloudflare con un database D1 nel tuo account. Il template è pubblico, senza cartelle cliniche né credenziali: forma-dashboard-template. L’accesso è protetto da password.
Servono un account Cloudflare con Workers e D1, Node.js 20 o successivo (il README consiglia 22.13+, ed è la versione richiesta per i test SQLite inclusi), npm e Git. Python non serve.
I comandi, come nel README del template:
npm install
npx wrangler login
npx wrangler d1 create forma-health
cp wrangler.example.toml wrangler.toml
Copi in wrangler.toml il database_id stampato da d1 create, scegli un nome del Worker che ti appartiene, e allinei database_name. Poi crei lo schema vuoto e imposti i tre secret, ciascuno al proprio prompt, senza metterli nel file TOML né nel codice:
npm run db:migrate:remote
npx wrangler secret put SITE_PASSWORD
npx wrangler secret put SESSION_KEY
npx wrangler secret put INGEST_SECRET
Per SESSION_KEY e INGEST_SECRET il README suggerisce, come esempio, openssl rand -base64 48. Conserva i valori nel tuo gestore di password. Poi:
npm run deploy
L’indirizzo predefinito è https://<name>.<tuo-subdomain>.workers.dev. Se vuoi un dominio tuo, decommenti il blocco routes in cima a wrangler.toml e sostituisci dash.example.com con il tuo dominio: la zona DNS deve appartenere al tuo account. In alternativa, aggiungi il dominio da Workers → Settings → Domains & Routes, e fai di nuovo il deploy.
Dal telefono la stessa interfaccia si legge in una colonna sola, come nelle schermate iPhone qui sotto.
Le schermate qui sotto sono la mia dashboard su forma.jaack.me. Sono dati reali, usati come riferimento visivo. Il template riproduce la stessa interfaccia, vuota, sul tuo account.
I dettagli, i test con dati sintetici e le variabili opzionali sono nel README del template. Se qualcosa in questa pagina e nel README non coincidono, vale il README.
Forma Sync, l’app per iPhone
Per mandare i dati di Apple Health alla dashboard c’è Forma Sync. La compili tu sul Mac con Xcode e la installi sul telefono, senza TestFlight. Il codice è pubblico: forma-sync. La guida completa è in docs/INSTALL-XCODE.md.
Servono un Mac con Xcode, un iPhone con iOS 17 o successivo, un Apple ID (anche gratuito), Homebrew, e una dashboard già funzionante. Poi, dal Terminale:
brew install xcodegen
git clone https://github.com/iJaack/forma-sync.git
cd forma-sync
cp Config/Local.xcconfig.example Config/Local.xcconfig
In Config/Local.xcconfig inserisci il tuo Team ID e un bundle ID unico, per esempio com.tuonome.formasync. Quel file resta sul tuo Mac e Git lo ignora. Poi:
xcodegen generate
open FormaSync.xcodeproj
In Xcode scegli lo schema FormaSync e il tuo iPhone, controlli la firma in Signing & Capabilities, e lasci attivo Automatically manage signing. Sul telefono attivi la Modalità sviluppatore (Impostazioni → Privacy e sicurezza) e, se iOS lo chiede, autorizzi lo sviluppatore in Impostazioni → Generali → VPN e gestione dispositivi. Premi ▶, apri l’app e consenti l’accesso a Salute. Forma Sync legge soltanto: non scrive in Apple Health.
Con un Apple ID gratuito (Personal Team) il profilo di sviluppo scade dopo 7 giorni. L’app smette di aprirsi e non sincronizza più, finché non ricolleghi l’iPhone e premi di nuovo ▶ in Xcode, con lo stesso team e lo stesso bundle ID. Con l’Apple Developer Program il profilo dura un anno.
Per collegare la dashboard, in app vai su Configura connessione. Puoi incollare o scansionare un QR con questo JSON, sostituendo i segnaposto in locale e senza condividere il file:
{
"url": "https://<tuo-sito>/api/ingest/health",
"client_id": "unused",
"client_secret": "unused",
"bearer": "<INGEST_SECRET>"
}
url deve usare https. Se indichi solo la radice del sito, l’app aggiunge /api/ingest/health. bearer è lo stesso INGEST_SECRET impostato sul Worker, senza le parentesi. client_id e client_secret devono essere presenti: unused va bene quando la dashboard chiede soltanto il bearer.
Dopo il salvataggio, premi Prova connessione. Poi, con l’iPhone sbloccato e l’app aperta, premi Sincronizza ora e controlla i giorni recenti sulla tua dashboard, dopo aver fatto il login. Sonno, HRV e frequenza cardiaca a riposo arrivano da Apple Health e si vedono nel capitolo Recupero.
Nel tempo la dashboard accumula anche il capitolo Direzione: peso, bilancio medio e costanza degli allenamenti.
Non usare generatori QR online: la configurazione contiene un segreto. I comandi per creare il QR in locale, e i casi più comuni di errore, sono nella guida di installazione.
Privacy, e un avviso
I dati di salute e il diario dei pasti restano nel tuo account Cloudflare. Il template della dashboard non contiene cartelle cliniche, cronologia dei pasti o credenziali. Non ha analytics, né export verso terzi, né font esterni.
Il bot non invia messaggi, non pubblica e non attiva nulla da solo. Il calendario, se lo colleghi, è in sola lettura. L’email, se la colleghi, è anch’essa in sola lettura.
Forma non è un medico. Le stime dei pasti e i target provvisori servono a tenerti organizzato. Le decisioni su dieta, integrazione e allenamento restano tue, e conviene farle confermare a un professionista.
Le schermate di questa guida arrivano da forma.jaack.me, la mia istanza, e servono solo a mostrare l’interfaccia. Il sito è protetto da password: non è un servizio condiviso a cui registrarsi.
Domande brevi
Devo per forza avere un dominio? No. Puoi usare l’indirizzo workers.dev che Cloudflare ti assegna.
Devo pagare Apple per installare l’app? No. Con un Apple ID gratuito l’app si installa da Xcode. Il limite è la scadenza del profilo dopo 7 giorni, e al massimo tre app con provisioning gratuito sul dispositivo.
Serve TestFlight? No. Compili l’app da Xcode e la installi sul tuo iPhone.
Posso correggere un pasto già registrato? Sì. Diglielo: aggiorna la voce esistente, non ne crea una seconda.
I promemoria arrivano da soli? No. Restano in pausa finché non li attivi tu.
Dove sono i dettagli tecnici? Nel README del template della dashboard e in docs/INSTALL-XCODE.md di Forma Sync. Per il formato con cui il bot scrive i pasti c’è anche docs/forma-agent.md.
Il punto di partenza è il template del bot, insieme a quei due repository. Se dopo l’installazione qualcosa non torna, parti da lì.