vmux/.planning/research/SUMMARY.md

Project Research Summary

Project: vmux Domain: CLI/TUI session monitor — Claude Code + i3 WM integration Researched: 2026-03-23 Confidence: HIGH

Executive Summary

vmux est un outil de monitoring desktop pour les sessions Claude Code sous i3 WM. La recherche confirme que ce domaine est bien documenté via des outils communautaires existants (agent-deck, amux, dmux, agentdock), mais aucun d'eux ne cible un tiling WM. Tous s'appuient sur tmux ou un dashboard web. La proposition de valeur de vmux est claire : mapper les sessions Claude Code aux workspaces i3 pour permettre la navigation en une action, sans quitter le workflow natif i3.

L'approche recommandée est une architecture daemon + CLI avec deux sources de données. Claude Code expose des hooks HTTP (depuis début 2026) qui permettent une détection d'état push, sans polling. Les fichiers JSONL de ~/.claude/projects/ servent de source secondaire pour la découverte au démarrage et la réconciliation. Cette combinaison est supérieure à l'approche file-watching pure utilisée par la plupart des outils existants. La stack Go + Bubble Tea v2 + go.i3wm.org/i3/v4 est vérifiée sur la machine cible.

Les risques principaux sont la fragilité du format JSONL (API non stable), les fichiers de session qui peuvent atteindre plusieurs Go, et les deadlocks potentiels de l'IPC i3 si les events ne sont pas consommés assez vite. Ces trois risques ont des mitigations concrètes identifiées et doivent être adressés dès la Phase 1.

Key Findings

Recommended Stack

Go 1.25.7 (disponible via nix-shell) avec Bubble Tea v2 pour la TUI est la combinaison recommandée. La lib officielle i3 Go (go.i3wm.org/i3/v4) couvre 100% de l'API IPC et gère les reconnexions automatiquement. Tout a été vérifié sur la machine cible : 4 sessions Claude actives, format JSONL inspecté directement, titres de fenêtres i3 contenant "Claude Code" confirmés.

La recommandation est de commencer par un MVP CLI-first (sans TUI) pour valider la détection avant d'investir dans l'interface. La TUI et le widget i3bar sont des couches de présentation interchangeables une fois la détection validée.

Core technologies:

• Go 1.25.7 : langage — single binary, cohérence avec piaire, disponible via nix-shell
• Bubble Tea v2 : TUI — framework Elm, renderer Cursed anti-tearing, standard de facto
• go.i3wm.org/i3/v4 : i3 IPC — lib officielle, reconnexion auto, 100% de l'API
• stdlib net/http : hook server — recevoir les events push de Claude Code
• stdlib os/io : /proc + tail JSONL — pas besoin de libs tierces pour ces cas simples
• esiqveland/notify : notifications D-Bus — natif desktop, zero dépendance runtime

Expected Features

Must have (table stakes) :

• Session discovery (process + JSONL) — sans ça, l'outil est vide
• State detection (Working / Needs Input / Idle) — la valeur centrale
• Workspace i3 association (PID -> window -> workspace) — différenciateur clé vs tmux-centric
• Session list with status — retour visuel immédiat
• Switch to workspace — navigation en une action
• Desktop notifications on state transition — alerte passive via dunst

Should have (competitive) :

• Session preview (dernières lignes du dernier message assistant) — peek sans switcher
• Attention priority ordering (sessions "attend input" en haut) — priorisation naturelle
• Statusline i3bar widget — info passive, zero friction
• Multi-screen awareness — Pierre a 2 écrans, détecter sur quel output est le workspace

Defer (v2+) :

• Intégration piaire (lier session <-> ticket/feature) — haute valeur, haute complexité
• Keyboard shortcuts globaux i3 pour naviguer sans ouvrir vmux
• Historique des sessions

Architecture Approach

L'architecture retenue est daemon (vmuxd) + CLI client (vmux) communiquant via socket Unix. Le daemon maintient le registre des sessions en mémoire, reçoit les hooks HTTP de Claude Code, et distribue les changements d'état via channels Go internes aux consommateurs (TUI, notifier, i3bar). Cette architecture évite les problèmes de re-scan à chaque invocation et permet les notifications asynchrones.

Major components:

1. HTTP Hook Server — reçoit les events Claude Code (Stop, Notification, PreToolUse, PostToolUse) sur localhost:7483
2. Session Registry + State Machine — maintient l'état de toutes les sessions, transitions Working/Needs Input/Waiting/Inactive
3. JSONL Scanner — scan initial au démarrage + reconciliation toutes les 30s
4. i3 Bridge — associe sessions aux workspaces via GetTree() + /proc/PID/cwd, commandes workspace
5. Event Bus — channels Go, fan-out vers TUI, notifier, i3bar
6. Notifier — notify-send vers dunst sur transition vers "Needs Input"
7. TUI / CLI — couche présentation, query le daemon via socket Unix

Critical Pitfalls

1. JSONL parsing fragile — abstraire derrière une interface dès le départ (un seul session/parser.go). Le format est un détail d'implémentation non contractuel, il changera.

2. JSONL files géants (3.8 Go documenté) — ne JAMAIS charger un fichier JSONL en entier. Toujours tail-read (io.SeekEnd + remonter). Tester avec des fichiers > 100 Mo dès la Phase 1.

3. i3 IPC deadlock si events non consommés — goroutine dédiée exclusivement à recv.Next(), jamais bloquante. Sockets séparés pour requêtes et subscriptions.

4. Detection process non fiable par nom — croiser cmdline /proc/[pid]/cmdline + mtime JSONL + titre fenêtre i3. Jamais un seul signal.

5. inotify sans garantie de correction — utiliser inotify comme signal uniquement, toujours re-scanner après event. Compléter par un poll toutes les 2-3s.

Implications for Roadmap

L'ordre de construction est dicté par les dépendances identifiées dans ARCHITECTURE.md. Chaque phase doit être fonctionnelle de façon autonome pour valider le concept avant de construire la suivante.

Phase 1: Foundation — Session Discovery et State Detection

Rationale: Tout dépend de la capacité à trouver et interpréter les sessions. Sans ça, aucun autre composant n'a de données. Valide le concept sans aucune config Claude Code.

Delivers: Binaire CLI one-shot vmux list qui affiche les sessions Claude actives avec leur état. Pas de daemon, pas de TUI, juste la détection.

Addresses: Session discovery, state detection (Working/Needs Input/Idle)

Avoids: JSONL parsing fragile (abstraire l'interface dès le départ), JSONL memory (tail-read obligatoire), detection process (multi-signal dès le départ)

Phase 2: Daemon et i3 Integration

Rationale: La persistance d'état est nécessaire pour les notifications et le switch. L'i3 bridge a besoin du registry peuplé pour faire le mapping.

Delivers: vmuxd daemon + socket Unix + association sessions/workspaces + vmux switch <session> fonctionnel.

Addresses: Workspace i3 association, switch to workspace

Avoids: i3 IPC deadlock (goroutine dédiée events), mapping workspace instable (event window::move), i3 reload (tester la survie des subscriptions)

Phase 3: Hook Server et Réactivité

Rationale: Les hooks remplacent le polling comme source primaire. Nécessite que le registry (Phase 1) et le daemon (Phase 2) existent.

Delivers: Réception des hooks Claude Code, transitions d'état immédiates (< 1s), plus de dépendance au polling.

Addresses: State detection améliorée, latence notification

Avoids: Polling-only architecture (anti-pattern documenté), missed events (garder le scan JSONL comme reconciliation toutes les 30s)

Phase 4: Notifications et Présentation

Rationale: Couche de présentation et alertes, dépend de tout ce qui précède. Peut être TUI Bubble Tea ou widget i3bar selon les préférences après validation du core.

Delivers: Desktop notifications dunst sur transition vers "Needs Input", session list avec statut coloré, attention priority ordering.

Addresses: Desktop notifications, session list with status, attention priority ordering, session preview

Avoids: Notification spam (debounce 3s), force focus i3 automatique (notifier seulement, pas forcer), preview trop verbeux (1-2 lignes du dernier message assistant)

Phase 5: Polish et Features v1.x

Rationale: Features différenciatrices une fois le core validé sur usage réel.

Delivers: Widget i3bar (si TUI en Phase 4) ou TUI (si widget en Phase 4), multi-screen awareness, historique temps d'attente.

Addresses: Statusline i3bar widget, multi-screen awareness, "il y a N min" dans la liste

Phase Ordering Rationale

• Phases 1 et 2 en séquence stricte : le daemon a besoin du registry, l'i3 bridge a besoin du daemon
• Phase 3 après Phase 2 : les hooks alimentent le registry, donc le registry doit exister
• Phase 4 dernière : c'est de la présentation, elle consomme tout ce qui est en amont
• Pas de TUI en Phase 1 : valider la détection avant d'investir dans l'UI (recommandation STACK.md)
• Notifications en Phase 4 : elles dépendent de l'Event Bus qui est en Phase 2-3

Research Flags

Phases nécessitant une recherche approfondie lors du planning :

• Phase 2 (i3 Bridge): Mapping PID -> fenêtre -> workspace a plusieurs cas limites documentés. Nécessite des tests avec des cas réels (fenêtres déplacées, terminaux multiples dans un workspace, i3 reload).
• Phase 3 (Hook Server): La configuration des hooks Claude Code dans ~/.claude/settings.json doit être validée sur la version actuelle de Claude Code installée. Le format a évolué.

Phases avec patterns standard (pas de recherche nécessaire) :

• Phase 1 (Session Discovery): JSONL format vérifié sur la machine, /proc API stable Linux, patterns bien documentés.
• Phase 4 (Notifications): notify-send + dunst est trivial, Bubble Tea v2 a une documentation complète.

Confidence Assessment

Area	Confidence	Notes
Stack	HIGH	Vérifié sur machine cible (Go 1.25.7, i3 4.24, sessions Claude actives). Versions et imports confirmés.
Features	HIGH	Analyse comparative de 4+ outils concurrents. Scope bien délimité. Anti-features clairement identifiées.
Architecture	HIGH	Architecture hook-first confirmée par sources officielles Claude Code (hooks depuis début 2026). Patterns Go établis.
Pitfalls	MEDIUM-HIGH	6 pitfalls critiques avec sources primaires. Certains (inotify, JSONL OOM) basés sur issues GitHub documentées.

Overall confidence: HIGH

Gaps to Address

• Hook configuration format actuel : Les hooks Claude Code sont récents (début 2026). Le format exact de ~/.claude/settings.json doit être validé lors de la Phase 3 contre la version installée.
• sessions-index.json structure : Mentionné comme source d'index dans PITFALLS.md mais son format exact n'a pas été inspecté directement. À vérifier en Phase 1.
• Comportement multi-PTY : Quand plusieurs terminaux dans le même workspace pointent vers le même projet, la résolution PID -> workspace est ambiguë. Stratégie de tie-breaking à définir en Phase 2.

Sources

Primary (HIGH confidence)

• Machine locale (NixOS, i3 4.24, Go 1.25.7) — sessions Claude actives, JSONL inspecté, fenêtres i3 vérifiées, PTY mapping confirmé
• Claude Code Hooks reference — format des hooks, events disponibles
• go.i3wm.org/i3/v4 — API officielle i3 Go, EventReceiver, Restart()
• i3 IPC documentation — protocole, events, socket buffer

Secondary (MEDIUM confidence)

• agent-deck, dmux, amux, agentdock — analyse comparative features
• claude-sessions-monitor — valide l'approche JSONL + /proc
• Real-time dashboard implementation — patterns de monitoring JSONL
• Large JSONL issue #22365 — OOM documenté sur fichiers géants

Tertiary (LOW confidence)

• Correct or inotify: pick one — limitations inotify, contexte différent mais applicable
• i3 window::focus bug #3562 — bug fixé en 2018, vérifier non-regression sur i3 4.24

---

Research completed: 2026-03-23 Ready for roadmap: yes