convoptics 0.1.0

package/src/claude-code/scanner.js

@@ -0,0 +1,99 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import readline from 'node:readline';
+
+async function* walkJsonl(root) {
+  const rootDir = await fs.opendir(root);
+  for await (const entry of rootDir) {
+    if (!entry.isDirectory()) continue;
+    const projectDir = await fs.opendir(path.join(root, entry.name));
+    for await (const file of projectDir) {
+      if (!file.isFile() || !file.name.endsWith('.jsonl')) continue;
+      yield path.join(root, entry.name, file.name);
+    }
+  }
+}
+
+export async function* scanSessions(root) {
+  for await (const filePath of walkJsonl(root)) {
+    const fd = await fs.open(filePath, 'r');
+    try {
+      const stream = fd.createReadStream();
+      const lines = readline.createInterface({ input: stream, crlfDelay: Infinity });
+      let cwd = null;
+      let gitBranch = null;
+      let sessionId = null;
+      let version = null;
+      let startedAt = null;
+      let endedAt = null;
+      let summary = null;
+      let messageCount = 0;
+      let malformed = 0;
+      const tokens = { input: 0, output: 0, cacheCreation: 0, cacheRead: 0 };
+      const tokensByModel = {};
+
+      for await (const line of lines) {
+        if (!line.trim()) continue;
+
+        let record;
+        try {
+          record = JSON.parse(line);
+        } catch {
+          malformed += 1;
+          continue;
+        }
+
+        messageCount += 1;
+
+        if (!startedAt && record.timestamp) startedAt = record.timestamp;
+        if (cwd === null && record.cwd) cwd = record.cwd;
+        if (gitBranch === null && record.gitBranch) gitBranch = record.gitBranch;
+        if (sessionId === null && record.sessionId) sessionId = record.sessionId;
+        if (version === null && record.version) version = record.version;
+        if (summary === null && record.type === 'summary' && record.summary) {
+          summary = record.summary;
+        }
+
+        if (record.timestamp) endedAt = record.timestamp;
+
+        const usage = record.message && record.message.usage;
+        if (usage) {
+          const inp = usage.input_tokens ?? 0;
+          const out = usage.output_tokens ?? 0;
+          const cw = usage.cache_creation_input_tokens ?? 0;
+          const cr = usage.cache_read_input_tokens ?? 0;
+          tokens.input += inp;
+          tokens.output += out;
+          tokens.cacheCreation += cw;
+          tokens.cacheRead += cr;
+          const model = (record.message.model && String(record.message.model)) || 'unknown';
+          if (!tokensByModel[model]) {
+            tokensByModel[model] = { input: 0, output: 0, cacheCreation: 0, cacheRead: 0 };
+          }
+          tokensByModel[model].input += inp;
+          tokensByModel[model].output += out;
+          tokensByModel[model].cacheCreation += cw;
+          tokensByModel[model].cacheRead += cr;
+        }
+      }
+
+      yield {
+        path: filePath,
+        sessionId: sessionId || path.basename(filePath, '.jsonl'),
+        projectFolder: cwd ? path.basename(cwd) : null,
+        cwd,
+        gitBranch,
+        version,
+        startedAt,
+        endedAt,
+        summary,
+        messageCount,
+        malformedCount: malformed,
+        tokens,
+        tokensByModel,
+      };
+    } finally {
+      await fd.close();
+    }
+  }
+}

package/src/cli.js

@@ -0,0 +1,267 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import readline from 'node:readline';
+import { Command } from 'commander';
+import { parseQuery } from './query.js';
+import { match } from './matcher.js';
+import * as claudeCodeAdapter from './claude-code/scanner.js';
+import { exportSession as exportClaudeCodeSession } from './claude-code/exporter.js';
+import * as cursorAdapter from './cursor/scanner.js';
+import { exportSession as exportCursorSession } from './cursor/exporter.js';
+import { costForSession, resolveModel } from './claude-code/pricing.js';
+
+const ADAPTERS = {
+  'claude-code': {
+    scan: claudeCodeAdapter.scanSessions,
+    exportSession: exportClaudeCodeSession,
+    defaultRoot: () => path.join(os.homedir(), '.claude', 'projects'),
+    rootLabel: 'Claude Code projects root',
+    supportsCost: true,
+  },
+  cursor: {
+    scan: cursorAdapter.scanSessions,
+    exportSession: exportCursorSession,
+    defaultRoot: () => cursorAdapter.defaultCursorRoot(),
+    rootLabel: 'Cursor user-data root',
+    supportsCost: false,
+  },
+};
+
+function pAll(items, fn, concurrency) {
+  const results = [];
+  const executing = [];
+  let i = 0;
+
+  const enqueue = async () => {
+    if (i >= items.length) return;
+    const item = items[i++];
+    const p = Promise.resolve().then(() => fn(item));
+    results.push(p);
+    const e = p.then(() => executing.splice(executing.indexOf(e), 1));
+    executing.push(e);
+    if (executing.length >= concurrency) {
+      await Promise.race(executing);
+    }
+    return enqueue();
+  };
+
+  return enqueue().then(() => Promise.all(results));
+}
+
+async function streamJsonlToStdout(session) {
+  const stream = await fs.open(session.path, 'r');
+  try {
+    const reader = readline.createInterface({ input: stream.createReadStream(), crlfDelay: Infinity });
+    for await (const line of reader) {
+      process.stdout.write(`${line}\n`);
+    }
+  } finally {
+    await stream.close();
+  }
+}
+
+function emitCursorSessionJson(session) {
+  const { _cursor, ...publicFields } = session;
+  process.stdout.write(`${JSON.stringify(publicFields)}\n`);
+}
+
+function formatSummary(session) {
+  return `${session.sessionId.slice(0, 8)} ${session.gitBranch ?? 'nobranch'} ${session.startedAt ?? ''} ${session.summary ?? ''}`;
+}
+
+function fmtNum(n) {
+  return Number(n || 0).toLocaleString('en-US');
+}
+
+function fmtCost(usd) {
+  if (!usd) return '$0.00';
+  if (usd < 0.01) return `$${usd.toFixed(4)}`;
+  return `$${usd.toFixed(2)}`;
+}
+
+function dominantModel(tokensByModel) {
+  const entries = Object.entries(tokensByModel || {});
+  if (entries.length === 0) return '—';
+  let best = entries[0];
+  let bestSum = (best[1].input || 0) + (best[1].output || 0);
+  for (const entry of entries.slice(1)) {
+    const sum = (entry[1].input || 0) + (entry[1].output || 0);
+    if (sum > bestSum) {
+      best = entry;
+      bestSum = sum;
+    }
+  }
+  const resolved = resolveModel(best[0]);
+  const label = resolved ? resolved.key : best[0];
+  return entries.length > 1 ? `${label} (+${entries.length - 1})` : label;
+}
+
+function renderOutputOnly(matches) {
+  const lines = ['# Session usage', ''];
+  lines.push('| date | session | branch | model | input | output | cache R | cache W | cost |');
+  lines.push('|---|---|---|---|---:|---:|---:|---:|---:|');
+
+  const totals = { input: 0, output: 0, cacheRead: 0, cacheCreation: 0, cost: 0 };
+  const unknown = new Set();
+
+  for (const session of matches) {
+    const tokens = session.tokens ?? { input: 0, output: 0, cacheCreation: 0, cacheRead: 0 };
+    const { cost, unknownModels } = costForSession(session.tokensByModel ?? {});
+    for (const m of unknownModels) unknown.add(m);
+    totals.input += tokens.input || 0;
+    totals.output += tokens.output || 0;
+    totals.cacheRead += tokens.cacheRead || 0;
+    totals.cacheCreation += tokens.cacheCreation || 0;
+    totals.cost += cost;
+    const date = session.startedAt ? session.startedAt.slice(0, 10) : '';
+    lines.push(
+      `| ${date} | ${session.sessionId.slice(0, 8)} | ${session.gitBranch ?? ''} | ${dominantModel(session.tokensByModel)} | ${fmtNum(tokens.input)} | ${fmtNum(tokens.output)} | ${fmtNum(tokens.cacheRead)} | ${fmtNum(tokens.cacheCreation)} | ${fmtCost(cost)} |`,
+    );
+  }
+
+  lines.push('', '## Totals', '');
+  lines.push('| metric | value |');
+  lines.push('|---|---:|');
+  lines.push(`| sessions | ${fmtNum(matches.length)} |`);
+  lines.push(`| input tokens | ${fmtNum(totals.input)} |`);
+  lines.push(`| output tokens | ${fmtNum(totals.output)} |`);
+  lines.push(`| cache read tokens | ${fmtNum(totals.cacheRead)} |`);
+  lines.push(`| cache write tokens | ${fmtNum(totals.cacheCreation)} |`);
+  lines.push(`| cost (USD) | ${fmtCost(totals.cost)} |`);
+
+  return { text: lines.join('\n') + '\n', unknown: [...unknown] };
+}
+
+async function main() {
+  const program = new Command();
+  program
+    .name('convoptics')
+    .description('Extract Claude Code conversations by query and export Markdown transcripts.')
+    .argument('[filters...]', 'filter tokens such as tool:claude-code branch:main date>=2026-05-01')
+    .option('--root <path>', 'override ~/.claude/projects')
+    .option('--out <dir>', 'override output directory')
+    .option('--dry-run', 'list matches, do not write files')
+    .option('--json', 'emit JSONL of matches to stdout instead of markdown files')
+    .option('--output-only', 'print a token + cost summary table to stdout; do not write markdown files')
+    .option('--limit <n>', 'stop after N matches', Number)
+    .option('--full', 'do not truncate tool results')
+    .option('-v, --verbose', 'show scan progress to stderr')
+    .version('0.1.0');
+
+  program.parse(process.argv);
+  const filters = program.args;
+  const opts = program.opts();
+
+  let filterSpec;
+  try {
+    filterSpec = parseQuery(filters);
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+
+  const adapter = ADAPTERS[filterSpec.tool];
+  if (!adapter) {
+    console.error(`Error: no adapter registered for tool:${filterSpec.tool}`);
+    process.exit(1);
+  }
+
+  if (opts.outputOnly && !adapter.supportsCost) {
+    console.error(`Error: --output-only is not supported for tool:${filterSpec.tool} (token usage is not exported)`);
+    process.exit(1);
+  }
+
+  const root = opts.root ? path.resolve(opts.root) : adapter.defaultRoot();
+  try {
+    const rootStat = await fs.stat(root);
+    if (!rootStat.isDirectory()) {
+      throw new Error('not a directory');
+    }
+  } catch {
+    console.error(`Error: ${adapter.rootLabel} does not exist: ${root}`);
+    process.exit(2);
+  }
+
+  const timestamp = new Date().toISOString().slice(0, 19).replace(/:/g, '');
+  const outDir = opts.out
+    ? path.resolve(opts.out)
+    : path.join(os.homedir(), 'Downloads', `convos-${timestamp}`);
+  const matches = [];
+  let scanned = 0;
+
+  for await (const session of adapter.scan(root)) {
+    scanned += 1;
+    if (opts.verbose) {
+      console.error(`scanned ${session.path}`);
+      if (session.malformedCount) {
+        console.error(`  malformed lines: ${session.malformedCount}`);
+      }
+    }
+    if (match(filterSpec, session)) {
+      matches.push(session);
+      if (opts.verbose) {
+        console.error(`  matched ${session.sessionId}`);
+      }
+      if (opts.limit && matches.length >= opts.limit) break;
+    }
+  }
+
+  if (opts.dryRun) {
+    for (const session of matches) {
+      process.stdout.write(`${session.sessionId} ${session.gitBranch ?? 'nobranch'} ${session.startedAt ?? ''} ${session.summary ?? ''}\n`);
+    }
+    console.error(`Found ${matches.length} matching sessions from ${scanned} scanned.`);
+    process.exit(0);
+  }
+
+  if (opts.json) {
+    for (const session of matches) {
+      if (filterSpec.tool === 'cursor') {
+        emitCursorSessionJson(session);
+      } else {
+        await streamJsonlToStdout(session);
+      }
+    }
+    console.error(`Emitted JSONL for ${matches.length} matching sessions from ${scanned} scanned.`);
+    process.exit(0);
+  }
+
+  if (opts.outputOnly) {
+    const { text, unknown } = renderOutputOnly(matches);
+    process.stdout.write(text);
+    if (unknown.length) {
+      console.error(`Warning: cost excludes ${unknown.length} unpriced model(s): ${unknown.join(', ')}`);
+    }
+    console.error(`Summarized ${matches.length} matching sessions from ${scanned} scanned.`);
+    process.exit(0);
+  }
+
+  await fs.mkdir(outDir, { recursive: true });
+
+  let exportResults;
+  try {
+    const exportOpts = { full: opts.full, noDiffs: filterSpec.diffs === 'no-diffs' };
+    exportResults = await pAll(matches, (session) => adapter.exportSession(session, outDir, exportOpts), 8);
+  } catch (error) {
+    console.error(`Error exporting sessions: ${error.message}`);
+    process.exit(3);
+  }
+
+  const indexLines = [
+    '# Export index',
+    '',
+    '| filename | date | branch | summary |',
+    '|---|---|---|---|',
+    ...exportResults.map((result, index) => {
+      const session = matches[index];
+      return `| ${result.filename} | ${session.startedAt ? session.startedAt.slice(0, 10) : ''} | ${session.gitBranch ?? ''} | ${session.summary ?? ''} |`;
+    }),
+  ];
+  await fs.writeFile(path.join(outDir, '_index.md'), indexLines.join('\n') + '\n', 'utf8');
+
+  console.log(`Exported ${exportResults.length} of ${scanned} scanned sessions to ${outDir}`);
+  process.exit(0);
+}
+
+main();

package/src/cursor/exporter.js

@@ -0,0 +1,264 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import Database from 'better-sqlite3';
+
+const MAX_TOOL_RESULT = 4096;
+const EXPECTED_SCHEMA_VERSION = 3;
+const DIFF_FIELDS = [
+  'editTrailContexts',
+  'fileDiffTrajectories',
+  'gitDiffs',
+  'humanChanges',
+  'diffsSinceLastApply',
+  'assistantSuggestedDiffs',
+];
+
+function slugifyBranch(branch) {
+  if (!branch) return 'nobranch';
+  return branch
+    .replace(/\//g, '-')
+    .toLowerCase()
+    .replace(/[^a-z0-9-]/g, '')
+    .replace(/-+/g, '-');
+}
+
+function yamlQuote(value) {
+  if (value === null || value === undefined) return '""';
+  const str = String(value);
+  return `"${str.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+
+function truncateIfNeeded(text, full) {
+  if (full || text.length <= MAX_TOOL_RESULT) return text;
+  const truncated = text.slice(0, MAX_TOOL_RESULT);
+  const remaining = text.length - MAX_TOOL_RESULT;
+  return `${truncated}… [${remaining} more chars truncated]`;
+}
+
+function asJsonBlock(value) {
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return String(value);
+  }
+}
+
+function parseJsonValue(value) {
+  if (value === null || value === undefined) return null;
+  const text = Buffer.isBuffer(value) ? value.toString('utf8') : String(value);
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+function fenced(lang, body) {
+  return ['', '```' + lang, body, '```', ''].join('\n');
+}
+
+function roleForBubble(bubble) {
+  if (bubble.type === 1) return 'user';
+  if (bubble.type === 2) return 'assistant';
+  return null;
+}
+
+function collectThinking(bubble) {
+  const parts = [];
+  if (typeof bubble.thinking === 'string' && bubble.thinking.trim()) {
+    parts.push(bubble.thinking);
+  } else if (bubble.thinking && typeof bubble.thinking === 'object') {
+    parts.push(asJsonBlock(bubble.thinking));
+  }
+  if (Array.isArray(bubble.allThinkingBlocks)) {
+    for (const block of bubble.allThinkingBlocks) {
+      if (typeof block === 'string') parts.push(block);
+      else if (block && typeof block.text === 'string') parts.push(block.text);
+      else if (block) parts.push(asJsonBlock(block));
+    }
+  }
+  return parts.join('\n\n').trim();
+}
+
+function hasContent(value) {
+  if (value === null || value === undefined) return false;
+  if (Array.isArray(value)) return value.some(hasContent);
+  if (typeof value === 'object') return Object.values(value).some(hasContent);
+  if (typeof value === 'string') return value.length > 0;
+  return true;
+}
+
+function hasAnyDiffField(bubble) {
+  return DIFF_FIELDS.some((field) => hasContent(bubble[field]));
+}
+
+function renderBubble(bubble, opts) {
+  const out = [];
+  const text = typeof bubble.text === 'string' ? bubble.text.trim() : '';
+  if (text) out.push(text);
+
+  const thinking = collectThinking(bubble);
+  if (thinking) out.push(fenced('thinking', thinking));
+
+  const hasCapabilityPayload =
+    hasContent(bubble.capabilities) ||
+    hasContent(bubble.capabilityContexts) ||
+    hasContent(bubble.capabilityStatuses);
+  if (hasCapabilityPayload) {
+    const capabilityName =
+      (Array.isArray(bubble.capabilities) && bubble.capabilities[0]?.name) ||
+      bubble.capabilityType ||
+      'capability';
+    const payload = {};
+    if (bubble.capabilityType !== undefined) payload.capabilityType = bubble.capabilityType;
+    if (hasContent(bubble.capabilities)) payload.capabilities = bubble.capabilities;
+    if (hasContent(bubble.capabilityContexts)) payload.capabilityContexts = bubble.capabilityContexts;
+    if (hasContent(bubble.capabilityStatuses)) payload.capabilityStatuses = bubble.capabilityStatuses;
+    out.push(fenced(`tool:${capabilityName}`, asJsonBlock(payload)));
+  }
+
+  if (Array.isArray(bubble.toolResults) && bubble.toolResults.length > 0) {
+    const body = truncateIfNeeded(asJsonBlock(bubble.toolResults), opts.full);
+    out.push(fenced('result', body));
+  }
+
+  if (hasAnyDiffField(bubble)) {
+    if (opts.noDiffs) {
+      out.push(fenced('diff', '[diffs redacted]'));
+    } else {
+      const payload = {};
+      for (const field of DIFF_FIELDS) {
+        if (bubble[field] !== undefined && bubble[field] !== null) {
+          payload[field] = bubble[field];
+        }
+      }
+      const body = truncateIfNeeded(asJsonBlock(payload), opts.full);
+      out.push(fenced('diff', body));
+    }
+  }
+
+  return out.join('\n').trim();
+}
+
+async function resolveFilename(session, outDir) {
+  const date = session.startedAt ? session.startedAt.slice(0, 10) : 'unknown-date';
+  const prefix = session.sessionId.slice(0, 8);
+  const branchSlug = slugifyBranch(session.gitBranch);
+  const base = `${date}_${prefix}_${branchSlug}`;
+  let candidate = `${base}.md`;
+  let suffix = 1;
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    const fullPath = path.join(outDir, candidate);
+    try {
+      await fs.access(fullPath);
+      suffix += 1;
+      candidate = `${base}_${suffix}.md`;
+    } catch {
+      return candidate;
+    }
+  }
+}
+
+function loadBubbles(dbPath, composerId) {
+  const db = new Database(dbPath, { readonly: true, fileMustExist: true });
+  try {
+    const rows = db
+      .prepare('SELECT key, value FROM cursorDiskKV WHERE key LIKE ? ORDER BY key')
+      .all(`bubbleId:${composerId}:%`);
+    const byId = new Map();
+    for (const row of rows) {
+      const bubble = parseJsonValue(row.value);
+      if (!bubble) continue;
+      const id = bubble.bubbleId || row.key.slice(`bubbleId:${composerId}:`.length);
+      byId.set(id, bubble);
+    }
+    return byId;
+  } finally {
+    db.close();
+  }
+}
+
+export async function exportSession(session, outDir, opts = {}) {
+  const cursor = session._cursor;
+  if (!cursor || !cursor.dbPath) {
+    throw new Error('cursor exporter requires session._cursor.dbPath');
+  }
+
+  const filename = await resolveFilename(session, outDir);
+  const tempPath = path.join(outDir, `${filename}.tmp`);
+  const finalPath = path.join(outDir, filename);
+  const stream = await fs.open(tempPath, 'w');
+  let succeeded = false;
+
+  try {
+    const frontmatter = [
+      '---',
+      `sessionId: ${yamlQuote(session.sessionId)}`,
+      `cwd: ${yamlQuote(session.cwd ?? '')}`,
+      `gitBranch: ${yamlQuote(session.gitBranch ?? '')}`,
+      `version: ${yamlQuote(session.version ?? '')}`,
+      `startedAt: ${yamlQuote(session.startedAt ?? '')}`,
+      `endedAt: ${yamlQuote(session.endedAt ?? '')}`,
+      `summary: ${yamlQuote(session.summary ?? '')}`,
+      'tokensInput: 0',
+      'tokensOutput: 0',
+      'tokensCacheCreation: 0',
+      'tokensCacheRead: 0',
+      '---',
+      '',
+    ].join('\n');
+    await stream.write(frontmatter);
+
+    const bubbles = loadBubbles(cursor.dbPath, cursor.composerId);
+    const orderedIds = [...(cursor.conversationOrder ?? [])];
+    const seen = new Set();
+    const orderedBubbles = [];
+    for (const id of orderedIds) {
+      if (seen.has(id)) continue;
+      const bubble = bubbles.get(id);
+      if (!bubble) continue;
+      seen.add(id);
+      orderedBubbles.push(bubble);
+    }
+    for (const [id, bubble] of bubbles) {
+      if (seen.has(id)) continue;
+      orderedBubbles.push(bubble);
+    }
+
+    const schemaWarnings = new Set();
+    let lastRole = null;
+    for (const bubble of orderedBubbles) {
+      if (typeof bubble._v === 'number' && bubble._v !== EXPECTED_SCHEMA_VERSION) {
+        schemaWarnings.add(bubble._v);
+      }
+      const role = roleForBubble(bubble);
+      if (!role) continue;
+      const body = renderBubble(bubble, opts);
+      if (!body) continue;
+
+      const heading = role === 'user' ? '## User' : '## Assistant';
+      if (heading !== lastRole) {
+        await stream.write(`${heading}\n\n`);
+        lastRole = heading;
+      }
+      await stream.write(`${body}\n\n`);
+    }
+
+    if (schemaWarnings.size > 0) {
+      const versions = [...schemaWarnings].join(', ');
+      process.stderr.write(
+        `Warning: cursor session ${session.sessionId} contains bubbles with unexpected _v values: ${versions}\n`,
+      );
+    }
+
+    succeeded = true;
+  } finally {
+    await stream.close().catch(() => {});
+    if (!succeeded) await fs.unlink(tempPath).catch(() => {});
+  }
+
+  await fs.rename(tempPath, finalPath);
+  const { size: bytes } = await fs.stat(finalPath);
+  return { filename, bytes };
+}