# Agent GUI Local - Plan de construction

## Vision

Créer une web app locale qui sert de surcouche graphique universelle pour des agents LLM existants.

Objectif: ne pas remplacer Hermes, Claude Code, OpenClaw ou autres agents, mais leur fournir une interface commune avec chat, historique, timeline d'activité, logs, approbations futures, et avatar visuel. La première version utilise un avatar ASCII, puis pourra évoluer vers sprites 2D.

## Principes produit

- Local-first: l'app tourne sur `127.0.0.1`, sans cloud obligatoire.
- Agent-agnostic: chaque agent est branché via un adaptateur.
- Simple à installer: Python stdlib pour le backend, HTML/CSS/JS vanilla pour le frontend.
- Extensible: ajout d'un agent via un fichier de config ou une nouvelle classe adapter.
- Lisible pour reprise par d'autres agents: code commenté, README, tests, plan de continuité.

## Architecture prévue

```text
agent-gui/
  agent_gui/
    __init__.py
    app.py              # serveur HTTP local, API REST, endpoints statiques
    adapters.py         # protocole commun + adaptateurs CLI
    sessions.py         # stockage léger en JSONL
    config.py           # chargement configs d'agents
    avatar.py           # états et frames ASCII
  static/
    index.html          # UI principale
    styles.css          # style app + avatar ASCII
    app.js              # logique frontend, appels API
  configs/
    agents.json         # agents disponibles: echo, hermes, claude, openclaw
  tests/
    test_adapters.py
    test_sessions.py
    test_avatar.py
  README.md
  PLAN.md
```

## Protocole interne commun

Chaque agent externe doit être ramené à des événements standardisés:

```json
{
  "type": "assistant_message | user_message | tool_request | tool_result | status | error",
  "agent": "hermes",
  "session_id": "...",
  "content": "texte visible",
  "raw": "sortie brute optionnelle",
  "created_at": "ISO timestamp"
}
```

La V1 simplifie: elle exécute un agent CLI en mode one-shot, récupère stdout/stderr, puis retourne un message assistant + événements status.

## Adaptateurs V1

### EchoAdapter

Adaptateur de test intégré. Il renvoie le prompt utilisateur sans appeler de modèle. Il sert aux tests et au smoke-test sans credentials.

### CliAdapter

Adaptateur universel pour commandes terminal.

Exemples prévus dans `configs/agents.json`:

- Hermes:
  - commande: `hermes chat -q {prompt}`
- Claude Code:
  - commande indicative: `claude -p {prompt}`
- OpenClaw:
  - commande indicative à ajuster selon installation

Important: l'adaptateur ne doit jamais passer le prompt par interpolation shell non protégée. Il utilisera une liste d'arguments avec placeholder `{prompt}`.

## UI V1

Écran unique:

- Sidebar agents
- Sélecteur d'agent
- Chat central
- Zone de saisie
- Avatar ASCII à droite
- Panneau timeline / logs
- Boutons:
  - envoyer
  - nouvelle session
  - recharger agents

États avatar:

- idle: repos
- thinking: réflexion
- tool: utilisation outil / commande
- speaking: réponse reçue
- error: erreur

## Tests prévus

- Avatar: chaque état retourne une frame non vide.
- Config: chargement du fichier agents JSON.
- Adapters:
  - EchoAdapter renvoie bien un événement assistant.
  - CliAdapter exécute une commande de test Python simple.
- Sessions:
  - append événement JSONL
  - relire historique

Commandes de validation:

```bash
cd /home/wildlama/agent-gui
python3 -m unittest discover -s tests -v
python3 -m agent_gui.app --host 127.0.0.1 --port 8765
curl http://127.0.0.1:8765/health
curl -X POST http://127.0.0.1:8765/api/chat \
  -H 'Content-Type: application/json' \
  -d '{"agent":"echo","message":"hello"}'
```

## État actuel du travail

Débuté le 2026-06-15.

Fait:

- Dossier projet créé: `/home/wildlama/agent-gui`
- Package Python créé: `/home/wildlama/agent-gui/agent_gui/__init__.py`
- Plan de reprise créé: `/home/wildlama/agent-gui/PLAN.md`
- Backend Python stdlib créé: `agent_gui/app.py`
- Adaptateurs créés: `agent_gui/adapters.py`
- Config agents créée: `agent_gui/config.py` + `configs/agents.json`
- Stockage sessions JSONL créé: `agent_gui/sessions.py`
- Avatar ASCII à états créé: `agent_gui/avatar.py`
- Frontend créé: `static/index.html`, `static/styles.css`, `static/app.js`
- Tests créés: `tests/test_avatar.py`, `tests/test_adapters.py`, `tests/test_config.py`, `tests/test_sessions.py`
- README créé: `/home/wildlama/agent-gui/README.md`
- Tests unitaires passés: `python3 -m unittest discover -s tests -v` -> 10 tests OK
- Serveur lancé en arrière-plan sur `http://127.0.0.1:8765`
- Smoke-test API OK: `/health`, `/api/agents`, `/api/chat` avec agent `echo`
- Smoke-test navigateur OK: message envoyé via l'UI, réponse Echo affichée
- Hermes CLI détecté sur cette machine: `/home/wildlama/.local/bin/hermes`

En cours:

- L'interface a été transformée en bureau pixel art avec sprites animés et ambiance arcade.
- Rien de bloquant. La V2 visuelle est en place.

À faire ensuite si un autre agent reprend:

1. Ajouter streaming temps réel via SSE ou WebSocket.
2. Ajouter parsing d'événements JSON structurés pour agents compatibles.
3. Ajouter approbations interactives côté UI.
4. Ajouter sprites 2D à la place de l'avatar ASCII.
5. Créer un adaptateur Hermes profond, au-delà du simple `hermes chat -q`.
6. Créer un adaptateur Claude Code profond si son format stream/JSON est disponible.
7. Ajouter packaging desktop Tauri si besoin.

## Notes pour un agent qui reprendrait le travail

- Ne pas demander plus de specs: partir sur une V1 minimaliste mais fonctionnelle.
- Ne pas installer de dépendances lourdes pour la V1.
- Préférer Python stdlib pour que ça marche immédiatement.
- Ne pas faire une simple maquette statique: il faut une vraie app qui lance au moins l'adaptateur echo et peut appeler des commandes CLI configurées.
- Pour les commandes externes, éviter `shell=True`.
- Prévoir que Hermes existe probablement sur cette machine, mais ne pas rendre les tests dépendants de Hermes.
- Le README doit expliquer comment ajouter un nouvel agent.

## Roadmap après V1

- Streaming temps réel via SSE ou WebSocket.
- Approbations de commandes dans l'UI.
- Import/export sessions.
- Avatars sprites 2D par état.
- Adaptateur Hermes plus profond via gateway API ou session store.
- Adaptateur Claude Code plus profond si son format JSON/stream est disponible.
- Thèmes visuels par agent.