pierre/vmux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f9a53632a3128ff953a22366a4b2baae0db6dfdc
vmux/.planning/research/FEATURES.md
Pierre Martin 3030b88057 docs: complete project research
2026-03-23 11:25:05 +01:00

13 KiB
Raw Blame History

Feature Research

Domain: AI session management / desktop workspace orchestration Researched: 2026-03-23 Confidence: HIGH

Feature Landscape

Table Stakes (Users Expect These)

Features users assume exist. Missing these = product feels incomplete.

Feature Why Expected Complexity Notes
Session discovery Sans detection automatique des sessions Claude Code, l'outil n'a aucun sens. Tous les concurrents (agent-deck, dmux, amux, agentdock) font ca. MEDIUM Poll des process claude via /proc + lecture des fichiers JSONL dans ~/.claude/projects/. Refresh toutes les 2-3s.
State detection (working / waiting / idle) Le coeur de la valeur. agent-deck utilise un modele 3 etats (running/waiting/idle), amux ajoute "needs input" et "stuck". C'est le minimum pour savoir ou porter son attention. MEDIUM Parsing du dernier entry JSONL de la session + detection de process activity. Les hooks Claude Code (notification event avec idle_prompt, permission_prompt) sont la source la plus fiable.
Session list with status Tous les outils du domaine affichent une liste de sessions avec indicateur visuel de statut. Sans ca, on revient au scan manuel des workspaces. LOW Liste filtrable avec couleurs : vert (travaille), jaune (attend), gris (idle).
Workspace association vmux cible specifiquement i3. Chaque session doit etre associee a son workspace i3 et worktree git. C'est le lien entre "cette session" et "ou elle vit sur mon ecran". MEDIUM Correlation via PID du process claude -> window -> workspace i3 (via i3 IPC). Le worktree git se deduit du cwd du process.
Switch to workspace Pouvoir naviguer vers la session qui a besoin d'attention. agent-deck fait ca avec tmux (Ctrl+b puis numero), vmux le fait avec i3-msg. LOW i3-msg workspace [name] via IPC. Trivial une fois l'association etablie.
Desktop notifications Quand une session passe de "travaille" a "attend input", le dev doit etre prevenu. Tous les outils serieux le font : amux, agent-deck, et meme les hooks Claude Code natifs. dunst est le standard sur i3. LOW Notification via notify-send / D-Bus vers dunst. Se declenche sur transition d'etat.

Differentiators (Competitive Advantage)

Features that set the product apart. Not required, but valuable.

Feature Value Proposition Complexity Notes
i3-native integration Aucun concurrent ne cible i3 specifiquement. dmux/agent-deck/agentdock sont tous tmux-centric. vmux est le seul a mapper sessions Claude -> workspaces i3, ce qui correspond exactement au workflow de Pierre (1 workspace = 1 sujet = 1 worktree). MEDIUM i3 IPC (socket Unix) pour lister workspaces, detecter les fenetres, switcher. Pas de dependance tmux.
Session preview (last output lines) Voir ce que Claude fait/demande sans switcher de workspace. amux appelle ca "peek mode", agentdock a un "live terminal". vmux peut faire plus leger : juste les dernieres lignes pertinentes. MEDIUM Lecture du JSONL de session pour extraire le dernier message assistant. Pas besoin de terminal complet, juste un apercu texte.
Attention priority ordering Au lieu d'une simple liste, trier les sessions par urgence : "attend input" en haut, "permission needed" en second, "working" en bas. Aucun concurrent ne fait ca explicitement. LOW Tri de la liste par etat. Trivial en logique, fort en UX.
Multi-screen awareness Pierre utilise 2 ecrans. vmux peut savoir sur quel ecran/output se trouve chaque workspace i3, et optimiser le placement (ex: sessions actives sur ecran 1, sessions en attente sur ecran 2). LOW i3 IPC expose les outputs (ecrans) et leurs workspaces. Lecture seule suffit pour l'affichage.
Integration piaire piaire gere deja le workflow (timetracking, features, MRs). vmux pourrait exposer l'etat des sessions a piaire ou consommer les infos de piaire (quel ticket = quelle session). Synergie unique a cet ecosysteme. HIGH Necessite une API/IPC entre les deux outils. A evaluer apres v1.
Statusline i3bar widget Au lieu d'une TUI separee, afficher le resume dans la barre i3 elle-meme : "3 sessions: 1 attend, 2 travaillent". Information passive, zero friction. LOW Script i3status/i3blocks qui lit l'etat des sessions. Format texte simple.

Anti-Features (Commonly Requested, Often Problematic)

Features that seem good but create problems.

Feature Why Requested Why Problematic Alternative
Terminal integre / repondre depuis vmux Eviter de switcher de workspace pour repondre a Claude. Agentdock et amux le font. Complexite enorme (terminal emulation, xterm.js, gestion input). 80% de la valeur vient de savoir ou aller, pas de repondre sur place. Pierre l'a deja identifie comme out of scope. Switch rapide vers le workspace i3 en 1 touche. Le terminal natif est deja la-bas.
Lancement de sessions dmux et amux permettent de creer des sessions. Ca semble pratique. vmux observe, ne cree pas. Lancer des sessions implique gerer worktrees, branches, contexte initial. C'est le role des skills piaire/Claude Code. Ajouter ca cree un second "lanceur" concurrent. Rester observateur. Les sessions sont lancees par les skills existants.
Auto-reponse / watchdog amux auto-repond aux prompts de permission, auto-compacte le contexte. Semble utile pour le mode "unattended". Dangereux. Approuver automatiquement des actions Claude Code sans review humaine. Le watchdog d'amux est pour des workloads batch, pas pour du dev interactif ou la review compte. Notifier rapidement pour que le dev reponde lui-meme.
Dashboard web agentdock et amux proposent un dashboard web avec WebSocket. Plus joli, accessible depuis le telephone. Over-engineering pour un outil local single-user. Ajoute Node.js/serveur web/WebSocket a la stack. vmux est un outil desktop i3, pas un SaaS. TUI ou widget i3bar. Leger, natif, zero overhead.
Support multi-agent (Cursor, Codex, Gemini...) agent-deck et dmux supportent N agents differents. vmux est specifiquement pour Claude Code. Supporter d'autres agents dilue le focus et complexifie la detection d'etat (chaque agent a son propre format). Cibler Claude Code uniquement. Si le besoin emerge, generaliser plus tard.
Token/cost tracking Plusieurs outils (amux, Claude Code Usage Monitor) trackent les tokens et couts. Deja disponible via claude usage et le dashboard Anthropic. Dupliquer cette feature n'apporte rien. La statusline Claude Code expose deja ces metriques. Laisser Claude Code gerer ses propres metriques. vmux se concentre sur l'etat et la navigation.

Feature Dependencies

[Session Discovery]
    |
    +--requires--> [State Detection]
    |                   |
    |                   +--enables--> [Desktop Notifications]
    |                   |
    |                   +--enables--> [Attention Priority Ordering]
    |
    +--requires--> [Workspace Association]
    |                   |
    |                   +--enables--> [Switch to Workspace]
    |                   |
    |                   +--enables--> [Multi-screen Awareness]
    |
    +--enables--> [Session Preview]

[Session List with Status]
    +--requires--> [Session Discovery]
    +--requires--> [State Detection]

[Statusline i3bar Widget]
    +--requires--> [Session Discovery]
    +--requires--> [State Detection]
    +--independent-of--> [Session List TUI]

[Integration piaire]
    +--requires--> [Session Discovery]
    +--requires--> [Workspace Association]
    +--deferred--> after v1 validation

Dependency Notes

  • Session Discovery is the foundation: Tout depend de la capacite a trouver et monitorer les process Claude Code actifs. Sans ca, rien ne fonctionne.
  • State Detection depends on Discovery: On ne peut determiner l'etat d'une session qu'apres l'avoir trouvee.
  • Workspace Association is parallel to State Detection: Les deux enrichissent la session decouverte, mais sont independants l'un de l'autre.
  • Notifications require State Detection: On notifie sur les transitions d'etat, donc il faut d'abord detecter l'etat.
  • i3bar Widget et TUI sont independants: On peut avoir l'un sans l'autre. Le widget i3bar est plus leger et potentiellement suffisant en v1.

MVP Definition

Launch With (v1)

Minimum viable product pour valider le concept : "savoir instantanement quelle session a besoin de moi".

  • Session discovery (detect Claude Code processes + read JSONL state files)
  • State detection (working / waiting for input / idle)
  • Workspace i3 association (PID -> window -> workspace)
  • Session list with status (TUI ou i3bar widget, au choix)
  • Switch to workspace (navigation en 1 action)
  • Desktop notifications on state transition (via dunst/notify-send)

Add After Validation (v1.x)

Features to add once core is working.

  • Session preview (dernieres lignes de sortie) si le simple switch ne suffit pas
  • Attention priority ordering si le nombre de sessions depasse 5+
  • Multi-screen awareness si la repartition ecran 1/ecran 2 reste un pain point
  • Statusline i3bar widget (si v1 est TUI) ou TUI (si v1 est widget)

Future Consideration (v2+)

Features to defer until product-market fit is established.

  • Integration piaire pour lier session <-> ticket/feature
  • Keyboard shortcuts globaux (i3 bindings) pour naviguer sans ouvrir vmux
  • Historique des sessions (quand elles ont commence, duree, etc.)

Feature Prioritization Matrix

Feature User Value Implementation Cost Priority
Session discovery HIGH MEDIUM P1
State detection HIGH MEDIUM P1
Workspace i3 association HIGH MEDIUM P1
Session list with status HIGH LOW P1
Switch to workspace HIGH LOW P1
Desktop notifications HIGH LOW P1
Session preview MEDIUM MEDIUM P2
Attention priority ordering MEDIUM LOW P2
Statusline i3bar widget MEDIUM LOW P2
Multi-screen awareness LOW LOW P2
Integration piaire MEDIUM HIGH P3

Priority key:

  • P1: Must have for launch
  • P2: Should have, add when possible
  • P3: Nice to have, future consideration

Competitor Feature Analysis

Feature agent-deck dmux amux agentdock vmux (our approach)
Session detection tmux-based tmux-based tmux-based tmux-based Process/JSONL + i3 IPC
State detection 3 states (run/wait/idle) Basic 4 states + stuck Live terminal 3 states via hooks + JSONL
WM integration None (tmux only) None (tmux only) None (web) None (web) Native i3 workspace mapping
Notifications tmux statusbar None Web + mobile push Web dunst/D-Bus (native desktop)
Terminal embed Yes (tmux pane) Yes (tmux pane) Yes (web xterm.js) Yes (web xterm.js) No (switch to workspace)
Session creation Yes Yes Yes Yes No (observe only)
Multi-agent Yes (10+ agents) Yes (11 agents) Claude Code only Claude + Cursor Claude Code only
Git worktrees Optional Core feature Optional Core feature Detected, not managed
Overhead Go binary Node.js Python + web server Node.js + React Go binary (lightweight)

Key differentiator: vmux is the only tool that integrates with a tiling WM instead of wrapping everything in tmux. For a dev who already organizes work in i3 workspaces, this is more natural than a tmux-within-i3 approach.

Sources

Feature research for: AI session management / desktop workspace orchestration Researched: 2026-03-23

Reference in New Issue View Git Blame Copy Permalink