vmux/README.md

vmux

Cockpit pour le vibe coding. vmux surveille toutes vos sessions Claude Code actives, détecte leur état (travaille / attend input / idle), et vous notifie quand l'une d'elles a besoin de vous.

Problème résolu : savoir instantanément quelle session Claude Code attend votre attention, sans scanner manuellement vos workspaces i3.

Aperçu

2-vmux[W]  3-api[⚡ 2m]  5-front[?]

Chaque bloc i3bar représente une session. Les indicateurs :

• [W] vert — Claude travaille
• [⚡ 2m] rouge — attend une permission (depuis 2 min)
• [?] rouge — attend une réponse
• [I] gris — idle

Prérequis

• Linux avec i3 WM
• Go 1.22+ (build uniquement)
• notify-send (paquet libnotify)
• X11

Installation

# Cloner et builder
git clone https://gitea.example.com/pieMusic/vmux
cd vmux
make build

# Installer le binaire
install -m755 vmux ~/.local/bin/vmux

# Configurer les hooks Claude Code (idempotent)
vmux setup

vmux setup injecte des hooks dans ~/.claude/settings.json pour les événements Notification, Stop, PostToolUse et PreToolUse. Redémarrez vos sessions Claude Code après.

Configuration i3

Ajoutez vmux i3bar comme status_command dans votre config i3 :

bar {
    status_command vmux i3bar
    ...
}

Puis rechargez i3 : $mod+Shift+r.

Commandes

Commande	Description
vmux list	Lister les sessions actives
vmux switch <query>	Basculer vers le workspace i3 de la session
vmux label <id> <texte>	Assigner un label à une session
vmux focus <minutes>	Couper les notifications pendant N minutes
vmux stop	Arrêter le daemon
vmux setup	Configurer les hooks Claude Code
vmux i3bar	Lancer la sortie i3bar (usage : config i3)

Exemples

# Voir l'état de toutes les sessions
vmux list

# Switcher vers la session "vmux" ou "api"
vmux switch vmux
vmux switch api

# Nommer une session (accepte un UUID partiel)
vmux label abc123 "refacto auth"

# Couper les notifs 30 minutes (focus session de travail)
vmux focus 30
vmux focus 0   # réactiver immédiatement

Comment ça marche

Le daemon (~/.vmux/vmux.sock) tourne en arrière-plan, lancé automatiquement par la première commande vmux. Il :

1. Scrute /proc toutes les 5s pour détecter les processus claude
2. Lit les fichiers JSONL de ~/.claude/projects/ pour obtenir l'état et le contexte de chaque session
3. Reçoit les hooks de Claude Code sur localhost:3119 pour des mises à jour temps réel
4. Résout les workspaces i3 via IPC + X11 (quel workspace contient quel terminal)
5. Envoie une notification notify-send quand une session passe de "Working" à "Needs Input"

Voir docs/architecture.md pour le détail technique.

Développement

# Environnement Nix
nix-shell

# Build + watch
make watch

# Tests
make test

Licence

WTFPL — Do What The Fuck You Want To Public License.