Kiro Scout

Applicativo web a dipendenze zero (solo moduli built-in di Node) che avvia un server locale e apre una dashboard per esplorare e analizzare tutte le informazioni recuperabili dalle sessioni salvate di Kiro. Vengono lette sia le sessioni della CLI (~/.kiro/sessions/cli/, formato <id>.json/.jsonl/.history) sia quelle di chat/IDE (~/.kiro/sessions/<workspace>/sess_*/ con session.json + messages.jsonl). Ogni sessione è etichettata con l'Origine (CLI o Chat) e tutte concorrono ai conteggi e agli aggregati generali.

Installazione ed esecuzione rapida

Installa il comando globalmente:

npm install -g kiro-scout
kiro-scout

Oppure eseguilo al volo, senza installarlo, con npx:

npx kiro-scout

In entrambi i casi il server parte e il browser si apre automaticamente su http://127.0.0.1:4321/.

Avvio

cd kiro-scout
npm start

Oppure direttamente:

node server.js

Il browser si apre automaticamente su http://127.0.0.1:4321/.

Opzioni

node server.js --port 8080          # cambia porta
node server.js --host 127.0.0.1     # cambia host (default: solo locale)
node server.js --dir "C:\percorso\.kiro\sessions"   # cartella sessioni alternativa
node server.js --no-open            # non aprire il browser
node server.js --no-resume          # disabilita il pulsante "Riprendi" (nessun terminale lanciabile)
node server.js --kiro-cmd kiro-cli  # nome/percorso dell'eseguibile Kiro CLI (default: kiro-cli)

Cosa mostra

• Panoramica: sessioni totali, score medio di efficienza (1–10), crediti totali e n° interazioni, spazio su disco, messaggi, prompt, chiamate a tool, blocchi thinking, n° progetti.
• Grafici: sessioni per progetto, modelli, agenti, tool più usati e crediti per progetto.
• Timeline: grafico dell'andamento temporale (sessioni per giorno); clic su una barra per filtrare la tabella su quel giorno.
• Ricerca full-text: cerca una parola/frase dentro le conversazioni e mostra gli snippet evidenziati; clic su un risultato per aprire la sessione.
• Filtri: per progetto e per intervallo di date, oltre alla ricerca rapida sui metadati.
• Tabella sessioni: ricercabile e ordinabile (score, origine CLI/Chat, aggiornata, progetto, titolo, agente, modello, n° messaggi, n° tool, dimensione).
• Dettaglio sessione (clic su una riga): metadati completi, statistiche conversazione, permessi, dimensioni file, crediti totali e consumo per singola interazione (turno: crediti, richieste al modello, durata, uso del contesto, orario) e trascrizione completa (prompt utente, testo assistente, blocchi thinking, chiamate a tool e risultati).

Nota sui crediti: il consumo è letto da> session_state.conversation_metadata.user_turn_metadatas[].metering_usage (unità "credit"), presente in ~metà delle sessioni. I conteggi di token (input_token_count/output_token_count) esistono nello schema ma Kiro li salva sempre a 0, quindi non vengono mostrati.

• Export: dal pannello di dettaglio, pulsanti per scaricare la sessione in Markdown o JSON.
• Riprendi sessione: accanto a ogni sessione CLI (nella tabella e nel pannello di dettaglio) un pulsante ▶ Riprendi chiede al server di aprire un terminale sulla macchina che esegue il server ed eseguire kiro-cli chat --resume-id <ID> nella cartella originale della sessione. Il pulsante non compare per le sessioni chat/IDE, che non si riprendono con kiro-cli (l'endpoint risponde 400 se richiesto). Accanto al pulsante Riprendi c'è 📋 Copia comando, che copia negli appunti kiro-cli chat --resume-id <ID> così puoi lanciarlo nel terminale che preferisci (la copia è lato client e resta disponibile anche con --no-resume). Supporta Windows (cmd), macOS (Terminal.app via osascript) e Linux (x-terminal-emulator/gnome-terminal/konsole/xterm). Si disabilita con --no-resume; l'eseguibile si personalizza con --kiro-cmd.

Score di efficienza (1–10)

Ogni chat riceve uno score di efficienza della comunicazione (colonna "Score", ordinabile; breakdown nel dettaglio). Metodo ispirato a PARADISE (Walker et al. 1997): performance = successo − costi pesati. I pesi sono stati derivati dall'analisi statistica delle sessioni reali; le metriche ridondanti (fortemente correlate) sono state unificate per non contare due volte lo stesso segnale.

Sotto-punteggi e pesi di default (personalizzabili dal pannello "⚙ Pesi"):

| Fattore | Cosa misura | Peso | Normalizzazione | |---|---|---|---| | Economicità | crediti/turno (o richieste/turno se mancano i crediti) | 0.40 | rango percentile invertito | | Correzioni utente | quota di prompt di correzione/ripensamento | 0.30 | cap-based (0 = perfetto) | | Affidabilità tool | tasso di errore dei tool | 0.20 | cap-based | | Gestione contesto | picco di uso del contesto | 0.10 | rango percentile invertito |

score = 1 + 9 × media_pesata(sotto-punteggi). Le sessioni con pochi segnali (es. senza crediti) vengono avvicinate a un valore neutro tramite shrinkage bayesiano (regolarizzazione), così non ottengono un 10 "facile". I cap delle metriche di qualità sono ricavati dal 90° percentile del tuo storico. I pesi si possono cambiare a runtime (via UI o query ?wCost&wCorrection&wToolReliability&wContext).

API JSON

| Endpoint | Descrizione | |---|---| | GET /api/health | stato + numero sessioni | | GET /api/stats | aggregati globali (include byDay per la timeline) | | GET /api/sessions | elenco sessioni con metadati e statistiche | | GET /api/sessions/:id | dettaglio sessione (accetta anche il prefisso dell'id) | | GET /api/sessions/:id/export?format=md\|json | scarica la sessione in Markdown o JSON | | GET /api/search?q=... | ricerca full-text nelle conversazioni (con snippet) | | POST /api/refresh | ricostruisce l'indice in memoria | | POST /api/sessions/:id/resume | apre un terminale sul server ed esegue kiro-cli chat --resume-id <ID> (disattivabile con --no-resume) |

Nota sulla sicurezza

Il server si lega di default a 127.0.0.1 (raggiungibile solo dal tuo PC) e non ha autenticazione. Espone in sola lettura i dati delle sessioni, che possono contenere informazioni sensibili (percorsi, codice, trascrizioni). Non usare --host 0.0.0.0 né esporlo in rete senza aggiungere un livello di autenticazione.

Il pulsante Riprendi è l'unica operazione che esegue qualcosa: lancia un terminale sulla macchina del server con kiro-cli chat --resume-id <ID>. Per limitare i rischi:

• l'id di sessione è validato (^[A-Za-z0-9._-]+$) e risolto contro l'indice, così non è possibile iniettare comandi tramite l'URL;
• l'endpoint rifiuta le richieste POST con header Origin cross-site (mitigazione CSRF), evitando che una pagina web esterna apra terminali sul tuo PC mentre la dashboard è in ascolto in locale;
• la funzione si disattiva del tutto con --no-resume;
• impostando la variabile d'ambiente KIRO_SCOUT_NO_EXEC=1 l'endpoint non apre alcun terminale e restituisce solo il comando che avrebbe eseguito (modalità sicura / dry-run).

Trattandosi di esecuzione di processi locali, mantieni il server su 127.0.0.1 e non esporlo in rete.

Struttura

kiro-scout/
├── package.json      # script npm (start)
├── server.js         # server HTTP + API (built-in http/fs/path)
├── parser.js         # lettura e analisi delle sessioni
└── public/
    ├── index.html    # struttura dashboard
    ├── styles.css    # tema scuro
    └── app.js         # logica frontend (vanilla JS)