| name | analyze-sessions |
| description | Extract automation patterns from session logs and rank by impact. Use periodically after multiple sessions to identify repetitive workflows that could become skills or hooks. |
| argument-hint | [--project <name>] [--targets-only] |
| allowed-tools | Read, Write, Glob, Grep, Bash |
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:
- Read the transcript file
- 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
