codex-session-insights 0.2.1 → 0.2.3

package/README.md

@@ -60,6 +60,12 @@ Default run:
 npx codex-session-insights
 ```
 
+Lite local run for prompt and layout testing:
+
+```bash
+npx codex-session-insights --preset lite
+```
+
 Estimate first, then decide:
 
 ```bash
@@ -120,6 +126,7 @@ Current default analysis plan:
 
 Important behavior defaults:
 
+- `--preset lite` maps to `days=7`, `limit=20`, `facet-limit=8`, `preview=10`
 - `limit` means the target number of substantive threads to include in the report, not just the first 50 indexed threads
 - `facet-limit` means the max number of uncached per-thread facet analyses to run in a single report
 - Report language follows a best-effort system locale check
@@ -195,7 +202,9 @@ Useful local commands:
 npm install
 npm test
 npm run check
+npm run report:lite
 npm run generate:test-report
 ```
 
+`npm run report:lite` runs a smaller local analysis preset for testing prompt and layout changes without paying the full 200/50 default cost.
 `npm run generate:test-report` writes a deterministic sample report page to `test-artifacts/sample-report/`.

package/lib/cli.js

@@ -99,6 +99,7 @@ export async function runCli(argv) {
   })
   report.analysisMode = 'llm'
   report.provider = parsed.options.provider
+  report.analysisEstimate = estimate
   report.analysisUsage = llmResult.analysisUsage
 
   progress.startStage(parsed.options, getUiText(parsed.options.lang).writingFiles)
@@ -135,11 +136,18 @@ export async function runCli(argv) {
 
 function parseArgs(argv) {
   let command = null
+  const explicit = {
+    days: false,
+    limit: false,
+    preview: false,
+    facetLimit: false,
+  }
   const options = {
     codexHome: null,
     outDir: null,
     jsonPath: null,
     htmlPath: null,
+    preset: DEFAULT_SCOPE_PRESET,
     days: 30,
     limit: 200,
     preview: 50,
@@ -195,14 +203,21 @@ function parseArgs(argv) {
       continue
     }
     if (arg === '--days') {
+      explicit.days = true
       options.days = toPositiveInt(requireValue(argv, ++i, '--days'), '--days')
       continue
     }
+    if (arg === '--preset') {
+      options.preset = normalizeScopePreset(requireValue(argv, ++i, '--preset'))
+      continue
+    }
     if (arg === '--limit') {
+      explicit.limit = true
       options.limit = toPositiveInt(requireValue(argv, ++i, '--limit'), '--limit')
       continue
     }
     if (arg === '--preview') {
+      explicit.preview = true
       options.preview = toPositiveInt(requireValue(argv, ++i, '--preview'), '--preview')
       continue
     }
@@ -255,6 +270,7 @@ function parseArgs(argv) {
       continue
     }
     if (arg === '--facet-limit') {
+      explicit.facetLimit = true
       options.facetLimit = toPositiveInt(requireValue(argv, ++i, '--facet-limit'), '--facet-limit')
       continue
     }
@@ -298,6 +314,19 @@ function parseArgs(argv) {
     throw new Error(`Invalid provider "${options.provider}". Expected codex-cli or openai.`)
   }
 
+  options.preset = normalizeScopePreset(options.preset)
+  const explicitValues = {
+    days: options.days,
+    limit: options.limit,
+    preview: options.preview,
+    facetLimit: options.facetLimit,
+  }
+  Object.assign(options, applyScopePreset(options, options.preset))
+  if (explicit.days) options.days = explicitValues.days
+  if (explicit.limit) options.limit = explicitValues.limit
+  if (explicit.preview) options.preview = explicitValues.preview
+  if (explicit.facetLimit) options.facetLimit = explicitValues.facetLimit
+
   return { command, options, help }
 }
 
@@ -330,6 +359,7 @@ Options:
   --json-path <path>        Exact path for report.json
   --html-path <path>        Exact path for report.html
   --days <n>                Only include threads updated in the last N days (default: 30)
+  --preset <name>           Scope preset: lite, standard, or deep (default: standard)
   --limit <n>               Target number of substantive threads to include (default: 200)
   --preview <n>             Number of threads to embed in the HTML report (default: 50)
   --provider <name>         Model provider: codex-cli or openai (default: codex-cli)
@@ -681,11 +711,22 @@ function inferQualityPreset(options) {
 }
 
 function applyScopePreset(options, preset) {
-  if (preset === 'conservative') return { ...options, limit: 20, facetLimit: 8 }
+  if (preset === 'lite' || preset === 'conservative') {
+    return { ...options, days: 7, limit: 20, facetLimit: 8, preview: 10 }
+  }
   if (preset === 'deep') return { ...options, limit: 400, facetLimit: 50 }
   return { ...options, limit: 200, facetLimit: 50 }
 }
 
+function normalizeScopePreset(value) {
+  const preset = String(value || '').trim().toLowerCase()
+  if (preset === 'lite') return 'lite'
+  if (preset === 'conservative') return 'conservative'
+  if (preset === 'deep') return 'deep'
+  if (preset === 'standard' || !preset) return 'standard'
+  throw new Error(`Invalid preset "${value}". Expected lite, standard, or deep.`)
+}
+
 function applyQualityPreset(options, preset) {
   if (preset === 'cheaper') {
     return {
@@ -997,6 +1038,8 @@ export const __test = {
   applyScopePreset,
   applyQualityPreset,
   buildEquivalentCommand,
+  parseArgs,
+  normalizeScopePreset,
   normalizeLang,
   detectSystemLanguage,
 }

package/lib/codex-data.js

@@ -8,8 +8,16 @@ import { promisify } from 'node:util'
 const execFileAsync = promisify(execFile)
 const MAX_TRANSCRIPT_CHARS = 30000
 const USER_TRANSCRIPT_LIMIT = 500
-const ASSISTANT_TRANSCRIPT_LIMIT = 180
+const ASSISTANT_TRANSCRIPT_LIMIT = 300
 const FAILURE_SUMMARY_LIMIT = 120
+const MAX_TOOL_LINES_PER_BURST = 2
+const LOW_SIGNAL_ASSISTANT_PATTERNS = [
+  /^i('| a)?m\s+(checking|looking|reviewing|reading|investigating)\b/i,
+  /^i('| wi)?ll\s+(check|look|review|inspect|read|investigate|start by)\b/i,
+  /^let me\b/i,
+  /^(checking|reviewing|reading|looking at|investigating)\b/i,
+  /^(next|now)\b/i,
+]
 const TASK_AGENT_TOOLS = new Set([
   'spawn_agent',
   'send_input',
@@ -422,7 +430,7 @@ export function summarizeThread(thread, events) {
     averageResponseTimeSeconds: average(responseTimesSeconds),
     activeHours,
     userMessageTimestamps: sortedUserTs.map(tsMs => new Date(tsMs).toISOString()),
-    transcriptForAnalysis: clampTranscript(transcriptLines.join('\n')),
+    transcriptForAnalysis: clampTranscript(compactTranscriptLines(transcriptLines).join('\n')),
     gitCommits,
     gitPushes,
     userInterruptions,
@@ -627,6 +635,38 @@ function clampTranscript(text) {
   return `${clean.slice(0, MAX_TRANSCRIPT_CHARS)}\n[Transcript truncated]`
 }
 
+function compactTranscriptLines(lines) {
+  const compacted = []
+  let pendingToolBurst = []
+
+  const flushToolBurst = () => {
+    if (!pendingToolBurst.length) return
+    compacted.push(...pendingToolBurst.slice(0, MAX_TOOL_LINES_PER_BURST))
+    const remaining = pendingToolBurst.length - MAX_TOOL_LINES_PER_BURST
+    if (remaining > 0) {
+      compacted.push(`[Tool activity truncated: ${remaining} more tool calls]`)
+    }
+    pendingToolBurst = []
+  }
+
+  for (const line of lines) {
+    if (isLowSignalAssistantLine(line)) continue
+
+    if (isToolLine(line)) {
+      pendingToolBurst.push(line)
+      continue
+    }
+
+    flushToolBurst()
+    if (!compacted.length || compacted[compacted.length - 1] !== line) {
+      compacted.push(line)
+    }
+  }
+
+  flushToolBurst()
+  return compacted
+}
+
 function appendTranscriptLine(lines, line, setLastLine, lastLine) {
   const clean = String(line ?? '').trim()
   if (!clean || clean === lastLine) return
@@ -634,6 +674,20 @@ function appendTranscriptLine(lines, line, setLastLine, lastLine) {
   setLastLine(clean)
 }
 
+function isToolLine(line) {
+  const text = String(line || '')
+  return text.startsWith('[Tool: ')
+}
+
+function isLowSignalAssistantLine(line) {
+  const text = String(line || '')
+  if (!text.startsWith('[Assistant] ')) return false
+  const body = text.slice('[Assistant] '.length).trim()
+  if (!body) return true
+  if (body.length > 60) return false
+  return LOW_SIGNAL_ASSISTANT_PATTERNS.some(pattern => pattern.test(body))
+}
+
 function sanitizeTranscriptText(value, limit) {
   const text = String(value ?? '')
     .replace(/<system_instruction>[\s\S]*?<\/system_instruction>/g, ' ')

package/lib/llm-insights.js

@@ -411,6 +411,7 @@ Guardrails:
 - 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"
+- Use AGENTS.md as the canonical repo instruction filename in examples; do not mention CLAUDE.md
 - 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`,
@@ -597,6 +598,7 @@ export async function estimateLlmAnalysisCost({ threadSummaries, options = {} })
   const facetModel = options.facetModel || DEFAULT_FACET_MODEL
   const fastSectionModel = options.fastSectionModel || DEFAULT_FAST_SECTION_MODEL
   const insightModel = options.insightModel || DEFAULT_INSIGHT_MODEL
+  const provider = options.provider || DEFAULT_PROVIDER
   const cacheRoot = resolveCacheRoot(options.cacheDir)
   const facetCacheDir = path.join(cacheRoot, 'facets')
   await fs.mkdir(facetCacheDir, { recursive: true })
@@ -618,20 +620,35 @@ export async function estimateLlmAnalysisCost({ threadSummaries, options = {} })
   let combineSummaryCalls = 0
   let estimatedFacetInputTokens = 0
   let estimatedFacetOutputTokens = 0
-  let estimatedSummaryInputTokens = 0
-  let estimatedSummaryOutputTokens = 0
+  let estimatedChunkSummaryInputTokens = 0
+  let estimatedChunkSummaryOutputTokens = 0
+  let estimatedCombineSummaryInputTokens = 0
+  let estimatedCombineSummaryOutputTokens = 0
+  const facetSystemPrompt = buildFacetSystemPrompt(options.lang)
 
   for (const job of uncachedFacetJobs) {
     const transcript = String(job.thread.transcriptForAnalysis || '').trim()
     const transcriptChars = transcript.length
     if (!transcriptChars) {
-      estimatedFacetInputTokens += 600
+      estimatedFacetInputTokens += estimateModelInputTokens({
+        provider,
+        systemPrompt: facetSystemPrompt,
+        userPrompt: buildFacetExtractionPrompt(job.thread, `${job.thread.title || '(untitled)'}\n${job.thread.firstUserMessage || ''}`.trim(), options.lang),
+        schema: FACET_SCHEMA,
+        structured: true,
+      })
       estimatedFacetOutputTokens += 350
       continue
     }
 
     if (transcriptChars <= LONG_TRANSCRIPT_THRESHOLD) {
-      estimatedFacetInputTokens += estimateTokensFromChars(transcriptChars) + 1200
+      estimatedFacetInputTokens += estimateModelInputTokens({
+        provider,
+        systemPrompt: facetSystemPrompt,
+        userPrompt: buildFacetExtractionPrompt(job.thread, transcript, options.lang),
+        schema: FACET_SCHEMA,
+        structured: true,
+      })
       estimatedFacetOutputTokens += 350
       continue
     }
@@ -639,30 +656,65 @@ export async function estimateLlmAnalysisCost({ threadSummaries, options = {} })
     const chunks = chunkText(transcript, TRANSCRIPT_CHUNK_SIZE)
     chunkSummaryCalls += chunks.length
     for (const chunk of chunks) {
-      estimatedSummaryInputTokens += estimateTokensFromChars(chunk.length) + 220
-      estimatedSummaryOutputTokens += 260
+      estimatedChunkSummaryInputTokens += estimateModelInputTokens({
+        provider,
+        systemPrompt: `${FACET_TRANSCRIPT_SUMMARY_DIRECTIVE}\n\nPreserve user goal, outcome, friction, command/tool issues, and what the assistant actually achieved.`,
+        userPrompt: `Chunk 1 of ${chunks.length}\n\n${chunk}`,
+        structured: false,
+      })
+      estimatedChunkSummaryOutputTokens += 260
     }
     const combinedSummaryChars = chunks.length * 1100
     if (combinedSummaryChars > LONG_TRANSCRIPT_THRESHOLD) {
       combineSummaryCalls += 1
-      estimatedSummaryInputTokens += estimateTokensFromChars(combinedSummaryChars) + 180
-      estimatedSummaryOutputTokens += 320
+      estimatedCombineSummaryInputTokens += estimateModelInputTokens({
+        provider,
+        systemPrompt:
+          'Combine these coding-session chunk summaries into one compact transcript summary. Keep only material signal for later facet extraction. Do not carry boilerplate, stack traces, or command details.',
+        userPrompt: makePlaceholderText(combinedSummaryChars, 'Chunk summaries'),
+        structured: false,
+      })
+      estimatedCombineSummaryOutputTokens += 320
     }
-    estimatedFacetInputTokens += 2400
+    estimatedFacetInputTokens += estimateModelInputTokens({
+      provider,
+      systemPrompt: facetSystemPrompt,
+      userPrompt: buildFacetExtractionPrompt(
+        job.thread,
+        makePlaceholderText(
+          combinedSummaryChars > LONG_TRANSCRIPT_THRESHOLD ? 1200 : combinedSummaryChars,
+          '[Long transcript summarized before facet extraction]',
+        ),
+        options.lang,
+      ),
+      schema: FACET_SCHEMA,
+      structured: true,
+    })
     estimatedFacetOutputTokens += 350
   }
 
-  const estimatedSectionInputs = estimateSectionInputs(candidateThreads, facetJobs)
+  const estimatedSectionInputs = estimateSectionInputs(candidateThreads, facetJobs, options)
   const fastSectionCalls = SECTION_DEFS.filter(section => section.modelTier === 'fast').length
   const fullSectionCalls = SECTION_DEFS.filter(section => section.modelTier !== 'fast').length
-  const estimatedFastSectionInputTokens = SECTION_DEFS.filter(section => section.modelTier === 'fast')
+  let estimatedFastSectionInputTokens = SECTION_DEFS.filter(section => section.modelTier === 'fast')
     .reduce((sum, section) => sum + estimatedSectionInputs[section.contextKind] + 500, 0)
   const estimatedFastSectionOutputTokens = fastSectionCalls * 500
-  const estimatedFullSectionInputTokens = SECTION_DEFS.filter(section => section.modelTier !== 'fast')
+  let estimatedFullSectionInputTokens = SECTION_DEFS.filter(section => section.modelTier !== 'fast')
     .reduce((sum, section) => sum + estimatedSectionInputs[section.contextKind] + 650, 0)
   const estimatedFullSectionOutputTokens = fullSectionCalls * 700
-  const estimatedAtAGlanceInputTokens = estimatedSectionInputs.at_a_glance + 2200
+  let estimatedAtAGlanceInputTokens = estimatedSectionInputs.at_a_glance + 2200
   const estimatedAtAGlanceOutputTokens = 260
+  const estimatedSummaryInputTokens =
+    estimatedChunkSummaryInputTokens + estimatedCombineSummaryInputTokens
+  const estimatedSummaryOutputTokens =
+    estimatedChunkSummaryOutputTokens + estimatedCombineSummaryOutputTokens
+
+  estimatedFacetInputTokens += estimateCodexCliFreshOverhead(provider, facetModel, uncachedFacetJobs.length)
+  estimatedChunkSummaryInputTokens += estimateCodexCliFreshOverhead(provider, facetModel, chunkSummaryCalls)
+  estimatedCombineSummaryInputTokens += estimateCodexCliFreshOverhead(provider, facetModel, combineSummaryCalls)
+  estimatedFastSectionInputTokens += estimateCodexCliFreshOverhead(provider, fastSectionModel, fastSectionCalls)
+  estimatedFullSectionInputTokens += estimateCodexCliFreshOverhead(provider, insightModel, fullSectionCalls)
+  estimatedAtAGlanceInputTokens += estimateCodexCliFreshOverhead(provider, insightModel, 1)
 
   const byStage = [
     buildEstimateBucket(
@@ -675,16 +727,16 @@ export async function estimateLlmAnalysisCost({ threadSummaries, options = {} })
     buildEstimateBucket(
       'transcript_summary:chunk',
       chunkSummaryCalls,
-      estimatedSummaryInputTokens - (combineSummaryCalls ? estimateTokensFromChars(combineSummaryCalls * 1100) + combineSummaryCalls * 180 : 0),
+      estimatedChunkSummaryInputTokens,
       0,
-      estimatedSummaryOutputTokens - combineSummaryCalls * 320,
+      estimatedChunkSummaryOutputTokens,
     ),
     buildEstimateBucket(
       'transcript_summary:combine',
       combineSummaryCalls,
-      combineSummaryCalls ? estimateTokensFromChars(combineSummaryCalls * 1100) + combineSummaryCalls * 180 : 0,
+      estimatedCombineSummaryInputTokens,
       0,
-      combineSummaryCalls * 320,
+      estimatedCombineSummaryOutputTokens,
     ),
     buildEstimateBucket(
       'section:fast',
@@ -784,6 +836,14 @@ export async function estimateLlmAnalysisCost({ threadSummaries, options = {} })
   }
 }
 
+function estimateCodexCliFreshOverhead(provider, model, calls) {
+  if (provider !== 'codex-cli' || !calls) return 0
+  const normalized = String(model || '').trim()
+  if (normalized === 'gpt-5.4') return calls * 25_000
+  if (normalized === 'gpt-5.4-mini' || normalized === 'gpt-5.3-codex-spark') return calls * 4_500
+  return calls * 8_000
+}
+
 async function planFacetJobs(threadSummaries, { cacheDir, model, uncachedLimit }) {
   const jobs = []
   let uncachedCount = 0
@@ -824,61 +884,14 @@ async function getFacetForThread(thread, { cacheDir, model, provider, providerOp
     provider,
     providerOptions,
   })
-  const prompt = `Analyze this Codex coding session and extract structured facets.
-
-CRITICAL GUIDELINES:
-1. goal_categories should count only what the user explicitly asked for.
-2. user_satisfaction_counts should rely on explicit user signals or strong transcript evidence.
-3. friction_counts should be specific: misunderstood_request, wrong_approach, buggy_code, user_rejected_action, excessive_changes, tool_failed, slow_or_verbose, user_unclear, external_issue.
-4. If the session is mostly warmup, rehearsal, or cache-filling, use warmup_minimal as the only goal category.
-5. If evidence is insufficient after transcript compression, use conservative values such as unclear_from_transcript rather than guessing.
-6. Do not infer the user's goal from assistant or tool activity alone.
-7. Do not count assistant-led exploration or extra implementation work unless the user clearly asked for it.
-
-Allowed values:
-- outcome: fully_achieved | mostly_achieved | partially_achieved | not_achieved | unclear_from_transcript
-- assistant_helpfulness: unhelpful | slightly_helpful | moderately_helpful | very_helpful | essential
-- session_type: single_task | multi_task | iterative_refinement | exploration | quick_question
-- primary_success: none | fast_accurate_search | correct_code_edits | good_explanations | proactive_help | multi_file_changes | good_debugging
-
-Language:
-- Keep enum values and keys exactly as requested.
-- Write free-text fields in ${describeLanguage(langFromProviderOptions(providerOptions))}.
-
-Transcript:
-${transcript}
-
-Summary stats:
-${JSON.stringify(
-    {
-      title: thread.title,
-      cwd: thread.cwd,
-      durationMinutes: thread.durationMinutes,
-      userMessages: thread.userMessages,
-      assistantMessages: thread.assistantMessages,
-      totalToolCalls: thread.totalToolCalls,
-      totalCommandFailures: thread.totalCommandFailures,
-      toolCounts: thread.toolCounts,
-      toolFailures: thread.toolFailures,
-      userInterruptions: thread.userInterruptions,
-      usesTaskAgent: thread.usesTaskAgent,
-      usesMcp: thread.usesMcp,
-      usesWebSearch: thread.usesWebSearch,
-      usesWebFetch: thread.usesWebFetch,
-    },
-    null,
-    2,
-  )}
-
-RESPOND WITH ONLY A VALID JSON OBJECT matching the requested schema.`
+  const prompt = buildFacetExtractionPrompt(thread, transcript, langFromProviderOptions(providerOptions))
 
   const rawFacet = await callStructuredModel({
     provider,
     model,
     schemaName: 'codex_session_facet',
     schema: FACET_SCHEMA,
-    systemPrompt:
-      `You extract structured coding-session facets from compressed transcripts. Use only transcript evidence. Be conservative when evidence is weak. Do not infer intent from tool activity alone. ${getStructuredLanguageInstruction(langFromProviderOptions(providerOptions))}`.trim(),
+    systemPrompt: buildFacetSystemPrompt(langFromProviderOptions(providerOptions)),
     userPrompt: prompt,
       options: {
         ...providerOptions,
@@ -1154,6 +1167,124 @@ ${compactJson(compactInsightDigest(insights))}
 RESPOND WITH ONLY A VALID JSON OBJECT matching the schema.`
 }
 
+function buildFacetSystemPrompt(lang) {
+  return `You extract structured coding-session facets from compressed transcripts. Use only transcript evidence. Be conservative when evidence is weak. Do not infer intent from tool activity alone. ${getStructuredLanguageInstruction(lang)}`.trim()
+}
+
+function buildFacetExtractionPrompt(thread, transcript, lang) {
+  return `Analyze this Codex coding session and extract structured facets.
+
+CRITICAL GUIDELINES:
+1. goal_categories should count only what the user explicitly asked for.
+2. user_satisfaction_counts should rely on explicit user signals or strong transcript evidence.
+3. friction_counts should be specific: misunderstood_request, wrong_approach, buggy_code, user_rejected_action, excessive_changes, tool_failed, slow_or_verbose, user_unclear, external_issue.
+4. If the session is mostly warmup, rehearsal, or cache-filling, use warmup_minimal as the only goal category.
+5. If evidence is insufficient after transcript compression, use conservative values such as unclear_from_transcript rather than guessing.
+6. Do not infer the user's goal from assistant or tool activity alone.
+7. Do not count assistant-led exploration or extra implementation work unless the user clearly asked for it.
+
+Allowed values:
+- outcome: fully_achieved | mostly_achieved | partially_achieved | not_achieved | unclear_from_transcript
+- assistant_helpfulness: unhelpful | slightly_helpful | moderately_helpful | very_helpful | essential
+- session_type: single_task | multi_task | iterative_refinement | exploration | quick_question
+- primary_success: none | fast_accurate_search | correct_code_edits | good_explanations | proactive_help | multi_file_changes | good_debugging
+
+Language:
+- Keep enum values and keys exactly as requested.
+- Write free-text fields in ${describeLanguage(lang)}.
+
+Transcript:
+${transcript}
+
+Summary stats:
+${JSON.stringify(
+    {
+      title: thread.title,
+      cwd: thread.cwd,
+      durationMinutes: thread.durationMinutes,
+      userMessages: thread.userMessages,
+      assistantMessages: thread.assistantMessages,
+      totalToolCalls: thread.totalToolCalls,
+      totalCommandFailures: thread.totalCommandFailures,
+      toolCounts: thread.toolCounts,
+      toolFailures: thread.toolFailures,
+      userInterruptions: thread.userInterruptions,
+      usesTaskAgent: thread.usesTaskAgent,
+      usesMcp: thread.usesMcp,
+      usesWebSearch: thread.usesWebSearch,
+      usesWebFetch: thread.usesWebFetch,
+    },
+    null,
+    2,
+  )}
+
+RESPOND WITH ONLY A VALID JSON OBJECT matching the requested schema.`
+}
+
+function buildEstimatedFacet(thread) {
+  return {
+    threadId: thread.id,
+    title: thread.title,
+    cwd: thread.cwd,
+    updatedAt: thread.updatedAt,
+    durationMinutes: thread.durationMinutes,
+    userMessages: thread.userMessages,
+    assistantMessages: thread.assistantMessages,
+    totalToolCalls: thread.totalToolCalls,
+    totalCommandFailures: thread.totalCommandFailures,
+    underlying_goal: truncateForContext(thread.firstUserMessage || thread.title, 160),
+    goal_categories: {},
+    outcome: thread.totalCommandFailures > 0 ? 'partially_achieved' : 'unclear_from_transcript',
+    user_satisfaction_counts: {},
+    assistant_helpfulness: 'moderately_helpful',
+    session_type: thread.userMessages > 2 ? 'iterative_refinement' : 'single_task',
+    friction_counts: thread.totalCommandFailures > 0 ? { tool_failed: 1 } : {},
+    friction_detail: 'none',
+    primary_success: 'none',
+    brief_summary: truncateForContext(thread.firstUserMessage || thread.title, 180),
+    user_instructions: [],
+  }
+}
+
+function buildEstimatedInsightsPlaceholder(context) {
+  return {
+    project_areas: {
+      areas: (context.session_summaries || []).slice(0, 3).map((item, index) => ({
+        name: item.project || item.title || `Workstream ${index + 1}`,
+        session_count: 1,
+        description: truncateForContext(item.summary || item.goal || '', 120),
+      })),
+    },
+    interaction_style: {
+      key_pattern: 'Tight scope before execution',
+      narrative: truncateForContext('You first align scope and constraints, then execute and verify against explicit acceptance bars.', 180),
+    },
+    what_works: {
+      impressive_workflows: [
+        { title: 'Scope first', description: 'You repeatedly tighten scope before execution.' },
+        { title: 'Verification loop', description: 'You use evidence to confirm changes before closing.' },
+      ],
+    },
+    friction_analysis: {
+      categories: [
+        { category: 'Direction drift', description: 'Some sessions need scope tightening.', examples: ['Scope had to be pulled back.'] },
+      ],
+    },
+    suggestions: {
+      features_to_try: [{ feature: 'AGENTS.md' }],
+      usage_patterns: [{ title: 'Split review and execution' }],
+      agents_md_additions: [{ addition: 'Read existing docs before editing.' }],
+    },
+    on_the_horizon: {
+      opportunities: [{ title: 'Longer workflows', how_to_try: 'Add staged execution.' }],
+    },
+    fun_ending: {
+      headline: 'Memorable moment',
+      detail: 'A compact placeholder for estimate sizing.',
+    },
+  }
+}
+
 /**
  * @param {InsightRunOptions} options
  * @param {string} provider
@@ -1172,71 +1303,36 @@ function buildProviderOptions(options, provider, onUsage) {
   }
 }
 
-function estimateSectionInputs(candidateThreads, facetJobs) {
-  const contextShape = {
-    metadata: {
-      thread_count: candidateThreads.length,
-    },
-    summary: {
-      total_user_messages: candidateThreads.reduce((sum, thread) => sum + Number(thread.userMessages || 0), 0),
-      total_tool_calls: candidateThreads.reduce((sum, thread) => sum + Number(thread.totalToolCalls || 0), 0),
-      total_failures: candidateThreads.reduce((sum, thread) => sum + Number(thread.totalCommandFailures || 0), 0),
-    },
-    charts: {
-      projects: candidateThreads.slice(0, 6).map(thread => compactProjectPath(thread.cwd)),
-      models: Array.from(new Set(candidateThreads.map(thread => thread.model).filter(Boolean))).slice(0, 4),
-      tools: [],
-    },
-    aggregate_facets: {
-      sessions_with_facets: facetJobs.length,
-    },
-    session_summaries: facetJobs.slice(0, MAX_CONTEXT_FACETS).map(job => {
-      if (job.cachedFacet) {
-        return {
-          title: truncateForContext(job.cachedFacet.title, 80),
-          project: compactProjectPath(job.cachedFacet.cwd),
-          goal: truncateForContext(job.cachedFacet.underlying_goal, 120),
-          outcome: job.cachedFacet.outcome,
-          primary_success: job.cachedFacet.primary_success,
-          summary: truncateForContext(job.cachedFacet.brief_summary, 160),
-          friction: compactCountObject(job.cachedFacet.friction_counts, 2),
-        }
-      }
-      return {
-        title: truncateForContext(job.thread.title, 80),
-        project: compactProjectPath(job.thread.cwd),
-        goal: truncateForContext(job.thread.firstUserMessage, 120),
-        outcome: 'unknown',
-        primary_success: 'unknown',
-        summary: truncateForContext(job.thread.firstUserMessage, 160),
-        friction: {},
-      }
-    }),
-    recent_threads: candidateThreads.slice(0, MAX_RECENT_THREADS).map(thread => ({
-      title: truncateForContext(thread.title, 80),
-      project: compactProjectPath(thread.cwd),
-      duration_minutes: thread.durationMinutes,
-      user_messages: thread.userMessages,
-      tool_calls: thread.totalToolCalls,
-      files_modified: thread.filesModified,
-    })),
-    friction_details: [],
-    user_instructions: [],
-  }
-  const sectionKinds = [
-    'project_areas',
-    'interaction_style',
-    'what_works',
-    'friction_analysis',
-    'suggestions',
-    'on_the_horizon',
-    'fun_ending',
-    'at_a_glance',
-  ]
+function estimateSectionInputs(candidateThreads, facetJobs, options = {}) {
+  const provider = options.provider || DEFAULT_PROVIDER
+  const lang = options.lang || 'en'
+  const estimatedFacets = facetJobs.map(job => job.cachedFacet || buildEstimatedFacet(job.thread))
+  const report = buildReport(candidateThreads, { facets: estimatedFacets })
+  const context = buildInsightContext(report, candidateThreads, estimatedFacets)
   const estimated = {}
-  for (const kind of sectionKinds) {
-    estimated[kind] = estimateTokensFromChars(compactJson(buildSectionContext(contextShape, kind)).length)
+
+  for (const section of SECTION_DEFS) {
+    const systemPrompt = `${SECTION_SYSTEM_PROMPT} ${getNarrativeLanguageInstruction(lang)}`.trim()
+    const sectionContext = buildSectionContext(context, section.contextKind)
+    const userPrompt = `${section.prompt}\n\n${getNarrativeLanguageInstruction(lang)}\n\nDATA:\n${compactJson(sectionContext)}`
+    estimated[section.contextKind] = estimateModelInputTokens({
+      provider,
+      systemPrompt,
+      userPrompt,
+      schema: section.schema,
+      structured: true,
+    })
   }
+
+  const placeholderInsights = buildEstimatedInsightsPlaceholder(context)
+  estimated.at_a_glance = estimateModelInputTokens({
+    provider,
+    systemPrompt: `${AT_A_GLANCE_SYSTEM_PROMPT} ${getNarrativeLanguageInstruction(lang)}`.trim(),
+    userPrompt: buildAtAGlancePrompt(buildSectionContext(context, 'at_a_glance'), placeholderInsights),
+    schema: AT_A_GLANCE_SCHEMA,
+    structured: true,
+  })
+
   return estimated
 }
 
@@ -1397,6 +1493,36 @@ function estimateTokensFromChars(chars) {
   return Math.ceil(Number(chars || 0) / 4)
 }
 
+function estimateModelInputTokens({ provider, systemPrompt, userPrompt, schema = null, structured }) {
+  const promptText =
+    provider === 'codex-cli'
+      ? structured
+        ? buildStructuredEstimatePrompt(systemPrompt, userPrompt, schema)
+        : buildPlainEstimatePrompt(systemPrompt, userPrompt)
+      : buildApiEstimatePrompt(systemPrompt, userPrompt, schema, structured)
+  return estimateTokensFromChars(promptText.length)
+}
+
+function buildPlainEstimatePrompt(systemPrompt, userPrompt) {
+  return `${String(systemPrompt || '').trim()}\n\n${String(userPrompt || '').trim()}`
+}
+
+function buildStructuredEstimatePrompt(systemPrompt, userPrompt, schema) {
+  return `${buildPlainEstimatePrompt(systemPrompt, userPrompt)}\n\nRESPOND WITH ONLY A VALID JSON OBJECT matching this schema:\n${JSON.stringify(schema, null, 2)}`
+}
+
+function buildApiEstimatePrompt(systemPrompt, userPrompt, schema, structured) {
+  if (!structured) return buildPlainEstimatePrompt(systemPrompt, userPrompt)
+  return `${buildPlainEstimatePrompt(systemPrompt, userPrompt)}\n\nJSON schema:\n${JSON.stringify(schema, null, 2)}`
+}
+
+function makePlaceholderText(length, prefix = '') {
+  const target = Math.max(0, Number(length || 0))
+  const seed = prefix ? `${prefix}\n` : ''
+  if (seed.length >= target) return seed.slice(0, target)
+  return `${seed}${'x'.repeat(Math.max(0, target - seed.length))}`
+}
+
 function getNarrativeLanguageInstruction(lang) {
   if (lang === 'zh-CN') {
     return 'Write all free-text narrative fields in Simplified Chinese.'

package/lib/report.js

@@ -178,6 +178,7 @@ export async function writeReportFiles(report, options) {
 
 export function renderTerminalSummary(report) {
   const text = getReportText(report.metadata.language)
+  const estimateComparison = buildEstimateComparison(report)
   const lines = []
   lines.push(text.reportTitle)
   lines.push(
@@ -190,6 +191,11 @@ export function renderTerminalSummary(report) {
     lines.push(
       `  ${text.inputLabel}=${formatMillionTokens(report.analysisUsage.inputTokens)} | ${text.cachedLabel}=${formatMillionTokens(report.analysisUsage.cachedInputTokens)} | ${text.outputLabel}=${formatMillionTokens(report.analysisUsage.outputTokens)}`,
     )
+    if (estimateComparison) {
+      lines.push(
+        `  ${text.estimateVsActualLabel}: ${formatMillionTokens(estimateComparison.estimatedTotalTokens)} -> ${formatMillionTokens(estimateComparison.actualTotalTokens)} ${text.actualFreshSuffix} (${formatSignedMillionTokens(estimateComparison.deltaTokens)}, ${formatSignedPercent(estimateComparison.deltaPercent)})`,
+      )
+    }
   }
   if (report.metadata.dateRange.start && report.metadata.dateRange.end) {
     lines.push(`${report.metadata.dateRange.start} -> ${report.metadata.dateRange.end}`)
@@ -214,8 +220,12 @@ function renderHtmlReport(report) {
   const analysisUsage = report.analysisUsage || null
   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 sessionTypes = renderBarList(report.charts.sessionTypes, {
+    formatLabel: value => formatSessionTypeLabel(value, report.metadata.language),
+  })
+  const outcomes = renderBarList(report.charts.outcomes, {
+    formatLabel: value => formatOutcomeLabel(value, report.metadata.language),
+  })
   const capabilitySignals = renderBarList(report.charts.capabilities)
   const toolFailures = renderBarList(report.charts.toolFailures)
   const toolErrorCategories = renderBarList(report.charts.toolErrorCategories)
@@ -793,7 +803,7 @@ function renderProjectAreas(insights) {
               <div class="project-area">
                 <div class="area-header">
                   <span class="area-name">${escapeHtml(area.name)}</span>
-                  <span class="area-count">~${formatNumber(area.session_count)} ${escapeHtml(text.sessionsLabel)}</span>
+                  <span class="area-count">${escapeHtml(text.workstreamBadge)}</span>
                 </div>
                 <div class="area-desc">${escapeHtml(area.description)}</div>
               </div>
@@ -875,9 +885,9 @@ function renderSuggestions(insights) {
   const suggestions = insights.suggestions
   if (!suggestions) return ''
   const text = getReportText(insights.__lang)
-  const agentItems = suggestions.agents_md_additions || []
-  const featureItems = suggestions.features_to_try || []
-  const patternItems = suggestions.usage_patterns || []
+  const agentItems = (suggestions.agents_md_additions || []).map(normalizeSuggestionTextItem)
+  const featureItems = (suggestions.features_to_try || []).map(normalizeSuggestionTextItem)
+  const patternItems = (suggestions.usage_patterns || []).map(normalizeSuggestionTextItem)
 
   return `
     <section class="panel">
@@ -995,6 +1005,7 @@ function renderReportMeta(report, context = {}) {
   const text = getReportText(report.metadata.language)
   const usage = report.analysisUsage
   const hasUsage = Boolean(usage?.totalTokens)
+  const estimateComparison = buildEstimateComparison(report)
   const analysisByStage = context.analysisByStage || ''
   const analysisByModel = context.analysisByModel || ''
 
@@ -1010,6 +1021,7 @@ function renderReportMeta(report, context = {}) {
         ${hasUsage ? renderStat(text.analysisTokens, formatMillionTokens(usage.totalTokens)) : ''}
         ${hasUsage ? renderStat(text.modelCalls, formatNumber(usage.calls)) : ''}
         ${hasUsage ? renderStat(text.cachedInput, formatMillionTokens(usage.cachedInputTokens)) : ''}
+        ${estimateComparison ? renderStat(text.estimateDelta, `${formatSignedMillionTokens(estimateComparison.deltaTokens)} (${formatSignedPercent(estimateComparison.deltaPercent)})`) : ''}
         ${renderStat(text.historicalSessionTokens, formatNumber(report.summary.totalTokens))}
       </div>
       ${
@@ -1035,6 +1047,14 @@ function renderReportMeta(report, context = {}) {
           })}
           <p class="meta">${escapeHtml(text.freshInput)}: ${formatMillionTokens(freshInputTokens)}. ${escapeHtml(text.analysisCostFootnote)}</p>
         </div>
+        ${
+          estimateComparison
+            ? `<div class="usage-breakdown">
+          <h3>${escapeHtml(text.estimateVsActualHeading)}</h3>
+          ${renderEstimateComparisonCard(estimateComparison, text)}
+        </div>`
+            : ''
+        }
       </div>`
           : ''
       }
@@ -1079,6 +1099,29 @@ function renderUsageCard(item) {
   `
 }
 
+function renderEstimateComparisonCard(comparison, text) {
+  return `
+    <div class="usage-card">
+      <div class="topline">
+        <h3>${escapeHtml(text.estimateVsActualLabel)}</h3>
+        <span class="pill">${escapeHtml(comparison.verdictLabel)}</span>
+      </div>
+      <div class="meta-row">
+        <span>${escapeHtml(text.estimatedLabel)}: ${formatMillionTokens(comparison.estimatedTotalTokens)}</span>
+        <span>${escapeHtml(text.actualFreshLabel)}: ${formatMillionTokens(comparison.actualTotalTokens)}</span>
+        <span>${escapeHtml(text.estimateDelta)}: ${formatSignedMillionTokens(comparison.deltaTokens)} (${formatSignedPercent(comparison.deltaPercent)})</span>
+      </div>
+      <div class="token-row">
+        <div class="token-box"><strong>${escapeHtml(text.estimatedLabel)}</strong><br>${formatMillionTokens(comparison.estimatedTotalTokens)}</div>
+        <div class="token-box"><strong>${escapeHtml(text.actualFreshLabel)}</strong><br>${formatMillionTokens(comparison.actualTotalTokens)}</div>
+        <div class="token-box"><strong>${escapeHtml(text.estimateRangeLabel)}</strong><br>${formatMillionTokens(comparison.lowEstimate)} -> ${formatMillionTokens(comparison.highEstimate)}</div>
+        <div class="token-box"><strong>${escapeHtml(text.estimateDelta)}</strong><br>${formatSignedMillionTokens(comparison.deltaTokens)}</div>
+        <div class="token-box"><strong>${escapeHtml(text.estimateError)}</strong><br>${formatSignedPercent(comparison.deltaPercent)}</div>
+      </div>
+    </div>
+  `
+}
+
 function renderStat(label, value) {
   return `<div class="stat"><div class="value">${escapeHtml(String(value))}</div><div>${escapeHtml(label)}</div></div>`
 }
@@ -1147,6 +1190,20 @@ function renderCopyRow(value, text) {
   `
 }
 
+function normalizeSuggestionTextItem(item) {
+  if (!item || typeof item !== 'object') return item
+  return Object.fromEntries(
+    Object.entries(item).map(([key, value]) => [key, normalizeSuggestionText(value)]),
+  )
+}
+
+function normalizeSuggestionText(value) {
+  if (typeof value !== 'string') return value
+  return value
+    .replaceAll('CLAUDE.md / AGENTS.md', 'AGENTS.md')
+    .replaceAll('CLAUDE.md', 'AGENTS.md')
+}
+
 function formatAgentInstruction(item) {
   const placement = String(item?.prompt_scaffold || '').trim()
   const addition = String(item?.addition || '').trim()
@@ -1171,6 +1228,44 @@ function formatProjectLabel(value) {
   return formatDisplayPath(value, { tailSegments: 2, preferHomeAlias: false, ellipsis: true })
 }
 
+function formatSessionTypeLabel(value, lang) {
+  const key = String(value || '')
+  const zh = {
+    iterative_refinement: '反复收敛',
+    exploration: '探索调研',
+    single_task: '单任务推进',
+    multi_task: '多任务并行',
+    quick_question: '快速提问',
+  }
+  const en = {
+    iterative_refinement: 'Iterative refinement',
+    exploration: 'Exploration',
+    single_task: 'Single-task execution',
+    multi_task: 'Multi-task coordination',
+    quick_question: 'Quick question',
+  }
+  return lang === 'zh-CN' ? zh[key] || key : en[key] || key
+}
+
+function formatOutcomeLabel(value, lang) {
+  const key = String(value || '')
+  const zh = {
+    fully_achieved: '完全达成',
+    mostly_achieved: '基本达成',
+    partially_achieved: '部分达成',
+    not_achieved: '未达成',
+    unclear_from_transcript: '从记录中无法判断',
+  }
+  const en = {
+    fully_achieved: 'Fully achieved',
+    mostly_achieved: 'Mostly achieved',
+    partially_achieved: 'Partially achieved',
+    not_achieved: 'Not achieved',
+    unclear_from_transcript: 'Unclear from transcript',
+  }
+  return lang === 'zh-CN' ? zh[key] || key : en[key] || key
+}
+
 function formatDisplayPath(value, options = {}) {
   const text = String(value || '').trim()
   if (!text) return '(unknown)'
@@ -1225,6 +1320,12 @@ function formatMillionTokens(value) {
   return `${round(number / 1_000)}K tokens`
 }
 
+function formatSignedMillionTokens(value) {
+  const number = Number(value || 0)
+  const prefix = number > 0 ? '+' : number < 0 ? '-' : ''
+  return `${prefix}${formatMillionTokens(Math.abs(number))}`
+}
+
 function formatPercent(value, total) {
   const numerator = Number(value || 0)
   const denominator = Number(total || 0)
@@ -1232,6 +1333,12 @@ function formatPercent(value, total) {
   return `${round((numerator / denominator) * 100)}%`
 }
 
+function formatSignedPercent(value) {
+  const number = Number(value || 0)
+  const prefix = number > 0 ? '+' : number < 0 ? '-' : ''
+  return `${prefix}${round(Math.abs(number))}%`
+}
+
 function average(values) {
   if (!values.length) return 0
   return round(values.reduce((sum, value) => sum + value, 0) / values.length)
@@ -1286,6 +1393,41 @@ function escapeAttribute(value) {
   return escapeHtml(String(value)).replaceAll("'", '&#39;').replaceAll('\n', '&#10;')
 }
 
+function buildEstimateComparison(report) {
+  const estimate = report.analysisEstimate
+  const usage = report.analysisUsage
+  if (!estimate?.estimatedTotalTokens || !usage?.totalTokens) return null
+
+  const estimated = Number(estimate.estimatedTotalTokens || 0)
+  const actualFresh =
+    Math.max(0, Number(usage.inputTokens || 0) - Number(usage.cachedInputTokens || 0)) +
+    Number(usage.outputTokens || 0)
+  const delta = actualFresh - estimated
+  const deltaPercent = estimated > 0 ? (delta / estimated) * 100 : 0
+
+  return {
+    estimatedTotalTokens: estimated,
+    actualTotalTokens: actualFresh,
+    lowEstimate: Number(estimate.estimatedRange?.low || estimated),
+    highEstimate: Number(estimate.estimatedRange?.high || estimated),
+    deltaTokens: delta,
+    deltaPercent,
+    verdictLabel: classifyEstimateDelta(deltaPercent, report.metadata.language),
+  }
+}
+
+function classifyEstimateDelta(deltaPercent, lang) {
+  const abs = Math.abs(Number(deltaPercent || 0))
+  if (lang === 'zh-CN') {
+    if (abs <= 10) return '估算接近'
+    if (deltaPercent > 0) return '实际偏高'
+    return '实际偏低'
+  }
+  if (abs <= 10) return 'Close estimate'
+  if (deltaPercent > 0) return 'Actual higher'
+  return 'Actual lower'
+}
+
 function getReportText(lang) {
   if (lang === 'zh-CN') {
     return {
@@ -1304,7 +1446,7 @@ function getReportText(lang) {
       filesModified: '修改文件',
       toolErrors: '工具错误',
       avgResponse: '平均响应',
-      topProjects: 'Top Projects',
+      topProjects: '项目分布',
       modelMix: '模型分布',
       sessionTypes: '会话类型',
       outcomes: '结果分布',
@@ -1318,6 +1460,7 @@ function getReportText(lang) {
       quickWins: '可以立刻尝试的优化',
       ambitiousWorkflows: '值得尝试的更强工作流',
       sessionsLabel: '次会话',
+      workstreamBadge: '代表性工作流',
       impressiveThingsLink: '做得好的地方',
       whereThingsGoWrongLink: '容易出问题的地方',
       whatYouWorkOn: '你主要在做什么',
@@ -1348,6 +1491,15 @@ function getReportText(lang) {
       dateRange: '时间范围',
       modelCalls: '模型调用',
       cachedInput: '缓存输入',
+      estimatedLabel: '预估',
+      actualLabel: '实际',
+      actualFreshLabel: '实际（不含缓存）',
+      actualFreshSuffix: '（不含缓存）',
+      estimateRangeLabel: '预估区间',
+      estimateVsActualHeading: '预估与实际',
+      estimateVsActualLabel: '预估 vs 实际',
+      estimateDelta: '偏差',
+      estimateError: '偏差比例',
       historicalSessionTokens: '历史会话 Tokens',
       analysisCostByStage: '按阶段拆分的分析成本',
       analysisCostByModel: '按模型拆分的分析成本',
@@ -1397,6 +1549,7 @@ function getReportText(lang) {
     quickWins: 'Quick wins to try',
     ambitiousWorkflows: 'Ambitious workflows',
     sessionsLabel: 'sessions',
+    workstreamBadge: 'Representative workstream',
     impressiveThingsLink: 'Impressive Things You Did',
     whereThingsGoWrongLink: 'Where Things Go Wrong',
     whatYouWorkOn: 'What You Work On',
@@ -1427,6 +1580,15 @@ function getReportText(lang) {
     dateRange: 'Date Range',
     modelCalls: 'Model Calls',
     cachedInput: 'Cached Input',
+    estimatedLabel: 'Estimated',
+    actualLabel: 'Actual',
+    actualFreshLabel: 'Actual (fresh)',
+    actualFreshSuffix: '(fresh)',
+    estimateRangeLabel: 'Estimate range',
+    estimateVsActualHeading: 'Estimate vs Actual',
+    estimateVsActualLabel: 'Estimate vs Actual',
+    estimateDelta: 'Delta',
+    estimateError: 'Error',
     historicalSessionTokens: 'Historical Session Tokens',
     analysisCostByStage: 'Analysis Cost by Stage',
     analysisCostByModel: 'Analysis Cost by Model',

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "codex-session-insights",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Generate a report analyzing your Codex sessions.",
   "type": "module",
   "bin": {
-    "codex-session-insights": "./bin/codex-insights.js"
+    "codex-session-insights": "bin/codex-insights.js"
   },
   "files": [
     "bin",
@@ -25,6 +25,7 @@
   },
   "scripts": {
     "report": "node ./bin/codex-insights.js report",
+    "report:lite": "node ./bin/codex-insights.js --preset lite --yes",
     "generate:test-report": "node ./scripts/generate-test-report.mjs",
     "test": "node --test",
     "check": "node --check ./bin/codex-insights.js && node --check ./lib/cli.js && node --check ./lib/codex-data.js && node --check ./lib/report.js && node --check ./lib/llm-insights.js && node --check ./lib/model-provider.js && npm run typecheck",