@liustack/modlens 2.4.0 → 2.4.2

package/README.md

@@ -113,6 +113,15 @@ modlens -i <image-path-or-url> [options]
 
 Reach for `-m gemini-3.1-pro-high` on dense screenshots or tricky documents. Output contract: [skills/modlens/references/output-schema.md](skills/modlens/references/output-schema.md).
 
+Two more subcommands: `modlens config <init|set|show>` manages providers and keys (details below), and `modlens recover-paste` rescues images pasted into Claude Code:
+
+```bash
+modlens recover-paste                 # newest pasted image, path printed as JSON
+modlens recover-paste --count 3       # the three newest
+modlens recover-paste --session <id>  # exact session (skills pass ${CLAUDE_SESSION_ID})
+# --transcript <path> overrides everything; --cwd <dir> sets the project directory
+```
+
 ## Providers and config
 
 ModLens ships five vision providers. `antigravity-cli` stays the default: zero keys, pure free quota.

package/README.zh-CN.md

@@ -113,6 +113,15 @@ modlens -i <图片路径或 URL> [选项]
 
 截图信息密集或文档难啃，换成 `-m gemini-3.1-pro-high`。输出契约见 [skills/modlens/references/output-schema.md](skills/modlens/references/output-schema.md)。
 
+另外两个子命令：`modlens config <init|set|show>` 管 provider 和 key（下文详述），`modlens recover-paste` 抢救粘贴进 Claude Code 的图片：
+
+```bash
+modlens recover-paste                 # 捞最新一张，路径以 JSON 打印
+modlens recover-paste --count 3       # 捞最近三张
+modlens recover-paste --session <id>  # 精确会话（skill 会传 ${CLAUDE_SESSION_ID}）
+# --transcript <path> 优先级最高，--cwd <dir> 指定项目目录
+```
+
 ## Provider 与配置
 
 ModLens 内置五个视觉 provider，默认还是 `antigravity-cli`：零 key，纯免费额度。

package/dist/main.js

@@ -982,7 +982,7 @@ function recoverPastedImages(options = {}) {
   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.4.0");
+program.name("modlens").description("Plug-in vision for text-only LLMs: image in, structured JSON evidence out").version("2.4.2");
 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);

package/package.json

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

package/skills/modlens/SKILL.md

@@ -61,14 +61,19 @@ Speed expectations: `gemini-api` typically 5-10 seconds, `antigravity-cli` 15-40
 
 ## Finding the image path in the chat
 
-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 recovers the pasted image bytes from the local session transcripts and prints real file paths as JSON. Feed that path to `modlens -i`.
-  Session targeting: your session id is ${CLAUDE_SESSION_ID}. If that value reads as a UUID, Claude Code has substituted it; pass it along as `--session <that-uuid>` for exact targeting. If it still reads as a literal placeholder (older Claude Code, or another harness), just omit `--session`: no env var carries a session id in Bash, and the command then auto-locates by scanning every transcript of the current project and picking the session holding the newest pasted-image message by timestamp, which is the one the user just pasted into, even with concurrent sessions. Run it from the project directory the conversation is happening in. 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.
+Harnesses rarely hand you a clean path. First identify which harness you are in, then use its route. Never mix routes across harnesses.
+
+**Codex** (you see a text tag like `<image name=[Image #1] path="/tmp/xxxx.png">`):
+
+- Extract the `path` value from the tag and run modlens on it. Pasted images live in a temp file Codex already created; a stripped image keeps its path tag next to the placeholder. Do NOT use `recover-paste` here: it reads Claude Code session files, which do not exist for Codex.
+
+**Claude Code** (no path tag anywhere; the placeholder looks like `[Unsupported Image]` or a bare `[Image #1]`, and `${CLAUDE_SESSION_ID}` below reads as a UUID):
+
+- Claude Code never writes pasted images to a regular temp file, but it logs them into its local session transcript. Run `modlens recover-paste` (add `--count <n>` for several images): it recovers the pasted image bytes and prints real file paths as JSON. Feed that path to `modlens -i`.
+- Session targeting: your session id is ${CLAUDE_SESSION_ID}. If that value reads as a UUID, pass it as `--session <uuid>` for exact targeting. If it reads as a literal placeholder, omit `--session`: the command auto-locates by scanning this project's transcripts for the newest pasted-image message, which is the session the user just pasted into, even with concurrent sessions. Run it from the project directory the conversation is happening in.
+- If recovery fails (transcript format is Claude Code internals and may change), ask the user to drag the image file into the terminal or type its path.
+
+**Any other harness, or nothing matches** (no path tag, `${CLAUDE_SESSION_ID}` still a literal placeholder, no Claude Code transcripts): do not guess and do not run `recover-paste`. Ask the user for the image file path, or suggest dragging the file into the terminal.
 
 ## Workflow