172 lines
13 KiB
Markdown
172 lines
13 KiB
Markdown
# 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
|
|
|
|
- [agent-deck](https://github.com/asheshgoplani/agent-deck) - Go + Bubble Tea TUI, tmux-based session manager
|
|
- [dmux](https://github.com/formkit/dmux) - Node.js agent multiplexer with git worktrees
|
|
- [amux](https://github.com/mixpeek/amux) - Python multiplexer with web dashboard and watchdog
|
|
- [agentdock](https://github.com/vishalnarkhede/agentdock) - Web dashboard for parallel agents
|
|
- [Claude Code Hooks Reference](https://code.claude.com/docs/en/hooks) - Official hook events including notification types
|
|
- [Claude Code Notification Hooks](https://alexop.dev/posts/claude-code-notification-hooks/) - Practical guide to notification setup
|
|
- [tmuxwatch](https://github.com/steipete/tmuxwatch) - Charmbracelet-powered tmux session dashboard
|
|
- [Claude Code session monitoring via JSONL](https://www.ksred.com/managing-multiple-claude-code-sessions-building-a-real-time-dashboard/) - Real-time dashboard implementation details
|
|
- [i3 IPC documentation](https://i3wm.org/docs/userguide.html) - i3 workspace and window management
|
|
|
|
---
|
|
*Feature research for: AI session management / desktop workspace orchestration*
|
|
*Researched: 2026-03-23*
|