Deep Dive: How Claude Code's /insights Command Works

Summarize this portion of a Claude Code session transcript. Focus on:
1. What the user asked for
2. What Claude did (tools used, files modified)
3. Any friction or issues
4. The outcome

Keep it concise - 3-5 sentences. Preserve specific details like file names,
error messages, and user feedback.

TRANSCRIPT CHUNK:

Analyze this Claude Code session and extract structured facets.

CRITICAL GUIDELINES:

1. **goal_categories**: Count ONLY what the USER explicitly asked for.
   - DO NOT count Claude's autonomous codebase exploration
   - DO NOT count work Claude decided to do on its own
   - ONLY count when user says "can you...", "please...", "I need...", "let's..."

2. **user_satisfaction_counts**: Base ONLY on explicit user signals.
   - "Yay!", "great!", "perfect!" → happy
   - "thanks", "looks good", "that works" → satisfied
   - "ok, now let's..." (continuing without complaint) → likely_satisfied
   - "that's not right", "try again" → dissatisfied
   - "this is broken", "I give up" → frustrated

3. **friction_counts**: Be specific about what went wrong.
   - misunderstood_request: Claude interpreted incorrectly
   - wrong_approach: Right goal, wrong solution method
   - buggy_code: Code didn't work correctly
   - user_rejected_action: User said no/stop to a tool call
   - excessive_changes: Over-engineered or changed too much

4. If very short or just warmup, use warmup_minimal for goal_category

SESSION:
<session transcript is inserted here>

RESPOND WITH ONLY A VALID JSON OBJECT matching this schema:
{
  "underlying_goal": "What the user fundamentally wanted to achieve",
  "goal_categories": {"category_name": count, ...},
  "outcome": "fully_achieved|mostly_achieved|partially_achieved|not_achieved|unclear_from_transcript",
  "user_satisfaction_counts": {"level": count, ...},
  "claude_helpfulness": "unhelpful|slightly_helpful|moderately_helpful|very_helpful|essential",
  "session_type": "single_task|multi_task|iterative_refinement|exploration|quick_question",
  "friction_counts": {"friction_type": count, ...},
  "friction_detail": "One sentence describing friction or empty",
  "primary_success": "none|fast_accurate_search|correct_code_edits|good_explanations|proactive_help|multi_file_changes|good_debugging",
  "brief_summary": "One sentence: what user wanted and whether they got it"
}

{
  sessions: <total sessions>,
  analyzed: <sessions with facets>,
  date_range: { start, end },
  messages: <total messages>,
  hours: <total duration in hours>,
  commits: <git commits>,
  top_tools: [top 8 tools by usage],
  top_goals: [top 8 goal categories],
  outcomes: { outcome distribution },
  satisfaction: { satisfaction distribution },
  friction: { friction type counts },
  success: { success category counts },
  languages: { language usage counts }
}

Analyze this Claude Code usage data and identify project areas.

RESPOND WITH ONLY A VALID JSON OBJECT:
{
  "areas": [
    {
      "name": "Area name",
      "session_count": N,
      "description": "2-3 sentences about what was worked on and how Claude Code was used."
    }
  ]
}

Include 4-5 areas. Skip internal CC operations.

Analyze this Claude Code usage data and describe the user's interaction style.

RESPOND WITH ONLY A VALID JSON OBJECT:
{
  "narrative": "2-3 paragraphs analyzing HOW the user interacts with Claude Code.
               Use second person 'you'. Describe patterns: iterate quickly vs
               detailed upfront specs? Interrupt often or let Claude run?
               Include specific examples. Use **bold** for key insights.",
  "key_pattern": "One sentence summary of most distinctive interaction style"
}

Analyze this Claude Code usage data and identify what's working well for this user.
Use second person ("you").

RESPOND WITH ONLY A VALID JSON OBJECT:
{
  "intro": "1 sentence of context",
  "impressive_workflows": [
    {
      "title": "Short title (3-6 words)",
      "description": "2-3 sentences describing the impressive workflow or approach.
                      Use 'you' not 'the user'."
    }
  ]
}

Include 3 impressive workflows.

Analyze this Claude Code usage data and identify friction points for this user.
Use second person ("you").

RESPOND WITH ONLY A VALID JSON OBJECT:
{
  "intro": "1 sentence summarizing friction patterns",
  "categories": [
    {
      "category": "Concrete category name",
      "description": "1-2 sentences explaining this category and what could be
                      done differently. Use 'you' not 'the user'.",
      "examples": ["Specific example with consequence", "Another example"]
    }
  ]
}

Include 3 friction categories with 2 examples each.

Analyze this Claude Code usage data and suggest improvements.

## CC FEATURES REFERENCE (pick from these for features_to_try):

1. **MCP Servers**: Connect Claude to external tools, databases, and APIs via
   Model Context Protocol.
   - How to use: Run `claude mcp add <server-name> -- <command>`
   - Good for: database queries, Slack integration, GitHub issue lookup,
     connecting to internal APIs

2. **Custom Skills**: Reusable prompts you define as markdown files that run
   with a single /command.
   - How to use: Create `.claude/skills/commit/SKILL.md` with instructions.
     Then type `/commit` to run it.
   - Good for: repetitive workflows - /commit, /review, /test, /deploy, /pr,
     or complex multi-step workflows

3. **Hooks**: Shell commands that auto-run at specific lifecycle events.
   - How to use: Add to `.claude/settings.json` under "hooks" key.
   - Good for: auto-formatting code, running type checks, enforcing conventions

4. **Headless Mode**: Run Claude non-interactively from scripts and CI/CD.
   - How to use: `claude -p "fix lint errors" --allowedTools "Edit,Read,Bash"`
   - Good for: CI/CD integration, batch code fixes, automated reviews

5. **Task Agents**: Claude spawns focused sub-agents for complex exploration
   or parallel work.
   - How to use: Claude auto-invokes when helpful, or ask "use an agent to explore X"
   - Good for: codebase exploration, understanding complex systems

RESPOND WITH ONLY A VALID JSON OBJECT:
{
  "claude_md_additions": [
    {
      "addition": "A specific line or block to add to CLAUDE.md based on workflow
                   patterns. E.g., 'Always run tests after modifying auth-related files'",
      "why": "1 sentence explaining why this would help based on actual sessions",
      "prompt_scaffold": "Instructions for where to add this in CLAUDE.md.
                          E.g., 'Add under ## Testing section'"
    }
  ],
  "features_to_try": [
    {
      "feature": "Feature name from CC FEATURES REFERENCE above",
      "one_liner": "What it does",
      "why_for_you": "Why this would help YOU based on your sessions",
      "example_code": "Actual command or config to copy"
    }
  ],
  "usage_patterns": [
    {
      "title": "Short title",
      "suggestion": "1-2 sentence summary",
      "detail": "3-4 sentences explaining how this applies to YOUR work",
      "copyable_prompt": "A specific prompt to copy and try"
    }
  ]
}

IMPORTANT for claude_md_additions: PRIORITIZE instructions that appear MULTIPLE TIMES
in the user data. If user told Claude the same thing in 2+ sessions (e.g.,
'always run tests', 'use TypeScript'), that's a PRIME candidate - they shouldn't
have to repeat themselves.

IMPORTANT for features_to_try: Pick 2-3 from the CC FEATURES REFERENCE above.
Include 2-3 items for each category.

Analyze this Claude Code usage data and identify future opportunities.

RESPOND WITH ONLY A VALID JSON OBJECT:
{
  "intro": "1 sentence about evolving AI-assisted development",
  "opportunities": [
    {
      "title": "Short title (4-8 words)",
      "whats_possible": "2-3 ambitious sentences about autonomous workflows",
      "how_to_try": "1-2 sentences mentioning relevant tooling",
      "copyable_prompt": "Detailed prompt to try"
    }
  ]
}

Include 3 opportunities. Think BIG - autonomous workflows, parallel agents,
iterating against tests.

Analyze this Claude Code usage data and find a memorable moment.

RESPOND WITH ONLY A VALID JSON OBJECT:
{
  "headline": "A memorable QUALITATIVE moment from the transcripts - not a statistic.
               Something human, funny, or surprising.",
  "detail": "Brief context about when/where this happened"
}

Find something genuinely interesting or amusing from the session summaries.

You're writing an "At a Glance" summary for a Claude Code usage insights report
for Claude Code users. The goal is to help them understand their usage and
improve how they can use Claude better, especially as models improve.

Use this 4-part structure:

1. **What's working** - What is the user's unique style of interacting with Claude
   and what are some impactful things they've done? You can include one or two
   details, but keep it high level since things might not be fresh in the user's
   memory. Don't be fluffy or overly complimentary. Also, don't focus on the
   tool calls they use.

2. **What's hindering you** - Split into (a) Claude's fault (misunderstandings,
   wrong approaches, bugs) and (b) user-side friction (not providing enough
   context, environment issues -- ideally more general than just one project).
   Be honest but constructive.

3. **Quick wins to try** - Specific Claude Code features they could try from the
   examples below, or a workflow technique if you think it's really compelling.
   (Avoid stuff like "Ask Claude to confirm before taking actions" or "Type out
   more context up front" which are less compelling.)

4. **Ambitious workflows for better models** - As we move to much more capable
   models over the next 3-6 months, what should they prepare for? What workflows
   that seem impossible now will become possible? Draw from the appropriate
   section below.

Keep each section to 2-3 not-too-long sentences. Don't overwhelm the user.
Don't mention specific numerical stats or underlined_categories from the
session data below. Use a coaching tone.

RESPOND WITH ONLY A VALID JSON OBJECT:
{
  "whats_working": "(refer to instructions above)",
  "whats_hindering": "(refer to instructions above)",
  "quick_wins": "(refer to instructions above)",
  "ambitious_workflows": "(refer to instructions above)"
}

SESSION DATA:
<aggregated statistics JSON>

## Project Areas (what user works on)
<project_areas results>

## Big Wins (impressive accomplishments)
<what_works results>

## Friction Categories (where things go wrong)
<friction_analysis results>

## Features to Try
<suggestions.features_to_try results>

## Usage Patterns to Adopt
<suggestions.usage_patterns results>

## On the Horizon (ambitious workflows for better models)
<on_the_horizon results>

function generateInsights():
    // Stage 1: Load and filter sessions
    sessions = loadSessionLogs("~/.claude/projects/")
    sessions = sessions.filter(s =>
        !isAgentSession(s) &&
        !isInternalSession(s) &&
        s.userMessageCount >= 2 &&
        s.durationMinutes >= 1
    )

    // Extract metadata from each session
    metadata = sessions.map(extractMetadata)

    // Stage 2 & 3: Extract facets (with caching)
    facets = {}
    for session in sessions:
        cached = loadCachedFacet(session.id)
        if cached:
            facets[session.id] = cached
        else:
            transcript = session.transcript
            if transcript.length > 30000:
                transcript = summarizeInChunks(transcript)

            facets[session.id] = callLLM(FACET_EXTRACTION_PROMPT + transcript)
            saveFacetToCache(session.id, facets[session.id])

    // Stage 4: Aggregate and analyze
    aggregated = aggregateAllData(metadata, facets)

    insights = {}
    insights.project_areas = callLLM(PROJECT_AREAS_PROMPT, aggregated)
    insights.interaction_style = callLLM(INTERACTION_STYLE_PROMPT, aggregated)
    insights.what_works = callLLM(WHAT_WORKS_PROMPT, aggregated)
    insights.friction = callLLM(FRICTION_PROMPT, aggregated)
    insights.suggestions = callLLM(SUGGESTIONS_PROMPT, aggregated)
    insights.on_the_horizon = callLLM(ON_THE_HORIZON_PROMPT, aggregated)
    insights.fun_ending = callLLM(FUN_ENDING_PROMPT, aggregated)

    // Stage 5: Generate executive summary
    insights.at_a_glance = callLLM(AT_A_GLANCE_PROMPT, aggregated + insights)

    // Stage 6: Render HTML report
    html = renderReport(aggregated, insights)
    saveFile("~/.claude/usage-data/report.html", html)

    return insights