@liustack/modlens 2.2.0 → 2.3.1

package/README.md

@@ -90,6 +90,10 @@ Batch mode works too: drop three illustrations at once, and the model announces
 
 ![Text-only DeepSeek reading three images in one go via ModLens](https://raw.githubusercontent.com/liustack/modlens/main/assets/demo-codex-batch.png)
 
+Stress test: a scatter plot of 128 models. ModLens pulls out the axes, the log scale, and the highlighted DeepSeek V4 Flash point at $0.028 and score 50, then walks through the cost-performance cutoff line. Dense charts are where vision models usually fold; this one holds.
+
+![Text-only DeepSeek reading a 128-model scatter plot via ModLens](https://raw.githubusercontent.com/liustack/modlens/main/assets/demo-codex-chart.png)
+
 ## CLI reference
 
 ```bash
@@ -141,6 +145,12 @@ One catch: once text-only is declared, the Codex TUI **blocks Ctrl+V image paste
 - **Drag the image file into the terminal**, or type its path. The path lands as plain text, and the modlens skill picks it up from there.
 - Attach it with `codex exec -i image.png "..."`. The skill reads the path out of the message tag.
 
+## Using it in Claude Code (gateway models)
+
+No setup needed: drag the image file into the terminal, or type its path, and the skill takes over.
+
+Paste is trickier. If you run a text-only model behind `ANTHROPIC_BASE_URL`, Claude Code never writes pasted images to a regular temp file and has no modality switch, so a pasted image reaches the model as a pathless `[Unsupported Image]` placeholder (lenient gateways like DeepSeek's Anthropic endpoint) or breaks the request outright ([#62009](https://github.com/anthropics/claude-code/issues/62009)). But the bytes are not gone: Claude Code appends every user message, images included, to the local session transcript before the gateway ever sees it. That is what `modlens recover-paste` exploits: it pulls the most recent pasted images back out of the transcript and prints real file paths, ready for `modlens -i`. The skill runs this automatically when it spots the placeholder. Transcripts are per-session files; recovery picks the one holding the newest pasted image by message timestamp, so concurrent sessions in the same project do not confuse it. One honest caveat: the transcript layout is Claude Code internals with no compatibility promise; if recovery ever breaks, dragging the file still works everywhere.
+
 ## Why a bridge instead of a multimodal model?
 
 - **Keep your model.** You picked DeepSeek-V4-Flash (or gpt-oss, or whatever else) for its price and its reasoning, not its eyesight. ModLens adds sight without touching that choice.

package/README.zh-CN.md

@@ -90,6 +90,10 @@ npx @liustack/modlens -i workflow.jpg
 
 ![纯文本 DeepSeek 通过 ModLens 一次读完三张图](https://raw.githubusercontent.com/liustack/modlens/main/assets/demo-codex-batch.png)
 
+压力测试：一张 128 个模型的智能对成本散点图。ModLens 读出双轴、对数刻度，把高亮的 DeepSeek V4 Flash 精准拎出来（成本约 $0.028、智能指数 50），还讲明白了性价比斩杀线。密集图表是识图模型最容易露怯的地方，这一关它扛住了。
+
+![纯文本 DeepSeek 通过 ModLens 读 128 个模型的散点图](https://raw.githubusercontent.com/liustack/modlens/main/assets/demo-codex-chart.png)
+
 ## CLI 参数
 
 ```bash
@@ -141,6 +145,12 @@ Codex 只认 Responses API，DeepSeek 官方端点原生支持。先照着[官
 - **把图片文件拖进终端**，或者手打路径。路径以纯文本形式落进消息，modlens skill 接着从这里接手。
 - 用 `codex exec -i 图片.png "..."` skill 从这里把路径抠出来。
 
+## 在 Claude Code 里用（网关接第三方模型）
+
+不用任何配置：把图片文件拖进终端，或手打路径，skill 直接接手。
+
+粘贴要多说两句。走 `ANTHROPIC_BASE_URL` 网关跑纯文本模型时，Claude Code 粘贴的图片从不写普通临时文件，也没有声明模型无视觉的开关，粘贴的图要么变成一个不带路径的 `[Unsupported Image]` 占位符到达模型（DeepSeek 的 Anthropic 兼容端点这类宽容网关），要么直接把请求搞挂（[#62009](https://github.com/anthropics/claude-code/issues/62009)）。但图片字节没有蒸发：Claude Code 在网关看到消息之前，就把每条用户消息（含图片）原样写进了本地会话记录。`modlens recover-paste` 干的就是这件事：从会话记录里把最近粘贴的图捞回来，落成真实文件路径，直接喂给 `modlens -i`。skill 看到占位符会自动跑这一步。会话记录本来就是一个会话一个文件，recover-paste 按消息时间戳挑「持有最新粘贴图」的那份，同项目并发开多个会话也不会拿错。一句老实话：会话记录格式是 Claude Code 的内部实现，没有兼容承诺，哪天捞不动了，拖文件永远是保底。
+
 ## 为什么外挂，而不是换多模态模型？
 
 - **模型不用换。** 你选 DeepSeek-V4-Flash（或 gpt-oss，或别的什么）图的是价格和推理能力，不是视力。ModLens 只加视力，不碰这个选择。

package/dist/main.js

@@ -4,6 +4,7 @@ import * as fs from "fs";
 import * as path from "path";
 import { spawn } from "child_process";
 import * as os from "os";
+import * as crypto from "crypto";
 const CONFIG_DIR = path.join(os.homedir(), ".modlens");
 const CONFIG_PATH = path.join(CONFIG_DIR, "config.json");
 const ENV_BINDINGS = {
@@ -843,8 +844,129 @@ function runCommand(providerName, invocation, timeoutMs) {
     });
   });
 }
+const EXT_BY_MIME = {
+  "image/png": "png",
+  "image/jpeg": "jpg",
+  "image/webp": "webp",
+  "image/gif": "gif"
+};
+function projectSlug(cwd) {
+  return path.resolve(cwd).replace(/[/.]/g, "-");
+}
+function locateTranscript(cwd) {
+  const dir = path.join(os.homedir(), ".claude", "projects", projectSlug(cwd));
+  let entries;
+  try {
+    entries = fs.readdirSync(dir).filter((name) => name.endsWith(".jsonl"));
+  } catch {
+    throw new Error(
+      `No Claude Code transcripts found for this directory (${dir}). Run from the project the image was pasted in, or pass --transcript <path>.`
+    );
+  }
+  if (entries.length === 0) {
+    throw new Error(`No transcripts in ${dir}. Pass --transcript <path> to pick one manually.`);
+  }
+  let best = null;
+  for (const name of entries) {
+    const full = path.join(dir, name);
+    const timestamp = lastImageTimestamp(full);
+    if (timestamp && (!best || timestamp > best.timestamp)) {
+      best = { full, timestamp };
+    }
+  }
+  if (!best) {
+    throw new Error(
+      `No pasted images found in any transcript under ${dir}. The user may not have pasted any, or the transcript format changed; ask for a file path instead.`
+    );
+  }
+  return best.full;
+}
+function lastImageTimestamp(transcriptPath) {
+  let raw;
+  try {
+    raw = fs.readFileSync(transcriptPath, "utf-8");
+  } catch {
+    return null;
+  }
+  let latest = null;
+  for (const line of raw.split("\n")) {
+    if (!line.includes('"image"')) {
+      continue;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const entry = parsed;
+    if (entry.message?.role !== "user" || !Array.isArray(entry.message.content)) {
+      continue;
+    }
+    const hasImage = entry.message.content.some(
+      (block) => block?.type === "image" && block.source?.type === "base64"
+    );
+    if (hasImage && entry.timestamp && (!latest || entry.timestamp > latest)) {
+      latest = entry.timestamp;
+    }
+  }
+  return latest;
+}
+function extractUserImages(transcriptPath) {
+  let raw;
+  try {
+    raw = fs.readFileSync(transcriptPath, "utf-8");
+  } catch (error) {
+    throw new Error(`Cannot read transcript ${transcriptPath}: ${error.message}`);
+  }
+  const images = [];
+  for (const line of raw.split("\n")) {
+    if (!line.includes('"image"')) {
+      continue;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const message = parsed.message;
+    if (message?.role !== "user" || !Array.isArray(message.content)) {
+      continue;
+    }
+    for (const block of message.content) {
+      const source = block?.source;
+      if (block?.type === "image" && source?.type === "base64" && source.data) {
+        images.push({ mediaType: source.media_type ?? "image/png", data: source.data });
+      }
+    }
+  }
+  return images;
+}
+function recoverPastedImages(options = {}) {
+  const transcript = options.transcript ?? locateTranscript(options.cwd ?? process.cwd());
+  const count = Math.max(1, options.count ?? 1);
+  const outDir = options.outDir ?? path.join(os.tmpdir(), "modlens-paste");
+  const all = extractUserImages(transcript);
+  if (all.length === 0) {
+    throw new Error(
+      `No pasted images found in ${transcript}. The user may not have pasted any, or the transcript format changed; ask for a file path instead.`
+    );
+  }
+  fs.mkdirSync(outDir, { recursive: true });
+  const picked = all.slice(-count);
+  const images = picked.map((image) => {
+    const buffer = Buffer.from(image.data, "base64");
+    const hash = crypto.createHash("sha256").update(buffer).digest("hex").slice(0, 8);
+    const ext = EXT_BY_MIME[image.mediaType] ?? "png";
+    const filePath = path.join(outDir, `paste-${hash}.${ext}`);
+    fs.writeFileSync(filePath, buffer);
+    return { path: filePath, mediaType: image.mediaType, bytes: buffer.length };
+  });
+  return { transcript, images };
+}
 const program = new Command();
-program.name("modlens").description("Plug-in vision for text-only LLMs: image in, structured JSON evidence out").version("2.2.0");
+program.name("modlens").description("Plug-in vision for text-only LLMs: image in, structured JSON evidence out").version("2.3.1");
 program.command("analyze", { isDefault: true }).description("Analyze an image into structured JSON evidence (default command)").requiredOption("-i, --input <path|url>", "Input image path or https URL").option("-o, --output <path>", "Write result JSON to a file").option("-m, --model <name>", "Provider model name").option("-p, --provider <name>", `Vision provider (${listProviders().join(", ")})`).option("--prompt <text>", "Extra focus for this image").option("--timeout <ms>", "Provider timeout in milliseconds", "180000").option("--provider-bin <path>", "Provider binary path (default: agy)").option("--workdir <path>", "Working directory for the provider").action(async (options) => {
   try {
     const timeoutMs = Number.parseInt(options.timeout, 10);
@@ -876,6 +998,30 @@ program.command("analyze", { isDefault: true }).description("Analyze an image in
     process.exit(1);
   }
 });
+program.command("recover-paste").description(
+  "Recover images pasted into Claude Code from the session transcript (they never hit disk otherwise)"
+).option("--count <n>", "How many recent pasted images to recover", "1").option("--out-dir <path>", "Directory to write recovered images to").option("--transcript <path>", "Explicit transcript .jsonl (default: newest for cwd)").option("--cwd <path>", "Project directory the image was pasted in", process.cwd()).action(async (options) => {
+  try {
+    const count = Number.parseInt(options.count, 10);
+    if (!Number.isFinite(count) || count <= 0) {
+      throw new Error("Invalid --count. Use a positive integer.");
+    }
+    const result = recoverPastedImages({
+      count,
+      outDir: options.outDir,
+      transcript: options.transcript,
+      cwd: options.cwd
+    });
+    process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+  } catch (error) {
+    process.stderr.write(
+      `Error: ${error instanceof Error ? error.message : String(error)}
+`
+    );
+    process.exit(1);
+  }
+});
 const config = program.command("config").description(`Manage ${CONFIG_PATH} (providers, keys, models)`);
 config.command("init").description(`Create a starter config at ${CONFIG_PATH}`).option("--force", "Overwrite an existing config file").action((options) => {
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liustack/modlens",
-  "version": "2.2.0",
+  "version": "2.3.1",
   "description": "Plug-in vision for text-only LLMs, powered by the free Antigravity CLI",
   "type": "module",
   "bin": {

package/skills/modlens/SKILL.md

@@ -66,6 +66,7 @@ Harnesses rarely hand you a clean path. Look for these signals:
 - Codex wraps every pasted or attached image in a text tag like
   `<image name=[Image #1] path="/tmp/xxxx.png">`. Extract the `path` value and run modlens on it. Pasted images live in a temp file the harness already created.
 - A placeholder like `image content omitted because you do not support image input` means the harness stripped an image for you. The path tag next to it still holds the real file. Use it.
+- Claude Code never writes pasted images to a regular temp file. Behind a text-only gateway you will only see a placeholder like `[Unsupported Image]` or `[Image #1]`, with no path. When that happens, run `modlens recover-paste` (add `--count <n>` for several images): it pulls the pasted image bytes out of the local session transcript and prints the recovered file paths as JSON. Feed that path to `modlens -i`. If recovery fails (transcript format is Claude Code internals and may change), fall back to asking the user to drag the image file into the terminal or type its path.
 - If the user mentions an image but no tag or path appears anywhere in the message, ask for the file path instead of guessing.
 
 ## Workflow