reread-cli 0.0.0-stage → 0.2.1

package/src/files.js

@@ -0,0 +1,116 @@
+// @ts-check
+// Walking folders for session files and reading them line by line, for every tool's reader.
+import { closeSync, existsSync, fstatSync, openSync, readdirSync, readSync } from 'node:fs'
+import path from 'node:path'
+
+/**
+ * Every file under a folder that `keep` accepts. Symbolic links are not followed, so a link loop cannot hang the
+ * walk, and a folder that cannot be read is skipped.
+ * @param {string} dir
+ * @param {(file: string) => boolean} keep
+ * @returns {string[]}
+ */
+export function filesUnder(dir, keep) {
+  /** @type {string[]} */
+  const out = []
+  /** @type {import('node:fs').Dirent[]} */
+  let entries
+  try {
+    entries = readdirSync(dir, { withFileTypes: true })
+  } catch {
+    return out
+  }
+  for (const e of entries) {
+    const p = path.join(dir, e.name)
+    if (e.isDirectory()) out.push(...filesUnder(p, keep))
+    else if (e.isFile() && keep(p)) out.push(p)
+  }
+  return out
+}
+
+/**
+ * Whether a path is a folder or inside it. Paths are compared as written, ignoring case on macOS and Windows, whose
+ * disks usually do.
+ * @param {string} p
+ * @param {string} folder
+ */
+export function isInside(p, folder) {
+  const fold = process.platform === 'darwin' || process.platform === 'win32'
+  const a = path.resolve(p)
+  const b = path.resolve(folder)
+  const [x, y] = fold ? [a.toLowerCase(), b.toLowerCase()] : [a, b]
+  return x === y || x.startsWith(y.endsWith(path.sep) ? y : y + path.sep)
+}
+
+/** The folders that exist. */
+export const existingDirs = (/** @type {string[]} */ dirs) => dirs.filter((d) => existsSync(d))
+
+const CHUNK = 1 << 20
+const NEWLINE = 10
+
+/**
+ * Read the complete lines of a file from a byte offset, synchronously and in 1 MB chunks. Lines are handed over as
+ * Buffers, so a long line that is not wanted is never turned into a string.
+ * @param {string} file
+ * @param {number} from  the byte offset to start at; must be the start of a line
+ * @param {(line: Buffer) => void} onLine
+ * @returns {{ offset: number, rest: Buffer, size: number }}  offset: where the unfinished last line starts; rest: that line
+ */
+export function readLines(file, from, onLine) {
+  const fd = openSync(file, 'r')
+  try {
+    const size = fstatSync(fd).size
+    /** @type {Buffer[]} */
+    let pieces = []
+    let pending = 0
+    let pos = from
+    while (pos < size) {
+      const chunk = Buffer.allocUnsafe(Math.min(CHUNK, size - pos))
+      const got = readSync(fd, chunk, 0, chunk.length, pos)
+      if (got <= 0) break
+      pos += got
+      const buf = got < chunk.length ? chunk.subarray(0, got) : chunk
+      let start = 0
+      let nl
+      while ((nl = buf.indexOf(NEWLINE, start)) !== -1) {
+        const part = buf.subarray(start, nl)
+        onLine(pieces.length ? Buffer.concat([...pieces, part]) : part)
+        pieces = []
+        pending = 0
+        start = nl + 1
+      }
+      if (start < buf.length) {
+        pieces.push(buf.subarray(start))
+        pending += buf.length - start
+      }
+    }
+    return { offset: pos - pending, rest: Buffer.concat(pieces), size }
+  } finally {
+    closeSync(fd)
+  }
+}
+
+/**
+ * Hand each line of a buffer to onLine, the last one too.
+ * @param {Buffer} buf
+ * @param {(line: Buffer) => void} onLine
+ */
+export function splitLines(buf, onLine) {
+  let start = 0
+  let nl
+  while ((nl = buf.indexOf(NEWLINE, start)) !== -1) {
+    onLine(buf.subarray(start, nl))
+    start = nl + 1
+  }
+  if (start < buf.length) onLine(buf.subarray(start))
+}
+
+/**
+ * Every line of a file, the last one too even with no newline after it.
+ * @param {string} file
+ * @param {(line: Buffer) => void} onLine
+ */
+export function eachLine(file, onLine) {
+  const { rest } = readLines(file, 0, onLine)
+  if (rest.length) onLine(rest)
+}

package/src/findings.js

@@ -0,0 +1,122 @@
+// @ts-check
+// Key findings: a few short cards, each with one number, what it means and what to do, the costliest first.
+import { pct, round2, tokens, usd } from './format.js'
+import { TOOLS } from './tools.js'
+
+/**
+ * @typedef {object} Finding
+ * @property {string} id
+ * @property {string} value   the number on the card
+ * @property {string} title
+ * @property {string} text
+ * @property {string} action
+ * @property {number | null} usd  what it is about, in US dollars at API prices; null when it has no price
+ */
+
+/** Context sizes counted as long in the long-context finding (from 150k up). */
+const LONG = ['150–200k', '200–500k', '500k+']
+
+/** The rebuild reason's words: why it happened, and what to do. */
+const LOST = {
+  cold: {
+    why: (/** @type {number} */ n) => `mostly after breaks longer than the cache's life (${n} times)`,
+    action: 'Before a long break, compact or finish the session; a cold cache writes the whole history again.',
+  },
+  model: {
+    why: (/** @type {number} */ n) => `mostly from switching model mid-session (${n} times)`,
+    action: 'Pick the model at the start of a task; each model has its own cache.',
+  },
+  prefix: {
+    why: (/** @type {number} */ n) =>
+      `mostly from changes near the start of the context, such as tools, MCP servers or settings (${n} times)`,
+    action: 'Avoid changing tools, MCP servers or settings in the middle of a long session.',
+  },
+}
+
+/**
+ * The compaction advice, for the tools used.
+ * @param {import('./tools.js').Tool[]} tools
+ */
+function freshAction(tools) {
+  if (tools.length === 1 && tools[0] === 'claude') {
+    return 'Run /compact earlier, or /clear when you switch task, instead of waiting for the automatic compaction.'
+  }
+  if (tools.length === 1 && tools[0] === 'codex') {
+    return 'Run /compact earlier, or /new when you switch task, instead of waiting for the automatic compaction.'
+  }
+  return `Compact earlier, or start fresh when you switch task (${tools.map((t) => TOOLS[t].fresh).join(', ')}).`
+}
+
+/**
+ * @param {import('./analyze.js').Analysis} a
+ * @param {import('./tools.js').Tool[]} [tools]  the tools the sessions came from
+ * @returns {Finding[]}
+ */
+export function findingsOf(a, tools = ['claude']) {
+  const { total, sessions } = a
+  /** @type {Finding[]} */
+  const out = []
+
+  const top10 = sessions.slice(0, 10).reduce((sum, s) => sum + s.cost, 0)
+  const topShare = pct(top10, total.cost)
+  if (sessions.length >= 15 && topShare >= 30) {
+    out.push({
+      id: 'concentration',
+      value: `${topShare.toFixed(0)}%`,
+      title: `Your 10 costliest sessions made ${topShare.toFixed(0)}% of your usage`,
+      text: `Out of ${sessions.length} sessions. A few long sessions drive most of the bill.`,
+      action: 'Open them in the sessions table to see where each one grew.',
+      usd: round2(top10),
+    })
+  }
+
+  let longCost = 0
+  let longRead = 0
+  let longCalls = 0
+  for (const [label, v] of a.buckets) {
+    if (!LONG.includes(label)) continue
+    longCost += v.usd
+    longRead += v.readUsd
+    longCalls += v.calls
+  }
+  const longShare = pct(longCost, total.cost)
+  if (longShare >= 20) {
+    out.push({
+      id: 'long-context',
+      value: `${longShare.toFixed(0)}%`,
+      title: `Replies past 150k context made ${longShare.toFixed(0)}% of your usage`,
+      text: `${longCalls.toLocaleString('en-US')} replies, each re-reading at least 150k tokens of history; ${pct(longRead, longCost).toFixed(0)}% of what they cost was that re-reading.`,
+      action: 'Start a fresh session for each new task, so every reply re-reads less.',
+      usd: round2(longCost),
+    })
+  }
+
+  if (total.compact.n >= 3) {
+    const avg = tokens(total.compact.ctx / total.compact.n)
+    out.push({
+      id: 'compaction',
+      value: avg,
+      title: `Your context was compacted or cleared ${total.compact.n} times, at ${avg} on average`,
+      text: 'Every reply before that point re-read the whole context, so the longer it grows before a compaction, the more each reply costs.',
+      action: freshAction(tools.length ? tools : ['claude']),
+      usd: null,
+    })
+  }
+
+  const rb = total.rebuilds
+  const reasons = /** @type {const} */ (['cold', 'model', 'prefix'])
+  const [worst] = [...reasons].sort((x, y) => rb[y].cost - rb[x].cost)
+  const lostShare = pct(total.rebuildCost, total.cost)
+  if (lostShare >= 1 && rb[worst].n) {
+    out.push({
+      id: 'cache-lost',
+      value: usd(total.rebuildCost),
+      title: `Losing the cache cost ${usd(total.rebuildCost)}, ${lostShare.toFixed(1)}% of your usage`,
+      text: `The whole history was written again ${rb.cold.n + rb.model.n + rb.prefix.n} times, ${LOST[worst].why(rb[worst].n)}.`,
+      action: LOST[worst].action,
+      usd: round2(total.rebuildCost),
+    })
+  }
+
+  return out.sort((x, y) => (y.usd ?? 0) - (x.usd ?? 0))
+}

package/src/format.js

@@ -0,0 +1,23 @@
+// @ts-check
+// Small number helpers shared by the analysis and the outputs.
+
+/** a as a percentage of b, or 0 when b is 0. */
+export const pct = (/** @type {number} */ a, /** @type {number} */ b) => (b ? (100 * a) / b : 0)
+export const round1 = (/** @type {number} */ v) => Math.round(v * 10) / 10
+export const round2 = (/** @type {number} */ v) => Math.round(v * 100) / 100
+
+/** A count in the en-US style: 10,551. */
+export const int = (/** @type {number} */ n) => n.toLocaleString('en-US')
+
+/** US dollars: $2.40, or $1,250 from $100 up. */
+export const usd = (/** @type {number} */ v) => `$${v >= 100 ? int(Math.round(v)) : v.toFixed(2)}`
+
+/** Tokens: 950, 176k, 1.2M. */
+export const tokens = (/** @type {number} */ n) =>
+  n >= 1e6 ? `${(n / 1e6).toFixed(1)}M` : n >= 1e3 ? `${Math.round(n / 1e3)}k` : String(Math.round(n))
+
+/** The local calendar day of a time, as YYYY-MM-DD. */
+export function dayOf(/** @type {number} */ ts) {
+  const d = new Date(ts)
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`
+}

package/src/meta.js

@@ -0,0 +1,10 @@
+// @ts-check
+import { readFileSync } from 'node:fs'
+
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+
+/** The version in package.json, the only place it is written. */
+export const VERSION = /** @type {string} */ (pkg.version)
+
+/** Where ReRead lives, for links in the outputs. */
+export const HOMEPAGE = 'https://github.com/tecyfyai/reread'

package/src/prices.js

@@ -0,0 +1,172 @@
+// @ts-check
+// What each kind of token costs on the API, used only to weigh token kinds against each other the way the API bill
+// does. ReRead never sends anything anywhere; these numbers are a fixed table.
+//
+// Sources (read 2026-10-19; to update, change the rows, the date here and CHANGELOG.md, then run `npm test`):
+//   Anthropic: https://platform.claude.com/docs/en/about-claude/pricing
+//   OpenAI:    https://developers.openai.com/api/docs/pricing
+//   Google:    https://ai.google.dev/gemini-api/docs/pricing
+
+/**
+ * US dollars per million tokens: [input, cache write, cache read, output], optionally followed by the rates that apply
+ * once the context passes a size: [above, input, cache write, cache read, output]. Anthropic's 1-hour cache write
+ * costs 2 times input, so it is not listed. Where a maker has no cache-write price, a write costs input; where a model
+ * has no cache, a read costs input.
+ * @typedef {[number, number, number, number]} Rates
+ * @type {Record<string, Rates | [number, number, number, number, [number, number, number, number, number]]>}
+ */
+export const PRICES = {
+  // Anthropic
+  'claude-fable-5-1': [10, 12.5, 0.25, 50],
+  'claude-mythos-5-1': [10, 12.5, 0.25, 50],
+  'claude-fable-5': [10, 12.5, 1, 50],
+  'claude-mythos-5': [10, 12.5, 1, 50],
+  'claude-opus-5-5': [4, 5, 0.2, 20],
+  'claude-opus-5': [5, 6.25, 0.5, 25],
+  'claude-opus-4-8': [5, 6.25, 0.5, 25],
+  'claude-opus-4-7': [5, 6.25, 0.5, 25],
+  'claude-opus-4-6': [5, 6.25, 0.5, 25],
+  'claude-opus-4-5': [5, 6.25, 0.5, 25],
+  'claude-opus-4-1': [15, 18.75, 1.5, 75],
+  'claude-opus-4': [15, 18.75, 1.5, 75],
+  'claude-sonnet-5-5': [2, 2.5, 0.1, 10],
+  'claude-sonnet-5': [2, 2.5, 0.2, 10],
+  'claude-sonnet-4-6': [3, 3.75, 0.3, 15],
+  'claude-sonnet-4-5': [3, 3.75, 0.3, 15],
+  'claude-sonnet-4': [3, 3.75, 0.3, 15],
+  'claude-haiku-5-5': [0.1, 0.125, 0.01, 0.5, [100e3, 0.5, 0.625, 0.05, 2.5]],
+  'claude-haiku-4-5': [1, 1.25, 0.1, 5],
+  'claude-haiku-3-5': [0.8, 1, 0.08, 4],
+  // OpenAI
+  'gpt-6-astra': [10, 12.5, 1, 50, [272e3, 20, 25, 2, 75]],
+  'gpt-6.1-sol': [2, 2.5, 0.1, 10, [272e3, 4, 5, 0.2, 15]],
+  'gpt-6-sol': [2, 2.5, 0.2, 10, [272e3, 4, 5, 0.4, 15]],
+  'gpt-6-luna': [0.1, 0.125, 0.01, 0.5, [272e3, 0.2, 0.25, 0.02, 0.75]],
+  'gpt-5.6-sol': [4, 5, 0.4, 20, [272e3, 8, 10, 0.8, 30]],
+  'gpt-5.6-terra': [2, 2.5, 0.2, 12, [272e3, 4, 5, 0.4, 18]],
+  'gpt-5.6-luna': [0.2, 0.25, 0.02, 1.2, [272e3, 0.4, 0.5, 0.04, 1.8]],
+  'gpt-5.5': [5, 5, 0.5, 30, [272e3, 10, 10, 1, 45]],
+  'gpt-5.5-pro': [30, 30, 30, 180, [272e3, 60, 60, 60, 270]],
+  'gpt-5.4': [2.5, 2.5, 0.25, 15, [272e3, 5, 5, 0.5, 22.5]],
+  'gpt-5.4-mini': [0.75, 0.75, 0.075, 4.5],
+  'gpt-5.4-nano': [0.2, 0.2, 0.02, 1.25],
+  'gpt-5.4-pro': [30, 30, 30, 180, [272e3, 60, 60, 60, 270]],
+  'gpt-5.2': [1.75, 1.75, 0.175, 14],
+  'gpt-5.2-pro': [21, 21, 21, 168],
+  'gpt-5.1': [1.25, 1.25, 0.125, 10],
+  'gpt-5': [1.25, 1.25, 0.125, 10],
+  'gpt-5-mini': [0.25, 0.25, 0.025, 2],
+  'gpt-5-nano': [0.05, 0.05, 0.005, 0.4],
+  'gpt-5-pro': [15, 15, 15, 120],
+  'gpt-4.1': [2, 2, 0.5, 8],
+  'gpt-4.1-mini': [0.4, 0.4, 0.1, 1.6],
+  'gpt-4.1-nano': [0.1, 0.1, 0.025, 0.4],
+  'gpt-4o': [2.5, 2.5, 1.25, 10],
+  'gpt-4o-mini': [0.15, 0.15, 0.075, 0.6],
+  o3: [2, 2, 0.5, 8],
+  'o4-mini': [1.1, 1.1, 0.275, 4.4],
+  // Google (Gemini caches on its own, with no write price)
+  'gemini-4-argon': [2, 2, 0.1, 10],
+  'gemini-3.8-flash': [0.75, 0.75, 0.075, 3.75],
+  'gemini-3.6-flash': [0.75, 0.75, 0.075, 3.75],
+  'gemini-3.5-flash-lite': [0.3, 0.3, 0.03, 2.5],
+  'gemini-3.1-pro-preview': [2, 2, 0.2, 12, [200e3, 4, 4, 0.4, 18]],
+  'gemini-3.1-flash-lite': [0.25, 0.25, 0.025, 1.5],
+  'gemini-3-flash-preview': [0.5, 0.5, 0.05, 3],
+  'gemini-2.5-pro': [1.25, 1.25, 0.125, 10, [200e3, 2.5, 2.5, 0.25, 15]],
+  'gemini-2.5-flash': [0.3, 0.3, 0.03, 2.5],
+  'gemini-2.5-flash-lite': [0.1, 0.1, 0.01, 0.4],
+}
+
+/** For a model id ReRead does not know: the newest model of the family its name names, else FALLBACK_MODEL. */
+const FAMILIES = /** @type {const} */ ([
+  [/fable/, 'claude-fable-5-1'],
+  [/mythos/, 'claude-mythos-5-1'],
+  [/opus/, 'claude-opus-5-5'],
+  [/sonnet/, 'claude-sonnet-5-5'],
+  [/haiku/, 'claude-haiku-5-5'],
+  [/^gpt-.*astra/, 'gpt-6-astra'],
+  [/^gpt-.*luna/, 'gpt-6-luna'],
+  [/^gpt-.*terra/, 'gpt-5.6-terra'],
+  [/^(gpt-|o\d|codex)/, 'gpt-6.1-sol'],
+  [/^gemini-.*flash-lite/, 'gemini-3.5-flash-lite'],
+  [/^gemini-.*flash/, 'gemini-3.8-flash'],
+  [/^gemini-.*pro/, 'gemini-3.1-pro-preview'],
+  [/^gemini/, 'gemini-4-argon'],
+])
+export const FALLBACK_MODEL = 'claude-opus-5-5'
+
+// Longest first, so 'gpt-5.4-mini' is tried before 'gpt-5.4'.
+const IDS = Object.keys(PRICES).sort((a, b) => b.length - a.length)
+
+/**
+ * Whether a model id is a known id, or one with a suffix: a date ('claude-opus-4-1-20250805') or a variant
+ * ('gpt-5.1-codex-max'). A newer version is not a suffix: 'claude-opus-4-9' is not 'claude-opus-4', and 'gpt-5.6-x' is
+ * not 'gpt-5'.
+ * @param {string} model
+ * @param {string} id
+ */
+function isOf(model, id) {
+  if (model === id) return true
+  if (!model.startsWith(`${id}-`)) return false
+  const rest = model.slice(id.length + 1)
+  return /^\d{8}(\b|$)/.test(rest) || /^[a-z]/i.test(rest)
+}
+
+/**
+ * @typedef {{ input: number, write5m: number, write1h: number, read: number, output: number }} Price
+ * @typedef {object} Call  One model response: its token counts by kind.
+ * @property {string} key    unique id, to count it once
+ * @property {number} ts     time, ms since 1970
+ * @property {string} model
+ * @property {number} input  new input, not read from the cache and not written to it
+ * @property {number} cw5    tokens written to the cache (Anthropic's 5-minute cache, or OpenAI's)
+ * @property {number} cw1    tokens written to Anthropic's 1-hour cache
+ * @property {number} read   tokens read from the cache
+ * @property {number} out    output, reasoning included
+ * @property {boolean} [seen]  counted already in an earlier file
+ */
+
+/** @type {Map<string, { base: Price, long?: { above: number, price: Price } }>} */
+const cache = new Map()
+
+/** @param {number[]} r */
+const priceFrom = ([input, write5m, read, output]) => ({ input, write5m, write1h: input * 2, read, output })
+
+/**
+ * The price of a model id for a reply with a given context size. An unknown id is priced as the newest model of its
+ * family, or as FALLBACK_MODEL.
+ * @param {string} [model]
+ * @param {number} [context]  the reply's context in tokens, for prices that rise past a size
+ * @returns {Price}
+ */
+export function priceOf(model = '', context = 0) {
+  let entry = cache.get(model)
+  if (!entry) {
+    const id =
+      IDS.find((k) => isOf(model, k)) ?? FAMILIES.find(([re]) => re.test(model.toLowerCase()))?.[1] ?? FALLBACK_MODEL
+    const row = PRICES[id]
+    const long = row[4]
+    entry = {
+      base: priceFrom(/** @type {number[]} */ (row.slice(0, 4))),
+      long: long ? { above: long[0], price: priceFrom(long.slice(1)) } : undefined,
+    }
+    cache.set(model, entry)
+  }
+  return entry.long && context > entry.long.above ? entry.long.price : entry.base
+}
+
+/**
+ * The tokens a reply sent: new input, cache writes and cache reads.
+ * @param {Call} c
+ */
+export const contextOf = (c) => c.input + c.cw5 + c.cw1 + c.read
+
+/**
+ * What a reply would cost on the API, in US dollars.
+ * @param {Call} c
+ */
+export function costOf(c) {
+  const p = priceOf(c.model, contextOf(c))
+  return (c.input * p.input + c.cw5 * p.write5m + c.cw1 * p.write1h + c.read * p.read + c.out * p.output) / 1e6
+}

package/src/render.js

@@ -0,0 +1,213 @@
+// @ts-check
+// The terminal summary, the Markdown summary and the CSV. Each returns a string; the CLI prints it.
+import { REASONS } from './analyze.js'
+import { int, pct, tokens, usd } from './format.js'
+import { HOMEPAGE, VERSION } from './meta.js'
+
+/** @typedef {import('./analyze.js').Report} Report */
+
+/**
+ * A count and its noun: '1 session', '12 sessions'.
+ * @param {number} n
+ * @param {string} one
+ * @param {string} [many]
+ */
+const plural = (n, one, many = `${one}s`) => `${int(n)} ${n === 1 ? one : many}`
+
+const NOTE = 'Plans count usage in their own way; the shares weigh each kind of token by its API price.'
+
+const REASON_TEXT = {
+  cold: 'Cache went cold (a break longer than its life)',
+  model: 'Model changed mid-session',
+  prefix: 'Something early in the context changed',
+}
+
+/**
+ * The summary for the terminal.
+ * @param {Report} data
+ * @param {{ top: number, by: '' | 'project' | 'model' | 'day' | 'tool', color: boolean }} opts
+ */
+export function renderText(data, { top, by, color }) {
+  const paint = (/** @type {number} */ code) => (/** @type {unknown} */ t) =>
+    color ? `\x1b[${code}m${t}\x1b[0m` : String(t)
+  const bold = paint(1)
+  const dim = paint(2)
+  const yellow = paint(33)
+  const cyan = paint(36)
+  const pad = (/** @type {unknown} */ t, /** @type {number} */ n) => String(t).padEnd(n)
+  const lpad = (/** @type {unknown} */ t, /** @type {number} */ n) => String(t).padStart(n)
+  const S = data.summary
+
+  const out = [
+    '',
+    `  ${bold(yellow(`${S.rereadShare.toFixed(0)}%`))} ${bold(`of your ${data.product} usage was re-reading context`)}`,
+    dim(
+      `  ${data.span} · ${plural(S.sessions, 'session')} · ${plural(S.calls, 'reply', 'replies')} · ${usd(S.apiEquivalentUSD)} at API prices`,
+    ),
+    '',
+    `  ${pad('Reading history from the cache', 34)}${lpad(`${S.cacheReadShare.toFixed(1)}%`, 7)}  ${dim(`${S.tokensReadFromCache}% of all tokens read`)}`,
+    `  ${pad('Writing history again', 34)}${lpad(`${S.rebuildShare.toFixed(1)}%`, 7)}  ${dim('after the cache was lost')}`,
+    `  ${pad('Everything else', 34)}${lpad(`${S.otherShare.toFixed(1)}%`, 7)}  ${dim('new input, first cache writes, output')}`,
+    '',
+  ]
+
+  const reasons = REASONS.filter((w) => S.rebuilds[w].count)
+  if (reasons.length) {
+    out.push(bold('  Times the whole history was written again'))
+    for (const w of reasons) {
+      out.push(
+        `  ${pad(REASON_TEXT[w], 48)}${lpad(S.rebuilds[w].count, 5)}  ${dim(`${S.rebuilds[w].share}% of usage`)}`,
+      )
+    }
+    out.push('')
+  }
+
+  if (by) {
+    /** @type {[string, number, number, number][]} */
+    const rows =
+      by === 'project'
+        ? data.projects.map((p) => [p.project, p.calls, p.usd, p.rereadShare])
+        : by === 'model'
+          ? data.models.map((m) => [m.model, m.calls, m.usd, pct(m.readUsd + m.rebuildUsd, m.usd)])
+          : by === 'tool'
+            ? data.tools.map((t) => [t.name, t.calls, t.usd, t.rereadShare])
+            : data.daily
+                .filter((d) => d.calls)
+                .map((d) => [d.day, d.calls, d.usd, pct(d.readUsd + d.rebuildUsd, d.usd)])
+    out.push(bold(`  By ${by}`))
+    out.push(dim(`  ${pad(by, 30)}${lpad('replies', 9)}${lpad('cost', 10)}${lpad('re-read', 9)}`))
+    for (const [name, calls, cost, rr] of rows) {
+      out.push(
+        `  ${pad(name.slice(0, 28), 30)}${lpad(int(calls), 9)}${lpad(usd(cost), 10)}${lpad(`${rr.toFixed(0)}%`, 9)}`,
+      )
+    }
+    out.push('')
+  }
+
+  if (top > 0) {
+    out.push(bold('  Costliest sessions') + dim('  (API price of the same tokens)'))
+    out.push(
+      dim(
+        `  ${pad('started', 12)}${pad('project', 24)}${lpad('replies', 8)}${lpad('peak ctx', 10)}${lpad('cost', 10)}${lpad('re-read', 9)}`,
+      ),
+    )
+    for (const s of data.sessions.slice(0, top)) {
+      out.push(
+        `  ${pad(s.started.slice(0, 10), 12)}${pad((s.project || s.id).slice(0, 22), 24)}${lpad(s.calls, 8)}${lpad(tokens(s.peak), 10)}${lpad(usd(s.usd), 10)}${lpad(`${s.rereadShare.toFixed(0)}%`, 9)}`,
+      )
+    }
+    out.push('')
+  }
+
+  if (data.findings.length) {
+    out.push(bold('  Key findings'))
+    for (const f of data.findings) out.push(`  · ${f.title}. ${dim(f.action)}`)
+    out.push('')
+  }
+
+  out.push(dim(`  ${NOTE}`), '', `  ${dim('Share it:')} ${cyan(data.share)}`, '')
+  return out.join('\n') + '\n'
+}
+
+/**
+ * A Markdown summary, to paste into an issue or a pull request.
+ * @param {Report} data
+ * @param {{ top: number }} opts
+ */
+export function renderMarkdown(data, { top }) {
+  const S = data.summary
+  const cell = (/** @type {unknown} */ t) => String(t).replace(/\|/g, '\\|')
+  const out = [
+    `## ${S.rereadShare.toFixed(0)}% of my ${data.product} usage was re-reading context`,
+    '',
+    `_${data.span} · ${plural(S.sessions, 'session')} · ${plural(S.calls, 'reply', 'replies')} · ${usd(S.apiEquivalentUSD)} at API prices · [ReRead](${HOMEPAGE}) ${VERSION}_`,
+    '',
+    '| Where the usage went | Share |',
+    '|---|---:|',
+    `| Reading history from the cache | ${S.cacheReadShare.toFixed(1)}% |`,
+    `| Writing history again, after the cache was lost | ${S.rebuildShare.toFixed(1)}% |`,
+    `| Everything else (new input, first cache writes, output) | ${S.otherShare.toFixed(1)}% |`,
+    '',
+  ]
+  const reasons = REASONS.filter((w) => S.rebuilds[w].count)
+  if (reasons.length) {
+    out.push(
+      '| Why the history was written again | Times | Share |',
+      '|---|---:|---:|',
+      ...reasons.map((w) => `| ${REASON_TEXT[w]} | ${S.rebuilds[w].count} | ${S.rebuilds[w].share}% |`),
+      '',
+    )
+  }
+  if (top > 0) {
+    out.push(
+      '| Costliest sessions | Project | Replies | Peak context | API price | Re-read |',
+      '|---|---|---:|---:|---:|---:|',
+      ...data.sessions
+        .slice(0, top)
+        .map(
+          (s) =>
+            `| ${s.started.slice(0, 10)} \`${s.id}\` | ${cell(s.project)} | ${s.calls} | ${tokens(s.peak)} | ${usd(s.usd)} | ${s.rereadShare.toFixed(0)}% |`,
+        ),
+      '',
+    )
+  }
+  if (data.findings.length) {
+    out.push('### Key findings', '', ...data.findings.map((f) => `- **${f.title}.** ${f.text} ${f.action}`), '')
+  }
+  out.push(`_${NOTE}_`)
+  return out.join('\n') + '\n'
+}
+
+/**
+ * One CSV cell. A value that starts like a formula gets a leading ' so a spreadsheet app shows it as text.
+ * @param {unknown} v
+ */
+export function csvCell(v) {
+  let t = String(v)
+  if (/^[=+\-@\t\r]/.test(t)) t = `'${t}`
+  return /[",\n\r]/.test(t) ? `"${t.replace(/"/g, '""')}"` : t
+}
+
+/** The CSV header, shared with the report's own CSV export. */
+export const CSV_HEADER = [
+  'session',
+  'tool',
+  'project',
+  'branch',
+  'started',
+  'ended',
+  'replies',
+  'peak_context',
+  'api_usd',
+  'reread_pct',
+  'rebuilds_cold',
+  'rebuilds_model',
+  'rebuilds_prefix',
+]
+
+/**
+ * Every session as CSV.
+ * @param {Report} data
+ */
+export function renderCsv(data) {
+  const rows = data.sessions.map((s) =>
+    [
+      s.id,
+      s.tool,
+      s.project,
+      s.branch,
+      s.started,
+      s.ended,
+      s.calls,
+      s.peak,
+      s.usd,
+      s.rereadShare,
+      s.rebuilds.cold,
+      s.rebuilds.model,
+      s.rebuilds.prefix,
+    ]
+      .map(csvCell)
+      .join(','),
+  )
+  return [CSV_HEADER.join(','), ...rows].join('\n') + '\n'
+}