codex-session-insights 0.2.0 → 0.2.1

package/lib/llm-insights.js

@@ -276,24 +276,27 @@ const SECTION_DEFS = [
     contextKind: 'project_areas',
     schemaName: 'codex_project_areas',
     schema: PROJECT_AREAS_SCHEMA,
-    prompt: `Analyze this Codex usage data and identify project areas.
+    prompt: `Analyze this Codex usage data and identify the user's main workstreams.
 
 RESPOND WITH ONLY A VALID JSON OBJECT:
 {
   "areas": [
-    {"name": "Area name", "session_count": 0, "description": "2-3 sentences about what was worked on and how Codex was used."}
+    {"name": "Area name", "session_count": 0, "description": "2-3 sentences describing the workstream, its recurring tasks, and why it matters."}
   ]
 }
 
-Include 4-5 areas. Skip Codex self-hosting/meta work unless it is a dominant project area.
+Include 3-4 areas. Skip Codex self-hosting/meta work unless it is a dominant project area.
 
 Guardrails:
 - Use concrete project or workstream names, not generic labels like "coding" or "development"
 - Base areas on repeated evidence across summaries, not one-off threads
 - Prefer project + task framing over tool-centric framing
-- Group related tasks into a coherent workstream instead of listing each task separately
-- Each description should sound like a mini report paragraph: what kinds of work clustered together, then how Codex contributed
-- Prefer descriptions that mention representative tasks or artifacts instead of vague labels`,
+- Group related tasks into a coherent long-running workstream instead of listing each task separately
+- Prefer fewer, broader areas that still feel accurate over a more complete but fragmented list
+- Do not turn recent sub-tasks, bugfixes, or cleanup passes into separate areas unless they clearly form their own repeated stream
+- Each description should read like a workstream summary, not a changelog
+- Mention representative tasks, artifacts, or decisions so the area feels concrete without enumerating every thread
+- Keep the focus on what the user was trying to accomplish; mention Codex only lightly when it clarifies the shape of the work`,
   },
   {
     name: 'interaction_style',
@@ -311,9 +314,12 @@ RESPOND WITH ONLY A VALID JSON OBJECT:
 
 Guardrails:
 - Focus on stable interaction patterns, not isolated moments
-- Talk about how the user scopes work, interrupts, redirects, or trusts execution
+- Talk about how the user scopes work, redirects goals, sets acceptance bars, or trusts execution
+- Prefer evidence from user requests, follow-up corrections, repeated constraints, and outcome patterns over implementation telemetry
 - Do not infer user preference from Codex's default tool mix or harness behavior; high exec/tool usage can reflect the agent's operating style rather than the user's instructions
 - Treat shell usage, file reads, and verification commands as weak evidence unless the user explicitly asked for that working style
+- Do not infer style from repository type, documentation volume, or language mix alone
+- Avoid turning a single repo's workflow shape into a personality claim about the user
 - If evidence is mixed, describe the tension instead of forcing one clean story`,
   },
   {
@@ -360,6 +366,7 @@ Include 3 friction categories with 2 examples each.
 Guardrails:
 - Separate model-side friction from user/workflow-side friction when useful
 - Examples must be concrete and tied to the supplied evidence
+- Treat overlap or concurrency metrics as weak supporting evidence unless the summaries or friction details also show real switching pain
 - Do not invent root causes that are not visible in the data`,
   },
   {
@@ -401,6 +408,9 @@ Guardrails:
 - Suggest only actions that clearly connect to repeated evidence
 - Avoid generic advice like "give more context" unless it is overwhelmingly justified
 - Prefer changes with strong leverage: repo memory, repeatable workflows, automation, or parallelism
+- Do not recommend first-time adoption of AGENTS.md, Skills, codex exec, Sub-agents, or MCP Servers when the capability_adoption evidence shows the user already uses them in a moderate or strong way
+- When a capability is already adopted, suggest a deeper refinement or a tighter operating pattern instead of basic adoption
+- Distinguish "you should start using this" from "you should formalize or deepen how you already use this"
 - Write AGENTS.md additions as directly pasteable instruction lines, not commentary about instructions
 - Make feature examples immediately usable; avoid placeholders like "insert your repo path here" unless unavoidable
 - Make usage pattern suggestions sound like concrete next actions the user can try today, not abstract best practices`,
@@ -989,6 +999,8 @@ function buildInsightContext(report, threadSummaries, facets) {
     ),
   ).slice(0, MAX_USER_INSTRUCTIONS)
 
+  const capabilityAdoption = summarizeCapabilityAdoption(report, threadSummaries, facets)
+
   return {
     metadata: {
       generated_at: report.metadata.generatedAt,
@@ -1025,6 +1037,7 @@ function buildInsightContext(report, threadSummaries, facets) {
       friction,
       success,
     },
+    capability_adoption: capabilityAdoption,
     session_summaries: sortedFacets.slice(0, MAX_CONTEXT_FACETS).map(facet => ({
       thread_id: facet.threadId,
       title: truncateForContext(facet.title, 80),
@@ -1051,6 +1064,69 @@ function buildInsightContext(report, threadSummaries, facets) {
   }
 }
 
+function summarizeCapabilityAdoption(report, threadSummaries, facets) {
+  const textByThread = new Map()
+  for (const thread of threadSummaries) {
+    textByThread.set(
+      thread.id,
+      [thread.title, thread.firstUserMessage]
+        .map(value => String(value || ''))
+        .join('\n')
+        .toLowerCase(),
+    )
+  }
+
+  for (const facet of facets) {
+    const existing = textByThread.get(facet.threadId) || ''
+    const facetText = [
+      facet.underlying_goal,
+      facet.brief_summary,
+      ...(facet.user_instructions || []),
+    ]
+      .map(value => String(value || ''))
+      .join('\n')
+      .toLowerCase()
+    textByThread.set(facet.threadId, `${existing}\n${facetText}`.trim())
+  }
+
+  const detectMentionedThreads = regex => {
+    let count = 0
+    for (const text of textByThread.values()) {
+      if (regex.test(text)) count += 1
+    }
+    return count
+  }
+
+  const totalThreads = Math.max(1, Number(report.metadata.threadCount || threadSummaries.length || 0))
+  const signals = {
+    agents_md: detectMentionedThreads(/\bagents\.md\b/i),
+    skills: detectMentionedThreads(/\bskills?\b/i),
+    codex_exec: detectMentionedThreads(/\bcodex exec\b/i),
+    subagents: Number(report.summary.sessionsUsingTaskAgent || 0),
+    mcp_servers: Number(report.summary.sessionsUsingMcp || 0),
+    web_search: Number(report.summary.sessionsUsingWebSearch || 0),
+    web_fetch: Number(report.summary.sessionsUsingWebFetch || 0),
+  }
+
+  return Object.fromEntries(
+    Object.entries(signals).map(([key, count]) => [
+      key,
+      {
+        count,
+        status: classifyCapabilityAdoption(count, totalThreads),
+      },
+    ]),
+  )
+}
+
+function classifyCapabilityAdoption(count, totalThreads) {
+  const share = Number(count || 0) / Math.max(1, Number(totalThreads || 0))
+  if (count >= 10 || share >= 0.25) return 'strong'
+  if (count >= 4 || share >= 0.1) return 'moderate'
+  if (count > 0) return 'light'
+  return 'none'
+}
+
 function buildAtAGlancePrompt(context, insights) {
   return `You are writing an "At a Glance" summary for a Codex usage insights report.
 

package/lib/report.js

@@ -1,3 +1,4 @@
+import os from 'node:os'
 import path from 'node:path'
 import { promises as fs } from 'node:fs'
 
@@ -6,6 +7,9 @@ export function buildReport(threadSummaries, options = {}) {
   const modelCounts = {}
   const toolCounts = {}
   const commandKindCounts = {}
+  const capabilityCounts = {}
+  const outcomeCounts = {}
+  const sessionTypeCounts = {}
   const toolFailureCounts = {}
   const activeHourCounts = {}
   const responseTimes = []
@@ -81,8 +85,20 @@ export function buildReport(threadSummaries, options = {}) {
     if (thread.usesMcp) sessionsUsingMcp += 1
     if (thread.usesWebSearch) sessionsUsingWebSearch += 1
     if (thread.usesWebFetch) sessionsUsingWebFetch += 1
+    if (thread.filesModified > 0) increment(capabilityCounts, 'Repo edits')
+    if (thread.gitCommits > 0 || thread.gitPushes > 0) increment(capabilityCounts, 'Git activity')
   }
 
+  for (const facet of options.facets || []) {
+    if (facet.outcome) increment(outcomeCounts, facet.outcome)
+    if (facet.session_type) increment(sessionTypeCounts, facet.session_type)
+  }
+
+  if (sessionsUsingTaskAgent > 0) increment(capabilityCounts, 'Sub-agents', sessionsUsingTaskAgent)
+  if (sessionsUsingMcp > 0) increment(capabilityCounts, 'MCP servers', sessionsUsingMcp)
+  if (sessionsUsingWebSearch > 0) increment(capabilityCounts, 'Web search', sessionsUsingWebSearch)
+  if (sessionsUsingWebFetch > 0) increment(capabilityCounts, 'Web fetch', sessionsUsingWebFetch)
+
   const sortedThreads = [...threadSummaries].sort(
     (a, b) => Date.parse(b.updatedAt) - Date.parse(a.updatedAt),
   )
@@ -130,6 +146,9 @@ export function buildReport(threadSummaries, options = {}) {
       models: topEntries(modelCounts, 10),
       tools: topEntries(toolCounts, 12),
       commandKinds: topEntries(commandKindCounts, 12),
+      capabilities: topEntries(capabilityCounts, 8),
+      outcomes: topEntries(outcomeCounts, 8),
+      sessionTypes: topEntries(sessionTypeCounts, 8),
       toolFailures: topEntries(toolFailureCounts, 8),
       toolErrorCategories: topEntries(toolErrorCategoryCounts, 8),
       activeHours: buildHourSeries(activeHourCounts),
@@ -176,13 +195,13 @@ export function renderTerminalSummary(report) {
     lines.push(`${report.metadata.dateRange.start} -> ${report.metadata.dateRange.end}`)
   }
   lines.push('')
-  lines.push(`${text.topTools}:`)
-  for (const item of report.charts.tools.slice(0, 5)) {
-    lines.push(`  ${item.label}: ${item.value}`)
-  }
-  lines.push('')
   lines.push(`${text.topProjects}:`)
   for (const item of report.charts.projects.slice(0, 5)) {
+    lines.push(`  ${formatProjectLabel(item.label)}: ${item.value}`)
+  }
+  lines.push('')
+  lines.push(`${text.modelMix}:`)
+  for (const item of report.charts.models.slice(0, 5)) {
     lines.push(`  ${item.label}: ${item.value}`)
   }
   return lines.join('\n')
@@ -193,9 +212,11 @@ function renderHtmlReport(report) {
   const insights = report.insights
   if (insights && !insights.__lang) insights.__lang = report.metadata.language
   const analysisUsage = report.analysisUsage || null
-  const topTools = renderBarList(report.charts.tools)
-  const topProjects = renderBarList(report.charts.projects)
-  const commandKinds = renderBarList(report.charts.commandKinds)
+  const topProjects = renderBarList(report.charts.projects, { formatLabel: formatProjectLabel })
+  const modelMix = renderBarList(report.charts.models)
+  const sessionTypes = renderBarList(report.charts.sessionTypes)
+  const outcomes = renderBarList(report.charts.outcomes)
+  const capabilitySignals = renderBarList(report.charts.capabilities)
   const toolFailures = renderBarList(report.charts.toolFailures)
   const toolErrorCategories = renderBarList(report.charts.toolErrorCategories)
   const activeHours = renderHourHistogram(report.charts.activeHours)
@@ -639,7 +660,7 @@ function renderHtmlReport(report) {
       <section class="hero">
         <span class="eyebrow">${escapeHtml(text.eyebrow)}</span>
         <h1>${escapeHtml(text.reportTitle)}</h1>
-        <p class="meta">${escapeHtml(text.generatedLabel)} ${escapeHtml(report.metadata.generatedAt)} ${escapeHtml(text.generatedFrom)} ${report.metadata.threadCount} ${escapeHtml(text.substantiveThreads)} ${escapeHtml(text.inCodexHome)} ${escapeHtml(report.metadata.codexHome)}.</p>
+        <p class="meta">${escapeHtml(text.generatedLabel)} ${escapeHtml(report.metadata.generatedAt)} ${escapeHtml(text.generatedFrom)} ${report.metadata.threadCount} ${escapeHtml(text.substantiveThreads)} ${escapeHtml(text.inCodexHome)} ${escapeHtml(formatCodexHome(report.metadata.codexHome))}.</p>
         <div class="summary-grid">
           ${renderStat(text.userMessages, formatNumber(report.summary.totalUserMessages))}
           ${renderStat(text.toolCalls, formatNumber(report.summary.totalToolCalls))}
@@ -672,17 +693,25 @@ function renderHtmlReport(report) {
           ${renderOnTheHorizon(insights)}
         </div>
         <aside class="side-column">
-          <section class="chart-panel">
-            <h2>${escapeHtml(text.topTools)}</h2>
-            ${topTools}
-          </section>
           <section class="chart-panel">
             <h2>${escapeHtml(text.topProjects)}</h2>
             ${topProjects}
           </section>
           <section class="chart-panel">
-            <h2>${escapeHtml(text.commandKinds)}</h2>
-            ${commandKinds}
+            <h2>${escapeHtml(text.modelMix)}</h2>
+            ${modelMix}
+          </section>
+          <section class="chart-panel">
+            <h2>${escapeHtml(text.sessionTypes)}</h2>
+            ${sessionTypes}
+          </section>
+          <section class="chart-panel">
+            <h2>${escapeHtml(text.outcomes)}</h2>
+            ${outcomes}
+          </section>
+          <section class="chart-panel">
+            <h2>${escapeHtml(text.capabilitySignals)}</h2>
+            ${capabilitySignals}
           </section>
           <section class="chart-panel">
             <h2>${escapeHtml(text.failureHotspots)}</h2>
@@ -1054,15 +1083,16 @@ function renderStat(label, value) {
   return `<div class="stat"><div class="value">${escapeHtml(String(value))}</div><div>${escapeHtml(label)}</div></div>`
 }
 
-function renderBarList(items) {
+function renderBarList(items, options = {}) {
   if (!items.length) return '<p class="meta">No data available.</p>'
+  const formatLabel = options.formatLabel || (value => value)
   const maxValue = Math.max(...items.map(item => item.value), 1)
   return `<div class="bar-list">${items
     .map(
       item => `
         <div class="bar-row">
           <div class="bar-label">
-            <span>${escapeHtml(item.label)}</span>
+            <span>${escapeHtml(formatLabel(item.label))}</span>
             <strong>${formatNumber(item.value)}</strong>
           </div>
           <div class="bar-track"><div class="bar-fill" style="width:${Math.max(6, (item.value / maxValue) * 100)}%"></div></div>
@@ -1133,6 +1163,36 @@ function topEntries(map, limit) {
     .map(([label, value]) => ({ label, value }))
 }
 
+function formatCodexHome(value) {
+  return formatDisplayPath(value, { tailSegments: 2, preferHomeAlias: true, ellipsis: false })
+}
+
+function formatProjectLabel(value) {
+  return formatDisplayPath(value, { tailSegments: 2, preferHomeAlias: false, ellipsis: true })
+}
+
+function formatDisplayPath(value, options = {}) {
+  const text = String(value || '').trim()
+  if (!text) return '(unknown)'
+
+  const normalized = text.replace(/\\/g, '/')
+  const home = os.homedir().replace(/\\/g, '/')
+  if (options.preferHomeAlias !== false && normalized === home) return '~'
+  if (options.preferHomeAlias !== false && normalized.startsWith(`${home}/`)) {
+    return `~/${normalized.slice(home.length + 1)}`
+  }
+
+  const parts = normalized.split('/').filter(Boolean)
+  const tailSegments = Math.max(1, Number(options.tailSegments || 2))
+  if (parts.length <= tailSegments) {
+    return normalized.startsWith('/') ? `/${parts.join('/')}` : parts.join('/')
+  }
+
+  const tail = parts.slice(-tailSegments).join('/')
+  if (options.ellipsis === false) return tail
+  return `…/${tail}`
+}
+
 function buildHourSeries(hourMap) {
   return Array.from({ length: 24 }, (_, hour) => ({
     hour,
@@ -1244,9 +1304,11 @@ function getReportText(lang) {
       filesModified: '修改文件',
       toolErrors: '工具错误',
       avgResponse: '平均响应',
-      topTools: 'Top Tools',
       topProjects: 'Top Projects',
-      commandKinds: '命令类型',
+      modelMix: '模型分布',
+      sessionTypes: '会话类型',
+      outcomes: '结果分布',
+      capabilitySignals: '能力信号',
       failureHotspots: '失败热点',
       errorCategories: '错误分类',
       timeOfDay: '活跃时段',
@@ -1321,9 +1383,11 @@ function getReportText(lang) {
     filesModified: 'Files Modified',
     toolErrors: 'Tool Errors',
     avgResponse: 'Avg Response',
-    topTools: 'Top Tools',
     topProjects: 'Top Projects',
-    commandKinds: 'Command Kinds',
+    modelMix: 'Model Mix',
+    sessionTypes: 'Session Types',
+    outcomes: 'Outcomes',
+    capabilitySignals: 'Capability Signals',
     failureHotspots: 'Failure Hotspots',
     errorCategories: 'Error Categories',
     timeOfDay: 'Time of Day',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-session-insights",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Generate a report analyzing your Codex sessions.",
   "type": "module",
   "bin": {