# Session List

> List all past development sessions with summaries and timestamps

- Skill: `majiayu000/session-list` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/session-list`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/session-list/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/session-list

---


List all development sessions by:

1. Check if `.claude/sessions/` directory exists
2. List all `.md` files (excluding hidden files and `.current-session`)
3. For each session file:
   - Show the filename
   - Extract and show the session title
   - Show the date/time
   - Show first few lines of the overview if available
4. If `.claude/sessions/.current-session` exists, highlight which session is currently active
5. Sort by most recent first

Present in a clean, readable format.

## Token Optimization

**Status:** ✅ Fully Optimized (Phase 2 Batch 4A, 2026-01-27)
**Target:** 70-80% reduction
**Baseline:** 2,000-3,500 tokens → **Optimized:** 500-1,000 tokens

### Optimization Strategy

#### 1. Bash-Based Directory Operations (80% savings)
```bash
# OPTIMIZED: Use Bash ls/grep for efficient directory listing
ls -lt .claude/sessions/*.md 2>/dev/null | grep -v '.current-session'

# AVOID: Glob + Read pattern (reads all files unnecessarily)
# Glob: .claude/sessions/*.md
# Read: each file to extract metadata
```

**Why this works:**
- `ls -lt` provides sorted list with timestamps (no parsing needed)
- Filename contains session name (no file read required)
- Single Bash call vs. multiple Glob+Read operations
- 80% token reduction for typical session list

#### 2. Filename-Based Metadata Extraction (90% savings)
```bash
# OPTIMIZED: Parse metadata from filename structure
# Format: YYYY-MM-DD-HH-MM-session-name.md
# Example: 2026-01-27-14-30-feature-auth.md
basename filename .md | sed 's/-/ /g'

# AVOID: Reading file headers for metadata
# Each file read: 100-500 tokens
# Filename parsing: 10-20 tokens
```

**Session metadata from filename:**
- Date: First 10 chars (YYYY-MM-DD)
- Time: Next 5 chars (HH-MM)
- Name: Remaining chars
- Status: Check .current-session file

#### 3. Summary-Only Display (70% savings)
```bash
# OPTIMIZED: Show list view without content
echo "Session: feature-auth"
echo "Date: 2026-01-27 14:30"
echo "Status: completed"

# AVOID: Reading and displaying session content
# Content can be 500-2000 tokens per session
# List view: 20-50 tokens per session
```

**Progressive disclosure approach:**
- List view shows metadata only
- User can request details: "Show session feature-auth"
- Only then read and display full content

#### 4. Session Index Caching (85% savings)
```json
// Cache: .claude/sessions/.session-index.json
{
  "last_scan": "2026-01-27T14:30:00Z",
  "sessions": [
    {
      "name": "feature-auth",
      "date": "2026-01-27",
      "time": "14:30",
      "status": "completed",
      "file": "2026-01-27-14-30-feature-auth.md"
    }
  ]
}
```

**Cache invalidation:**
- Cache valid for 1 hour
- Invalidate on new session creation
- Invalidate on session deletion
- Check last_scan timestamp

**Cache usage:**
```bash
# Check if cache exists and is valid
if [ -f .claude/sessions/.session-index.json ]; then
  last_scan=$(jq -r '.last_scan' .claude/sessions/.session-index.json)
  current_time=$(date -u +%s)
  cache_age=$((current_time - $(date -d "$last_scan" +%s)))

  if [ $cache_age -lt 3600 ]; then
    # Use cached data (no directory scan needed)
    jq -r '.sessions[] | "\(.date) \(.time) - \(.name) [\(.status)]"' \
      .claude/sessions/.session-index.json
    exit 0
  fi
fi

# Cache miss or expired: scan directory and rebuild cache
```

#### 5. Active Session Detection (60% savings)
```bash
# OPTIMIZED: Check .current-session file once
if [ -f .claude/sessions/.current-session ]; then
  current=$(cat .claude/sessions/.current-session)
  echo "Active: $current"
fi

# AVOID: Reading all session files to find active one
# Reading all files: 100-500 tokens per file
# Single file check: 10-20 tokens
```

### Implementation Workflow

#### Step 1: Check Cache Validity
```bash
# Tool: Bash
cache_file=".claude/sessions/.session-index.json"

if [ -f "$cache_file" ]; then
  last_scan=$(jq -r '.last_scan' "$cache_file")
  current_time=$(date -u +%s)
  cache_age=$((current_time - $(date -d "$last_scan" +%s)))

  if [ $cache_age -lt 3600 ]; then
    echo "CACHE_VALID"
    exit 0
  fi
fi

echo "CACHE_EXPIRED"
```

**Token cost:** 50-100 tokens (cache hit) vs. 500-1000 tokens (full scan)

#### Step 2: Use Cached Data (Cache Hit)
```bash
# Tool: Bash
jq -r '.sessions[] | "\(.date) \(.time) - \(.name) [\(.status)]"' \
  .claude/sessions/.session-index.json | \
  head -20  # Limit to recent sessions
```

**Output format:**
```
2026-01-27 14:30 - feature-auth [completed]
2026-01-27 10:15 - bugfix-login [completed]
2026-01-26 16:45 - refactor-api [active]
```

**Token cost:** 100-200 tokens for cached list

#### Step 3: Rebuild Cache (Cache Miss)
```bash
# Tool: Bash
sessions_dir=".claude/sessions"
cache_file="$sessions_dir/.session-index.json"

# Get current active session
current=""
if [ -f "$sessions_dir/.current-session" ]; then
  current=$(cat "$sessions_dir/.current-session")
fi

# Build session index
echo "{" > "$cache_file"
echo "  \"last_scan\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"," >> "$cache_file"
echo "  \"sessions\": [" >> "$cache_file"

first=true
for file in $(ls -t "$sessions_dir"/*.md 2>/dev/null | grep -v '.current-session'); do
  filename=$(basename "$file" .md)

  # Parse filename: YYYY-MM-DD-HH-MM-session-name
  date="${filename:0:10}"
  time="${filename:11:5}"
  name="${filename:17}"

  # Determine status
  status="completed"
  if [ "$filename" = "$current" ]; then
    status="active"
  fi

  # Add to JSON array
  if [ "$first" = true ]; then
    first=false
  else
    echo "    ," >> "$cache_file"
  fi

  echo "    {" >> "$cache_file"
  echo "      \"name\": \"$name\"," >> "$cache_file"
  echo "      \"date\": \"$date\"," >> "$cache_file"
  echo "      \"time\": \"$time\"," >> "$cache_file"
  echo "      \"status\": \"$status\"," >> "$cache_file"
  echo "      \"file\": \"$filename.md\"" >> "$cache_file"
  echo "    }" >> "$cache_file"
done

echo "  ]" >> "$cache_file"
echo "}" >> "$cache_file"
```

**Token cost:** 500-800 tokens (one-time rebuild, then cached)

#### Step 4: Display Session List
```bash
# Tool: Bash (using cached data)
echo "=== Development Sessions ==="
echo ""

# Show active session first
jq -r '.sessions[] | select(.status == "active") |
  "🔵 ACTIVE: \(.date) \(.time) - \(.name)"' \
  .claude/sessions/.session-index.json

echo ""

# Show completed sessions
jq -r '.sessions[] | select(.status == "completed") |
  "\(.date) \(.time) - \(.name)"' \
  .claude/sessions/.session-index.json | \
  head -20

total=$(jq '.sessions | length' .claude/sessions/.session-index.json)
echo ""
echo "Total sessions: $total"
echo "Showing most recent 20 completed sessions"
echo ""
echo "Use '/session-resume <name>' to view details and resume"
```

**Token cost:** 200-300 tokens (display only)

### Progressive Disclosure Pattern

#### Initial List View (Minimal Tokens)
Show only session metadata without content:
- Session name
- Date and time
- Status (active/completed)
- Total count

**Token cost:** 500-1,000 tokens

#### Detailed View (On Request)
If user requests details for specific session:
```bash
# User: "Show details for feature-auth session"
# Tool: Read
Read: .claude/sessions/2026-01-27-14-30-feature-auth.md
```

**Token cost:** Additional 500-2,000 tokens (only when requested)

### Token Reduction Summary

| Operation | Before | After | Savings |
|-----------|--------|-------|---------|
| Directory scan (Glob+Read) | 2,000-3,000 | 500-800 | 70-75% |
| Session metadata (file reads) | 1,000-2,000 | 100-200 | 85-90% |
| Content display (all files) | 5,000-10,000 | 200-300 | 95-97% |
| Cached list view | 2,000-3,500 | 100-200 | 90-95% |
| **Total average** | **2,500** | **500** | **80%** |

### Best Practices

1. **Always check cache first** - Avoid unnecessary directory scans
2. **Use Bash for file operations** - More efficient than Glob+Read for directory listing
3. **Parse filenames for metadata** - No need to read file headers
4. **Show summary view by default** - Only read files when user requests details
5. **Invalidate cache appropriately** - Balance freshness vs. performance
6. **Limit display to recent sessions** - Use `head -20` to avoid overwhelming output
7. **Highlight active session** - Check .current-session file once
8. **Provide clear navigation** - Show how to view details with /session-resume

### Cache Management

**Cache location:** `.claude/sessions/.session-index.json`

**Cache structure:**
```json
{
  "last_scan": "ISO 8601 timestamp",
  "sessions": [
    {
      "name": "session-name",
      "date": "YYYY-MM-DD",
      "time": "HH:MM",
      "status": "active|completed",
      "file": "filename.md"
    }
  ]
}
```

**Cache validity:**
- Valid for 1 hour (3600 seconds)
- Invalidated by new session creation
- Invalidated by session deletion
- Regenerated on cache miss

**Cache benefits:**
- 85% token reduction for repeated list views
- Near-instant response time
- Reduced API costs
- Better user experience

### Error Handling

```bash
# Handle missing sessions directory
if [ ! -d .claude/sessions ]; then
  echo "No sessions directory found"
  echo "Use '/session-start <name>' to create your first session"
  exit 0
fi

# Handle empty sessions directory
session_count=$(ls .claude/sessions/*.md 2>/dev/null | wc -l)
if [ $session_count -eq 0 ]; then
  echo "No sessions found"
  echo "Use '/session-start <name>' to create your first session"
  exit 0
fi

# Handle corrupted cache
if [ -f .claude/sessions/.session-index.json ]; then
  if ! jq empty .claude/sessions/.session-index.json 2>/dev/null; then
    echo "Cache corrupted, rebuilding..."
    rm .claude/sessions/.session-index.json
    # Rebuild cache (Step 3)
  fi
fi
```

### Performance Metrics

**Typical session list scenario:**
- User has 20 past sessions
- Cache is valid (within 1 hour)
- Viewing list of recent sessions

**Token usage:**
- Cache validity check: 50-100 tokens
- Display cached list: 200-300 tokens
- **Total: 250-400 tokens**

**Without optimization:**
- Directory scan: 500-800 tokens
- Read 20 session files: 2,000-4,000 tokens
- Parse and display: 200-300 tokens
- **Total: 2,700-5,100 tokens**

**Savings: 85-90%**