diff --git a/.planning/phases/02-daemon-et-i3-bridge/02-CONTEXT.md b/.planning/phases/02-daemon-et-i3-bridge/02-CONTEXT.md new file mode 100644 index 0000000..e01d307 --- /dev/null +++ b/.planning/phases/02-daemon-et-i3-bridge/02-CONTEXT.md @@ -0,0 +1,101 @@ +# 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 "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 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. + + + + +## 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 + + + + +## 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* diff --git a/.planning/phases/02-daemon-et-i3-bridge/02-DISCUSSION-LOG.md b/.planning/phases/02-daemon-et-i3-bridge/02-DISCUSSION-LOG.md new file mode 100644 index 0000000..3ebf428 --- /dev/null +++ b/.planning/phases/02-daemon-et-i3-bridge/02-DISCUSSION-LOG.md @@ -0,0 +1,83 @@ +# Phase 2: Daemon et i3 Bridge - Discussion Log + +> **Audit trail only.** Do not use as input to planning, research, or execution agents. +> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered. + +**Date:** 2026-03-23 +**Phase:** 02-daemon-et-i3-bridge +**Areas discussed:** Daemon design, i3 workspace mapping, Lib i3, Label & switch UX + +--- + +## Daemon design + +### Communication +| Option | Description | Selected | +|--------|-------------|----------| +| Unix socket | vmuxd écoute sur ~/.vmux/vmux.sock, JSON protocol | ✓ | +| HTTP localhost | API HTTP sur port local, compatible curl/piaire | | +| Tu décides | | | + +### Polling interval +| Option | Description | Selected | +|--------|-------------|----------| +| 2 secondes | Bon compromis réactivité/perf | | +| 5 secondes | Plus économe, suffisant avant hooks push | ✓ | +| Tu décides | | | + +### Lifecycle +| Option | Description | Selected | +|--------|-------------|----------| +| Autostart | vmux list démarre vmuxd auto si pas running. vmux stop pour arrêter | ✓ | +| Manuel | vmuxd lancé manuellement (i3 config) | | +| Tu décides | | | + +--- + +## i3 workspace mapping + +### Strategy +| Option | Description | Selected | +|--------|-------------|----------| +| PID → fenêtre i3 | Croiser PID Claude avec arbre i3 pour trouver workspace | ✓ | +| Cwd → workspace name | Convention nommage workspaces | | +| Tu décides | | | + +### Multi-session par workspace +| Option | Description | Selected | +|--------|-------------|----------| +| Toutes listées | Afficher toutes, même workspace | ✓ | +| Tu décides | | | + +--- + +## Lib i3 + +| Option | Description | Selected | +|--------|-------------|----------| +| go.i3wm.org/i3/v4 | Lib officielle Go, API propre | ✓ | +| i3-msg subprocess | Plus simple, plus fragile | | +| Tu décides | | | + +--- + +## Label & switch UX + +| Option | Description | Selected | +|--------|-------------|----------| +| Index numérique | vmux switch 1 | | +| Branche git | vmux switch feature/auth | | +| Fuzzy match | vmux switch auth (matche branche, label, cwd) | ✓ | +| Tu décides | | | + +--- + +## Claude's Discretion + +- Format JSON sur Unix socket +- PID file management +- Fallback si i3 non disponible + +## Deferred Ideas + +None