# Phase 2: Daemon et i3 Bridge - Context

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

<domain>
## 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.

</domain>

<decisions>
## 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)

</decisions>

<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>

<specifics>
## 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

</specifics>

<deferred>
## Deferred Ideas

None — discussion stayed within phase scope

</deferred>

---

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