Session Index - Claude Code Session Scanner

Generate comprehensive markdown and JSON indexes of all Claude Code sessions, organized by project with complete metadata.

Usage

# Basic usage - generate complete index
/session-index

# Filter by project
/session-index --project coditect

# Generate JSON output
/session-index --json

# Verbose output with progress
/session-index --verbose

# Custom output path
/session-index --output ~/my-sessions.md

# Combined options
/session-index --project coditect --json --verbose

System Prompt

System Prompt

⚠️ EXECUTION DIRECTIVE: When the user invokes this command, you MUST:

1. IMMEDIATELY execute - no questions, no explanations first
2. ALWAYS show full output from script/tool execution
3. ALWAYS provide summary after execution completes

DO NOT:

• Say "I don't need to take action" - you ALWAYS execute when invoked
• Ask for confirmation unless requires_confirmation: true in frontmatter
• Skip execution even if it seems redundant - run it anyway

The user invoking the command IS the confirmation.

---

Use the session-analyzer agent to scan, index, and analyze Claude Code sessions.

Use the session-analyzer subagent to generate a comprehensive index of all Claude Code sessions

What This Command Does

1. Scans ~/.claude/projects for all session and agent execution files
2. Organizes by project with human-readable paths
3. Generates markdown index with tables, timestamps, and file:// links
4. Optionally generates JSON for programmatic access
5. Provides session insights and analysis

Output Format

Markdown Index (CLAUDE-SESSION-INDEX.md)

# Claude Code Session Index

**Generated:** 2025-11-29 08:00:00

## Summary

- **Total Projects:** 19
- **Total Sessions:** 76
- **Total Agent Executions:** 520
- **Total Files:** 596

## Table of Contents

- [~/PROJECTS/coditect/rollout/master](#projects-coditect-rollout-master) (38 sessions, 310 agents)
- [~/PROJECTS/CLAUDE-CODE](#projects-claude-code) (1 sessions, 8 agents)
...

## Projects

### ~/PROJECTS/coditect/rollout/master

**Location:** `-Users-halcasteel-PROJECTS-coditect-rollout-master`

#### Sessions (38)

| Session ID | Created | Last Updated | Size |
|------------|---------|--------------|------|
| [cbe665f8-2712-4ed6-8721-2da739cf5e7e](file://...) | 2025-11-24 07:36 | 2025-11-29 07:49 | 89282.9 KB |
| [613aec95-115a-496f-a3d7-95c371204b6c](file://...) | 2025-11-28 23:35 | 2025-11-28 23:35 | 36.4 KB |

#### Agent Executions (310)

| Agent ID | Created | Last Updated | Size |
|----------|---------|--------------|------|
| [agent-6c64e7be](file://...) | 2025-11-29 06:39 | 2025-11-29 06:39 | 264.8 KB |

JSON Output (CLAUDE-SESSION-INDEX.json)

{
  "generated": "2025-11-29T08:00:00",
  "projects": [
    {
      "name": "~/PROJECTS/coditect/rollout/master",
      "location": "-Users-halcasteel-PROJECTS-coditect-rollout-master",
      "sessions": [
        {
          "id": "cbe665f8-2712-4ed6-8721-2da739cf5e7e",
          "path": "/Users/halcasteel/.claude/projects/.../session.jsonl",
          "created": "2025-11-24T07:36:00",
          "modified": "2025-11-29T07:49:00",
          "size": 91234567
        }
      ],
      "agents": [...]
    }
  ]
}

Options

Option	Short	Description
--output PATH	-o	Output file path (default: ./CLAUDE-SESSION-INDEX.md)
--json	-j	Also generate JSON output
--project PATTERN	-p	Filter to projects matching pattern
--verbose	-v	Show progress during scan

Use Cases

1. Find Specific Session

# Generate index
/session-index

# Search for session by date or project in markdown
# Click file:// link to open session

2. Analyze Project Activity

# Filter to specific project
/session-index --project coditect

# Review session count and recent activity

3. Session Recovery

# Generate complete index with JSON
/session-index --json

# Use JSON to find sessions by date range
# Identify sessions for context restoration

4. Storage Management

# Generate index with JSON
/session-index --json

# Parse JSON to find large sessions
jq '.projects[].sessions[] | select(.size > 10000000)' CLAUDE-SESSION-INDEX.json

5. Development Tracking

# Regular index generation
/session-index --verbose

# Track development patterns over time
# Monitor agent usage and project activity

What Gets Indexed

Session Files:

• All *.jsonl files in ~/.claude/projects/
• Organized by parent directory (project)
• Full metadata: creation time, last modified, size

Agent Files:

• All agent-*.jsonl files (agent executions)
• Separate section per project
• Same metadata as sessions

Projects:

• Automatically discovered from directory structure
• Human-readable path conversion
• Table of contents with quick links

Technical Details

Backend: scripts/session-index-generator.py

• Python script for scanning and indexing
• Handles 500+ files efficiently
• Graceful error handling for missing/corrupted files
• Privacy-preserving (metadata only, no content parsing)

Performance:

• Scans 596 files in <2 seconds
• Memory-efficient streaming
• Progress indicators for large scans
• Parallel file stat operations

Safety:

• Read-only operations
• No session content parsing
• No file modifications
• Works with any project structure

Integration with CODITECT

Agent: session-analyzer

• Provides deep session analysis
• Development pattern insights
• Agent usage statistics
• Session recommendations

Skill: session-analysis

• Reusable session scanning capability
• Markdown and JSON generation
• Filtering and analysis

Automation:

• Can be scheduled via cron
• CI/CD integration for tracking
• Automated development reports

Examples

Example 1: Quick Session Lookup

Task: Find recent CODITECT sessions

/session-index --project coditect

Result: Filtered index showing only CODITECT projects, sorted by most recent

Example 2: Complete Development Audit

Task: Generate full audit with analytics

/session-index --json --verbose

Result:

• Markdown index for browsing
• JSON for programmatic analysis
• Progress output during scan

Example 3: Storage Optimization

Task: Identify large sessions for archival

# Generate JSON index
/session-index --json

# Find sessions > 50 MB
cat CLAUDE-SESSION-INDEX.json | jq '.projects[].sessions[] | select(.size > 50000000) | {id, size, project: (.path | split("/")[-2])}'

Result: List of large sessions with recommendations

Related Commands

• /agent-dispatcher - Select optimal agents for tasks
• /suggest-agent - Get agent recommendations
• None of the other commands provide session indexing functionality

Related Components

Agent: session-analyzer

Use the session-analyzer subagent to generate comprehensive session index with insights

Skill: session-analysis

• Backend capability for session scanning
• Located at: skills/session-analysis/
• Provides: Indexing, filtering, JSON generation

Script: session-index-generator.py

• Location: scripts/session-index-generator.py
• Direct execution: python3 scripts/session-index-generator.py [options]
• Full CLI with arguments

Tips

1. Run periodically - Generate index weekly to track development
2. Use JSON for analysis - Structured data enables complex queries
3. Filter by project - Focus on specific work
4. Check session sizes - Monitor storage usage
5. Use clickable links - Markdown file:// links open sessions directly

Privacy & Security

• No content parsing - Only metadata is indexed
• Read-only - Never modifies session files
• Local only - All data stays on your machine
• No network - Completely offline operation

Performance Notes

• Handles 100+ sessions efficiently
• Scales to 500+ agent executions
• <2 second scan time for typical projects
• Memory-efficient streaming
• Works with multi-GB sessions

Troubleshooting

Issue: No sessions found Solution: Verify ~/.claude/projects exists and contains *.jsonl files

Issue: Permission denied Solution: Check file permissions on ~/.claude/projects

Issue: Large output file Solution: Use --project filter to reduce scope

Issue: Slow performance Solution: Normal for first scan; subsequent scans are faster

Future Enhancements

Planned features:

• Session content analysis (topic extraction)
• Agent performance metrics
• Timeline visualization
• Session similarity matching
• Export to CSV, SQLite
• Integration with session recovery tools

---

Action Policy

<default_behavior> This command analyzes and generates output without making changes. Provides:

• Comprehensive session index
• JSON export for analysis
• Project organization
• Clickable file links

Read-only operation on session metadata. </default_behavior>

After execution, verify: - Index file generated - All projects discovered - Sessions and agents counted - Links working

Success Output

When session indexing completes:

✅ COMMAND COMPLETE: /session-index
Projects: N discovered
Sessions: M indexed
Agent Executions: P indexed
Output: CLAUDE-SESSION-INDEX.md
JSON: CLAUDE-SESSION-INDEX.json (if --json)

Completion Checklist

Before marking complete:

• All projects scanned
• Sessions indexed with metadata
• Agent executions cataloged
• Output file generated
• Links verified

Failure Indicators

This command has FAILED if:

• ❌ ~/.claude/projects not found
• ❌ Permission denied on session files
• ❌ No sessions discovered
• ❌ Output file not created

When NOT to Use

Do NOT use when:

• No Claude Code sessions exist
• Need session content analysis (sessions are JSONL)
• Need real-time monitoring

Anti-Patterns (Avoid)

Anti-Pattern	Problem	Solution
Parse session content	Privacy violation	Only index metadata
Modify sessions	Data corruption	Read-only operations
Skip project filter	Large output	Use --project filter

Principles

This command embodies:

• #9 Based on Facts - Actual session metadata
• #6 Clear, Understandable - Organized index format

Full Standard: CODITECT-STANDARD-AUTOMATION.md

---

Version: 1.0.0 Status: Production-ready Last Updated: 2025-11-29