pi-hitl-programming/README.md

pi-hitl-programming

Estensione per pi coding agent che introduce un Human-in-the-Loop (HITL) focalizzato sulla programmazione.

Ogni volta che l'agente tenta di scrivere (write) o modificare (edit) un file di programmazione, l'estensione:

1. Mostra il percorso del file.
2. Genera una spiegazione brevissima (massimo 5-6 righe) del codice proposto.
3. Mostra il codice proposto in una finestra scrollabile.
4. Chiede all'utente cosa fare:
   • ✅ Accetta e applica
   • ✏️ Modifica prima di applicare
   • 💬 Discuti / chiedi
   • ❌ Rifiuta

Se l'utente sceglie di modificare, può editare il contenuto direttamente nell'editor di pi. Se sceglie di discutere, può scrivere una nota che viene riportata all'agente come motivo di blocco.

Controlli nella schermata HITL

• ↑ / ↓: scrolla il testo riga per riga.
• Ctrl+U / Ctrl+D: scrolla di una pagina.
• Home / End: va all'inizio / fine del testo.
• Tab: sposta il focus tra il pannello di testo e il menu azioni.
• Enter: seleziona l'azione evidenziata (quando il menu ha il focus).
• Esc: rifiuta la modifica.

Attivare / disattivare HITL al volo

L'estensione può essere accesa o spenta senza uscire da pi:

• Tasto F10.
• Comando slash /hitl, /hitl on, /hitl off.

Una notifica in TUI conferma lo stato attuale.

File intercettati

L'HITL si attiva solo su file con estensione di programmazione/configurazione (es. .py, .js, .ts, .java, .c, .cpp, .go, .rs, .sh, .html, .css, .json, .yaml, .toml, .md, …). I file generici (es. .txt) vengono lasciati passare.

Installazione

L'estensione e auto-scoperta da pi quando si trova in un percorso riconosciuto.

Project-local (consigliato per questo progetto)

Il repository contiene gia una copia in .pi/extensions/hitl-programming.ts. Devi solo fidarti del progetto e ricaricare:

cd /home/enne2/Development/pi-hitl
pi
# dentro pi, quando richiesto, seleziona "Trust"
/reload

Globale

cp /home/enne2/Development/pi-hitl/src/index.ts ~/.pi/agent/extensions/hitl-programming.ts
# riavvia pi o esegui /reload

Esempi di Tetris inclusi

Il repository include due implementazioni minimali di Tetris:

• tetris.py: versione con curses (terminale classico).
• tetris_textual.py: versione moderna con Textual.

Per eseguire la versione Textual:

pip install -r requirements.txt
python3 tetris_textual.py

Test rapido

Dopo il caricamento, dentro pi chiedi:

scrivi un file hello.py con contenuto print("ciao")

Dovrebbe apparire una schermata HITL con:

• spiegazione breve del codice proposto;
• anteprima del codice scrollabile;
• menu per accettare, modificare, discutere o rifiutare.

Modalita non interattiva

In modalita --mode print o --mode json l'estensione blocca scritture e modifiche perche non puo mostrare la UI. Usala solo in modalita TUI interattiva.

Note

• L'estensione aggiunge un'istruzione al system prompt per scoraggiare l'agente dall'usare bash con redirezioni (>, >>) per aggirare la conferma.
• La spiegazione e generata a partire dal codice completo proposto (fino a 60.000 caratteri), non dalla sola anteprima TUI.
• Quando HITL e disattivato, le operazioni write/edit su file di programmazione procedono normalmente.