docs: add README, licence WTFPL et documentation
- README.md : vision, installation, commandes, aperçu fonctionnement - LICENSE : WTFPL v2 - docs/architecture.md : composants, flux de données, index des fichiers - docs/i3-integration.md : config i3bar, switch, focus, dépannage - .gitignore : exclure .direnv/ Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Pierre Martin
101
docs/architecture.md
Normal file
101
docs/architecture.md
Normal file
@@ -0,0 +1,101 @@
|
||||
# Architecture
|
||||
|
||||
## Vue d'ensemble
|
||||
|
||||
vmux suit une architecture **daemon + CLI** classique. Un daemon unique tourne en arrière-plan ; toutes les commandes `vmux` communiquent avec lui via une Unix socket.
|
||||
|
||||
```
|
||||
Claude Code session
|
||||
│ hooks (HTTP localhost:3119)
|
||||
▼
|
||||
┌─────────────┐
|
||||
│ Daemon │◄── /proc scan (5s)
|
||||
│ │◄── JSONL reader (~/.claude/projects/)
|
||||
│ registry │◄── i3 IPC + X11 (workspace resolution)
|
||||
└──────┬──────┘
|
||||
│ Unix socket (~/.vmux/vmux.sock)
|
||||
▼
|
||||
vmux list / switch / label / focus / i3bar
|
||||
```
|
||||
|
||||
## Composants
|
||||
|
||||
### Daemon (`daemon.go`)
|
||||
|
||||
- Écoute sur `~/.vmux/vmux.sock` (Unix socket)
|
||||
- Lance un hook server HTTP sur `localhost:3119`
|
||||
- Maintient un `SessionRegistry` en mémoire (map sessionID → SessionInfo)
|
||||
- Poll `/proc` toutes les **5s** (ou **20s** si des hooks arrivent activement)
|
||||
|
||||
### Détection des processus (`proc.go`)
|
||||
|
||||
Scrute `/proc/*/cmdline` pour trouver les processus dont la commande contient `claude`. Pour chaque processus trouvé, lit :
|
||||
- `/proc/<pid>/cwd` — répertoire de travail courant
|
||||
- `/proc/<pid>/fd/0` — PTY associé (pour la résolution workspace)
|
||||
|
||||
### Lecture JSONL (`session.go`)
|
||||
|
||||
Claude Code écrit un fichier JSONL par session dans `~/.claude/projects/<encoded-cwd>/<uuid>.jsonl`. vmux associe un PID au bon fichier par correspondance du `cwd`, puis lit les messages pour extraire :
|
||||
- `sessionId`, `gitBranch` — identité de la session
|
||||
- `type: "assistant"` — dernier message Claude (pour le state et le preview)
|
||||
|
||||
### Détection d'état (`state.go`)
|
||||
|
||||
| État | Critère |
|
||||
|---|---|
|
||||
| `Working` | Dernier event hook = `PreToolUse` ou `PostToolUse` |
|
||||
| `Needs Input` | Dernier event hook = `Notification` ou `Stop` |
|
||||
| `Idle` | Aucun event récent, dernier message JSONL vieux de plus de 30s |
|
||||
|
||||
Les hooks Claude Code sont prioritaires sur la détection JSONL : ils arrivent en temps réel.
|
||||
|
||||
### Hooks Claude Code (`hook.go`)
|
||||
|
||||
Claude Code appelle `vmux hook` à chaque événement (via la config `~/.claude/settings.json`). Le binaire lit le JSON sur stdin et le transmet au daemon via la socket. Le daemon met à jour le registry et déclenche une notification si la session passe de `Working` à `Needs Input`.
|
||||
|
||||
### Résolution workspace i3 (`workspace.go`, `i3bridge.go`, `x11_resolver.go`)
|
||||
|
||||
1. `i3.GetTree()` — récupère l'arbre des fenêtres i3
|
||||
2. Pour chaque fenêtre avec "Claude Code" dans le titre : lit son PID via `_NET_WM_PID` (X11)
|
||||
3. Remonte la chaîne `/proc/<pid>/fd/0` → PTY → processus parent → PID Claude
|
||||
4. Associe le PID Claude au numéro de workspace i3
|
||||
|
||||
Dégradation gracieuse : si i3 ou X11 est indisponible, les workspaces restent vides (pas de crash).
|
||||
|
||||
### i3bar (`i3bar.go`)
|
||||
|
||||
Implémente le [protocole i3bar](https://i3wm.org/docs/i3bar-protocol.html). Tourne en boucle infinie, interroge le daemon toutes les 2s, écrit du JSON sur stdout.
|
||||
|
||||
### Notifications (`notify.go`)
|
||||
|
||||
Appelle `notify-send` avec `--urgency=critical` quand une session passe de `Working` à `Needs Input`. Le mode focus (`vmux focus <minutes>`) supprime les notifications pendant la durée donnée.
|
||||
|
||||
## Fichiers
|
||||
|
||||
| Fichier | Rôle |
|
||||
|---|---|
|
||||
| `main.go` | Entrypoint, routing des commandes CLI |
|
||||
| `daemon.go` | Daemon, registry, label store |
|
||||
| `proc.go` | Scan /proc pour les processus claude |
|
||||
| `session.go` | Lecture des fichiers JSONL Claude Code |
|
||||
| `state.go` | Détection d'état (Working/NeedsInput/Idle) |
|
||||
| `hook.go` | Réception et traitement des hooks Claude Code |
|
||||
| `workspace.go` | Résolution workspace via i3 tree |
|
||||
| `i3bridge.go` | Abstraction i3 IPC (testable) |
|
||||
| `x11_resolver.go` | Lecture _NET_WM_PID via XGB |
|
||||
| `i3bar.go` | Protocole i3bar |
|
||||
| `notify.go` | Notifications desktop (notify-send) |
|
||||
| `focus.go` | Timer de mode focus |
|
||||
| `display.go` | Affichage `vmux list` |
|
||||
| `client.go` | Client Unix socket |
|
||||
| `protocol.go` | Types Request/Response partagés |
|
||||
| `setup.go` | Injection des hooks dans settings.json |
|
||||
| `types.go` | Types de données (Session, SessionState…) |
|
||||
|
||||
## Données persistées
|
||||
|
||||
| Chemin | Contenu |
|
||||
|---|---|
|
||||
| `~/.vmux/vmux.sock` | Unix socket du daemon |
|
||||
| `~/.vmux/labels.json` | Labels assignés par l'utilisateur |
|
||||
| `~/.claude/settings.json` | Hooks Claude Code (modifié par `vmux setup`) |
|
||||
85
docs/i3-integration.md
Normal file
85
docs/i3-integration.md
Normal file
@@ -0,0 +1,85 @@
|
||||
# Intégration i3
|
||||
|
||||
## i3bar
|
||||
|
||||
Ajoutez `vmux i3bar` comme `status_command` dans votre `~/.config/i3/config` :
|
||||
|
||||
```
|
||||
bar {
|
||||
status_command vmux i3bar
|
||||
position top
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
Rechargez i3 (`$mod+Shift+r`). vmux démarre le daemon automatiquement si nécessaire.
|
||||
|
||||
### Format des blocs
|
||||
|
||||
Un bloc par session active, trié par numéro de workspace :
|
||||
|
||||
```
|
||||
3-vmux[W] 5-api[⚡ 45s] 7-front[? 3m]
|
||||
```
|
||||
|
||||
- `3-vmux` — workspace i3 + nom (label ou dernier composant du cwd)
|
||||
- `[W]` vert — Working
|
||||
- `[⚡ 45s]` rouge — Needs Input, type permission, en attente depuis 45s
|
||||
- `[?]` rouge — Needs Input, type question
|
||||
- `[!]` rouge — Needs Input, autre type
|
||||
- `[I]` gris — Idle
|
||||
- `[?]` gris — état inconnu
|
||||
|
||||
Si le daemon est offline : `vmux: offline`.
|
||||
Si aucune session détectée : `vmux: no sessions`.
|
||||
|
||||
## Commande switch
|
||||
|
||||
Basculez vers le workspace d'une session depuis votre terminal :
|
||||
|
||||
```sh
|
||||
vmux switch vmux # cherche une session dont le cwd ou label contient "vmux"
|
||||
vmux switch api
|
||||
```
|
||||
|
||||
La correspondance est fuzzy : le premier mot du workspace/label/cwd qui contient la query gagne.
|
||||
|
||||
Vous pouvez aussi lier cette commande à un raccourci i3 :
|
||||
|
||||
```
|
||||
bindsym $mod+F1 exec vmux switch feature-1
|
||||
bindsym $mod+F2 exec vmux switch feature-2
|
||||
```
|
||||
|
||||
## Notifications desktop
|
||||
|
||||
vmux envoie une notification `notify-send` quand une session passe de `Working` à `Needs Input`. Assurez-vous qu'un daemon de notification tourne (`dunst`, `mako`, etc.).
|
||||
|
||||
### Mode focus
|
||||
|
||||
Pour couper les notifications temporairement :
|
||||
|
||||
```sh
|
||||
vmux focus 30 # supprimer 30 minutes
|
||||
vmux focus 0 # réactiver immédiatement
|
||||
```
|
||||
|
||||
## Dépannage
|
||||
|
||||
**Le workspace n'apparaît pas dans `vmux list`**
|
||||
|
||||
vmux résout les workspaces via i3 IPC et X11. Vérifiez que `DISPLAY` est défini dans l'environnement du daemon. Si le daemon est lancé depuis un service systemd, il peut ne pas hériter de `DISPLAY`.
|
||||
|
||||
**Les hooks ne fonctionnent pas**
|
||||
|
||||
1. Vérifiez que `vmux setup` a été lancé et que `~/.claude/settings.json` contient les hooks
|
||||
2. Redémarrez les sessions Claude Code après `vmux setup`
|
||||
3. Le hook server écoute sur `localhost:3119` — vérifiez qu'aucun autre processus n'occupe ce port
|
||||
|
||||
**`vmux list` ne voit aucune session**
|
||||
|
||||
Le daemon scrute `/proc` pour les processus dont la commande contient `claude`. Vérifiez :
|
||||
```sh
|
||||
ps aux | grep claude
|
||||
```
|
||||
Si aucun processus n'apparaît, Claude Code n'est pas détecté. Vérifiez le nom du binaire sur votre système.
|
||||
Reference in New Issue
Block a user