insightful

Files (3)

• SKILL.md
• backfill-facets.mjs
• collect-insights.js

SKILL.md (first lines)

# Insightful — Complete Claude Code Usage Report

Generate a comprehensive HTML insights report covering every Claude Code conversation across all projects. This skill produces a report matching the depth and quality of the built-in `/insights` command — with the same structured analysis stages — but covering ALL sessions ever, not just recent ones.

## How Insightful differs from `/insights`

| | Built-in `/insights` | Insightful |
|:--|:-----|:-----|
| **Scope** | Recent sessions only | Every session ever recorded |
| **Data sources** | stats-cache + recent facets | 5 sources: history.jsonl, stats-cache, facets, session indexes, .jsonl transcripts |
| **Git commits** | Not tracked | Detected from Bash tool calls in .jsonl files |
| **Hours spent** | Not tracked | Calculated from session timestamps |
| **Multi-clauding** | Not analyzed | Detects concurrent session overlaps |
| **Notable sessions** | Not included | Top 5 most intense sessions highlighted |
| **Evolution** | Not tracked | Month-over-month usage trends |
| **Pre-tracking data** | Invisible | Recovers sessions from before stats-cache existed |
| **Output** | In-terminal summary | Interactive HTML report with charts, copy buttons, collapsible sections |

## Step 0: Backfill Facets (first-time setup)

Facets are qualitative per-session analysis files (goal, outcome, satisfaction, friction, helpfulness). Claude Code generates them automatically going forward, but older sessions may not have them — which means gaps in satisfaction and friction analysis.

Run the collect script first to check coverage:

```bash
node "${CLAUDE_PLUGIN_ROOT}/skills/insightful/collect-insights.js"
```

If it prints a `⚠️ FACET COVERAGE LOW` warning, backfill your historical sessions before generating the report. Backfill uses `claude -p` (your Claude Code subscription) — no API billing.

```bash
# Dry run — shows what would be processed, no LLM calls
node "${CLAUDE_PLUGIN_ROOT}/skills/insightful/backfill-facets.mjs" --dry-run

# Run first 50 sessions
node "${CLAUDE_PLUGIN_ROOT}/skills/insightful/backfill-facets.mjs" --chunk=50

# Run all remaining
node "${CLAUDE_PLUGIN_ROOT}/skills/insightful/backfill-facets.mjs" --chunk=500
```

Re-run `collect-insights.js` after backfilling to confirm coverage improved.

## Step 1: Collect Data

Run the pre-aggregation script to scan all session data:

```bash
node "${CLAUDE_PLUGIN_ROOT}/skills/insightful/collect-insights.js"
```

This merges 5 data sources (history.jsonl, stats-cache.json, facets, sessions-index.json, .jsonl transcripts) and writes a comprehensive JSON summary to `~/.claude/usage-data/insightful-data.json`.

Output includes: sessions, projects, git commits, hours spent, tool usage, model usage, facets, and message accounting.

## Step 2: Analyze Data with Parallel Agents (Structured Stages)

The JSON output is typically 500KB–1MB — too large for a single context window. **You MUST use parallel agents to analyze the data deeply.** The agents must return structured analysis matching these exact stages (the same ones the built-in `/insights` uses internally).

Launch these 2 agents concurrently:

### Agent 1: Narrative & Projects Agent
Use a `general-purpose` Task agent with this prompt:

> Read `~/.claude/usage-data/insightful-data.json`. Analyze the data and return a structured report with these EXACT sections. Be specific — reference actual project names, session counts, tool names, dates, and first_prompts from the data:
>
> **1. project_areas** — For each of the top 20 projects (by session count), provide: name, session_count, date_range (first–last session), and a detailed 3-4 sentence description referencing SPECIFIC things the user did (based on first_prompts, facet summaries, tools used). Group remaining small projects into a summary.
>
> **2. interaction_style** — Analyze how the user interacts with Claude Code: their iteration style (do they give detailed specs upfront or iterate?), interruption patterns (do they let Claude finish or redirect mid-task?), feedback style (how they express satisfaction/frustration), preferred workflow (agents, single-shot, planning mode?). Write 2 specific paragraphs with examples.
>
> **3. what_works** — Identify 3-4 impressive things the user accomplished. Each needs a title and a 2-3 sentence description referencing specific projects, sessions, and outcomes. These should be genuinely impressive achievements.
>
> **4. at_a_glance** — Write 4 short paragraphs: (a) What's working well — specific tools, patterns, projects succeeding, (b) What's hindering — specific friction points from facets and session data, (c) Quick wins to try — actionable 1-sentence suggestions, (d) Ambitious workflows to explore — forward-looking ideas based on what the user already does well.
>
> **5. fun_ending** — Find one genuinely funny, surprising, or memorable moment from the sessions. Write a punchy headline (under 10 words) and a 2-sentence detail. Look at first_prompts, session patterns, marathon sessions, or unusual projects.
>
> Return all 5 sections clearly labeled.

### Agent 2: Metrics & Suggestions Agent
Use a `general-purpose` Task agent with this prompt:

> Read `~/.claude/usage-data/insightful-data.json`. Analyze the data and return a structured report with these EXACT sections. Be specific — use actual numbers, project names, dates, and tool names from the data:
>
> **1. friction_analysis** — Identify the top 3-5 friction categories from the facets data (all_facets array). For each: category name, occurrence count, a description of the pattern, AND 1-2 specific examples quoting actual session data. If no facets exist, analyze session patterns for likely friction points.
>
> **2. personalization_plan** — Four sub-sections. Everything must be derived from the user's ACTUAL data — friction counts, session types, tool usage patterns, facets. No generic tips.
>   - **hooks**: 3-5 hooks to add to `settings.json`. For each: a title, the exact JSON block (hook event + shell command, ready to paste), and a "why" citing the specific pattern in their data that justifies it. Available hook events: `UserPromptSubmit` (fires when user submits a prompt — good for injecting context or reminders), `PostToolUse` (fires after any tool runs — good for auto-running tests after Edit, logging, etc.), `Stop` (fires when Claude finishes responding — good for mandatory git checks, reminders), `PreToolUse` (fires before a tool runs — good for safety gates). Example: if they have many sessions with missing-commit friction → `Stop` hook running `git status`. If they have context-loss friction → `UserPromptSubmit` hook echoing a project summary. Base every hook on evidence from their data.
>   - **claude_md_instructions**: 5-7 instructions for CLAUDE.md, each traceable to a real pattern or friction in their data. Each needs: the exact instruction text (imperative voice, copy-pasteable as a bullet or rule), whether it's global or project-specific, and a one-line "Evidence:" note citing the data. Must be specific to this user — not reminders every developer needs.
>   - **skills_to_build**: 3 custom Claude Code skills the user should build, based on tasks repeated across multiple sessions. Each needs: skill name, 2-sentence description of what it does, which specific sessions/projects show the repeating pattern, and a starter prompt they can paste to begin building it.
>   - **settings_to_configure**: 3-4 `settings.json` changes (tools to pre-allow in permissions, env vars to set, or other settings). Each needs: the exact JSON and a one-sentence justification from their tool usage or friction data.
>
> **3. on_the_horizon** — 3 forward-looking automation opportunities based on what the user already does. Each needs: title, description of the opportunity, and a specific copyable prompt to get started. Think about what they could automate next given their existing tools and projects.
>
> **4. multi_clauding** — Analyze session overlap: find sessions that overlap in time (compare first_timestamp to last_timestamp across sessions). Count: total overlap events, max concurrent sessions, peak date, and list the top 5 cross-project pairs that run simultaneously most often. If the data shows no overlaps, say so.
>
> **5. notable_sessions** — Find the 5 most interesting/intense sessions. For each: project, date, prompt count, tool count, duration, and a 1-2 sentence description of what happened.
>
> **6. evolution** — How has usage changed over time? Monthly trends in sessions/messages, model adoption changes, shifts in project focus, and any key inflection points. Include specific numbers.
>
> Return all 6 sections clearly labeled.

## Step 3: Read Summary Stats Directly

While agents process, extract the top-level stats:

```bash
node -e "const d=require(process.env.USERPROFILE+'/.claude/usage-data/insightful-data.json'); console.log(JSON.stringify({sessions:d.total_sessions_found, stats_sessions:d.total_sessions_from_stats, stats_messages:d.total_messages_from_stats, projects:d.total_projects, git_commits:d.total_git_commits, hours:d.total_hours, facets:d.sessions_with_facets, accounting:d.message_accounting, sources:d.data_sources, facets_summary:d.facets_summary, tools:d.global_tool_totals}, null, 2));"
```

Also extract: `stats_cache.modelUsage`, `stats_cache.hourCounts`, `stats_cache.dailyActivity`, `all_facets` friction details.

## Step 4: Launch Report Writer Agent

Once agents 1 & 2 return AND you have the summary stats from Step 3, launch a 3rd `general-purpose` Task agent to assemble and write the HTML report. This offloads report generation to a fresh context, keeping the main session lightweight and avoiding context bloat from the large HTML.

Pass these to the agent's prompt:
- The COMPLETE output from Agent 1 (all 5 sections)
- The COMPLETE output from Agent 2 (all 6 sections)
- The summary stats JSON from Step 3

From hamchowderr/braynee, MIT.

More from hamchowderr/braynee