vmux/.planning/phases/02-daemon-et-i3-bridge/02-CONTEXT.md

Phase 2: Daemon et i3 Bridge - Context

Gathered: 2026-03-23 Status: Ready for planning

## Phase Boundary

Daemon persistant (vmuxd) qui maintient un registre des sessions à jour, mapping sessions → workspaces i3, switch vers un workspace en une action, labels humains, temps d'attente relatif. Réutilise la détection /proc + JSONL de Phase 1.

## Implementation Decisions

Daemon architecture

• D-01: vmuxd communique avec le CLI via un Unix socket (~/.vmux/vmux.sock). Protocole JSON sur le socket.
• D-02: vmuxd poll /proc + JSONL toutes les 5 secondes pour mettre à jour le registre des sessions. La Phase 3 (hooks) réduira la latence à < 1s.
• D-03: Autostart : vmux list (ou tout autre commande) démarre vmuxd automatiquement s'il ne tourne pas. vmux stop pour arrêter proprement.

i3 integration

• D-04: Mapping session → workspace via le PID. i3 GetTree() donne le PID de chaque fenêtre terminal ; on croise avec le PID du processus Claude Code pour trouver le workspace.
• D-05: Si plusieurs sessions Claude Code sont dans le même workspace i3, elles sont toutes listées avec le même workspace.
• D-06: Utiliser go.i3wm.org/i3/v4 (lib officielle Go pour i3 IPC). Première dépendance externe du projet. API : GetTree, GetWorkspaces, RunCommand.

CLI UX

• D-07: vmux switch utilise du fuzzy match : vmux switch auth matche la première session contenant "auth" dans branche git, label ou cwd.
• D-08: vmux label <session> "texte" attribue un label humain. Le label est stocké en mémoire dans vmuxd (persisté sur disque dans ~/.vmux/labels.json pour survivre aux redémarrages).

Temps d'attente

• D-09: Le daemon track les transitions d'état. Quand une session passe à NeedsInput, il enregistre le timestamp. vmux list affiche "depuis X min".

Claude's Discretion

• Format de communication JSON sur le Unix socket (structure des requêtes/réponses)
• Gestion du PID file pour le daemon
• Gestion des erreurs de connexion i3 IPC (fallback gracieux si i3 non disponible)

<canonical_refs>

Canonical References

Downstream agents MUST read these before planning or implementing.

Existing codebase (Phase 1)

• types.go — Types Process, Session, SessionState. Session sera enrichie avec le champ Workspace.
• proc.go — FindClaudeProcesses(), EncodePath(). Réutilisé tel quel par le daemon.
• session.go — FindSessionForProcess(), TailReadJSONL(). Réutilisé tel quel.
• state.go — DetectState(), ExtractPreview(). Réutilisé tel quel.
• display.go — DisplaySessions(). Sera étendu pour afficher workspace, label, temps d'attente.
• main.go — Point d'entrée CLI. Sera refondu pour supporter les sous-commandes (list, switch, label, stop).

i3 IPC

• go.i3wm.org/i3/v4 — Lib officielle. GetTree() pour l'arbre des fenêtres, GetWorkspaces() pour la liste, RunCommand() pour switcher.

</canonical_refs>

<code_context>

Existing Code Insights

Reusable Assets

• FindClaudeProcesses("/proc") → []Process — scan /proc, retourne PID + Cwd
• FindSessionForProcess(claudeDir, proc) → (jsonlPath, messages, err) — matching JSONL
• DetectState(messages, now) → SessionState — heuristique Working/NeedsInput/Idle
• ExtractPreview(messages) → string — dernières lignes de sortie
• DisplaySessions(w, sessions, noColor) — affichage coloré

Established Patterns

• Package main unique à la racine (pas de sous-packages internal/)
• Go stdlib only (sauf go.i3wm.org/i3/v4 qui arrive en Phase 2)
• Tests avec fixtures fichiers temporaires (tmpDir pattern)
• Flag parsing avec flag stdlib

Integration Points

• main.go est le point d'entrée CLI, à refactorer pour supporter daemon + sous-commandes
• Session struct dans types.go à enrichir (Workspace, Label, WaitingSince)
• DisplaySessions dans display.go à étendre pour les nouveaux champs

</code_context>

## Specific Ideas

• Le daemon réutilise exactement les fonctions Phase 1 dans sa boucle de scan
• Le PID matching i3 nécessite de traverser l'arbre i3 : chaque node a un PID, on le croise avec nos PIDs Claude
• Les labels persistent dans ~/.vmux/labels.json (map session_id → label)
• Le fuzzy match pour vmux switch cherche dans : label > branche git > dernier segment du cwd

## Deferred Ideas

None — discussion stayed within phase scope

---

Phase: 02-daemon-et-i3-bridge Context gathered: 2026-03-23