MultiverbeBOS

BOS Live Sessions · Setup

2026-05-14 · Fa funzionare il widget "Sessioni attive" del BOS. Tempo setup: ~2 minuti, una tantum per macchina (Gregorio + Loris).

Cosa fa

Quando apri una sessione Claude Code in Multiverbe-Business (o in un repo correlato con questa config), degli hook registrano la sessione nello store KV di produzione. Risultato:

  • Su https://bos.multiverbe.com il widget Sessioni attive mostra in tempo reale chi sta lavorando e a cosa (polling ogni 5s).
  • All'avvio di ogni sessione, il tuo Claude Code stesso riceve nel contesto la lista delle sessioni attive — così sa se l'altro sta già lavorando su qualcosa.

Prima questo non funzionava: il lato server (endpoint /api/live/sessions KV-backed) e il lato browser (polling-live.js) erano già pronti, ma niente registrava le sessioni. Questo setup è il ponte mancante.

Come funziona

Pezzo File Ruolo
Hook wiring .claude/settings.json (committed) SessionStart→start, UserPromptSubmit+Stop→heartbeat, SessionEnd→end
Bridge script scripts/live/bos-session.mjs (committed) Chiama /api/live/sessions (register / heartbeat / end / list)
Config locale .claude/bos-live.local.json (gitignored) URL + credenziali Basic Auth + tuo nome (actor)
Stato per-sessione .claude/.live/<session_id>.json (gitignored) Mappa session_id Claude Code → id KV, per heartbeat/end
Endpoint api/live/sessions.js Funzione Vercel KV-backed · GC sessioni stale >5min

L'endpoint è dietro Basic Auth (come tutto il BOS), quindi lo script manda le credenziali nel config locale. Sono le stesse con cui apri il BOS nel browser — nessun segreto nuovo.

Setup (per Gregorio e per Loris, ognuno sulla propria macchina)

  1. Copia il template:

    .claude/bos-live.local.json.example  →  .claude/bos-live.local.json

    (stesso percorso, togli .example)

  2. Apri .claude/bos-live.local.json e compila:

    {
  "bos_url": "https://bos.multiverbe.com",
  "bos_user": "<utente Basic Auth del BOS>",
  "bos_pass": "<password Basic Auth del BOS>",
  "actor": "Gregorio"
}
    • bos_user / bos_pass: le stesse credenziali con cui apri bos.multiverbe.com.
    • actor: il tuo nome — "Gregorio" oppure "Loris".

  3. La prima volta che Claude Code apre il repo, chiede di approvare gli hook di .claude/settings.json. Approva.

  4. Fatto. Apri una nuova sessione Claude Code in Multiverbe-Business: comparirà nel widget Sessioni attive del BOS entro ~5s.

Il file .claude/bos-live.local.json è gitignored: resta solo sulla tua macchina, non finisce su GitHub.

Test manuale

Con la config a posto:

node scripts/live/bos-session.mjs list

Stampa le sessioni attive in quel momento. Se stampa Nessun altro al lavoro adesso ed effettivamente non c'è nessuno, funziona.

Troubleshooting

  • Widget sempre vuoto anche con sessioni aperte → verifica che .claude/bos-live.local.json esista e che le credenziali siano giuste (prova node scripts/live/bos-session.mjs list: se dà errore silenzioso, l'auth è sbagliata). Controlla anche che gli hook siano stati approvati.
  • list non stampa nulla / errore → KV non configurata su Vercel. Servono le env var KV_REST_API_URL + KV_REST_API_TOKEN sul progetto multiverbe-bos (vedi ops/phase-g-full-setup.md).
  • Sessione resta "attiva" dopo che ho chiuso Claude Code → normale fino a ~5 min: l'endpoint fa GC delle sessioni senza heartbeat da oltre 5 minuti.
  • Lo script non blocca mai una sessione: se la rete è giù o l'auth è sbagliata, gli hook falliscono in silenzio e Claude Code parte comunque.

Note

  • Heartbeat su UserPromptSubmit (così current_task = ultima richiesta) e su Stop. Durante un turno molto lungo (>5 min) la sessione può risultare stale per qualche secondo, poi si riallinea: comportamento accettato.
  • Più sessioni Claude Code nello stesso repo = più righe nel widget (ognuna ha un session_id distinto). Voluto.
  • Per estendere il tracking ad altri repo (es. D:\Desktop\Multiverbe\): copiare lì .claude/settings.json + scripts/live/bos-session.mjs + .claude/bos-live.local.json.