Session Analysis Skill

Session Analysis Skill

How to Use This Skill

1. Review the patterns and examples below
2. Apply the relevant patterns to your implementation
3. Follow the best practices outlined in this skill

Automated Claude Code session scanning, indexing, and analysis across all projects. Provides comprehensive session management, development pattern tracking, and instant access to historical conversations and agent executions.

When to Use This Skill

✅ Use this skill when:

• Need to find specific session or agent execution across all projects
• Want comprehensive index of all Claude Code sessions
• Analyzing development patterns and session activity
• Tracking long-running sessions and multi-day work
• Need session metadata (creation, modification, size)
• Building session recovery or context continuity systems
• Generating documentation of Claude Code usage
• Filtering sessions by project or time period

❌ Don't use this skill when:

• Just need to resume current session (use native Claude Code features)
• Working with single session in isolation
• ~/.claude/projects directory not accessible

What It Automates

Before: (Manual searching)

# Find a session manually
cd ~/.claude/projects
find . -name "*.jsonl" | grep -i coditect
ls -lh *coditect*/*.jsonl | sort -k 6,7
# Open each file to check content...
# Repeat for each project...

After: (Automated indexing)

# Generate complete index
python3 scripts/session-index-generator.py

# Filter by project
python3 scripts/session-index-generator.py -p coditect

# Generate JSON + Markdown
python3 scripts/session-index-generator.py -j -v

# Result: Complete markdown index with:
# - All sessions organized by project
# - Creation and modification timestamps
# - File sizes and clickable links
# - Agent execution tracking
# - Table of contents with quick navigation

Usage

Generate Complete Session Index

cd /path/to/coditect-core
python3 scripts/session-index-generator.py
# Output: ./claude-session-index.md

Output includes:

• Summary statistics (projects, sessions, agents)
• Table of contents with anchors
• Sessions organized by project
• Creation and last update timestamps
• File sizes in KB
• Clickable file:// links

Generate with Custom Output Path

python3 scripts/session-index-generator.py \
  --output ~/Documents/my-sessions.md

Filter by Project

# Only index CODITECT-related sessions
python3 scripts/session-index-generator.py \
  --project coditect

# Only drone instruction project
python3 scripts/session-index-generator.py \
  --project drone

Generate JSON Output

python3 scripts/session-index-generator.py \
  --json \
  --output ./sessions.md
# Creates: ./sessions.md + ./sessions.json

JSON structure:

{
  "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": 91,234,567
        }
      ],
      "agents": [...]
    }
  ]
}

Verbose Output

python3 scripts/session-index-generator.py --verbose
# Shows:
# Scanning /Users/halcasteel/.claude/projects...
#   Processed 50 files...
#   Processed 100 files...
# Scan complete. Found 596 files in 19 projects.

Output Format

Markdown Index

Summary Section:

## Summary

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

Session Table:

Session ID	Created	Last Updated	Size
cbe665f8...	2025-11-24 07:36	2025-11-29 07:49	89282.9 KB

Agent Table:

Agent ID	Created	Last Updated	Size
agent-6c64e7be	2025-11-29 06:39	2025-11-29 06:39	264.8 KB

JSON Output

Structured data for programmatic access:

• ISO 8601 timestamps
• Full file paths
• Sizes in bytes
• Easy parsing and filtering

Use Cases

1. Session Recovery

Find sessions from specific dates or projects to restore context.

2. Development Pattern Analysis

Track session duration, frequency, and project activity over time.

3. Agent Usage Tracking

Analyze which agents are used most frequently and in which contexts.

4. Multi-Session Continuity

Build systems that span multiple sessions using historical data.

5. Documentation Generation

Auto-generate development logs from session metadata.

6. Storage Management

Identify large sessions for archival or cleanup.

Integration with CODITECT

Slash Command:

/session-index [--project PATTERN] [--json]

Agent Integration:

• session-analyzer agent uses this skill for deep analysis
• Provides session insights and recommendations
• Tracks development velocity and patterns

Automated Workflows:

• Session index generation on project initialization
• Periodic updates via cron/scheduled tasks
• CI/CD integration for development tracking

Technical Details

Script: scripts/session-index-generator.py

• Scans ~/.claude/projects/ recursively
• Categorizes files: sessions vs agents
• Extracts metadata: size, birthtime, mtime
• Generates markdown tables with file:// links
• Optional JSON output for automation

Performance:

• Scans 596 files in <2 seconds
• Handles projects with 300+ agents
• Memory-efficient streaming processing
• Progress indicators for large scans

Safety:

• Read-only operations
• No session content parsing (privacy-preserving)
• Handles missing/corrupted files gracefully
• Works with any project structure

Examples

Example 1: Find Recent CODITECT Sessions

python3 scripts/session-index-generator.py -p coditect -v
# Output shows only CODITECT projects
# Sorted by most recent activity

Example 2: Generate Monthly Development Report

# Generate index
python3 scripts/session-index-generator.py \
  --json \
  --output reports/november-2025.md

# Process JSON for metrics
cat reports/november-2025.json | jq '.projects[].sessions | length'

Example 3: Session Archive Management

# Find large sessions
python3 scripts/session-index-generator.py -j
cat claude-session-index.json | jq '
  .projects[].sessions[] |
  select(.size > 10000000) |
  {id, size, path}
'

Token Efficiency

Before: Manual searching across 100+ sessions

• 10+ minutes per search
• Multiple file opens
• No organization

After: Automated indexing

• <1 second lookup
• One comprehensive document
• Organized by project
• Searchable markdown/JSON

Savings: 10+ minutes per session lookup × multiple searches per day

Production Validation

✅ Tested with:

• 19 projects
• 76 sessions
• 520 agent executions
• 596 total files
• Sessions up to 89 MB
• Multi-day session tracking

✅ Handles:

• Missing metadata gracefully
• Multiple project structures
• Long-running sessions
• High agent execution counts

Future Enhancements

Planned:

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

Related

• Agent: session-analyzer (comprehensive session analysis)
• Command: /session-index (slash command wrapper)
• Script: scripts/session-index-generator.py
• Output: claude-session-index.md, claude-session-index.json

Success Output

When successful, this skill MUST output:

✅ SKILL COMPLETE: session-analysis

Completed:
- [x] Scanned ~/.claude/projects directory (596 files processed)
- [x] Categorized sessions and agent executions
- [x] Generated markdown index with tables
- [x] Created JSON output for programmatic access

Outputs:
- claude-session-index.md (19 projects, 76 sessions, 520 agents)
- claude-session-index.json (structured data)
- Scan duration: 1.8 seconds
- All file:// links validated

Completion Checklist

Before marking this skill as complete, verify:

• All session files in ~/.claude/projects scanned successfully
• Sessions categorized correctly (vs agent executions)
• Metadata extracted: size, birthtime, mtime
• Markdown index generated with proper formatting
• JSON output created (if --json flag used)
• File:// links are clickable and correct
• Summary statistics accurate (projects, sessions, agents count)

Failure Indicators

This skill has FAILED if:

• ❌ Cannot access ~/.claude/projects directory
• ❌ File metadata extraction errors for >10% of files
• ❌ Generated markdown has malformed tables
• ❌ JSON output has invalid structure
• ❌ Summary statistics don't match actual file counts
• ❌ Script crashes on corrupted session files

When NOT to Use

Do NOT use this skill when:

• Just need to resume current active session (use native Claude Code features)
• Need deep content analysis of sessions (use session-analyzer agent instead)
• ~/.claude/projects directory not accessible or doesn't exist
• Only working with single project in isolation
• Need real-time session monitoring (this is a snapshot tool)

Use alternatives:

• Native Claude Code session resume for active sessions
• session-analyzer agent for deep content analysis and pattern detection
• Manual file browsing for single-session inspection
• Custom scripts for real-time monitoring

Anti-Patterns (Avoid)

Anti-Pattern	Problem	Solution
Running too frequently	Unnecessary I/O overhead	Schedule periodic runs (daily/weekly)
Parsing session content	Privacy concerns, slow	Only extract metadata, not content
Ignoring corrupted files	Script crashes	Handle exceptions gracefully
No filtering	Overwhelming output	Use --project flag for targeted scans
Hardcoded paths	Breaks on different systems	Use environment variables or config
No progress indicators	Appears hung on large scans	Enable --verbose for progress

Principles

This skill embodies:

• #3 Keep It Simple - Metadata-only, no complex content parsing
• #5 Eliminate Ambiguity - Clear categorization (session vs agent)
• #6 Clear, Understandable, Explainable - Structured output with tables and summary
• #8 No Assumptions - Scans actual filesystem, doesn't cache or assume
• #9 Automate Repetitive Tasks - Eliminates manual session searching
• Privacy-Preserving - Never parses session content, metadata only