vmux/.planning/ROADMAP.md

Roadmap: vmux

Overview

vmux passe de zero a un cockpit fonctionnel en 4 phases. La Phase 1 valide la detection (trouver les sessions, connaitre leur etat) via un CLI one-shot. La Phase 2 ajoute la persistance (daemon) et l'integration i3 (mapper sessions aux workspaces, switcher). La Phase 3 branche les hooks Claude Code pour une detection push et une distinction fine des types d'attente. La Phase 4 ajoute les notifications desktop et le widget i3bar.

Phases

Phase Numbering:

• Integer phases (1, 2, 3): Planned milestone work
• Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)

Decimal phases appear between their surrounding integers in numeric order.

• Phase 1: Session Discovery - CLI one-shot qui detecte les sessions Claude Code et affiche leur etat
• Phase 2: Daemon et i3 Bridge - Daemon persistant, mapping sessions/workspaces, switch en une action
• Phase 3: Hook Server - Detection push via hooks Claude Code, distinction fine des types d'attente
• Phase 4: Notifications et i3bar - Alertes desktop et widget statusline

Phase Details

Phase 1: Session Discovery

Goal: L'utilisateur peut lancer vmux list et voir toutes ses sessions Claude Code actives avec leur etat Depends on: Nothing (first phase) Requirements: DISC-01, DISC-02, DISC-03, STATE-01, STATE-02 Success Criteria (what must be TRUE):

1. vmux list affiche toutes les sessions Claude Code actives sur le poste (aucune session manquante)
2. Chaque session affiche son cwd, worktree git et branche git
3. Chaque session affiche son etat : Working, Needs Input ou Idle
4. Chaque session affiche un apercu des dernieres lignes de sortie Plans: 2 plans

Plans:

• 01-01-PLAN.md — Scaffolding projet Go + detection des processus Claude via /proc
• 01-02-PLAN.md — Parsing JSONL, heuristique d'etat et CLI vmux list

Phase 2: Daemon et i3 Bridge

Goal: L'utilisateur peut switcher vers n'importe quelle session Claude Code en une action via son workspace i3 Depends on: Phase 1 Requirements: DISC-04, I3-01, I3-02, STATE-04 Success Criteria (what must be TRUE):

1. vmuxd tourne en arriere-plan et maintient le registre des sessions a jour
2. Chaque session est associee a son workspace i3 (visible dans vmux list)
3. vmux switch <session> bascule vers le workspace i3 correspondant
4. L'utilisateur peut attribuer un label humain a une session (vmux label <session> "review MR !456")
5. Chaque session en attente affiche le temps ecoule ("depuis 3 min") Plans: TBD

Plans:

• 02-01: TBD
• 02-02: TBD

Phase 3: Hook Server

Goal: Les transitions d'etat sont detectees en moins d'une seconde grace aux hooks push de Claude Code Depends on: Phase 2 Requirements: STATE-03 Success Criteria (what must be TRUE):

1. vmuxd recoit les events hook de Claude Code (PreToolUse, PostToolUse, Stop, Notification) sur un port local
2. Les transitions d'etat apparaissent dans vmux list en moins d'une seconde apres l'event reel
3. vmux distingue le type d'attente : permission prompt, question utilisateur, idle prompt Plans: 2 plans

Plans:

• 03-01-PLAN.md — HookEvent types, processHookEvent mapping, HTTP handler, WaitType dans SessionInfo
• 03-02-PLAN.md — Hook server integre au daemon, poll dynamique, affichage WaitType

Phase 4: Notifications et i3bar

Goal: L'utilisateur est notifie passivement quand une session a besoin de lui, sans ouvrir vmux Depends on: Phase 3 Requirements: NOTIF-01, NOTIF-02, I3-03 Success Criteria (what must be TRUE):

1. Une notification dunst apparait quand une session passe de "Working" a "Needs Input"
2. Le mode focus supprime temporairement les notifications (vmux focus on/off)
3. Un widget i3bar affiche en temps reel le nombre de sessions et combien attendent de l'input Plans: TBD

Plans:

• 04-01: TBD
• 04-02: TBD

Progress

Execution Order: Phases execute in numeric order: 1 -> 2 -> 3 -> 4

Phase	Plans Complete	Status	Completed
1. Session Discovery	0/2	Not started	-
2. Daemon et i3 Bridge	0/2	Not started	-
3. Hook Server	0/2	Not started	-
4. Notifications et i3bar	0/2	Not started	-