codex-work-receipt 0.7.3 → 0.8.0

package/src/core/presentation.mjs

@@ -85,6 +85,15 @@ const RECEIPT_COPY = {
     exportSuccess: "图片已保存",
     exportError: "图片生成失败，请重试",
     receiptAria: "Codex AI 打工小票",
+    sidebar: {
+      aria: "相关信息",
+      supportTitle: "支持项目",
+      supportDescription: "喜欢这个工具？",
+      changelogTitle: "更新日志",
+      changelogLink: "查看更新日志 →",
+      sponsorLabel: "赞助伙伴",
+      sponsorAlt: "ModelFlare 标志",
+    },
     themes: {
       classic: "经典白票",
       diner: "复古粉票",
@@ -127,28 +136,37 @@ const RECEIPT_COPY = {
       seconds: ["秒", "秒"],
     },
     footerThanks: "谢谢惠顾，欢迎明天继续改需求",
-    transferAria: "传到手机导入联",
-    transferTitle: "传到手机 · LOCAL TRANSFER",
-    transferDescription: "主小票保持完整，这一联只负责打开小程序和搬运数据",
-    openMiniProgram: "1 · 打开小程序",
+    transferAria: "微信小程序导入联",
+    transferTitle: "导入到微信小程序",
+    transferDescription: "下载脱敏数据文件，通过微信聊天文件导入",
+    openMiniProgram: "打开小程序",
     openMiniProgramHint: "微信扫码进入 AI 打工图鉴",
-    importData: "2 · 扫描导入数据",
-    importDataHint: "在小程序里点击“从电脑导入”后扫描",
-    multipartOpenTitle: "先打开小程序",
-    multipartOpenHint: "数据码将在 {seconds} 秒后自动开始轮播，无需点击电脑",
-    multipartTransferTitle: "保持手机对准屏幕",
-    multipartTransferHint: "数据码会自动逐张轮播；漏扫或重复都没关系",
-    multipartPartLabel: "数据分片 {current}/{total}",
-    multipartRestart: "重新显示小程序码",
+    fileImportTitle: "从聊天文件导入",
+    fileImportSteps: [
+      "下载微信导入文件",
+      "把文件发送到“文件传输助手”或自己的聊天",
+      "在小程序中点击“从聊天文件导入”并选择该文件",
+    ],
+    downloadFile: "下载微信导入文件",
+    downloadFileHint: "下载后发送到文件传输助手",
+    downloadSuccess: "文件已下载，请发送到微信文件传输助手",
+    downloadError: "文件下载失败，请重试",
+    fileImportPrivacy: "文件只包含脱敏统计。发送到聊天前，请确认接收方可信。",
+    scanAlternativeTitle: "也可以扫码导入",
+    scanAlternativeHint: "这份数据可以由一个二维码完整承载",
+    showDataQr: "显示数据二维码",
+    showMiniProgramCode: "返回小程序码",
+    dataQrTitle: "扫描导入数据",
+    dataQrHint: "在小程序中选择扫码导入后扫描",
     dataQrAlt: "当前小票数据二维码",
     miniProgramAlt: "微信小程序码",
     exportMiniProgramLabel: "微信扫码打开小程序",
     placeholderLabel: "小程序码",
     placeholderValue: "待接入",
     placeholderAria: "小程序码待接入",
-    transferNote: "数据码只包含时间、轮次、Token和工具调用等统计，不包含Prompt、回复正文、代码、项目路径或文件名。",
+    transferNote: "导入文件和可选数据码只包含时间、轮次、Token 和工具调用等统计，不包含 Prompt、回复正文、代码、项目路径或文件名。",
     rollingSummaryNotice: "最近 {hours} 小时属于滚动摘要，只保存到私人历史，不参与 AI 供销社统计。需要统计时请生成“今日 / 本周 / 近 7 日 / 指定会话”小票。",
-    privacy: "结构数据同时保存在本机，未来可以批量导入小程序历史记录。",
+    privacy: "结构数据和微信导入文件同时保存在本机；只有你主动发送文件或扫码时，脱敏统计才会离开电脑。",
   },
   en: {
     htmlLang: "en",
@@ -160,6 +178,15 @@ const RECEIPT_COPY = {
     exportSuccess: "Image saved",
     exportError: "Could not generate the image. Please try again.",
     receiptAria: "Codex AI Work Receipt",
+    sidebar: {
+      aria: "Related information",
+      supportTitle: "Support the project",
+      supportDescription: "Enjoying this tool?",
+      changelogTitle: "Changelog",
+      changelogLink: "View the changelog →",
+      sponsorLabel: "Sponsored by",
+      sponsorAlt: "ModelFlare logo",
+    },
     themes: {
       classic: "Classic White",
       diner: "Vintage Pink",
@@ -202,28 +229,37 @@ const RECEIPT_COPY = {
       seconds: ["sec", "sec"],
     },
     footerThanks: "Thanks for your business. More revisions welcome tomorrow.",
-    transferAria: "Mobile transfer stub",
-    transferTitle: "TO YOUR PHONE · LOCAL TRANSFER",
-    transferDescription: "The main receipt stays intact. This stub only opens the mini program and transfers data.",
-    openMiniProgram: "1 · Open mini program",
+    transferAria: "WeChat mini-program import stub",
+    transferTitle: "IMPORT INTO WECHAT",
+    transferDescription: "Download the privacy-safe data file and import it from a WeChat chat.",
+    openMiniProgram: "Open mini program",
     openMiniProgramHint: "Scan with WeChat to open AI Work Archive",
-    importData: "2 · Import receipt data",
-    importDataHint: "Tap “从电脑导入小票” in the mini program, then scan this code",
-    multipartOpenTitle: "Open the mini program first",
-    multipartOpenHint: "The data codes will start rotating automatically in {seconds}s. No desktop click is required.",
-    multipartTransferTitle: "Keep your phone pointed at the screen",
-    multipartTransferHint: "Data codes rotate automatically. Missed or duplicate scans are safe.",
-    multipartPartLabel: "Data part {current}/{total}",
-    multipartRestart: "Show mini-program code again",
+    fileImportTitle: "Import from a chat file",
+    fileImportSteps: [
+      "Download the WeChat import file",
+      "Send it to File Transfer or one of your own chats",
+      "Tap “Import from chat file” in the mini program and select it",
+    ],
+    downloadFile: "Download WeChat import file",
+    downloadFileHint: "Then send it to WeChat File Transfer",
+    downloadSuccess: "File downloaded. Send it to WeChat File Transfer.",
+    downloadError: "Could not download the file. Please try again.",
+    fileImportPrivacy: "The file contains privacy-safe metrics only. Send it only to a chat you trust.",
+    scanAlternativeTitle: "Or import by scanning",
+    scanAlternativeHint: "This receipt fits completely in one data QR code.",
+    showDataQr: "Show data QR code",
+    showMiniProgramCode: "Back to mini-program code",
+    dataQrTitle: "Scan to import data",
+    dataQrHint: "Choose scan import in the mini program, then scan this code",
     dataQrAlt: "Current receipt data QR code",
     miniProgramAlt: "WeChat mini-program code",
     exportMiniProgramLabel: "Scan to open the mini program",
     placeholderLabel: "Mini program",
     placeholderValue: "Pending",
     placeholderAria: "Mini-program code pending",
-    transferNote: "The data code contains only statistics such as time, turns, Tokens, and tool calls. It does not contain prompts, responses, code, project paths, or file names.",
+    transferNote: "The import file and optional data code contain only statistics such as time, turns, Tokens, and tool calls. They do not contain prompts, responses, code, project paths, or file names.",
     rollingSummaryNotice: "The last {hours} hours is a rolling summary for private history only. It does not participate in AI Work Cooperative accounting. Use today, this week, the last seven days, or a specific session for accountable facts.",
-    privacy: "Structured data is also stored locally for future batch import into your mini-program history.",
+    privacy: "Structured data and the WeChat import file stay on this computer until you explicitly send the file or scan its data code.",
   },
 };
 

package/src/core/qr-payload.mjs

@@ -2,7 +2,9 @@ import crypto from "node:crypto";
 import zlib from "node:zlib";
 import QRCode from "qrcode";
 
-import { buildCompensation, getWorkProfileCopy } from "./presentation.mjs";
+import { compactReceipt } from "./transfer-record.mjs";
+
+export { compactReceipt } from "./transfer-record.mjs";
 
 const MAX_QR_VERSION = 25;
 const MAX_MULTIPART_PARTS = 12;
@@ -11,142 +13,6 @@ function checksum(value, length = 8) {
   return crypto.createHash("sha256").update(value).digest("hex").slice(0, length);
 }
 
-function compactPresentation(record) {
-  const profileId = record.presentation.work_profile;
-  const scope = record.source?.scope || (record.presentation.compensation?.label === "本日工资" ? "today" : "latest");
-  const mobileProfile = profileId
-    ? getWorkProfileCopy(profileId, "zh-CN")
-    : { title: record.presentation.work_title, review: record.presentation.review };
-  const mobileCompensation = profileId
-    ? buildCompensation(scope, record.presentation.compensation?.amount, "zh-CN")
-    : record.presentation.compensation;
-
-  return {
-    profileId,
-    scope,
-    mobileProfile,
-    mobileCompensation,
-  };
-}
-
-function compactBase(record) {
-  const presentation = compactPresentation(record);
-  return {
-    v: record.schema_version,
-    i: record.id,
-    g: record.generated_at,
-    o: presentation.scope,
-    d: [
-      record.period.start_at,
-      record.period.end_at,
-      record.period.timezone,
-      record.period.range_start_date || null,
-      record.period.range_end_date || null,
-    ],
-    s: [
-      record.stats.session_count,
-      record.stats.completed_turns,
-      record.stats.user_messages,
-      record.stats.tool_calls,
-      record.stats.interruptions,
-      record.stats.work_duration_ms,
-      record.stats.average_first_token_ms,
-    ],
-    t: [
-      record.stats.tokens.input_tokens,
-      record.stats.tokens.cached_input_tokens,
-      record.stats.tokens.output_tokens,
-      record.stats.tokens.reasoning_output_tokens,
-      record.stats.tokens.total_tokens,
-    ],
-    m: record.stats.models,
-    l: record.locale || "zh-CN",
-    r: presentation.profileId || null,
-    p: [
-      record.presentation.default_theme,
-      presentation.mobileProfile.title,
-      presentation.mobileProfile.review,
-      presentation.mobileCompensation
-        ? [
-            presentation.mobileCompensation.label,
-            presentation.mobileCompensation.amount,
-            presentation.mobileCompensation.unit,
-            presentation.mobileCompensation.note,
-            presentation.mobileCompensation.formula_version,
-          ]
-        : null,
-    ],
-  };
-}
-
-function compactFact(fact) {
-  const stats = fact.stats;
-  return [
-    fact.fact_id,
-    fact.session_id,
-    fact.identity_quality,
-    fact.source_type,
-    fact.local_date,
-    fact.bucket_start_at,
-    fact.bucket_end_at,
-    fact.source_watermark_at,
-    fact.observed_at,
-    [
-      fact.source_revision.kind,
-      fact.source_revision.row_count,
-      fact.source_revision.byte_length,
-      fact.source_revision.tail_hash,
-    ],
-    fact.content_hash,
-    [
-      stats.completed_turns,
-      stats.user_messages,
-      stats.tool_calls,
-      stats.interruptions,
-      stats.work_duration_ms,
-      stats.first_token_total_ms,
-      stats.first_token_sample_count,
-      stats.input_tokens,
-      stats.cached_input_tokens,
-      stats.output_tokens,
-      stats.reasoning_output_tokens,
-      stats.total_tokens,
-      stats.token_reset_count,
-      stats.models,
-    ],
-  ];
-}
-
-export function compactReceipt(record) {
-  const compact = compactBase(record);
-  if (record.schema_version !== 2) return compact;
-
-  const coverage = record.manifest.coverage;
-  return {
-    ...compact,
-    k: record.source.logical_key,
-    h: record.source.snapshot_hash,
-    a: [
-      record.manifest.version,
-      record.manifest.fact_schema_version,
-      record.manifest.metric_schema_version,
-      record.manifest.accounting_timezone,
-      record.manifest.fact_count,
-      record.manifest.fact_ids,
-      [
-        coverage.kind,
-        coverage.scan_mode,
-        coverage.start_date || null,
-        coverage.end_date || null,
-        coverage.complete_through_date || null,
-        coverage.observed_through_at,
-      ],
-      record.manifest.manifest_hash,
-    ],
-    f: record.facts.map(compactFact),
-  };
-}
-
 function encodeCompact(prefix, compact) {
   const compressed = zlib.deflateRawSync(Buffer.from(JSON.stringify(compact), "utf8"));
   return `${prefix}.${checksum(compressed)}.${compressed.toString("base64url")}`;
@@ -168,48 +34,11 @@ function fitsVersion(payload, maxVersion) {
   }
 }
 
-function multipartPayload(transferId, partIndex, partCount, totalChecksum, chunk) {
-  return `cwr2p.${transferId}.${partIndex}.${partCount}.${totalChecksum}.${checksum(chunk)}.${chunk}`;
-}
-
-function maxChunkSize(singlePayload, maxVersion) {
-  const transferId = checksum(singlePayload, 12);
-  const totalChecksum = checksum(singlePayload);
-  let low = 32;
-  let high = singlePayload.length;
-
-  while (low < high) {
-    const middle = Math.ceil((low + high) / 2);
-    const candidate = multipartPayload(transferId, 12, 12, totalChecksum, singlePayload.slice(0, middle));
-    if (fitsVersion(candidate, maxVersion)) low = middle;
-    else high = middle - 1;
-  }
-  return low;
-}
-
-export function encodeReceiptPayloads(record, options = {}) {
+export function encodeSingleReceiptQr(record, options = {}) {
   const maxVersion = options.maxVersion || MAX_QR_VERSION;
-  const maxParts = options.maxParts || MAX_MULTIPART_PARTS;
-  const singlePayload = encodeReceiptPayload(record);
-  if (fitsVersion(singlePayload, maxVersion)) return [singlePayload];
-  if (!singlePayload.startsWith("cwr2.")) {
-    throw new Error("旧版小票数据超过单个二维码容量");
-  }
-
-  const chunkSize = maxChunkSize(singlePayload, maxVersion);
-  const chunks = [];
-  for (let offset = 0; offset < singlePayload.length; offset += chunkSize) {
-    chunks.push(singlePayload.slice(offset, offset + chunkSize));
-  }
-  if (chunks.length > maxParts) {
-    throw new Error(`小票数据需要 ${chunks.length} 个二维码，超过 ${maxParts} 个上限，请缩小统计范围`);
-  }
-
-  const transferId = checksum(singlePayload, 12);
-  const totalChecksum = checksum(singlePayload);
-  return chunks.map((chunk, index) => (
-    multipartPayload(transferId, index + 1, chunks.length, totalChecksum, chunk)
-  ));
+  const payload = encodeReceiptPayload(record);
+  if (!fitsVersion(payload, maxVersion)) return null;
+  return { payload, version: qrVersion(payload) };
 }
 
 function decodeSinglePayload(payload) {

package/src/core/receipt-record.mjs

@@ -14,6 +14,8 @@ import {
   DEFAULT_LOCALE,
   getWorkProfileCopy,
 } from "./presentation.mjs";
+import { createReceiptFile } from "./file-payload.mjs";
+import { writeFileAtomicSync, writeWithAtomicFileSync } from "../lib/files.mjs";
 
 const SCHEMA_VERSION = 2;
 const SOURCE_VERSION = "cwr2";
@@ -127,7 +129,13 @@ export function buildReceiptRecord(metrics, defaultTheme = "classic", locale = D
   return record;
 }
 
-export function persistReceiptRecord(record, outputHtmlPath, requestedDataDir = null) {
+export function transferFilePathForOutput(outputHtmlPath) {
+  return /\.html?$/i.test(outputHtmlPath)
+    ? outputHtmlPath.replace(/\.html?$/i, ".cwr.json")
+    : `${outputHtmlPath}.cwr.json`;
+}
+
+export function persistReceiptRecord(record, outputHtmlPath, requestedDataDir = null, requestedTransferFile = null) {
   const dataDir = path.resolve(
     requestedDataDir || process.env.CODEX_WORK_RECEIPT_HOME || path.join(os.homedir(), ".codex-work-receipt"),
   );
@@ -135,8 +143,8 @@ export function persistReceiptRecord(record, outputHtmlPath, requestedDataDir =
   fs.mkdirSync(receiptsDir, { recursive: true });
 
   const receiptPath = path.join(receiptsDir, `${record.id}.json`);
-  fs.writeFileSync(receiptPath, `${JSON.stringify(record, null, 2)}\n`, "utf8");
-  fs.writeFileSync(path.join(dataDir, "latest.json"), `${JSON.stringify(record, null, 2)}\n`, "utf8");
+  writeFileAtomicSync(receiptPath, `${JSON.stringify(record, null, 2)}\n`);
+  writeFileAtomicSync(path.join(dataDir, "latest.json"), `${JSON.stringify(record, null, 2)}\n`);
 
   const allRecords = fs.readdirSync(receiptsDir)
     .filter((name) => name.endsWith(".json"))
@@ -156,16 +164,16 @@ export function persistReceiptRecord(record, outputHtmlPath, requestedDataDir =
   const history = [...deduplicated.values()]
     .sort((left, right) => String(left.period?.end_at).localeCompare(String(right.period?.end_at)));
   const historyPath = path.join(dataDir, "history.jsonl");
-  const historyDescriptor = fs.openSync(historyPath, "w");
-  try {
+  writeWithAtomicFileSync(historyPath, (historyDescriptor) => {
     for (const item of history) fs.writeSync(historyDescriptor, `${JSON.stringify(item)}\n`, null, "utf8");
-  } finally {
-    fs.closeSync(historyDescriptor);
-  }
+  });
 
   const companionPath = /\.html?$/i.test(outputHtmlPath)
     ? outputHtmlPath.replace(/\.html?$/i, ".json")
     : `${outputHtmlPath}.json`;
-  fs.writeFileSync(companionPath, `${JSON.stringify(record, null, 2)}\n`, "utf8");
-  return { dataDir, receiptPath, companionPath };
+  writeFileAtomicSync(companionPath, `${JSON.stringify(record, null, 2)}\n`);
+  const transferFile = requestedTransferFile || createReceiptFile(record);
+  const transferPath = transferFilePathForOutput(outputHtmlPath);
+  writeFileAtomicSync(transferPath, transferFile.content);
+  return { dataDir, receiptPath, companionPath, transferPath };
 }

package/src/core/transfer-record.mjs

@@ -0,0 +1,137 @@
+import { buildCompensation, getWorkProfileCopy } from "./presentation.mjs";
+
+function compactPresentation(record) {
+  const profileId = record.presentation.work_profile;
+  const scope = record.source?.scope || (record.presentation.compensation?.label === "本日工资" ? "today" : "latest");
+  const mobileProfile = profileId
+    ? getWorkProfileCopy(profileId, "zh-CN")
+    : { title: record.presentation.work_title, review: record.presentation.review };
+  const mobileCompensation = profileId
+    ? buildCompensation(scope, record.presentation.compensation?.amount, "zh-CN")
+    : record.presentation.compensation;
+
+  return {
+    profileId,
+    scope,
+    mobileProfile,
+    mobileCompensation,
+  };
+}
+
+function compactBase(record) {
+  const presentation = compactPresentation(record);
+  return {
+    v: record.schema_version,
+    i: record.id,
+    g: record.generated_at,
+    o: presentation.scope,
+    d: [
+      record.period.start_at,
+      record.period.end_at,
+      record.period.timezone,
+      record.period.range_start_date || null,
+      record.period.range_end_date || null,
+    ],
+    s: [
+      record.stats.session_count,
+      record.stats.completed_turns,
+      record.stats.user_messages,
+      record.stats.tool_calls,
+      record.stats.interruptions,
+      record.stats.work_duration_ms,
+      record.stats.average_first_token_ms,
+    ],
+    t: [
+      record.stats.tokens.input_tokens,
+      record.stats.tokens.cached_input_tokens,
+      record.stats.tokens.output_tokens,
+      record.stats.tokens.reasoning_output_tokens,
+      record.stats.tokens.total_tokens,
+    ],
+    m: record.stats.models,
+    l: record.locale || "zh-CN",
+    r: presentation.profileId || null,
+    p: [
+      record.presentation.default_theme,
+      presentation.mobileProfile.title,
+      presentation.mobileProfile.review,
+      presentation.mobileCompensation
+        ? [
+            presentation.mobileCompensation.label,
+            presentation.mobileCompensation.amount,
+            presentation.mobileCompensation.unit,
+            presentation.mobileCompensation.note,
+            presentation.mobileCompensation.formula_version,
+          ]
+        : null,
+    ],
+  };
+}
+
+function compactFact(fact) {
+  const stats = fact.stats;
+  return [
+    fact.fact_id,
+    fact.session_id,
+    fact.identity_quality,
+    fact.source_type,
+    fact.local_date,
+    fact.bucket_start_at,
+    fact.bucket_end_at,
+    fact.source_watermark_at,
+    fact.observed_at,
+    [
+      fact.source_revision.kind,
+      fact.source_revision.row_count,
+      fact.source_revision.byte_length,
+      fact.source_revision.tail_hash,
+    ],
+    fact.content_hash,
+    [
+      stats.completed_turns,
+      stats.user_messages,
+      stats.tool_calls,
+      stats.interruptions,
+      stats.work_duration_ms,
+      stats.first_token_total_ms,
+      stats.first_token_sample_count,
+      stats.input_tokens,
+      stats.cached_input_tokens,
+      stats.output_tokens,
+      stats.reasoning_output_tokens,
+      stats.total_tokens,
+      stats.token_reset_count,
+      stats.models,
+    ],
+  ];
+}
+
+export function compactReceipt(record) {
+  const compact = compactBase(record);
+  if (record.schema_version !== 2) return compact;
+
+  const coverage = record.manifest.coverage;
+  return {
+    ...compact,
+    k: record.source.logical_key,
+    h: record.source.snapshot_hash,
+    a: [
+      record.manifest.version,
+      record.manifest.fact_schema_version,
+      record.manifest.metric_schema_version,
+      record.manifest.accounting_timezone,
+      record.manifest.fact_count,
+      record.manifest.fact_ids,
+      [
+        coverage.kind,
+        coverage.scan_mode,
+        coverage.start_date || null,
+        coverage.end_date || null,
+        coverage.complete_through_date || null,
+        coverage.observed_through_at,
+      ],
+      record.manifest.manifest_hash,
+    ],
+    f: record.facts.map(compactFact),
+  };
+}

package/src/lib/files.mjs

@@ -0,0 +1,52 @@
+import fs from "node:fs";
+import path from "node:path";
+
+function stagingPathFor(filePath) {
+  return path.join(
+    path.dirname(filePath),
+    `.${path.basename(filePath)}.write-${process.pid}-${Date.now()}`,
+  );
+}
+
+function replaceFile(stagingPath, filePath) {
+  try {
+    fs.renameSync(stagingPath, filePath);
+  } catch (error) {
+    if (process.platform !== "win32" || !fs.existsSync(filePath)) throw error;
+    fs.rmSync(filePath, { force: true });
+    fs.renameSync(stagingPath, filePath);
+  }
+}
+
+export function writeFileAtomicSync(filePath, content, encoding = "utf8") {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const stagingPath = stagingPathFor(filePath);
+  try {
+    fs.writeFileSync(stagingPath, content, encoding);
+    replaceFile(stagingPath, filePath);
+  } catch (error) {
+    fs.rmSync(stagingPath, { force: true });
+    throw error;
+  }
+}
+
+export function writeJsonAtomicSync(filePath, value) {
+  writeFileAtomicSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+export function writeWithAtomicFileSync(filePath, write) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const stagingPath = stagingPathFor(filePath);
+  let descriptor = null;
+  try {
+    descriptor = fs.openSync(stagingPath, "w");
+    write(descriptor);
+    fs.closeSync(descriptor);
+    descriptor = null;
+    replaceFile(stagingPath, filePath);
+  } catch (error) {
+    if (descriptor !== null) fs.closeSync(descriptor);
+    fs.rmSync(stagingPath, { force: true });
+    throw error;
+  }
+}

package/src/parsers/codex.mjs

@@ -220,8 +220,8 @@ function sessionFromFile(file) {
   };
 }
 
-function codexSessionFiles() {
-  const codexHome = process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
+function codexSessionFiles(requestedCodexHome = null) {
+  const codexHome = requestedCodexHome || process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
   const sessionsDirectory = path.join(codexHome, "sessions");
   const files = walkJsonlFiles(sessionsDirectory)
     .map((filePath) => {
@@ -275,8 +275,8 @@ export function deduplicateCodexSessions(sessions) {
   return [...selected.values()];
 }
 
-export function loadCodexSessions(range) {
-  const files = codexSessionFiles();
+export function loadCodexSessions(range, { codexHome = null } = {}) {
+  const files = codexSessionFiles(codexHome);
   let candidates = files;
   let scanMode = "none";
 
@@ -310,8 +310,8 @@ export function loadCodexSessions(range) {
   return sessions;
 }
 
-export function listRecentCodexSessions(limit = 10) {
-  const sessions = deduplicateCodexSessions(codexSessionFiles()
+export function listRecentCodexSessions(limit = 10, { codexHome = null } = {}) {
+  const sessions = deduplicateCodexSessions(codexSessionFiles(codexHome)
     .slice(0, Math.max(40, limit * 3))
     .map(sessionFromFile)
     .filter((session) => session.rows.length))