From ecee09cd0f2a8c0f51328d8e414adfd866ef95a2 Mon Sep 17 00:00:00 2001 From: "Jinwook Jeong (Edgar)" Date: Wed, 20 May 2026 00:26:44 +0900 Subject: [PATCH] docs: document lifecycle session badges MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The badge concept was reworked in #39 (has-X → lifecycle states) but the markdown docs were never refreshed. Add a Session Badges section to the README describing independent badges ([HERE], [LIVE], [R·exp], custom) and the priority-ordered lifecycle badges ([BUSY], [BG], [STUCK], [WAIT], [DONE]) with their trigger conditions. Fix stale `badge:toggle` key list and `hidden_badges` example. Scope docs/CUSTOM_BADGES.md to user-tag badges and replace stale snippets. Claude-Session: LOCAL_a57c2ed3-9a92-4bd7-814f-2b00e527a75d --- README.md | 29 ++++++++++++++++++++++++++--- docs/CUSTOM_BADGES.md | 8 ++++---- 2 files changed, 30 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 843a2c0..a1578dc 100644 --- a/README.md +++ b/README.md @@ -109,7 +109,7 @@ The Claude data directory is resolved in order: `--dir` flag → `CLAUDE_CONFIG_ Browse all Claude Code sessions across projects, sorted by recency. -- **Live/Busy badges** — see which sessions are actively running +- **Status badges** — at-a-glance session state (see [Session Badges](#session-badges)) - **Search** (`/`) — filter by project, branch, prompt, window name, or tags - **Group modes** (`G` or `:group:*`): - **Flat** — simple list sorted by time @@ -146,6 +146,29 @@ Browse all Claude Code sessions across projects, sorted by recency. Plain text terms match against project path, name, branch, session ID, first prompt, and teammate name. Multiple terms are AND-matched. +#### Session Badges + +Each session row carries two kinds of badges. Independent badges can co-occur; lifecycle badges are mutually exclusive (highest-priority one wins). + +**Independent:** + +- `[HERE]` — session belongs to the current tmux window +- `[LIVE]` — a Claude process is attached to the session +- `[R·exp]` — remote session (experimental) +- Custom tags — user-applied via `x` → `t` (see [docs/CUSTOM_BADGES.md](docs/CUSTOM_BADGES.md)) + +**Lifecycle** (priority high → low; at most one shown): + +| Badge | When | +|-------|------| +| `[BUSY]` | Claude is actively responding (JSONL written within ~10s) | +| `[BG]` | Live session has a shell/Monitor job, or any cron is `active` | +| `[STUCK]` | Live, JSONL stale for >30min, and unfinished todos/tasks exist | +| `[WAIT]` | Live, idle, with unfinished todos/tasks | +| `[DONE]` | Session had todos/tasks and all are completed | + +Example: `[HERE][LIVE][WAIT] my-feature` — current window, live process, idle with pending work. + ### Cross-Session Search Search inside conversation content across all sessions (`Ctrl+S` or `:search`). @@ -377,7 +400,7 @@ Available from any view. Suggestions are context-aware — only relevant command | `search` | All | Cross-session content search | | `config:edit` | All | Edit config file | | `detail:text\|tool\|hook` | Conversation | Set detail level | -| `badge:toggle ` | Sessions | Toggle badge visibility (M,W,T,K,P,A,C,S,X,F,LIVE) | +| `badge:toggle ` | Sessions | Toggle badge visibility (HERE,LIVE,BUSY,BG,WAIT,DONE,STUCK) | Short aliases: `g:flat`, `v:stats`, `p:hooks`, `cfg:edit`. Multi-command: `view:config page:hooks`. @@ -425,7 +448,7 @@ preferences: conv_detail_level: 1 # 0=text, 1=tool, 2=hook split_ratio: 35 # 15-85 worktree_dir: .worktree # git worktree subdirectory name - hidden_badges: [C, S, X] # hide specific badges + hidden_badges: [DONE, STUCK] # hide specific badges filter_term: "is:live" # last applied session filter editor_input: true # prefer $EDITOR for live input (ctrl+e to toggle) ``` diff --git a/docs/CUSTOM_BADGES.md b/docs/CUSTOM_BADGES.md index 8c1f2db..ab1f56b 100644 --- a/docs/CUSTOM_BADGES.md +++ b/docs/CUSTOM_BADGES.md @@ -1,6 +1,6 @@ # Custom Badges -User-created badge labels for organizing and filtering Claude Code sessions. +User-created badge labels for organizing and filtering Claude Code sessions. Built-in system badges (`[HERE]`, `[LIVE]`, `[BUSY]`, `[BG]`, `[WAIT]`, `[DONE]`, `[STUCK]`, `[R·exp]`) are documented in the [README](../README.md#session-badges). ## Overview @@ -62,8 +62,8 @@ Shows confirmation: "Removed 'urgent' from 5 session(s)" Custom badges appear after built-in badges in lime green italic: ``` -[LIVE] [M] [T] [urgent] [bug-fix] - ↑ ↑ ↑ custom badges (italic) +[LIVE] [WAIT] [urgent] [bug-fix] + ↑ ↑ custom badges (italic) built-in ``` @@ -130,7 +130,7 @@ User presses x → t ``` Session list render → For each session - → Render built-in badges [LIVE] [M] [T] + → Render built-in badges [LIVE] [WAIT] → Loop through Session.CustomBadges → Render with customBadgeStyle (lime green italic) ```