analyze-sessions

Analyze recorded session data from ALL Claude Code projects to identify patterns and automation opportunities.

Arguments

• --project <name> — Analyze only sessions from the named project (matches the project field, which is the basename of the working directory)
• --targets-only — Exclude toolkit sessions; only analyze target projects

Data Location

Session logs are stored centrally in ~/.claude/logs/sessions.jsonl in JSONL format (one compact JSON object per line).

Each entry contains:

{"session_id":"...","timestamp":"2026-01-23T12:00:00Z","project":"project-name","cwd":"/path/to/project","transcript_path":"/path/to/transcript"}

The session-end-logger hook is installed at the user level (~/.claude/hooks/session-end-logger.sh) so it captures sessions from every project.

Analysis Process

Copy this checklist and track progress:

Analyze Sessions Progress:
- [ ] Step 1: Read session logs
- [ ] Step 2: Calculate statistics (grouped by project)
- [ ] Step 3: Identify target projects
- [ ] Step 4: Analyze transcripts
- [ ] Step 5: Find automation opportunities
- [ ] Step 6: Cross-project insights
- [ ] Step 7: Generate report

1. Read Session Logs

Read ~/.claude/logs/sessions.jsonl and parse all entries.

If --project <name> was given, filter to entries where project matches. If --targets-only was given, identify toolkit projects (see step 3) and exclude them.

If the file doesn't exist or is empty:

NO SESSION DATA
===============
No sessions have been logged yet.

Session logging is installed at the user level (~/.claude/hooks/session-end-logger.sh).
Run a few Claude Code sessions in any project, then run /analyze-sessions again.

If the hook is not installed, run /install-hooks and select "session-end-logger".

2. Calculate Statistics (Grouped by Project)

SESSION ANALYSIS
================

Total sessions: {N}
Date range: {earliest} to {latest}
Unique projects: {count}

Sessions per project:
- {project1}: {count} sessions ({first_date} – {last_date})
- {project2}: {count} sessions ({first_date} – {last_date})

3. Identify Target Projects

Scan ~/Projects/ for directories containing .claude/toolkit-version.json. These are toolkit target projects. All other projects are either the toolkit itself or standalone.

Project Classification:
  Toolkit: {toolkit project name}
  Target projects: {list of target project names}
  Other: {list of other project names}

4. Analyze Transcripts (If Available)

For each session with an accessible transcript_path:

1. Read the transcript file
2. Look for these patterns:

Manual Interventions:

• AskUserQuestion tool calls — Questions asked during sessions
• Text containing "manually", "by hand", "human must"
• Repeated similar questions across sessions

Common Blockers:

• Text containing "BLOCKED", "blocked", "waiting for"
• Error patterns that recur
• Missing credentials/env vars

Tool Usage Patterns:

• Count of each tool type used
• Sequences of tools that repeat

Workflow Friction:

• "cd" into directories (wrong directory issues)
• Repeated file lookups (missing context)
• Re-reading same files multiple times

5. Identify Automation Opportunities

Based on patterns found, identify:

High Impact (Repeated across 3+ sessions):

• Manual steps that could be automated with curl/Bash
• Questions that could be pre-answered in AGENTS.md
• Browser checks that could use Playwright

Medium Impact (Repeated 2 times):

• Verification steps that could be codified
• Setup steps that could be scripted

Low Impact (Single occurrence but notable):

• One-off manual interventions that might recur

6. Cross-Project Insights

Compare patterns across projects:

CROSS-PROJECT COMPARISON
========================

| Project | Sessions | Avg Questions/Session | Top Blocker | Autonomy Level |
|---------|----------|-----------------------|-------------|----------------|
| {proj}  | {N}      | {avg}                 | {blocker}   | {High/Med/Low} |

Autonomy Level = High (0-1 questions/session), Med (2-3), Low (4+)

Identify:

• Which projects need more AGENTS.md guidance (high question rate)
• Which projects have more context overflows (re-reading patterns)
• Common patterns that appear in multiple projects (shared automation opportunities)
• Skills from the toolkit that are underused in target projects

6b. Review Findings Before Writing

Before writing the report file, output a summary of key findings to the user:

SESSION ANALYSIS PREVIEW
========================
Sessions analyzed: {N}
Top patterns found: {count}

Key findings:
1. {finding 1}
2. {finding 2}
3. {finding 3}

Writing full report to .claude/logs/ANALYSIS_REPORT.md...

This gives the user visibility before the file is written.

7. Generate Report

Write analysis to .claude/logs/ANALYSIS_REPORT.md (in the toolkit).

See references/output-structure.md for the full report template including summary, per-project breakdown, cross-project insights, automation opportunities, recommended actions, and raw statistics tables.

8. Output Summary

After writing the report:

ANALYSIS COMPLETE
=================

Analyzed: {N} sessions across {M} projects
Report: .claude/logs/ANALYSIS_REPORT.md

Key Findings:
- {top finding 1}
- {top finding 2}
- {top finding 3}

Cross-Project:
- {cross-project insight 1}
- {cross-project insight 2}

Recommended next steps:
1. Review .claude/logs/ANALYSIS_REPORT.md for full details
2. Consider creating skills for high-priority patterns
3. Update AGENTS.md with guidance for common questions

Error Handling

Situation	Action
~/.claude/logs/ directory does not exist	Create it with mkdir -p ~/.claude/logs, report no sessions logged yet, suggest running /install-hooks
Session log file is malformed	Skip malformed lines, continue processing valid entries, note "X entries skipped due to malformed data"
Transcript files are inaccessible	Continue analysis without transcript data, mark transcript-dependent insights as "Limited (transcripts unavailable)"
No patterns found after analysis	Report "No automation opportunities identified", suggest running again after 5+ additional sessions
ANALYSIS_REPORT.md cannot be written	Output the report to the terminal instead, report the write failure with the specific error

Limitations

• Transcript files may not be accessible (permissions, deleted)
• Analysis quality depends on session data available
• Some patterns require human judgment to identify
• Cross-project analysis requires the user-level hook to be installed