diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index 7d7e51d..efe155d 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -66,25 +66,25 @@ Which phases cover which requirements. Updated during roadmap creation. | Requirement | Phase | Status | |-------------|-------|--------| -| DISC-01 | - | Pending | -| DISC-02 | - | Pending | -| DISC-03 | - | Pending | -| DISC-04 | - | Pending | -| STATE-01 | - | Pending | -| STATE-02 | - | Pending | -| STATE-03 | - | Pending | -| STATE-04 | - | Pending | -| I3-01 | - | Pending | -| I3-02 | - | Pending | -| I3-03 | - | Pending | -| NOTIF-01 | - | Pending | -| NOTIF-02 | - | Pending | +| DISC-01 | Phase 1 | Pending | +| DISC-02 | Phase 1 | Pending | +| DISC-03 | Phase 1 | Pending | +| DISC-04 | Phase 2 | Pending | +| STATE-01 | Phase 1 | Pending | +| STATE-02 | Phase 1 | Pending | +| STATE-03 | Phase 3 | Pending | +| STATE-04 | Phase 2 | Pending | +| I3-01 | Phase 2 | Pending | +| I3-02 | Phase 2 | Pending | +| I3-03 | Phase 4 | Pending | +| NOTIF-01 | Phase 4 | Pending | +| NOTIF-02 | Phase 4 | Pending | **Coverage:** - v1 requirements: 13 total -- Mapped to phases: 0 -- Unmapped: 13 ⚠️ +- Mapped to phases: 13 +- Unmapped: 0 --- *Requirements defined: 2026-03-23* -*Last updated: 2026-03-23 after initial definition* +*Last updated: 2026-03-23 after roadmap creation* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md new file mode 100644 index 0000000..ee6c99e --- /dev/null +++ b/.planning/ROADMAP.md @@ -0,0 +1,90 @@ +# 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**: TBD + +Plans: +- [ ] 01-01: TBD +- [ ] 01-02: TBD + +### 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 ` bascule vers le workspace i3 correspondant + 4. L'utilisateur peut attribuer un label humain a une session (`vmux label "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**: TBD + +Plans: +- [ ] 03-01: TBD + +### 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/1 | Not started | - | +| 4. Notifications et i3bar | 0/2 | Not started | - | diff --git a/.planning/STATE.md b/.planning/STATE.md new file mode 100644 index 0000000..d29a0fe --- /dev/null +++ b/.planning/STATE.md @@ -0,0 +1,60 @@ +# Project State + +## Project Reference + +See: .planning/PROJECT.md (updated 2026-03-23) + +**Core value:** Savoir instantanement quelle session Claude Code a besoin de moi, sans scanner manuellement mes workspaces. +**Current focus:** Phase 1 - Session Discovery + +## Current Position + +Phase: 1 of 4 (Session Discovery) +Plan: 0 of 2 in current phase +Status: Ready to plan +Last activity: 2026-03-23 — Roadmap created + +Progress: [░░░░░░░░░░] 0% + +## Performance Metrics + +**Velocity:** +- Total plans completed: 0 +- Average duration: - +- Total execution time: 0 hours + +**By Phase:** + +| Phase | Plans | Total | Avg/Plan | +|-------|-------|-------|----------| +| - | - | - | - | + +**Recent Trend:** +- Last 5 plans: - +- Trend: - + +*Updated after each plan completion* + +## Accumulated Context + +### Decisions + +Decisions are logged in PROJECT.md Key Decisions table. +Recent decisions affecting current work: + +- Roadmap: CLI one-shot en Phase 1 (pas de daemon), daemon en Phase 2, hooks en Phase 3 +- Roadmap: 4 phases derives des 4 categories de requirements + +### Pending Todos + +None yet. + +### Blockers/Concerns + +None yet. + +## Session Continuity + +Last session: 2026-03-23 +Stopped at: Roadmap created, ready to plan Phase 1 +Resume file: None diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..4b78246 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,158 @@ + +## Project + +**vmux** + +Cockpit central pour le vibe coding. vmux donne une vue unifiée de toutes les sessions Claude Code qui tournent sur le poste, détecte leur état (travaille / attend input), affiche un aperçu de ce que chaque session fait ou demande, et permet de switcher vers le bon workspace i3. + +**Core Value:** Savoir instantanément quelle session Claude Code a besoin de moi, sans scanner manuellement mes workspaces. + +### Constraints + +- **OS**: NixOS avec i3 — doit s'intégrer nativement (i3-msg, IPC i3) +- **Stack existante**: piaire est en Go stdlib + HTMX — cohérence souhaitable si intégration +- **Détection non-intrusive**: vmux observe les sessions sans les modifier ni les ralentir + + + +## Technology Stack + +## Recommended Stack +### Core Technologies +| Technology | Version | Purpose | Why Recommended | +|------------|---------|---------|-----------------| +| Go | 1.25.x | Language | Deja utilise par piaire, coherence stack. Single binary, bon pour les outils CLI. Disponible via `nix-shell -p go`. | +| Bubble Tea v2 | v2.x (charm.land/bubbletea/v2) | TUI framework | Standard de facto pour les TUI en Go (18k+ apps). Architecture Elm (Init/Update/View) qui structure bien le code. Le v2 apporte le renderer Cursed (base ncurses) et le mode 2026 (anti-tearing). | +| go.i3wm.org/i3/v4 | v4.21+ | i3 IPC | Lib officielle du projet i3. Couvre 100% de l'API IPC. Gere automatiquement les reconnexions si i3 redemarre. Supporte les subscriptions (workspace events). | +| fsnotify | v1.8+ | File watching | Surveiller les fichiers JSONL de `~/.claude/projects/` pour detecter l'activite des sessions. 13k+ importers, stable. | +### Supporting Libraries +| Library | Version | Purpose | When to Use | +|---------|---------|---------|-------------| +| Lip Gloss v2 | v2.x (charm.land/lipgloss/v2) | Styling TUI | Mise en forme du dashboard (couleurs, bordures, layout). Compose naturellement avec Bubble Tea v2. | +| Bubbles v2 | v2.x (charm.land/bubbles/v2) | TUI components | Composants pre-faits (list, table, spinner) pour le dashboard. Evite de tout coder from scratch. | +| esiqveland/notify | v0.11+ | Desktop notifications | Envoyer des notifs D-Bus quand une session passe de "travaille" a "attend input". Alternative legere a libnotify. | +| encoding/json (stdlib) | - | JSON parsing | Parser les JSONL des sessions Claude Code. Pas besoin de lib externe, le format est simple. | +| os (stdlib) | - | Process inspection | Lire `/proc//status`, `/proc//cmdline` pour detecter les processus Claude. Pas besoin de prometheus/procfs pour ce cas simple. | +| hpcloud/tail | v1.0+ | File tailing | Follow les fichiers JSONL en temps reel (comme `tail -f`). Alternative a fsnotify pour le cas specifique du suivi de fichiers qui grandissent. | +### Development Tools +| Tool | Purpose | Notes | +|------|---------|-------| +| nix-shell | Environment dev | `nix-shell -p go gopls` pour avoir Go + LSP sans pollution globale | +| goreleaser | Build & release | Single binary, cross-compile. Standard pour les outils Go distribues | +| golangci-lint | Linting | Aggregateur de linters, couvre les erreurs courantes | +## Architecture Decision: Pas de lib pour /proc +## Architecture Decision: JSONL comme source primaire d'etat +- `type` : "user", "assistant", "file-history-snapshot" +- `timestamp` : ISO 8601 +- `sessionId` : UUID +- `cwd` : repertoire de travail +- `gitBranch` : branche git courante +- `version` : version de Claude Code +- `message.content` : contenu du message +- "Travaille" = le dernier evenement est de type "assistant" et recent (< 30s), ou le processus est actif CPU +- "Attend input" = le dernier evenement est de type "assistant" (reponse terminee) et le processus idle +- "Idle" = pas d'activite recente +## Architecture Decision: i3 tree comme source de mapping +- `Claude Code` dans le titre de la fenetre +- Le workspace numerote est directement accessible +## Installation +# Nix shell pour le dev +# Init module +# Core +# i3 IPC +# File watching +# Notifications +## Alternatives Considered +| Recommended | Alternative | When to Use Alternative | +|-------------|-------------|-------------------------| +| Bubble Tea v2 | tview (rivo/tview) | Si on veut un style "formulaire terminal" classique (menus, tables, formulaires). Mais vmux est un dashboard de monitoring, l'archi Elm de Bubble Tea convient mieux. | +| Bubble Tea v2 | Pas de TUI (CLI simple) | Si la v1 se limite a un `vmux status` one-shot. Commencer en CLI pure, migrer vers TUI quand le dashboard prend forme. **Recommande pour le MVP.** | +| go.i3wm.org/i3/v4 | mdirkse/i3ipc-go | Si la lib officielle manque une feature. Mais elle couvre 100% de l'API IPC, pas de raison d'utiliser un fork. | +| go.i3wm.org/i3/v4 | Executer `i3-msg` via os/exec | Si on veut eviter la dependance. Viable pour un prototype rapide, mais la lib Go gere les reconnexions et le parsing. | +| fsnotify | Polling periodique | Si fsnotify pose des problemes avec NixOS/inotify limits. Le polling toutes les 2s est acceptable pour le use case. | +| stdlib /proc | prometheus/procfs | Si on a besoin de metriques systeme avancees. Pas le cas pour vmux. | +| esiqveland/notify | os/exec + notify-send | Plus simple, zero dependance. Viable si les notifs restent basiques (pas d'actions, pas d'icones). | +## What NOT to Use +| Avoid | Why | Use Instead | +|-------|-----|-------------| +| Rust / Ratatui | Briserait la coherence avec piaire (Go). Le gain de perf n'a aucun interet pour un dashboard. | Go + Bubble Tea | +| Python / Rich | Pas de single binary, runtime dependency, lent au demarrage. | Go | +| prometheus/procfs | Trop lourd pour lire 3 champs dans /proc. API instable (WARNING dans leur doc). | Go stdlib (os.ReadFile) | +| mitchellh/go-ps | Derniere release 2021. API minimaliste qui ne donne pas les FDs. | Go stdlib /proc scan | +| Bubble Tea v1 | v2 est sorti, le renderer Cursed est meilleur. Pas de raison de partir sur l'ancienne version. | Bubble Tea v2 | +| gRPC / API HTTP interne | Over-engineering pour un outil local single-user. | Channels Go internes | +## Stack Patterns by Variant +- Binary unique `vmux` +- Config dans `~/.config/vmux/` ou flags CLI +- Pas de serveur, pas de port +- vmux comme package Go importe par piaire +- Partage du module Go, meme conventions +- piaire expose le dashboard vmux dans son interface HTMX +- Phase 1 : `vmux` en one-shot, affiche l'etat des sessions en tableau +- Phase 2 : Mode watch (`vmux -w`) avec refresh periodique +- Phase 3 : TUI interactive avec Bubble Tea +- Cela permet de valider la detection avant d'investir dans la TUI +## Version Compatibility +| Package | Compatible With | Notes | +|---------|-----------------|-------| +| Bubble Tea v2 | Go 1.22+ | Import path: `charm.land/bubbletea/v2` (pas `github.com/...`) | +| Lip Gloss v2 | Bubble Tea v2 | Doivent etre upgrades ensemble | +| Bubbles v2 | Bubble Tea v2, Lip Gloss v2 | Trio indissociable | +| go.i3wm.org/i3/v4 | i3 4.x | Tags alignes sur les versions i3. v4.21+ pour i3 4.24 | +| fsnotify v1.8 | Go 1.17+ | Utilise inotify sur Linux | +| Go 1.25.x | NixOS current | Disponible dans nixpkgs stable | +## Verified on This Machine +| Element | Value | Source | +|---------|-------|--------| +| Go version (nix) | 1.25.7 | `nix-shell -p go --run "go version"` | +| i3 version | 4.24 | `i3-msg -t get_version` | +| Claude processes | 4 actifs (PID 6938, 10466, 13736, 16030) | `ps aux` | +| Session storage | `~/.claude/projects//.jsonl` | Verifie sur le poste | +| JSONL fields cles | type, timestamp, sessionId, cwd, gitBranch, message | Verifie par lecture directe | +| i3 window names | Contiennent "Claude Code" | `i3-msg -t get_tree` | +| PTY mapping | `/proc//fd/0` -> `/dev/pts/X` | Verifie sur PID 6938 | +## Sources +- [Bubble Tea GitHub](https://github.com/charmbracelet/bubbletea) - v2 release, 18k+ apps +- [Bubble Tea v2 release notes](https://github.com/charmbracelet/bubbletea/releases/tag/v2.0.0) - Cursed renderer, mode 2026 +- [go.i3wm.org/i3/v4](https://pkg.go.dev/go.i3wm.org/i3/v4) - Official i3 Go package, published Mar 2025 +- [i3 IPC docs](https://i3wm.org/docs/ipc.html) - Protocol reference +- [fsnotify](https://github.com/fsnotify/fsnotify) - Cross-platform file watcher, 13k+ importers +- [esiqveland/notify](https://github.com/esiqveland/notify) - D-Bus notification Go library +- [Claude Code CLI reference](https://code.claude.com/docs/en/cli-reference) - Session management docs +- [claude-code-log](https://github.com/daaain/claude-code-log) - Confirms JSONL format structure +- Machine locale (NixOS, i3 4.24, Go 1.25.7) - Verified by direct inspection + + + +## Conventions + +Conventions not yet established. Will populate as patterns emerge during development. + + + +## Architecture + +Architecture not yet mapped. Follow existing patterns found in the codebase. + + + +## GSD Workflow Enforcement + +Before using Edit, Write, or other file-changing tools, start work through a GSD command so planning artifacts and execution context stay in sync. + +Use these entry points: +- `/gsd:quick` for small fixes, doc updates, and ad-hoc tasks +- `/gsd:debug` for investigation and bug fixing +- `/gsd:execute-phase` for planned phase work + +Do not make direct repo edits outside a GSD workflow unless the user explicitly asks to bypass it. + + + + + +## Developer Profile + +> Profile not yet configured. Run `/gsd:profile-user` to generate your developer profile. +> This section is managed by `generate-claude-profile` -- do not edit manually. +