## Project **vmux** Cockpit central pour le vibe coding. vmux donne une vue unifiée de toutes les sessions Claude Code qui tournent sur le poste, détecte leur état (travaille / attend input), affiche un aperçu de ce que chaque session fait ou demande, et permet de switcher vers le bon workspace i3. **Core Value:** Savoir instantanément quelle session Claude Code a besoin de moi, sans scanner manuellement mes workspaces. ### Constraints - **OS**: NixOS avec i3 — doit s'intégrer nativement (i3-msg, IPC i3) - **Stack existante**: piaire est en Go stdlib + HTMX — cohérence souhaitable si intégration - **Détection non-intrusive**: vmux observe les sessions sans les modifier ni les ralentir ## Technology Stack ## Recommended Stack ### Core Technologies | Technology | Version | Purpose | Why Recommended | |------------|---------|---------|-----------------| | Go | 1.25.x | Language | Deja utilise par piaire, coherence stack. Single binary, bon pour les outils CLI. Disponible via `nix-shell -p go`. | | Bubble Tea v2 | v2.x (charm.land/bubbletea/v2) | TUI framework | Standard de facto pour les TUI en Go (18k+ apps). Architecture Elm (Init/Update/View) qui structure bien le code. Le v2 apporte le renderer Cursed (base ncurses) et le mode 2026 (anti-tearing). | | go.i3wm.org/i3/v4 | v4.21+ | i3 IPC | Lib officielle du projet i3. Couvre 100% de l'API IPC. Gere automatiquement les reconnexions si i3 redemarre. Supporte les subscriptions (workspace events). | | fsnotify | v1.8+ | File watching | Surveiller les fichiers JSONL de `~/.claude/projects/` pour detecter l'activite des sessions. 13k+ importers, stable. | ### Supporting Libraries | Library | Version | Purpose | When to Use | |---------|---------|---------|-------------| | Lip Gloss v2 | v2.x (charm.land/lipgloss/v2) | Styling TUI | Mise en forme du dashboard (couleurs, bordures, layout). Compose naturellement avec Bubble Tea v2. | | Bubbles v2 | v2.x (charm.land/bubbles/v2) | TUI components | Composants pre-faits (list, table, spinner) pour le dashboard. Evite de tout coder from scratch. | | esiqveland/notify | v0.11+ | Desktop notifications | Envoyer des notifs D-Bus quand une session passe de "travaille" a "attend input". Alternative legere a libnotify. | | encoding/json (stdlib) | - | JSON parsing | Parser les JSONL des sessions Claude Code. Pas besoin de lib externe, le format est simple. | | os (stdlib) | - | Process inspection | Lire `/proc//status`, `/proc//cmdline` pour detecter les processus Claude. Pas besoin de prometheus/procfs pour ce cas simple. | | hpcloud/tail | v1.0+ | File tailing | Follow les fichiers JSONL en temps reel (comme `tail -f`). Alternative a fsnotify pour le cas specifique du suivi de fichiers qui grandissent. | ### Development Tools | Tool | Purpose | Notes | |------|---------|-------| | nix-shell | Environment dev | `nix-shell -p go gopls` pour avoir Go + LSP sans pollution globale | | goreleaser | Build & release | Single binary, cross-compile. Standard pour les outils Go distribues | | golangci-lint | Linting | Aggregateur de linters, couvre les erreurs courantes | ## Architecture Decision: Pas de lib pour /proc ## Architecture Decision: JSONL comme source primaire d'etat - `type` : "user", "assistant", "file-history-snapshot" - `timestamp` : ISO 8601 - `sessionId` : UUID - `cwd` : repertoire de travail - `gitBranch` : branche git courante - `version` : version de Claude Code - `message.content` : contenu du message - "Travaille" = le dernier evenement est de type "assistant" et recent (< 30s), ou le processus est actif CPU - "Attend input" = le dernier evenement est de type "assistant" (reponse terminee) et le processus idle - "Idle" = pas d'activite recente ## Architecture Decision: i3 tree comme source de mapping - `Claude Code` dans le titre de la fenetre - Le workspace numerote est directement accessible ## Installation # Nix shell pour le dev # Init module # Core # i3 IPC # File watching # Notifications ## Alternatives Considered | Recommended | Alternative | When to Use Alternative | |-------------|-------------|-------------------------| | Bubble Tea v2 | tview (rivo/tview) | Si on veut un style "formulaire terminal" classique (menus, tables, formulaires). Mais vmux est un dashboard de monitoring, l'archi Elm de Bubble Tea convient mieux. | | Bubble Tea v2 | Pas de TUI (CLI simple) | Si la v1 se limite a un `vmux status` one-shot. Commencer en CLI pure, migrer vers TUI quand le dashboard prend forme. **Recommande pour le MVP.** | | go.i3wm.org/i3/v4 | mdirkse/i3ipc-go | Si la lib officielle manque une feature. Mais elle couvre 100% de l'API IPC, pas de raison d'utiliser un fork. | | go.i3wm.org/i3/v4 | Executer `i3-msg` via os/exec | Si on veut eviter la dependance. Viable pour un prototype rapide, mais la lib Go gere les reconnexions et le parsing. | | fsnotify | Polling periodique | Si fsnotify pose des problemes avec NixOS/inotify limits. Le polling toutes les 2s est acceptable pour le use case. | | stdlib /proc | prometheus/procfs | Si on a besoin de metriques systeme avancees. Pas le cas pour vmux. | | esiqveland/notify | os/exec + notify-send | Plus simple, zero dependance. Viable si les notifs restent basiques (pas d'actions, pas d'icones). | ## What NOT to Use | Avoid | Why | Use Instead | |-------|-----|-------------| | Rust / Ratatui | Briserait la coherence avec piaire (Go). Le gain de perf n'a aucun interet pour un dashboard. | Go + Bubble Tea | | Python / Rich | Pas de single binary, runtime dependency, lent au demarrage. | Go | | prometheus/procfs | Trop lourd pour lire 3 champs dans /proc. API instable (WARNING dans leur doc). | Go stdlib (os.ReadFile) | | mitchellh/go-ps | Derniere release 2021. API minimaliste qui ne donne pas les FDs. | Go stdlib /proc scan | | Bubble Tea v1 | v2 est sorti, le renderer Cursed est meilleur. Pas de raison de partir sur l'ancienne version. | Bubble Tea v2 | | gRPC / API HTTP interne | Over-engineering pour un outil local single-user. | Channels Go internes | ## Stack Patterns by Variant - Binary unique `vmux` - Config dans `~/.config/vmux/` ou flags CLI - Pas de serveur, pas de port - vmux comme package Go importe par piaire - Partage du module Go, meme conventions - piaire expose le dashboard vmux dans son interface HTMX - Phase 1 : `vmux` en one-shot, affiche l'etat des sessions en tableau - Phase 2 : Mode watch (`vmux -w`) avec refresh periodique - Phase 3 : TUI interactive avec Bubble Tea - Cela permet de valider la detection avant d'investir dans la TUI ## Version Compatibility | Package | Compatible With | Notes | |---------|-----------------|-------| | Bubble Tea v2 | Go 1.22+ | Import path: `charm.land/bubbletea/v2` (pas `github.com/...`) | | Lip Gloss v2 | Bubble Tea v2 | Doivent etre upgrades ensemble | | Bubbles v2 | Bubble Tea v2, Lip Gloss v2 | Trio indissociable | | go.i3wm.org/i3/v4 | i3 4.x | Tags alignes sur les versions i3. v4.21+ pour i3 4.24 | | fsnotify v1.8 | Go 1.17+ | Utilise inotify sur Linux | | Go 1.25.x | NixOS current | Disponible dans nixpkgs stable | ## Verified on This Machine | Element | Value | Source | |---------|-------|--------| | Go version (nix) | 1.25.7 | `nix-shell -p go --run "go version"` | | i3 version | 4.24 | `i3-msg -t get_version` | | Claude processes | 4 actifs (PID 6938, 10466, 13736, 16030) | `ps aux` | | Session storage | `~/.claude/projects//.jsonl` | Verifie sur le poste | | JSONL fields cles | type, timestamp, sessionId, cwd, gitBranch, message | Verifie par lecture directe | | i3 window names | Contiennent "Claude Code" | `i3-msg -t get_tree` | | PTY mapping | `/proc//fd/0` -> `/dev/pts/X` | Verifie sur PID 6938 | ## Sources - [Bubble Tea GitHub](https://github.com/charmbracelet/bubbletea) - v2 release, 18k+ apps - [Bubble Tea v2 release notes](https://github.com/charmbracelet/bubbletea/releases/tag/v2.0.0) - Cursed renderer, mode 2026 - [go.i3wm.org/i3/v4](https://pkg.go.dev/go.i3wm.org/i3/v4) - Official i3 Go package, published Mar 2025 - [i3 IPC docs](https://i3wm.org/docs/ipc.html) - Protocol reference - [fsnotify](https://github.com/fsnotify/fsnotify) - Cross-platform file watcher, 13k+ importers - [esiqveland/notify](https://github.com/esiqveland/notify) - D-Bus notification Go library - [Claude Code CLI reference](https://code.claude.com/docs/en/cli-reference) - Session management docs - [claude-code-log](https://github.com/daaain/claude-code-log) - Confirms JSONL format structure - Machine locale (NixOS, i3 4.24, Go 1.25.7) - Verified by direct inspection ## Conventions Conventions not yet established. Will populate as patterns emerge during development. ## Architecture Architecture not yet mapped. Follow existing patterns found in the codebase. ## GSD Workflow Enforcement Before using Edit, Write, or other file-changing tools, start work through a GSD command so planning artifacts and execution context stay in sync. Use these entry points: - `/gsd:quick` for small fixes, doc updates, and ad-hoc tasks - `/gsd:debug` for investigation and bug fixing - `/gsd:execute-phase` for planned phase work Do not make direct repo edits outside a GSD workflow unless the user explicitly asks to bypass it. ## Developer Profile > Profile not yet configured. Run `/gsd:profile-user` to generate your developer profile. > This section is managed by `generate-claude-profile` -- do not edit manually.