agent-wiki-ui

Eseguibile C# (.NET 10, Windows e Linux) che lancia Claude Code (claude -p) o Codex (codex exec) nella cartella in cui risiede l'eseguibile. Senza argomenti apre una GUI di chat (Avalonia), con argomenti funziona da riga di comando.

Requisiti

• claude (Claude Code) installato e nel PATH, già autenticato; per Codex lo stesso con codex. Istruzioni: docs/INSTALL.md
• Per sviluppare: .NET SDK 10
• Per usare l'eseguibile pubblicato: nessun runtime (è self-contained). Su Linux serve un desktop con X11 o XWayland per la GUI.

Uso

GUI (nessun argomento): finestra di chat in stile claude.ai, con la conversazione in markdown in alto e il campo messaggio in basso (Invio invia, Maiusc+Invio va a capo, "Nuova chat" azzera il contesto). Il riquadro Impostazioni (in alto a destra) permette di scegliere la CLI (Claude Code o Codex), il modello e l'effort di ragionamento. All'avvio, e a ogni cambio di CLI, sono scelti il modello più piccolo (Haiku 5.5 per Claude Code, GPT-5.6 Luna per Codex) ed effort low, per risposte rapide e economiche; "Predefinito" = nessun flag, vale la config del motore. Le chat si salvano su disco e l'ultima si riapre all'avvio. Sempre nel riquadro, la sezione Aggiornamenti dice se Claude Code e Codex hanno una versione nuova (pulsante evidenziato) e li aggiorna uno alla volta.

dotnet run --project src/agent-wiki-ui

CLI (con argomenti): il prompt viene stampato su terminale, l'exit code è quello del motore (127 se non è nel PATH). Di default usa Claude Code; --engine codex usa Codex.

dotnet run --project src/agent-wiki-ui -- "spiega questo progetto"
dotnet run --project src/agent-wiki-ui -- --engine codex "spiega questo progetto"

Creare gli eseguibili (Windows e Linux)

Ogni eseguibile è un unico file che include il runtime .NET: chi lo usa non deve installare nulla. Per crearlo serve solo il .NET SDK 10 sulla macchina che compila, e da ciascun sistema si creano entrambi gli eseguibili (da Windows anche quello per Linux, e viceversa).

1. Installare il .NET SDK 10

• Windows (PowerShell o Prompt dei comandi): winget install Microsoft.DotNet.SDK.10, oppure il programma di installazione da dotnet.microsoft.com/download.
• Linux / WSL / macOS: pacchetto della distribuzione o script ufficiale da dotnet.microsoft.com/download. Funziona anche su ARM64 (Raspberry Pi): curl -sSL https://dot.net/v1/dotnet-install.sh -o /tmp/dotnet-install.sh && bash /tmp/dotnet-install.sh --channel 10.0, poi export DOTNET_ROOT=$HOME/.dotnet PATH=$PATH:$HOME/.dotnet (da mettere in ~/.bashrc).
• Controllo: dotnet --version deve stampare 10.x.

2. Creare gli eseguibili

Dalla cartella del progetto.

Sistema	Comando	Scelta del sistema di destinazione
Linux, WSL, macOS (bash)	scripts/publish.sh	scripts/publish.sh linux-x64
Windows (PowerShell)	.\scripts\publish.ps1	.\scripts\publish.ps1 win-x64

Senza argomenti si creano entrambi. Su Windows, se PowerShell rifiuta di eseguire lo script (criteri di esecuzione): powershell -ExecutionPolicy Bypass -File .\scripts\publish.ps1.

Risultato (circa 47 MB per file), in dist/, ignorata da git:

Sistema	File
Windows x64	dist/win-x64/agent-wiki-ui.exe
Linux x64	dist/linux-x64/agent-wiki-ui

Altri identificatori (per esempio win-arm64, linux-arm64) si passano allo script allo stesso modo (scripts/publish.sh linux-arm64, risultato in dist/linux-arm64/), ma non sono verificati. Su un Raspberry Pi servono anche i motori: per Claude Code vedi docs/INSTALL.md. Lo script è solo una comodità: il comando sotto fa la stessa cosa.

Senza script (identico su qualsiasi sistema; sostituisci <rid> con win-x64 o linux-x64):

dotnet publish src/agent-wiki-ui -c Release -r <rid> --self-contained -p:PublishSingleFile=true -o dist/<rid>

Senza -o il risultato è in bin/Release/net10.0/<rid>/publish/.

Verificato: da Linux/WSL entrambi gli eseguibili; da Windows nativo (PowerShell 5.1, SDK 10.0.203) entrambi, e il .exe creato parte.

Usarli

• Windows: doppio clic su agent-wiki-ui.exe per la GUI (non si apre nessuna finestra di console), oppure da terminale agent-wiki-ui.exe "prompt" per la CLI. Da cmd o PowerShell il prompt torna subito e l'output compare dopo; per aspettare la fine e leggere l'exit code usa start /wait agent-wiki-ui.exe "prompt" (cmd) o Start-Process -Wait -NoNewWindow agent-wiki-ui.exe "prompt" (PowerShell); & .\agent-wiki-ui.exe "prompt" | Out-Host aspetta ma non dà l'exit code. Spiegazione in ADR-0005. Il file non è firmato: Windows può mostrare un avviso di sicurezza al primo avvio.
• Linux: chmod +x agent-wiki-ui (se serve) e poi ./agent-wiki-ui. La GUI richiede un desktop con X11 o XWayland.
• Al primo avvio le librerie native (Skia, HarfBuzz) vengono estratte in una cartella temporanea: il primo avvio è un po' più lento.
• I motori (claude, codex) devono essere installati e nel PATH dello stesso sistema: vedi docs/INSTALL.md.

Immagini nelle risposte (wiki con catalogo di figure)

Non esiste (ancora) uno standard per cartella e catalogo delle immagini: la struttura qui sotto è solo un esempio e può cambiare. L'app non la conosce: mostra il file indicato dal percorso scritto nella risposta, ovunque stia.

Se la risposta contiene ![didascalia](percorso) e il file esiste, la chat mostra l'immagine; altrimenti compare il testo [didascalia]. Gli URL http(s) non si scaricano. Un percorso relativo si cerca nella cartella dell'eseguibile e poi in quelle superiori, quindi funziona con una wiki (cartella di pagine markdown con un indice, un catalogo delle figure e le immagini) anche se l'eseguibile sta in una sottocartella dedicata alle sole query:

<wiki>/                        radice del progetto, con CLAUDE.md (schema completo della wiki)
  index.md                     indice delle pagine, con gli id delle figure di ogni pagina
  <catalogo-figure>.json       catalogo: metadati di ogni figura (file, didascalia, posizione, avvertenze)
  <cartella-immagini>/<file>   le immagini
  query/CLAUDE.md              istruzioni solo-query (sola lettura, instradamento per indici, regole per le figure)
  query/agent-wiki-ui          l'eseguibile, da avviare da qui: il motore legge sia query/CLAUDE.md sia quello della radice

Il catalogo lo legge il motore, non l'app: il CLAUDE.md chiede di trovare la figura nel catalogo e di citarla con un percorso relativo alla radice (![Figura 1](<cartella-immagini>/<file>)), con sotto la didascalia, la posizione e il link alla nota della figura. L'app mostra l'immagine e lascia la didascalia come testo markdown. Dettagli: ADR-0006. Per preparare una wiki alle query (indice con la mappa delle figure, catalogo, istruzioni solo-query) c'è una convenzione, ADR-0007,.

Piattaforme

Windows e Linux con lo stesso codice (ADR-0001). Motori supportati: Claude Code e Codex CLI, già installati da terminale; Antigravity CLI è pianificato: ADR-0002.

Stato: MVP (prima della 1.0): la parte funzionale c'è, i test automatici e alcune verifiche su macchine reali mancano. Dettagli in docs/PROJECT_STATE.md.

Documentazione: docs/README.md (indice, regole, decisioni), docs/MVP.md, docs/ROADMAP.md.