mb-dev-viz

Visualisation live, pixel art style de l'orchestration Claude Code entre un projet backend et un projet frontend. Deux personnages assis a leur bureau representent les sessions Claude Code — quand ils travaillent leur ecran s'anime, quand ils se parlent via talkie-walkie un avion en papier traverse la scene. Conçu pour montrer l'orchestration a un public non technique.

Installation & utilisation

Installation rapide (npx)

# 1. Configurer les projets (ajoute les hooks dans chaque .claude/settings.json)
npx mb-dev-viz install

# Ou en non-interactif :
npx mb-dev-viz install /path/to/backend  --as backend
npx mb-dev-viz install /path/to/frontend --as frontend

# 2. Lancer la visualisation
npx mb-dev-viz

La premiere commande vous demande le chemin de chaque projet, patche leur .claude/settings.json et enregistre la configuration dans ~/.mb-dev-viz.json.

La deuxieme lance le serveur sur http://localhost:3737 et ouvre l'UI dans le navigateur. Il suffit ensuite de demarrer Claude Code dans chaque projet : les hooks envoient automatiquement les evenements a la visualisation.

Le bouton Demo dans le panneau lateral joue une sequence d'exemple, utile pour tester l'affichage sans session Claude.

Commandes CLI

npx mb-dev-viz [start]                 Lance le serveur et ouvre l'UI
npx mb-dev-viz install                 Mode interactif (prompt pour chaque projet)
npx mb-dev-viz install <path> --as <backend|frontend>
npx mb-dev-viz uninstall <path>        Retire les hooks du projet
npx mb-dev-viz config                  Affiche la config courante
npx mb-dev-viz help

Variables d'environnement

| Variable | Defaut | Description | |----------|--------|-------------| | PORT | 3737 | Port du serveur | | NO_OPEN | (unset) | Si =1, ne pas ouvrir le navigateur automatiquement | | MB_VIZ_CONFIG | ~/.mb-dev-viz.json | Emplacement du fichier de config |

Fonctionnement

Architecture

+----------------------+            +----------------------+
|  Claude Code Backend |            | Claude Code Frontend |
|  (your backend repo) |            |  (your frontend repo)|
+----------+-----------+            +-----------+----------+
           |                                    |
           |  hooks POST /event                 |
           +---------+--------------------------+
                     |
                     v
           +----------------------+
           |  mb-dev-viz server   |
           |  - /event (ingest)   |
           |  - /ws    (broadcast)|
           |  - /      (UI)       |
           +----------+-----------+
                      |
                      v WebSocket
           +----------------------+
           |  UI Canvas (pixel)   |
           +----------------------+

Hooks captures

| Hook | Usage a l'ecran | |------|-----------------| | SessionStart / SessionEnd | Apparition / disparition du personnage | | UserPromptSubmit | Bulle de pensee au dessus de la tete | | PreToolUse (matcher mcp__talkie-walkie__send_message) | Avion en papier qui vole vers l'autre personnage | | PostToolUse | Engrenage qui tourne, code qui defile sur l'ecran | | SubagentStop | Etoile "teammate done" | | Stop | Retour en mode idle (Zzz) |

Attribution actor

La determination de quel personnage (backend vs frontend) utilise le cwd de chaque evenement et le compare aux chemins des projets enregistres dans ~/.mb-dev-viz.json. Le match le plus specifique (plus long prefixe) gagne, ce qui permet d'avoir des sous-dossiers enregistres differemment au besoin.

Fail-safe

Si le serveur de visualisation n'est pas demarre, les hooks ne cassent rien : curl timeout a 2 secondes et || true ignore les erreurs. Les sessions Claude continuent normalement. Meme chose si le navigateur n'est pas ouvert : le serveur bufferise les 500 derniers evenements et les renvoie en snapshot a la connexion.

Developpement local

git clone <repo>
cd mb-dev-viz
npm install
npm run dev      # node --watch

Pour publier sur npm :

npm version patch    # ou minor/major
npm publish --access public

Structure

mb-dev-viz/
├── bin/
│   └── mb-dev-viz.js          # Dispatcher CLI
├── src/
│   ├── server.js              # HTTP + WebSocket
│   ├── install.js             # Patch / unpatch settings.json
│   └── config.js              # Charge / ecrit ~/.mb-dev-viz.json
├── public/
│   ├── index.html             # Shell UI
│   ├── style.css              # Theme Game Boy pro
│   └── game.js                # Canvas : devs, bureaux, bulles, avions
├── package.json
└── README.md

Troubleshooting

• L'UI reste OFFLINE : le serveur n'est pas lance ou le port est occupe. Verifie lsof -i :3737.
• Aucun evenement quand Claude Code tourne : il faut redemarrer la session Claude apres mb-dev-viz install (les settings.json sont relus au demarrage).
• Un personnage bouge pour les deux projets : le cwd de Claude n'est pas dans le dossier enregistre. Verifie avec mb-dev-viz config que les chemins correspondent exactement.
• Les personnages ne bougent pas avec le bouton Demo non plus : le WebSocket n'est pas etabli — rechargez la page, regardez la console navigateur.

Licence

MIT