fitprompt

FitPrompt

Plugin per Claude Code che, quando un prompt impiega più di N secondi a essere elaborato, apre una finestrella desktop con un esercizio anti-sedentarietà da fare nell'attesa: immagine, istruzioni in italiano, countdown e tre bottoni (Fatto / +30s / Salta).

Pensato per chi passa la giornata davanti allo schermo e vuole sfruttare i tempi morti di Claude per sgranchirsi collo, spalle, schiena e gambe senza interrompere il flusso di lavoro.

Come funziona

UserPromptSubmit  →  start-timer.py registra timestamp e lancia watcher in background
                     │
                     ├─ aspetta 30 secondi
                     ├─ controlla se il lock esiste ancora (= Claude ancora al lavoro)
                     ├─ sceglie esercizio random anti-sedentarietà
                     ├─ avvia un piccolo HTTP server effimero su porta libera
                     ├─ genera HTML con immagine + countdown + bottoni
                     └─ apre finestra Chrome --app posizionata bottom-right

Stop / SessionEnd →  stop-timer.py rimuove il lock; il watcher si arrende silenziosamente

Il database degli esercizi è curato e contiene 25 voci che mappano ad altrettante entry del dataset pubblico free-exercise-db (licenza CC0 / pubblico dominio). Le immagini vengono caricate dal CDN GitHub al momento della notifica; se la rete non risponde, c'è un fallback grafico SVG inline.

Requisiti

• Claude Code v2.x o superiore (il sistema dei plugin è in public beta)
• Python 3.8+ disponibile come python nel PATH
• Un browser Chromium-based (Chrome, Edge, Chromium, Brave) — usato in modalità --app per una finestra standalone senza chrome del browser
• Sistemi supportati: Windows nativo, macOS, Linux nativo, WSL2 (sceglie automaticamente il browser host di Windows)

Installazione

Opzione A — Installazione locale diretta (development)

git clone https://github.com/giusepanzuto/fitprompt.git
claude --plugin-dir ./fitprompt

Il flag --plugin-dir carica il plugin per la sessione corrente, senza registrarlo. Utile per development.

Opzione A2 — Registrazione persistente da CLI

claude plugin add github:giusepanzuto/fitprompt

Poi quit completo dell'app desktop e riapri (Cmd+Q su macOS, chiudi processo da Task Manager su Windows).

Opzione B — Via marketplace GitHub

Se il repo è pubblico:

/plugin marketplace add giusepanzuto/fitprompt
/plugin install fitprompt

Configurazione

Tutte le opzioni sono variabili d'ambiente, da esportare nel tuo ~/.bashrc / ~/.zshrc:

Variabile	Default	Descrizione
FITPROMPT_THRESHOLD	30	Secondi di attesa prima di mostrare la notifica
FITPROMPT_COOLDOWN	600	Secondi minimi tra una notifica e la successiva
FITPROMPT_WIN_SIZE	380,640	Dimensioni della finestra larghezza,altezza

Verifica la configurazione attiva con il comando slash /fitprompt:config.

Comandi disponibili

• /fitprompt:stats — riassunto degli esercizi suggeriti e completati (totale e ultimi 7 giorni)
• /fitprompt:config — mostra la configurazione corrente

Stato e log

Tutti i dati persistenti vivono in ~/.fitprompt/:

~/.fitprompt/
├── state/          # lock file delle sessioni attive (effimeri)
├── html/           # HTML generati per le notifiche (auto-puliti dopo 1h)
└── log.jsonl       # log persistente delle azioni dell'utente

Il log.jsonl contiene una riga JSON per ogni azione, formato:

{"action":"completed","exercise_id":"Side_Neck_Stretch","exercise_name":"Stretching laterale del collo","remaining_sec":12,"total_sec":40,"timestamp":"2026-04-25T14:32:11"}

Azioni possibili: completed (click su Fatto), completed_auto (countdown a zero), skipped (Salta o ESC).

Personalizzazione del database esercizi

Modifica data/exercises.json. Ogni entry richiede:

• id — deve corrispondere al nome di una directory in free-exercise-db/exercises
• name — visualizzato nella finestra
• category — mobility, strength, ecc. (informativo)
• zone — etichetta zona corporea (es. collo, spalle)
• duration_sec — durata del countdown
• instructions — testo istruzioni mostrato sotto al titolo

Per usare un'altra fonte di immagini, modifica il campo images_base in cima al JSON e adegua la struttura URL nel template templates/popup.html.tpl.

Troubleshooting

Plugin installato ma il popup non appare — Il caso più comune è che la sessione di Claude Code sia stata aperta prima dell'installazione: gli hook si caricano una volta sola allo start del processo. Quit completo dell'app (non solo chiusura della finestra) e riapri. Su Windows, verifica con il Task Manager che il processo sia effettivamente terminato.