convoptics 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,366 @@
+# convoptics
+
+[![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+Convoptics scans your local Claude Code and Cursor history, filters sessions
+with a small `key:value` query language, and exports the matches as clean
+Markdown transcripts.
+
+## Quick start
+
+```bash
+# Run directly from the repo
+node bin/convoptics.js tool:claude-code branch:feature/payments
+node bin/convoptics.js tool:cursor branch:feature/payments
+
+# Or link it once and use the global command
+npm link
+convoptics tool:claude-code branch:feature/payments
+convoptics tool:cursor cwd:projectA
+```
+
+Output (defaults to your Downloads folder):
+
+```text
+~/Downloads/convos-2026-05-14T143000/
+  ├── 2026-05-12_a3f9c1d0_feature-payments.md
+  ├── 2026-05-13_b7c2e840_feature-payments.md
+  └── _index.md
+```
+
+> On macOS, the first time your terminal app writes to `~/Downloads` the OS
+> shows a one-time prompt ("Terminal would like to access files in your
+> Downloads folder"). Click Allow once; it won't ask again. Linux and Windows
+> don't prompt. Reading from `~/.claude/projects/` never triggers a prompt.
+
+## Installation
+
+Requires Node.js 18 or newer.
+
+```bash
+git clone <repo> && cd convoptics
+npm install
+npm link        # optional: exposes `convoptics` globally
+```
+
+Runtime dependencies:
+- [`commander`](https://www.npmjs.com/package/commander) for argv parsing.
+- [`better-sqlite3`](https://www.npmjs.com/package/better-sqlite3) to read
+  Cursor's SQLite databases. This is a native module; `npm install` will
+  download a prebuilt binary for common platforms or compile from source if
+  needed (which requires Python + a C++ toolchain).
+
+## Usage
+
+```bash
+convoptics [filters...] [options]
+```
+
+A `tool:` filter is required; everything else is optional.
+
+### Filters
+
+| Key       | Operator(s)            | Meaning                                                                 |
+|-----------|------------------------|-------------------------------------------------------------------------|
+| `tool`    | `:` `=`                | Required. One of `claude-code` or `cursor`.                             |
+| `branch`  | `:` `=`                | Exact branch name or glob (`*` matches one path segment, `**` matches across `/`). Case-insensitive. For Cursor this is the branch when the session was created; it does not track later branch switches. |
+| `cwd`     | `:` `=`                | Case-insensitive substring of the session's working directory.          |
+| `project` | `:` `=`                | Exact match of the project folder basename (the last path segment of `cwd`, e.g. `projectA` for `/Users/bren/projectA`). Use `cwd:` for a case-insensitive substring match on the full path. |
+| `session` | `:` `=`                | Session-id prefix match.                                                |
+| `version` | `:` `=`                | Exact Claude Code version string. Not supported for `tool:cursor` (no per-session client version is recorded). |
+| `date`    | `:` `=` `>` `>=` `<` `<=` | ISO date (`YYYY-MM-DD`). Comparisons use the session's `startedAt`.  |
+| `diffs`   | `:` `=`                | `diffs` (default) keeps full file-edit content; `no-diffs` redacts file edits to a placeholder so transcripts can be shared without leaking source. For Claude Code this targets `Edit`/`MultiEdit`/`Write`/`NotebookEdit` tool inputs; for Cursor it targets the per-bubble `editTrailContexts`, `fileDiffTrajectories`, `gitDiffs`, `humanChanges`, `diffsSinceLastApply`, and `assistantSuggestedDiffs` fields. |
+
+Repeating a key creates an OR: `branch:main branch:feature/*` matches sessions on
+either branch. Different keys combine with AND.
+
+### Options
+
+| Flag                | Description                                              |
+|---------------------|----------------------------------------------------------|
+| `--root <path>`     | Override the tool's data root. Default for `tool:claude-code` is `~/.claude/projects`. Default for `tool:cursor` is `~/Library/Application Support/Cursor/User` on macOS, `~/.config/Cursor/User` on Linux, `%APPDATA%/Cursor/User` on Windows. |
+| `--out <dir>`       | Override the output directory (default: `~/Downloads/convos-<timestamp>`). |
+| `--dry-run`         | List matches without writing files.                      |
+| `--json`            | Emit raw session data to stdout instead of Markdown. For Claude Code, the original JSONL; for Cursor, one JSON object per line with session metadata. |
+| `--limit <n>`       | Stop after N matches.                                    |
+| `--full`            | Do not truncate large tool results in the Markdown output. |
+| `--output-only`     | Print a Markdown token + cost summary table to stdout. Skips writing transcripts. **Claude Code only** — Cursor sessions do not record reliable token counts, so this flag is rejected with `tool:cursor`. |
+| `-v`, `--verbose`   | Show scan progress on stderr.                            |
+
+### Examples
+
+```bash
+# Everything on `working` in the last 2 days (today = 2026-05-14)
+convoptics tool:claude-code branch:working date>=2026-05-12
+
+# All feature branches, a single day
+convoptics tool:claude-code 'branch:feature/*' date:2026-05-12
+
+# A specific session prefix, full tool output, custom out dir
+convoptics tool:claude-code session:a1b2 --full --out ./payments-debug
+
+# Preview without writing anything
+convoptics tool:claude-code branch:main --dry-run -v
+
+# Pipe raw JSONL to another tool
+convoptics tool:claude-code branch:working --json | jq '.message.role'
+
+# Share a session externally without exposing source code
+convoptics tool:claude-code session:a1b2 diffs:no-diffs
+
+# Just see how many tokens / how much money a query covers (no files written)
+convoptics tool:claude-code branch:working date>=2026-05-12 --output-only
+
+# All Cursor sessions for a project, with secrets in edits redacted
+convoptics tool:cursor cwd:projectA diffs:no-diffs
+```
+
+> **Shell quoting.** Quote glob patterns (`'branch:feature/*'`) so the shell
+> does not expand `*`. Quote any token using `>`, `>=`, `<`, or `<=` (e.g.
+> `'date>=2026-05-12'`) — otherwise zsh/bash treat it as an output redirection.
+> Tokens using `:` or `=` are safe unquoted.
+
+## How it works
+
+Each tool has its own scanner + exporter under `src/<tool>/`. The CLI parses
+the query, picks the adapter based on `tool:`, and pipes sessions through a
+shared matcher into the adapter's exporter.
+
+```
+┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
+│ scanner  │ -> │  query   │ -> │ matcher  │ -> │ exporter │
+│ (per     │    │          │    │          │    │ (per     │
+│  tool)   │    │ parse    │    │ filter   │    │  tool)   │
+└──────────┘    │ argv     │    │ spec     │    └──────────┘
+                │ into     │    │ applied  │       per-session
+                │ a spec   │    │ to each  │       Markdown +
+                └──────────┘    │ session  │       index
+                                └──────────┘
+```
+
+**Claude Code** writes one `.jsonl` file per session into
+`~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl`. The Claude Code scanner
+streams those files line-by-line, extracting metadata only; the exporter
+re-streams them to render Markdown.
+
+**Cursor** stores sessions across SQLite databases: a global
+`globalStorage/state.vscdb` holds session headers (`composerData:<uuid>`) and
+individual message bubbles (`bubbleId:<uuid>:<bubbleId>`), and one
+`workspaceStorage/<hash>/state.vscdb` per workspace holds the registry that
+joins each composer to its `cwd` (via the sibling `workspace.json`) and
+`createdOnBranch`. The Cursor scanner reads the workspace registries first to
+build that lookup, then walks the global DB; the exporter re-opens the global
+DB to load bubbles in conversation order. See
+[docs/cursor-schema.md](docs/cursor-schema.md) for the on-disk layout this
+adapter is pinned against.
+
+### Modules
+
+- [src/cli.js](src/cli.js) — argv parsing, adapter dispatch, output. Uses a
+  small in-process concurrency limiter (`pAll`, default 8) to export sessions
+  in parallel.
+- [src/query.js](src/query.js) — `parseQuery(argv)` turns tokens like
+  `branch:main` and `date>=2026-05-01` into a structured filter spec. Repeated
+  keys accumulate into arrays (OR). Validates keys, operators, the required
+  `tool` filter, and rejects per-tool-incompatible keys.
+- [src/matcher.js](src/matcher.js) — `match(filter, session)` applies the spec.
+  Tool-agnostic: operates on the common session shape that every adapter
+  yields. Branch globs are compiled to anchored, case-insensitive regexes:
+  `*` becomes `[^/]*`, `**` becomes `.*`, and regex metacharacters in the rest
+  of the pattern are escaped.
+- [src/claude-code/scanner.js](src/claude-code/scanner.js) — async generator.
+  Streams every `.jsonl` under `~/.claude/projects` with `readline`, extracting
+  only metadata (`sessionId`, `cwd`, `gitBranch`, `version`, `startedAt`,
+  `endedAt`, `summary`, `messageCount`, `malformedCount`, plus per-model token
+  usage). Full message content is never buffered.
+- [src/claude-code/exporter.js](src/claude-code/exporter.js) — for each match,
+  re-streams the JSONL and writes a Markdown transcript. Writes go to a `.tmp`
+  file first and are renamed atomically on success, so an interrupted run
+  never leaves partial exports.
+- [src/claude-code/pricing.js](src/claude-code/pricing.js) — USD-per-million
+  pricing table for `--output-only` (Claude Code only).
+- [src/cursor/scanner.js](src/cursor/scanner.js) — opens each
+  `workspaceStorage/<hash>/state.vscdb` read-only with `better-sqlite3`, builds
+  a `composerId → {cwd, branch, name}` registry, then streams
+  `composerData:<uuid>` rows from the global DB. Token counts are emitted as
+  zero — Cursor's per-bubble `tokenCount` is unreliable (~96% report zero).
+- [src/cursor/exporter.js](src/cursor/exporter.js) — re-opens the global DB,
+  loads `bubbleId:<sessionId>:*` rows for the session, orders them by the
+  header's `conversation[]` cache (with leftover bubbles appended), and
+  renders each `type:1`/`type:2` bubble as Markdown. Same atomic
+  `.tmp` → rename pattern as the Claude Code exporter. Warns to stderr if any
+  bubble has an unexpected schema version (`_v` ≠ 3).
+
+### Filename scheme
+
+Each export is named `<YYYY-MM-DD>_<sessionId[:8]>_<branch-slug>.md`.
+Branch slugs lowercase the branch and replace `/` with `-`. If the same name
+already exists, a numeric suffix (`_2`, `_3`, …) is appended.
+
+### Output format
+
+Each Markdown file starts with quoted YAML frontmatter, followed by the
+conversation grouped by role:
+
+```markdown
+---
+sessionId: "a1b2c3d4"
+cwd: "/Users/bren/projectA"
+gitBranch: "feature/payments"
+version: "0.30.0"
+startedAt: "2026-05-12T08:00:00Z"
+endedAt: "2026-05-12T08:00:02Z"
+summary: "payments-refactor"
+tokensInput: 12345
+tokensOutput: 6789
+tokensCacheCreation: 1024
+tokensCacheRead: 4096
+---
+
+## User
+
+Please refactor the payment handler.
+
+## Assistant
+
+Sure, I will update the handler.
+```
+
+Token counts are summed across every assistant turn that reports a `usage`
+block in the source JSONL.
+
+### Token usage and cost (`--output-only`)
+
+> **Claude Code only.** Cursor stores per-bubble `tokenCount` values that are
+> `{0,0}` for ~96% of assistant bubbles, so cost reporting would be misleading.
+> The flag is rejected with `tool:cursor` until this changes upstream.
+
+`--output-only` skips writing Markdown and instead prints a Markdown report to
+stdout: one row per matching session, followed by a totals table.
+
+```text
+# Session usage
+
+| date | session | branch | model | input | output | cache R | cache W | cost |
+|---|---|---|---|---:|---:|---:|---:|---:|
+| 2026-05-12 | a1b2c3d4 | feature/payments | claude-opus-4-7 | 12,345 | 6,789 | 4,096 | 1,024 | $0.45 |
+| 2026-05-13 | b7c2e840 | feature/payments | claude-sonnet-4-6 | 20,000 | 10,000 | 0 | 0 | $0.21 |
+
+## Totals
+
+| metric | value |
+|---|---:|
+| sessions | 2 |
+| input tokens | 32,345 |
+| ... | ... |
+| cost (USD) | $0.66 |
+```
+
+The `model` column shows each session's *dominant* model — the one with the
+most input + output tokens — and appends `(+N)` if other models also appeared
+in that session. Cost is computed per-model and summed.
+
+Redirect to a file for sharing: `convoptics ... --output-only > usage.md`.
+
+#### Pricing table
+
+Rates live in [src/pricing.js](src/pricing.js) as USD per million tokens.
+Model resolution does a longest-prefix match, so dated variants like
+`claude-opus-4-7-20251022` map to the `claude-opus-4-7` row. If a session's
+model isn't in the table, its tokens are still reported but its cost is
+excluded and a warning is printed to stderr. Add new models by appending to
+the `PRICING` object.
+
+### Redacting diffs
+
+Use `diffs:no-diffs` to share a transcript without leaking the source you
+edited. File-edit tool calls (`Edit`, `MultiEdit`, `Write`, `NotebookEdit`)
+have their inputs replaced by a one-line summary:
+
+````markdown
+```tool:Edit
+[diff redacted: 4 lines added, 3 lines removed]
+```
+````
+
+Other tool calls and their results are unchanged. Token totals in the
+frontmatter are still emitted.
+
+Tool use and tool results render as fenced blocks:
+
+````markdown
+```tool:git
+{
+  "command": "status"
+}
+```
+
+```result
+All tests passed.
+```
+````
+
+Sidechain messages are prefixed with a `### sidechain` heading. Consecutive
+messages from the same role share a single role heading.
+
+### Truncation
+
+Tool results longer than 4 KB are truncated with a trailing
+`… [N more chars truncated]` marker. Pass `--full` to disable this.
+
+### Index file
+
+Every run also writes `_index.md` with a table of `filename | date | branch |
+summary` rows in match order.
+
+### Errors and resilience
+
+- Missing projects root → exit code `2` with a clear message.
+- Export failure → exit code `3`; the partial `.tmp` file is removed.
+- Invalid query tokens → exit code `1` with the offending token in the message.
+- Malformed JSONL lines are counted (`malformedCount`) and skipped; `--verbose`
+  prints the per-file count.
+
+## Project layout
+
+```
+bin/convoptics.js               # entry point shim
+src/cli.js                      # argv → adapter dispatch
+src/query.js                    # parseQuery
+src/matcher.js                  # tool-agnostic match + glob compilation
+src/claude-code/scanner.js      # walkJsonl + scanSessions (async generators)
+src/claude-code/exporter.js     # exportSession + Markdown rendering
+src/claude-code/pricing.js      # USD-per-million pricing for --output-only
+src/cursor/scanner.js           # SQLite-backed scanSessions + defaultCursorRoot
+src/cursor/exporter.js          # exportSession (bubble rendering)
+docs/cursor-schema.md           # Cursor on-disk schema reference
+test/                           # node:test suites + fixtures
+.github/workflows/ci.yml        # Node 18 + 20 matrix
+```
+
+## Running the tests
+
+```bash
+npm test
+```
+
+The suite uses Node's built-in `node:test` runner against fixtures under
+[test/fixtures/projects/](test/fixtures/projects/).
+
+## Adding support for other tools
+
+The `tool:` key dispatches to an adapter under `src/<tool>/`. Each adapter
+ships its own `scanner.js` (an async generator yielding the common session
+shape — see the Modules section) and `exporter.js` (writing Markdown for one
+session into the output directory). Register the adapter in the `ADAPTERS`
+map in [src/cli.js](src/cli.js), add the tool name to `VALID_TOOLS` in
+[src/query.js](src/query.js), and declare any per-tool incompatible filter
+keys in `TOOL_UNSUPPORTED_KEYS`. The matcher and query layers are
+tool-agnostic and don't need changes.
+
+Two adapters ship today: `claude-code` (JSONL files under `~/.claude/projects`)
+and `cursor` (SQLite databases under Cursor's user-data directory).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/bin/convoptics.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../src/cli.js';

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "convoptics",
+  "version": "0.1.0",
+  "type": "module",
+  "bin": {
+    "convoptics": "./bin/convoptics.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/"
+  },
+  "dependencies": {
+    "better-sqlite3": "^12.10.0",
+    "commander": "^12.0.0"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "LICENSE",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/brenoneill/convoptics.git"
+  },
+  "bugs": {
+    "url": "https://github.com/brenoneill/convoptics/issues"
+  },
+  "homepage": "https://github.com/brenoneill/convoptics#readme",
+  "keywords": [],
+  "author": "Brendan O'Neill <brendanoneill94@gmail.com>",
+  "license": "MIT",
+  "description": "A CLI for extracting Claude Code conversations by query."
+}

package/src/claude-code/exporter.js

@@ -0,0 +1,201 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import readline from 'node:readline';
+
+const MAX_TOOL_RESULT = 4096;
+
+function slugifyBranch(branch) {
+  if (!branch) return 'nobranch';
+  return branch
+    .replace(/\//g, '-')
+    .toLowerCase()
+    .replace(/[^a-z0-9-]/g, '')
+    .replace(/-+/g, '-');
+}
+
+function asString(value) {
+  if (value === null || value === undefined) return '';
+  if (typeof value === 'string') return value;
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return String(value);
+  }
+}
+
+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 countLines(value) {
+  if (value === null || value === undefined || value === '') return 0;
+  return String(value).split('\n').length;
+}
+
+function diffStatsForToolUse(block) {
+  const name = block.name || block.toolName || block.tool?.name || '';
+  const input = block.input ?? block.args ?? {};
+  if (!input || typeof input !== 'object') return null;
+  if (name === 'Edit') {
+    return { added: countLines(input.new_string), removed: countLines(input.old_string) };
+  }
+  if (name === 'MultiEdit' && Array.isArray(input.edits)) {
+    let added = 0;
+    let removed = 0;
+    for (const edit of input.edits) {
+      added += countLines(edit?.new_string);
+      removed += countLines(edit?.old_string);
+    }
+    return { added, removed };
+  }
+  if (name === 'Write') {
+    return { added: countLines(input.content), removed: 0 };
+  }
+  if (name === 'NotebookEdit') {
+    return { added: countLines(input.new_source), removed: countLines(input.old_source) };
+  }
+  return null;
+}
+
+function renderBlock(block, opts) {
+  if (typeof block === 'string') {
+    return block;
+  }
+
+  if (block.type === 'text') {
+    return block.text || '';
+  }
+
+  if (block.type === 'tool_use') {
+    const name = block.name || block.toolName || block.tool?.name || 'unknown';
+    if (opts.noDiffs) {
+      const stats = diffStatsForToolUse(block);
+      if (stats) {
+        const body = `[diff redacted: ${stats.added} lines added, ${stats.removed} lines removed]`;
+        return ['', '```tool:' + name, body, '```', ''].join('\n');
+      }
+    }
+    const input = asString(block.input ?? block.args ?? block.payload ?? block.content ?? '');
+    return ['','```tool:' + name, input, '```', ''].join('\n');
+  }
+
+  if (block.type === 'tool_result') {
+    let output = block.output ?? block.result ?? block.text ?? block.content ?? '';
+    output = asString(output);
+    output = truncateIfNeeded(output, opts.full);
+    return ['','```result', output, '```', ''].join('\n');
+  }
+
+  return asString(block.text ?? block.content ?? block);
+}
+
+function renderMessage(message, opts) {
+  const lines = [];
+  if (message.isSidechain) {
+    lines.push('### sidechain', '');
+  }
+
+  const content = message.content;
+  if (typeof content === 'string') {
+    lines.push(content);
+  } else if (Array.isArray(content)) {
+    for (const block of content) {
+      lines.push(renderBlock(block, opts));
+    }
+  } else {
+    lines.push(asString(content));
+  }
+
+  return lines.join('\n').trim() + '\n';
+}
+
+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;
+  while (true) {
+    const fullPath = path.join(outDir, candidate);
+    try {
+      await fs.access(fullPath);
+      suffix += 1;
+      candidate = `${base}_${suffix}.md`;
+      continue;
+    } catch {
+      return candidate;
+    }
+  }
+}
+
+function yamlQuote(value) {
+  if (value === null || value === undefined) return '""';
+  const str = String(value);
+  return `"${str.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+
+export async function exportSession(session, outDir, opts = {}) {
+  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 readStream = null;
+  let succeeded = false;
+  try {
+    const tokens = session.tokens ?? { input: 0, output: 0, cacheCreation: 0, cacheRead: 0 };
+    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: ${tokens.input ?? 0}`,
+      `tokensOutput: ${tokens.output ?? 0}`,
+      `tokensCacheCreation: ${tokens.cacheCreation ?? 0}`,
+      `tokensCacheRead: ${tokens.cacheRead ?? 0}`,
+      '---',
+      '',
+    ].join('\n');
+    await stream.write(frontmatter);
+
+    readStream = await fs.open(session.path, 'r');
+    const lines = readline.createInterface({ input: readStream.createReadStream(), crlfDelay: Infinity });
+    let lastRole = null;
+
+    for await (const line of lines) {
+      if (!line.trim()) continue;
+      let record;
+      try {
+        record = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      if (!record.message || !record.message.role) continue;
+      const role = record.message.role;
+      const heading = role === 'user' ? '## User' : role === 'assistant' ? '## Assistant' : `## ${role}`;
+      if (heading !== lastRole) {
+        await stream.write(`${heading}\n\n`);
+        lastRole = heading;
+      }
+      await stream.write(renderMessage(record.message, opts));
+      await stream.write('\n');
+    }
+
+    succeeded = true;
+  } finally {
+    if (readStream) await readStream.close().catch(() => {});
+    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 };
+}

package/src/claude-code/pricing.js

@@ -0,0 +1,58 @@
+// Prices in USD per 1,000,000 tokens.
+// Add new models here as they ship; resolveModel does a longest-prefix match,
+// so dated variants like "claude-opus-4-7-20251022" map to "claude-opus-4-7".
+export const PRICING = {
+  'claude-opus-4-7':   { input:  5.0, output: 25.0, cacheRead: 0.5,  cacheWrite:  6.25, cacheWrite1h: 10.0 },
+  'claude-opus-4-6':   { input:  5.0, output: 25.0, cacheRead: 0.5,  cacheWrite:  6.25, cacheWrite1h: 10.0 },
+  'claude-opus-4-5':   { input:  5.0, output: 25.0, cacheRead: 0.5,  cacheWrite:  6.25, cacheWrite1h: 10.0 },
+  'claude-opus-4-1':   { input: 15.0, output: 75.0, cacheRead: 1.5,  cacheWrite: 18.75, cacheWrite1h: 30.0 },
+  'claude-opus-4':     { input: 15.0, output: 75.0, cacheRead: 1.5,  cacheWrite: 18.75, cacheWrite1h: 30.0 },
+  'claude-sonnet-4-6': { input:  3.0, output: 15.0, cacheRead: 0.3,  cacheWrite:  3.75, cacheWrite1h:  6.0 },
+  'claude-sonnet-4-5': { input:  3.0, output: 15.0, cacheRead: 0.3,  cacheWrite:  3.75, cacheWrite1h:  6.0 },
+  'claude-sonnet-4':   { input:  3.0, output: 15.0, cacheRead: 0.3,  cacheWrite:  3.75, cacheWrite1h:  6.0 },
+  'claude-3-7-sonnet': { input:  3.0, output: 15.0, cacheRead: 0.3,  cacheWrite:  3.75, cacheWrite1h:  6.0 },
+  'claude-3-5-sonnet': { input:  3.0, output: 15.0, cacheRead: 0.3,  cacheWrite:  3.75, cacheWrite1h:  6.0 },
+  'claude-haiku-4-5':  { input:  1.0, output:  5.0, cacheRead: 0.1,  cacheWrite:  1.25, cacheWrite1h:  2.0 },
+  'claude-3-5-haiku':  { input:  0.8, output:  4.0, cacheRead: 0.08, cacheWrite:  1.0,  cacheWrite1h:  1.6 },
+};
+
+const SORTED_KEYS = Object.keys(PRICING).sort((a, b) => b.length - a.length);
+
+export function resolveModel(name) {
+  if (!name) return null;
+  if (PRICING[name]) return { key: name, rates: PRICING[name] };
+  for (const key of SORTED_KEYS) {
+    if (name.startsWith(key)) return { key, rates: PRICING[key] };
+  }
+  return null;
+}
+
+// tokens shape: { input, output, cacheCreation, cacheRead }
+// cacheCreation is priced at the 5-minute cacheWrite rate; Claude Code's JSONL
+// does not distinguish 5-minute from 1-hour cache creation today.
+export function costForTokens(tokens, rates) {
+  return (
+    (tokens.input ?? 0) * rates.input +
+    (tokens.output ?? 0) * rates.output +
+    (tokens.cacheRead ?? 0) * rates.cacheRead +
+    (tokens.cacheCreation ?? 0) * rates.cacheWrite
+  ) / 1_000_000;
+}
+
+// tokensByModel: { [modelName]: tokens }
+// Returns { cost, unknownModels: string[] }.
+export function costForSession(tokensByModel) {
+  let cost = 0;
+  const unknownModels = [];
+  for (const [model, tokens] of Object.entries(tokensByModel || {})) {
+    const resolved = resolveModel(model);
+    if (!resolved) {
+      if ((tokens.input || tokens.output || tokens.cacheRead || tokens.cacheCreation) > 0) {
+        unknownModels.push(model);
+      }
+      continue;
+    }
+    cost += costForTokens(tokens, resolved.rates);
+  }
+  return { cost, unknownModels };
+}