# 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*