Monitoraggio in tempo reale di sessioni Claude Code parallele
Monitora N sessioni Claude Code parallele su progetti diversi — zero configurazione manuale
Avvio Rapido • Funzionalità • Come Funziona • API • Troubleshooting
| Funzionalità | Descrizione |
|---|---|
| Scan Roots | Configura cartelle radice (C:\BIZ2017, C:\Progetti Pilota, ecc.) — tutte le sottocartelle con sessioni Claude vengono monitorate automaticamente, fino a 2 livelli di profondità |
| Aggiornamenti in tempo reale | Notifiche istantanee via WebSocket |
| Discovery dinamico | Nuovi progetti rilevati automaticamente senza riavvio del server |
| Stato intelligente | Distingue Attivo / Da Controllare / Inattivo / Errore in base al tipo di entry e ai timeout |
| Riconnessione automatica | Il client WebSocket si riconnette ogni 3 secondi |
- Dark theme completo con palette CSS tramite variabili
- Tipografia: Syne (interfaccia) + JetBrains Mono (dati/codice)
- Indicatori di stato con neon glow animato
- Layout a 3 colonne: Attivi / Da Controllare / Inattivi (colonna Inattivi collassabile)
- Ricerca in tempo reale nella colonna Inattivi — filtra card per nome
| Azione | Descrizione |
|---|---|
| Escludi percorso | Bottone ⊗ su ogni card — salvataggio in excluded-paths.json, attivo al prossimo riavvio del server |
| Apri CMD | Apre cmd.exe nella directory del progetto |
| Trova finestra | Individua la sessione Claude nel terminale leggendo ~/.claude/sessions/ — elenca ogni tab di Windows Terminal via UIAutomation |
| Porta in primo piano | Bottone ⬆ su ogni risultato — porta Windows Terminal in primo piano e seleziona la tab corretta |
| Segna controllato | Marca un progetto "Da Controllare" come rivisto → torna a Inattivo |
- Pannello laterale accessibile con ⚙ ADMIN nell'header
- Aggiungi / rimuovi cartelle radice di scansione
- Riscansiona Ora — trova nuovi progetti senza riavviare il server
- Visualizza e ripristina percorsi esclusi
La dashboard non scansiona ~/.claude/projects/ alla cieca. Il flusso è:
- Legge
backend/scan-paths.json— lista cartelle radice configurate - Per ogni radice, scansiona le sottocartelle ricorsivamente (profondità massima 2)
- Per ogni sottocartella controlla se esiste
~/.claude/projects/[path-codificato]/con file.jsonl - Include solo le cartelle con sessioni reali
C:\Progetti Pilota\ ← cartella radice
├── DashboardClaudeCode\ ← ha sessioni Claude → MONITORATA
├── gestione-preattività\
│ └── consultation-panel\ ← ha sessioni Claude (2 livelli) → MONITORATA
└── Archivio\ ← nessuna sessione → IGNORATA
Claude Code converte i path in nomi di directory:
C:\Progetti Pilota\MioProgetto → C--Progetti-Pilota-MioProgetto
I caratteri non-ASCII vengono codificati come uno o più - in base ai byte UTF-8 (es. à = 2 byte → --). La dashboard gestisce correttamente questa codifica.
Il flusso di Trova finestra:
- Legge i file
~/.claude/sessions/*.json— contengono{ pid, cwd, sessionId, startedAt } - Trova la sessione con
cwduguale al percorso del progetto - Risale la catena dei processi padre fino a trovare Windows Terminal (max 6 livelli)
- Usa UIAutomation (
System.Windows.Automation) per enumerare le singole tab di Windows Terminal - Restituisce ogni tab come riga separata con titolo e indice
Il bottone ⬆ su ogni riga porta Windows Terminal in primo piano (con il trucco del tasto ALT per bypassare la restrizione di SetForegroundWindow) e poi seleziona la tab tramite SelectionItemPattern.
Gli script PowerShell vengono scritti su file temporaneo in %TEMP% invece di essere passati come -EncodedCommand, evitando il limite di 8191 caratteri della riga di comando Windows.
| Stato | Colore | Condizione |
|---|---|---|
| Attivo | Verde | Tool in esecuzione o meno di 5 minuti dall'ultimo tool result |
| Da Controllare | Arancione | Completato da meno di 60 minuti |
| Inattivo | Grigio | Più di 60 minuti di inattività o segnato manualmente |
| Errore | Rosso | Impossibile leggere la sessione |
| Layer | Tecnologie |
|---|---|
| Backend | Node.js >= 18, Express, ws, chokidar |
| Frontend | React 18.2, Vite 5 |
| Font | Syne (Google Fonts), JetBrains Mono |
| Piattaforma | Windows — PowerShell + UIAutomation per il rilevamento terminale |
DashboardClaudeCode/
├── backend/
│ ├── server.js # Express + WebSocket + API REST
│ ├── claude-watcher.js # Monitora le sessioni reali Claude Code
│ ├── path-scanner.js # Discovery da cartelle radice
│ ├── scan-paths.json # Cartelle radice da scansionare
│ ├── excluded-paths.json # Percorsi esclusi dal monitoraggio
│ └── package.json
├── frontend/
│ ├── src/
│ │ ├── App.jsx # Layout + 3 colonne + Admin toggle
│ │ ├── components/
│ │ │ ├── ProjectCard.jsx # Card progetto con azioni
│ │ │ └── AdminPanel.jsx # Pannello Admin
│ │ ├── hooks/
│ │ │ └── useWebSocket.js # Hook WebSocket + riconnessione
│ │ └── index.css # Variabili CSS + animazioni
│ ├── index.html
│ └── package.json
├── start.bat # Avvio rapido Windows
├── package.json
└── README.md
Node.js >= 18
npm >= 9
Claude Code con sessioni attive
# 1. Clona il repository
git clone https://github.com/Attilio81/ClaudeCodeDashboard.git
cd ClaudeCodeDashboard
# 2. Installa le dipendenze
npm install
cd backend && npm install
cd ../frontend && npm install && cd ..
# 3. Configura le cartelle radice (vedi sezione Admin o modifica direttamente)
# backend/scan-paths.json
# 4. Avvia
npm run dev
# oppure su Windows: doppio click su start.batApri http://localhost:5173
[
"C:\\BIZ2017",
"C:\\Progetti Pilota",
"C:\\ProgettiEgm"
]Puoi anche usare l'Area Admin nell'interfaccia per aggiungere o rimuovere percorsi senza toccare file.
Popolato automaticamente quando clicchi ⊗ su una card. Per ripristinare un percorso usa il pannello Admin → sezione "Percorsi esclusi".
[
"C:\\Progetti Pilota\\ProgettoDaIgnorare"
]Se scan-paths.json è vuoto, il server usa config.json con lista manuale:
{
"projects": [
{ "name": "MioProgetto", "path": "C:\\Progetti\\MioProgetto" }
]
}| Metodo | Endpoint | Descrizione |
|---|---|---|
GET |
/api/health |
Stato server |
GET |
/api/projects |
Lista progetti monitorati |
POST |
/api/projects/:name/mark-checked |
Segna come controllato |
POST |
/api/projects/:name/exclude |
Escludi dal monitoraggio |
POST |
/api/projects/:name/open-terminal |
Apri CMD nella directory |
GET |
/api/projects/:name/terminal-windows |
Trova le tab del terminale |
POST |
/api/focus-window/:pid |
Porta finestra in primo piano e seleziona tab |
| Metodo | Endpoint | Descrizione |
|---|---|---|
GET |
/api/admin/scan-paths |
Lista cartelle radice |
POST |
/api/admin/scan-paths |
Aggiungi cartella ({ "path": "C:\\..." }) |
DELETE |
/api/admin/scan-paths/:index |
Rimuovi cartella radice |
POST |
/api/admin/rescan |
Riscansiona senza riavvio |
GET |
/api/admin/excluded-paths |
Lista percorsi esclusi |
DELETE |
/api/admin/excluded-paths/:index |
Ripristina percorso escluso |
Config (inviato alla connessione e ad ogni aggiornamento lista):
{
"type": "config",
"projects": [{ "name": "BNEGS076", "path": "C:\\BIZ2017\\BNEGS076" }]
}Status update (inviato ad ogni cambio sessione):
{
"type": "status",
"data": {
"status": "active",
"projectName": "BNEGS076",
"lastUpdate": "2026-04-02T10:00:00Z",
"lastOutput": "Bash: npm test",
"slug": "sharded-wibbling-crab",
"gitBranch": "main",
"sessionId": "abc-123",
"outputHistory": [{ "timestamp": "...", "output": "...", "toolName": "Bash" }]
}
}Progetto non rilevato
Verifica che esista una directory sessione in ~/.claude/projects/:
ls "$env:USERPROFILE\.claude\projects\" | Where-Object Name -like "*NOMEPROGETTO*"Se esiste ma non appare, controlla che il percorso sia in scan-paths.json e fai Riscansiona dal pannello Admin. Se il progetto è in una sottocartella con caratteri non-ASCII nel percorso (es. gestione-preattività), la codifica viene gestita automaticamente.
Nuovo progetto non compare in automatico
Il watcher dinamico rileva nuovi file .jsonl in tempo reale. Se il progetto non compare, fai Riscansiona dal pannello Admin oppure riavvia il server. Dopo il riavvio i nuovi progetti vengono rilevati automaticamente senza F5.
"Trova finestra" non trova nulla
La funzione richiede che:
- Claude Code sia attivo nel progetto (deve esistere un file in
~/.claude/sessions/concwdcorrispondente) - Il processo sia figlio di Windows Terminal o cmd
Se la sessione è attiva ma non viene trovata, verifica che i file in ~/.claude/sessions/*.json contengano cwd uguale al percorso del progetto.
Il bottone ⬆ non porta la finestra in primo piano
Windows blocca SetForegroundWindow dai processi in background. La dashboard usa un workaround con la simulazione del tasto ALT (keybd_event) per ottenere il permesso. Se non funziona, prova a cliccare prima sulla dashboard e poi su ⬆.
WebSocket si disconnette continuamente
Il client si riconnette ogni 3 secondi automaticamente. Se il problema persiste:
- Verifica che il backend sia in esecuzione sulla porta 3001
- Controlla che non ci siano firewall locali che bloccano
localhost:3001
- Ricerca card inattivi: barra di testo nella colonna Inattivi, filtra per nome in tempo reale
- Fix
excluded-paths.json: username Windows con punti (es.attilio.pregnolato.EGMSISTEMI) veniva salvato con backslash al posto dei punti — il percorso non matchava mai e il progetto non veniva escluso
- Apri CMD: imposta il titolo della finestra cmd a
claude - <nome>e salva il PID su file - Trova finestra: priorità al match tramite PID salvato dalla dashboard (badge viola dashboard)
- Trova finestra: nuovo fallback per titolo esatto della finestra
- claude-watcher: il periodic check rileva nuove sessioni e aggiorna il watcher dinamicamente
- ProjectCard: badge viola
dashboardper terminali aperti direttamente dalla dashboard
- Trova finestra: filtraggio tab tramite slug sessione Claude (
sharded-wibbling-crab, ecc.) - Trova finestra: fallback intelligente quando lo slug non è presente nel titolo
- ProjectCard: badge che indica il tipo di match trovato (slug / titolo / pid)
- Trova finestra: rilevamento sessioni da
~/.claude/sessions/*.jsoninvece di scansione processi - Trova finestra: elenca ogni singola tab di Windows Terminal via UIAutomation
- Porta in primo piano: selezione della tab specifica tramite
SelectionItemPattern - Porta in primo piano: workaround ALT-key per bypassare restrizione
SetForegroundWindow - Fix: script PowerShell scritti su file temporaneo (evita limite 8191 char della riga di comando)
- Fix: codifica percorsi non-ASCII (
à= 2 byte UTF-8 →--) inpath-scanner.js,claude-watcher.js,server.js - Fix: scansione ricorsiva a profondità 2 per rilevare progetti in sottocartelle (es.
gestione-preattività/consultation-panel) - Fix: broadcast
configal rilevamento dinamico di nuovi progetti (non più necessario fare F5) - Fix: log deduplicati — stampa solo quando lo stato cambia
- Colonna Inattivi collassabile (strip verticale 32px)
- Esclusione progetti con bottone ⊗ e persistenza
- Scan Roots: discovery da cartelle radice configurabili
- Area Admin: pannello UI per gestire percorsi di scansione e percorsi esclusi
- Trova finestra terminale: prima implementazione
- start.bat: avvio rapido su Windows
- Redesign completo UI — dark theme, Syne + JetBrains Mono, neon glow
- Auto-discovery dinamico — nuovi progetti aggiunti senza riavvio
- Timeout intelligenti (5 min tool, 60 min idle)
- Storico sessione (ultimi 20 eventi)
- Visualizzazione branch Git
- Marcatura manuale "controllato"
- Parsing file
.jsonlin tempo reale - Auto-detection sessioni Claude Code
- Monitoraggio via
status.json - WebSocket + UI