@liustack/modlens 2.1.0 → 2.3.0

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
@@ -111,7 +115,7 @@ Reach for `-m gemini-3.1-pro-high` on dense screenshots or tricky documents. Out
 
 ## Providers and config
 
-ModLens ships four vision providers. `antigravity-cli` stays the default: zero keys, pure free quota.
+ModLens ships five vision providers. `antigravity-cli` stays the default: zero keys, pure free quota.
 
 | Provider | Needs | Typical speed | Notes |
 | :-- | :-- | :-- | :-- |
@@ -119,6 +123,7 @@ ModLens ships four vision providers. `antigravity-cli` stays the default: zero k
 | `gemini-api` | free AI Studio key | 5-10s | fastest free route, schema enforced server-side |
 | `openai` | baseUrl + apiKey + model | endpoint-dependent | any OpenAI-compatible multimodal endpoint (qwen-vl, GLM, ...) |
 | `anthropic` | `ANTHROPIC_API_KEY` | a few seconds | Claude Haiku by default, schema via forced tool call |
+| `claude-cli` | Claude Code signed in | 20-45s | no key, rides your Claude subscription, Read-only permissions |
 
 Config lives in `~/.modlens/config.json`. Environment variables override the file (`GEMINI_API_KEY`, `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `ANTHROPIC_API_KEY`), and CLI flags override everything.
 
@@ -140,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. 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
@@ -111,7 +115,7 @@ modlens -i <图片路径或 URL> [选项]
 
 ## Provider 与配置
 
-ModLens 内置四个视觉 provider，默认还是 `antigravity-cli`：零 key，纯免费额度。
+ModLens 内置五个视觉 provider，默认还是 `antigravity-cli`：零 key，纯免费额度。
 
 | Provider | 需要什么 | 速度 | 说明 |
 | :-- | :-- | :-- | :-- |
@@ -119,6 +123,7 @@ ModLens 内置四个视觉 provider，默认还是 `antigravity-cli`：零 key
 | `gemini-api` | 免费 AI Studio key | 5-10 秒 | 最快的免费路线，服务端强制 schema |
 | `openai` | baseUrl + apiKey + model | 看端点 | 任何 OpenAI 兼容的多模态端点（qwen-vl、GLM 等） |
 | `anthropic` | `ANTHROPIC_API_KEY` | 几秒 | 默认 Claude Haiku，强制工具调用保 schema |
+| `claude-cli` | Claude Code 已登录 | 20-45 秒 | 零 key，吃你的 Claude 订阅额度，只放行 Read 工具 |
 
 配置放在 `~/.modlens/config.json`，环境变量能盖过它（`GEMINI_API_KEY`、`OPENAI_API_KEY`、`OPENAI_BASE_URL`、`ANTHROPIC_API_KEY`），CLI 参数最大。
 
@@ -140,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 看到占位符会自动跑这一步。一句老实话：会话记录格式是 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 = {
@@ -79,7 +80,8 @@ const CONFIG_TEMPLATE = {
     "antigravity-cli": { model: "gemini-3.6-flash-low" },
     "gemini-api": { apiKey: "", model: "gemini-3.6-flash" },
     openai: { baseUrl: "", apiKey: "", model: "" },
-    anthropic: { apiKey: "", model: "claude-haiku-4-5-20251001" }
+    anthropic: { apiKey: "", model: "claude-haiku-4-5-20251001" },
+    "claude-cli": { model: "haiku" }
   }
 };
 function initConfigFile(configPath = CONFIG_PATH, force = false) {
@@ -269,11 +271,11 @@ function buildAntigravityInvocation(options) {
   };
 }
 function parseAntigravityOutput(stdout) {
-  const envelope = parseEnvelope(stdout);
+  const envelope = parseEnvelope$1(stdout);
   if (envelope.status && envelope.status !== "SUCCESS") {
     throw new Error(`Antigravity CLI reported status ${envelope.status}.`);
   }
-  const result = envelope.structured_output ?? (typeof envelope.response === "string" ? tryParseJson(envelope.response) : null);
+  const result = envelope.structured_output ?? (typeof envelope.response === "string" ? tryParseJson$1(envelope.response) : null);
   if (result === null || result === void 0) {
     throw new Error(
       "Antigravity CLI output contains no structured result. Check that the model finished the task (auth, quota, timeout)."
@@ -288,14 +290,14 @@ function parseAntigravityOutput(stdout) {
     }
   };
 }
-function parseEnvelope(stdout) {
+function parseEnvelope$1(stdout) {
   const trimmed = stdout.trim();
-  let parsed = tryParseJson(trimmed);
+  let parsed = tryParseJson$1(trimmed);
   if (parsed === null) {
     const firstBrace = trimmed.indexOf("{");
     const lastBrace = trimmed.lastIndexOf("}");
     if (firstBrace >= 0 && lastBrace > firstBrace) {
-      parsed = tryParseJson(trimmed.slice(firstBrace, lastBrace + 1));
+      parsed = tryParseJson$1(trimmed.slice(firstBrace, lastBrace + 1));
     }
   }
   if (!parsed || typeof parsed !== "object") {
@@ -303,7 +305,7 @@ function parseEnvelope(stdout) {
   }
   return parsed;
 }
-function tryParseJson(text) {
+function tryParseJson$1(text) {
   try {
     return JSON.parse(text);
   } catch {
@@ -432,7 +434,7 @@ Report your findings by calling the ${TOOL_NAME} tool.`;
   });
   if (!response.ok) {
     const body = await response.text();
-    throw new Error(`Anthropic API error ${response.status}: ${truncate$2(body)}`);
+    throw new Error(`Anthropic API error ${response.status}: ${truncate$3(body)}`);
   }
   const payload = await response.json();
   const toolUse = payload.content?.find((block) => block.type === "tool_use");
@@ -448,7 +450,7 @@ Report your findings by calling the ${TOOL_NAME} tool.`;
     }
   };
 }
-function truncate$2(text) {
+function truncate$3(text) {
   return text.length > 300 ? `${text.slice(0, 300)}...` : text;
 }
 const anthropicApiProvider = {
@@ -456,6 +458,92 @@ const anthropicApiProvider = {
   defaultModel: ANTHROPIC_DEFAULT_MODEL,
   execute: executeAnthropicApi
 };
+const CLAUDE_CLI_DEFAULT_MODEL = "haiku";
+function buildClaudeCliInvocation(options) {
+  if (options.imageKind === "remote") {
+    throw new Error(
+      "claude-cli provider reads local files only. Download the image first, or use -p gemini-api for remote URLs."
+    );
+  }
+  const prompt = buildVisionPrompt({
+    imageSource: options.imageSource,
+    imageKind: "local",
+    extraPrompt: options.extraPrompt
+  });
+  const args = [
+    "-p",
+    prompt,
+    "--output-format",
+    "json",
+    "--json-schema",
+    visionResultSchemaJson(),
+    "--allowedTools",
+    "Read",
+    "--model",
+    options.model || options.settings?.model || CLAUDE_CLI_DEFAULT_MODEL
+  ];
+  return {
+    command: options.providerBin || "claude",
+    args,
+    cwd: path.resolve(options.workdir || path.dirname(options.imageSource))
+  };
+}
+function parseClaudeCliOutput(stdout) {
+  const envelope = parseEnvelope(stdout);
+  if (envelope.is_error || envelope.subtype && envelope.subtype !== "success") {
+    throw new Error(
+      `Claude CLI reported ${envelope.subtype ?? "an error"}: ${truncate$2(envelope.result ?? "")}`
+    );
+  }
+  if (typeof envelope.result !== "string" || !envelope.result.trim()) {
+    throw new Error("Claude CLI output contains no result. Check login state (run: claude).");
+  }
+  let result;
+  try {
+    result = JSON.parse(envelope.result);
+  } catch {
+    throw new Error(`Claude CLI returned non-JSON result: ${truncate$2(envelope.result)}`);
+  }
+  return {
+    result,
+    meta: {
+      conversationId: envelope.session_id ?? null,
+      durationSeconds: typeof envelope.duration_ms === "number" ? envelope.duration_ms / 1e3 : null,
+      usage: envelope.usage ?? null
+    }
+  };
+}
+function parseEnvelope(stdout) {
+  const trimmed = stdout.trim();
+  let parsed = tryParseJson(trimmed);
+  if (parsed === null) {
+    const firstBrace = trimmed.indexOf("{");
+    const lastBrace = trimmed.lastIndexOf("}");
+    if (firstBrace >= 0 && lastBrace > firstBrace) {
+      parsed = tryParseJson(trimmed.slice(firstBrace, lastBrace + 1));
+    }
+  }
+  if (!parsed || typeof parsed !== "object") {
+    throw new Error("Failed to parse Claude CLI JSON output.");
+  }
+  return parsed;
+}
+function tryParseJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+function truncate$2(text) {
+  return text.length > 300 ? `${text.slice(0, 300)}...` : text;
+}
+const claudeCliProvider = {
+  name: "claude-cli",
+  defaultModel: CLAUDE_CLI_DEFAULT_MODEL,
+  buildInvocation: buildClaudeCliInvocation,
+  parseOutput: parseClaudeCliOutput
+};
 const GEMINI_API_DEFAULT_MODEL = "gemini-3.6-flash";
 const DEFAULT_BASE_URL = "https://generativelanguage.googleapis.com";
 async function executeGeminiApi(options) {
@@ -615,7 +703,9 @@ const PROVIDERS = {
   openai: openaiCompatProvider,
   "openai-compat": openaiCompatProvider,
   anthropic: anthropicApiProvider,
-  claude: anthropicApiProvider
+  claude: anthropicApiProvider,
+  "claude-cli": claudeCliProvider,
+  "claude-code": claudeCliProvider
 };
 function resolveProvider(providerName = "antigravity-cli") {
   const normalized = providerName.trim().toLowerCase();
@@ -754,8 +844,89 @@ 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.`);
+  }
+  const newest = entries.map((name) => {
+    const full = path.join(dir, name);
+    return { full, mtime: fs.statSync(full).mtimeMs };
+  }).sort((a, b) => b.mtime - a.mtime)[0];
+  return newest.full;
+}
+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.1.0");
+program.name("modlens").description("Plug-in vision for text-only LLMs: image in, structured JSON evidence out").version("2.3.0");
 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);
@@ -787,6 +958,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.1.0",
+  "version": "2.3.0",
   "description": "Plug-in vision for text-only LLMs, powered by the free Antigravity CLI",
   "type": "module",
   "bin": {

package/skills/modlens/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: modlens
-description: "Plug-in vision for text-only models. Use whenever the user shares an image (local path, screenshot, photo, chart, document scan, or image URL) and the active model cannot see images or has no vision tool. Runs the modlens CLI to convert the image into structured JSON evidence: OCR text, layout, semantics, visual clues."
+description: "Plug-in vision for text-only models. Use whenever the user shares an image (local path, screenshot, photo, chart, document scan, or image URL) and the active model cannot see images or has no vision tool. Runs the modlens CLI to convert the image into structured JSON evidence: OCR text, layout, semantics, visual clues. Also use when the user asks how to install, configure, or switch modlens providers (Gemini API key, OpenAI-compatible endpoints, Claude API or Claude Code CLI)."
 allowed-tools:
   - Bash
 ---
@@ -12,6 +12,7 @@ Use this skill when:
 - The user provides an image path or image URL and asks anything about it
 - The active model has no native vision (text-only model in a coding agent)
 - You need OCR text, layout, or chart/document structure as evidence before reasoning
+- The user asks how to configure modlens, get an API key for it, or switch its provider: follow `references/configure.md` and run the commands for them
 
 Do not use this skill for:
 
@@ -26,7 +27,7 @@ modlens --version
 
 If `modlens` is missing, run it via `npx @liustack/modlens` instead.
 
-ModLens supports four vision providers. Check what is configured:
+ModLens supports five vision providers. Check what is configured:
 
 ```bash
 modlens config show
@@ -36,8 +37,9 @@ modlens config show
 - **gemini-api**: needs `GEMINI_API_KEY` env or `modlens config set gemini-api.apiKey <key>` (free key from https://aistudio.google.com).
 - **openai**: any OpenAI-compatible multimodal endpoint; needs baseUrl + apiKey + model via env (`OPENAI_BASE_URL`, `OPENAI_API_KEY`) or `modlens config set openai.<field> <value>`.
 - **anthropic**: needs `ANTHROPIC_API_KEY` env or config; defaults to Claude Haiku.
+- **claude-cli**: rides an existing Claude Code login (`claude`), no key, Read-only tool permissions, local files only.
 
-`modlens config init` writes a starter config to `~/.modlens/config.json` when none exists.
+`modlens config init` writes a starter config to `~/.modlens/config.json` when none exists. Full setup recipes per provider: `references/configure.md`.
 
 ## Command
 
@@ -55,7 +57,7 @@ Optional flags:
 modlens -i <image> -o <output.json> -m <model> --prompt "<extra focus>" --timeout <ms>
 ```
 
-Speed expectations: `gemini-api` typically 5-10 seconds, `antigravity-cli` 15-40 seconds (full agent loop), `openai`/`anthropic` depend on the endpoint. For dense or hard images on antigravity-cli, try `-m gemini-3.1-pro-high`.
+Speed expectations: `gemini-api` typically 5-10 seconds, `antigravity-cli` 15-40 seconds and `claude-cli` 20-45 seconds (full agent loops), `openai`/`anthropic` depend on the endpoint. For dense or hard images on antigravity-cli, try `-m gemini-3.1-pro-high`.
 
 ## Finding the image path in the chat
 
@@ -64,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
@@ -85,7 +88,7 @@ Top level: `{ image, provider, result, meta }`. Inside `result`:
 - `visual`: colors and style clues
 - `uncertainty[]`: what the vision engine was unsure about
 
-Structure is enforced by schema on antigravity-cli (`--json-schema`), gemini-api (`responseJsonSchema`), and anthropic (forced tool call). The openai route uses a template prompt plus shape validation and fails loudly on mismatch.
+Structure is enforced by schema on antigravity-cli and claude-cli (`--json-schema`), gemini-api (`responseJsonSchema`), and anthropic (forced tool call). The openai route uses a template prompt plus shape validation and fails loudly on mismatch.
 
 ## Failure Handling
 

package/skills/modlens/references/configure.md

@@ -0,0 +1,85 @@
+# Configuring ModLens
+
+Read this when the user asks how to set up, configure, or switch ModLens providers. Prefer running the commands for the user over explaining them.
+
+## Where config lives
+
+`~/.modlens/config.json`, managed by the CLI. Precedence: CLI flags > environment variables > config file > built-in defaults. The default provider with zero config is `antigravity-cli`.
+
+```bash
+modlens config init                     # write a starter config (refuses to overwrite; --force to redo)
+modlens config show                     # effective file, API keys masked
+modlens config set provider <name>      # change the default provider
+modlens config set <provider>.<field> <value>   # fields: apiKey, baseUrl, model
+```
+
+`config set` writes the file with 0600 permissions.
+
+## Provider setup recipes
+
+### antigravity-cli (default, free, no key)
+
+Needs Antigravity CLI installed and signed in:
+
+```bash
+curl -fsSL https://antigravity.google/cli/install.sh | bash
+agy    # user must complete browser sign-in themselves, then exit
+```
+
+Any free Google account works; no Google AI Pro needed. Sign-in cannot be automated, ask the user to run `agy` once.
+
+### gemini-api (free key, fastest free route, 5-10s)
+
+1. The user creates a key at https://aistudio.google.com (three minutes, no credit card, free tier does not expire).
+2. Store it either way:
+
+```bash
+modlens config set gemini-api.apiKey <key>
+# or environment: export GEMINI_API_KEY=<key>
+```
+
+Default model `gemini-3.6-flash` has vision on the free tier (about 10-15 requests/min, 1500/day). Free-tier data may be used by Google to improve products; mention this if the user handles sensitive images.
+
+### openai (any OpenAI-compatible multimodal endpoint)
+
+Needs three values. Example for DashScope qwen:
+
+```bash
+modlens config set openai.baseUrl https://dashscope.aliyuncs.com/compatible-mode/v1
+modlens config set openai.apiKey <sk-key>
+modlens config set openai.model qwen3.6-27b
+```
+
+For official OpenAI: baseUrl `https://api.openai.com/v1`, a vision-capable model. Environment equivalents: `OPENAI_BASE_URL`, `OPENAI_API_KEY`. The model must be multimodal; text-only models will fail or hallucinate. This route has no server-side schema enforcement, so occasional shape failures are surfaced as explicit errors; retry or switch provider.
+
+### anthropic (Claude API key)
+
+```bash
+modlens config set anthropic.apiKey <sk-ant-key>
+# or: export ANTHROPIC_API_KEY=<key>
+```
+
+Default model is Claude Haiku (`claude-haiku-4-5-20251001`). Schema is enforced through a forced tool call.
+
+### claude-cli (Claude Code login, no key)
+
+Rides an existing `claude` sign-in, so it costs the user's Claude subscription quota, not a separate API bill. Requires Claude Code installed and logged in (`claude --version` to check). Runs with `--allowedTools Read` only. Local image files only; for remote URLs use gemini-api instead. Default model alias `haiku`.
+
+```bash
+modlens config set provider claude-cli   # make it the default if the user wants
+```
+
+## Choosing a provider for the user
+
+- Wants zero setup and free: `antigravity-cli` (needs agy sign-in, 15-40s per image).
+- Wants fast and free: `gemini-api` (three-minute key, 5-10s).
+- Already pays for Claude: `claude-cli` (no extra key) or `anthropic` (API billing).
+- Has a favorite multimodal endpoint (qwen, GLM, ...): `openai`.
+
+## Troubleshooting
+
+- Error names a missing env var or `config set` command: run exactly that.
+- `Provider CLI not found: agy`: install Antigravity CLI or switch provider.
+- `Claude CLI reported ...` or empty result: check `claude` login state.
+- openai route `does not match the vision schema`: retry once, then switch to gemini-api or anthropic.
+- `config init` refusing to run: the file exists; use `modlens config show` first, `--force` only if the user agrees to overwrite.