Rapport d'enquête · 2026-07-04 · siteboon/claudecodeui v1.36.0 analysé sur clone local

CloudCLI (claudecodeui) & la V2 de PilotCLI

Enquête sur l'implémentation du chat Claude Code dans CloudCLI, inventaire de ce qui fait l'originalité de PilotCLI, et stratégie recommandée pour construire PilotCLI V2 sur cette base.

1. CloudCLI en bref

Le repo siteboon/claudecodeui a été rebrandé CloudCLI (@cloudcli-ai/cloudcli, Siteboon AI B.V.) avec une offre cloud commerciale à côté. Projet très actif : v1.36.0, 36 releases, dernier commit la veille de cette enquête. Licence AGPL-3.0-or-later.

2. La question clé : comment leur chat fonctionne

2.1 SDK structuré, pas de scraping

CloudCLI ne lance pas claude dans un terminal qu'il essaierait de lire. Le module server/claude-sdk.js (~900 lignes) appelle query() du Claude Agent SDK et itère sur un générateur asynchrone de messages typés :

import { query } from '@anthropic-ai/claude-agent-sdk';
const run = query({ prompt, options: { resume: sessionId, permissionMode, mcpServers, ... } });
for await (const message of run) { /* messages structurés */ }

Chaque événement est normalisé vers un format unique NormalizedMessage avec un champ kind (text, tool_use, tool_result, thinking, stream_delta, permission_request, interactive_prompt, complete…). Le frontend fait un simple switch sur kind et rend chaque tool avec un renderer dédié (diff pour Edit/Write, todo list, plan, panneau de question interactive).

2.2 Les problèmes que nous n'avons jamais vraiment résolus… déjà résolus

Notre propre code avait déjà tiré la conclusion : dev-cli-service (dev3/dev4, sortie JSON structurée pollée) est né précisément pour contourner le scraping. CloudCLI est cette même idée, poussée au bout avec le SDK officiel.

2.3 Et aussi

• Sessions gateway : ID applicatif stable en DB, mappé sur l'ID natif Claude au premier message — le front ne manipule jamais l'ID provider. Watcher chokidar sur ~/.claude/projects (+ équivalents Cursor/Codex/Gemini) pour la découverte en continu.
• Terminal brut conservé : onglet Shell node-pty (c'est le seul endroit où le CLI est spawné directement, ex. claude --resume <id>), PTY cachés 30 min avec replay pour la reconnexion.
• Images : collées/déposées en base64, écrites dans .tmp/images/ du projet, chemins injectés dans le prompt.
• Slash commands & skills : scan de .claude/commands/ projet + user, autocomplete avec ranking d'usage.
• Multi-CLI par registry de providers : ajouter un 6ᵉ CLI est un pattern établi (sessions, synchronizer, models, auth, mcp, skills par provider).

3. Inventaire des fonctionnalités CloudCLI

• Chat multi-provider streaming (thinking, diffs, plan mode, subagents, budget tokens)
• Terminal shell intégré (xterm + node-pty, reconnexion)
• Explorateur de fichiers + éditeur CodeMirror (diff/merge, minimap), recherche ripgrep
• Panneau Git complet (20 endpoints : status, diff, commit, branches, push, message de commit généré par IA)
• Gestion MCP (CRUD par provider, scopes user/projet)
• TaskMaster (kanban, éditeur de PRD, parse-prd → tâches)
• Voice STT/TTS via proxy compatible OpenAI (Whisper, LocalAI, Groq…)
• PWA mobile + notifications Web Push, app desktop Electron
• Command palette Cmd+K (fichiers, sessions, commits, actions)
• Browser-use (automatisation Playwright exposée en MCP)
• API agent headless (API key + SSE) pour CI/automatisation
• Onboarding providers (login CLI in-app, détection URL OAuth), auto-update
• Système de plugins (voir §5)

4. Ce que PilotCLI a et que CloudCLI n'a pas

L'intuition de départ se confirme : la valeur originale de PilotCLI est dans le workflow et l'infrastructure de projet, pas dans le code de l'UI.

Dans l'autre sens, CloudCLI apporte immédiatement ce que PilotCLI n'a pas ou a en fragile : chat SDK fiable, sessions/resume natifs, multi-CLI (Cursor, Codex, Gemini), panneau Git riche, gestion MCP, mobile/PWA + push, Electron, command palette, API headless.

5. Le système de plugins CloudCLI

Réel mais jeune. À connaître avant de tout miser dessus :

• Plugins installés depuis un repo git dans ~/.claude-code-ui/plugins/ (clone, npm install --ignore-scripts, build, activation dans Settings).
• Manifest : name, displayName, entry, type react|module, permissions[], et un seul slot : tab (un onglet du contenu principal).
• L'entry exporte mount(container, api) / unmount() ; l'API fournit le contexte (thème, projet, session), onContextChange() et rpc().
• Serveur par plugin : un process Node isolé, proxifié en HTTP (/api/plugins/:name/rpc/*) et WebSocket (/plugin-ws/:name) — c'est ce qui rend un plugin « web services + Caddy » réaliste.
• Limites : pas de hooks sur le pipeline de chat, pas de routes arbitraires, pas d'événements custom. Starter officiel : cloudcli-plugin-starter.

6. Recommandation : stratégie V2

Pourquoi pas un fork profond ?

• Vélocité upstream : plusieurs releases/mois ; un fork divergent transforme chaque update en séance de merge douloureuse.
• AGPL-3.0 : usage privé self-hosted sans obligation ; mais si un jour la V2 est exposée à des tiers (beta-testeurs sur le réseau), l'obligation de publier les sources modifiées s'applique. Moins on modifie le cœur, moins c'est un sujet.
• Les frictions réelles d'un fork (mono-user câblé partout, branding dispersé, migrations DB impératives) ne valent la peine que si on a besoin de toucher le cœur — or nos besoins sont périphériques (onglets + services).

Plan proposé

Pendant la transition, PilotCLI v1 continue de tourner (il gère les web services et les sous-domaines) ; on le décommissionne fonction par fonction. Le workflow markdown (plan/specs/web, screenshots, /validate-feature) ne bouge pas d'un pouce : il vit dans les projets et dans les skills Claude Code, pas dans l'UI.

Risques

Annexe — incident docs 502 (résolu)

Au passage, le site docs était bien en 502. Cause : au démarrage, le backend re-déclare les routes Caddy des services publics (intention en DB) mais ne relance pas leurs process serve (autoStart=false) → upstream mort → 502. Corrections : docs kwenta (31100) redémarré ; le projet mvp n'avait aucun service docs → créé et démarré (ce site, 30603.kwe.to, autoStart activé) ; « Snake Game » (31200) pointe sur un projet de test effacé (/tmp/snake-game), à purger. Amélioration suggérée : au boot, ne register une route Caddy qu'après health-check de l'upstream, ou auto-démarrer les services publics.