Phase 1: Session Discovery - Context

Gathered: 2026-03-23 Status: Ready for planning

## Phase Boundary

CLI one-shot (vmux list) qui détecte toutes les sessions Claude Code actives sur le poste et affiche leur état, cwd, worktree, branche git et un aperçu de la sortie. Pas de daemon, pas de persistance, pas d'intégration i3.

## Implementation Decisions

Détection des sessions

D-01: Scanner /proc pour trouver les PID des processus Claude Code actifs, puis enrichir avec les fichiers JSONL dans ~/.claude/projects/. Un JSONL sans PID correspondant = session terminée, ignorée.
D-02: Utiliser sessions-index.json (présent dans chaque dossier projet sous ~/.claude/projects/) comme source de métadonnées riches (sessionId, gitBranch, projectPath, summary, created, modified). Format vérifié sur le poste.
D-03: Le matching PID → session se fait via le cwd du processus (/proc/PID/cwd → readlink) croisé avec le projectPath du sessions-index.

Détection d'état

D-04: Se baser uniquement sur le JSONL (tail-read de la dernière entrée) pour déterminer l'état. Pas de lecture CPU en Phase 1.
D-05: Heuristique d'état basée sur le dernier message JSONL :
- type=assistant + content_types=['tool_use'] → Working (outil en cours)
- type=progress avec hook_progress → Working (hook en cours)
- type=assistant + content_types=['text'] → Needs Input (Claude a fini, attend l'utilisateur)
- Dernière activité > seuil → Idle
D-06: ATTENTION pitfall recherche : les JSONL peuvent faire > 100 Mo. Toujours tail-read (lire depuis la fin), jamais charger le fichier entier.

Format d'affichage

D-07: Couleurs activées par défaut pour l'état (vert = Working, rouge/jaune = Needs Input, gris = Idle).

Claude's Discretion

Format d'affichage : Claude choisit entre tableau compact ou blocs détaillés selon ce qui est le plus adapté. Libre de proposer un format hybride.
Gestion du --no-color pour la compatibilité pipe.

<canonical_refs>

Canonical References

Downstream agents MUST read these before planning or implementing.

Claude Code session format

~/.claude/projects/<encoded-cwd>/sessions-index.json — Index des sessions avec métadonnées (sessionId, gitBranch, projectPath, summary, messageCount, created, modified, isSidechain). Format JSON, champ version: 1, tableau entries.
~/.claude/projects/<encoded-cwd>/<uuid>.jsonl — Messages de session en append-only. Types : user, assistant, progress. Les messages assistant ont un champ message.content[] avec des objets {type: "text"|"tool_use"}. Les messages progress ont un champ data avec {type: "hook_progress", hookEvent, hookName}.

Processus

/proc/PID/cwd — Symlink vers le cwd du processus. Permet le matching PID → projet.
Les processus Claude Code apparaissent comme claude (ou claude -c) dans ps aux.

No external specs — requirements fully captured in decisions above.

</canonical_refs>

<code_context>

Existing Code Insights

Reusable Assets

Aucun code existant (greenfield)

Established Patterns

Projet Go stdlib uniquement, cohérent avec piaire (pas de framework CLI, pas de dépendance externe)
NixOS + direnv pour l'environnement de dev

Integration Points

Aucun pour la Phase 1 (standalone CLI)

</code_context>

## Specific Ideas

Le sessions-index.json contient un champ summary généré par Claude Code qui peut servir d'aperçu rapide en complément du tail JSONL
Le champ isSidechain permet de filtrer les sessions secondaires (subagents) si besoin
L'encoding du cwd dans le nom de dossier (-home-pierre-Code-vibe-vmux) est un remplacement / → -

## Deferred Ideas

None — discussion stayed within phase scope

Phase: 01-session-discovery Context gathered: 2026-03-23

3.9 KiB Raw Blame History