91 lines
3.9 KiB
Markdown
91 lines
3.9 KiB
Markdown
# Phase 1: Session Discovery - Context
|
|
|
|
**Gathered:** 2026-03-23
|
|
**Status:** Ready for planning
|
|
|
|
<domain>
|
|
## 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.
|
|
|
|
</domain>
|
|
|
|
<decisions>
|
|
## 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.
|
|
|
|
</decisions>
|
|
|
|
<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>
|
|
|
|
<specifics>
|
|
## 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 `/` → `-`
|
|
|
|
</specifics>
|
|
|
|
<deferred>
|
|
## Deferred Ideas
|
|
|
|
None — discussion stayed within phase scope
|
|
|
|
</deferred>
|
|
|
|
---
|
|
|
|
*Phase: 01-session-discovery*
|
|
*Context gathered: 2026-03-23*
|