agent-wiki-ui/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Progetto

LlmRun: eseguibile C# (.NET 10, Windows) che invoca Claude Code (claude -p) da terminale. Senza argomenti apre una GUI WinForms, con argomenti funziona da CLI. Non è un repo git.

Workflow doc-first (obbligatorio)

• Specifica e criteri di accettazione: docs/MVP.md. Fasi e stato: docs/ROADMAP.md. Indice dei doc e regole (SSOT, ADR): docs/README.md; una decisione architetturale si scrive solo nel suo ADR, gli altri doc la richiamano con un link. Uso: README.md.
• Ad ogni richiesta di modifica: aggiornare prima i doc interessati (MVP.md, ROADMAP.md con le spunte, README.md se cambia l'uso; un nuovo ADR in docs/adr/ per ogni scelta architetturale), poi il codice, poi questo file se cambiano comandi, design o vincoli. Nessuna modifica deve lasciare i doc disallineati.

In corso: migrazione a GUI Avalonia multipiattaforma (ADR-0001, ROADMAP Fase 5). Finché non è conclusa, le sezioni sotto descrivono lo stato attuale (WinForms + WebView2).

Comandi

• Build: dotnet build (LlmRun.csproj, net10.0-windows, WinForms)
• GUI: dotnet run; CLI: dotnet run -- "prompt"
• Publish single-file: dotnet publish -c Release -r win-x64 --self-contained -p:PublishSingleFile=true
• Test: non esistono ancora.

Architettura

• Program.cs: top-level statements. Senza argomenti avvia Gui; con argomenti è la CLI (claude -p <prompt> con ArgumentList, stdout/stderr ereditati, exit code propagato, 127 se claude non è nel PATH).
• Gui.cs: host WinForms sottile. Un solo WebView2 che carica ui.html (embedded resource; {{MODELS}} è sostituito con le opzioni dei modelli). Pagina e C# dialogano con WebMessage JSON (protocollo in docs/MVP.md). Per ogni send C# lancia claude -p con stdout/stderr rediretti, converte la risposta da markdown a HTML con Markdig (DisableHtml) e la rimanda alla pagina. Contesto: --session-id <guid> al primo messaggio, --resume <guid> poi. Cronologia: un JSON per chat in %LOCALAPPDATA%\LlmRun\chats\<guid>.json (il nome file è l'id di sessione, validato come Guid prima dell'uso), salvato appena l'utente invia e di nuovo alla risposta; all'avvio (primo list dalla pagina) viene riaperta la chat più recente. --model/--effort omessi se "Predefinito". Lista modelli hardcoded in Gui.Models, da aggiornare quando escono nuovi modelli.
• ui.html: tutta la UI (HTML+CSS+JS, nessuna libreria). Token di colore/tipografia come variabili CSS in cima; specifiche in docs/MVP.md → "Design (UI/UX)". Cambiando l'aspetto aggiornare quella sezione.
• Dipendenze NuGet (solo GUI): Markdig, Microsoft.Web.WebView2.

Vincoli non ovvi

• La working directory di claude deve essere la cartella dell'exe: usare AppContext.BaseDirectory, mai Environment.CurrentDirectory né Assembly.Location (vuoto in single-file).
• Lo stdin di claude va redirezionato e chiuso subito, altrimenti aspetta 3s.
• claude è un .exe nativo (~/.local/bin), avviabile direttamente. Se fosse claude.cmd serve cmd.exe /c.
• La logica di avvio processo è duplicata tra CLI (Program.cs) e GUI (Gui.cs): se cambia (cartella di lavoro, stdin, flag), modificarla in entrambi i punti.
• Nella GUI i link http(s) non devono navigare nella finestra: si aprono nel browser di sistema (NavigationStarting/NewWindowRequested).
• La GUI deve girare su un thread STA (creato a mano in Program.cs, perché i top-level statements non hanno [STAThread]): senza, WebView2 fallisce con RPC_E_CHANGED_MODE.

Skill del repo

.claude/settings.json abilita il plugin ui-ux-pro-max (marketplace nextlevelbuilder/ui-ux-pro-max-skill). Usarlo per le modifiche alla GUI WinForms (layout, usabilità, accessibilità).

Commit

Messaggi di commit in italiano: titolo breve all'indicativo o in forma nominale, eventuale corpo che spiega il perché. Mantenere la riga finale Co-Authored-By prevista dall'ambiente. Fare commit solo su richiesta.