From 514531aaf9e7f8e4d5543501343e82a1cf4d45a5 Mon Sep 17 00:00:00 2001 From: Ikalus1988 Date: Wed, 5 Aug 2026 00:26:03 +0800 Subject: [PATCH] docs: add known limitation for non-vision main models via custom API gateways When using CC-Vision with a non-multimodal main model accessed through a custom API gateway (e.g., corporate internal gateways), the hook may fail because Claude Code sends both the text description AND the raw image to the main model. The hook can add context but cannot remove the raw image. This commit adds: - docs/non-vision-model-limitation.md: detailed explanation of the issue - README.md: known limitations section with link to full documentation Tested with Claude Code 2.1.206 on Windows 11 with custom API gateway. --- README.md | 15 ++++++++++ docs/non-vision-model-limitation.md | 44 +++++++++++++++++++++++++++++ 2 files changed, 59 insertions(+) create mode 100644 docs/non-vision-model-limitation.md diff --git a/README.md b/README.md index d211c02..6c40dd8 100644 --- a/README.md +++ b/README.md @@ -156,6 +156,21 @@ Currently serial. If you often paste multiple images at once, swap the loop in ` The same approach works in any AI terminal that supports a `UserPromptSubmit`-equivalent hook (Cursor, Cline, etc.). The script itself doesn't depend on Claude Code-specific APIs — any hook system that passes stdin JSON and reads stdout JSON works. +## Known Limitations + +### Non-vision main models via custom API gateways + +When using CC-Vision with a **non-multimodal main model** accessed through a **custom API gateway** (e.g., corporate internal gateways, model proxies), the hook may fail to prevent image-related errors. + +**Root cause**: Claude Code sends BOTH the text description (from the hook) AND the original raw image to the main model. The hook can add context but cannot remove the raw image. If the main model doesn't support images, it may error out. + +**Workarounds**: +- Use a vision-capable main model if available +- Configure your API gateway to strip image content blocks for text-only models +- Run a local proxy to strip images before forwarding to the main model + +See [`docs/non-vision-model-limitation.md`](docs/non-vision-model-limitation.md) for full details. + ## FAQ **Q: After install, pasting an image still does nothing?** diff --git a/docs/non-vision-model-limitation.md b/docs/non-vision-model-limitation.md new file mode 100644 index 0000000..940c2c6 --- /dev/null +++ b/docs/non-vision-model-limitation.md @@ -0,0 +1,44 @@ +# Known Limitation: Non-Vision Main Models via Custom API Gateways + +## Problem + +When using CC-Vision with a **non-multimodal main model** accessed through a **custom API gateway** (e.g., corporate internal gateways, model proxies), the hook may fail to prevent image-related errors. + +## Root Cause + +Claude Code's behavior when handling pasted images: + +1. User pastes an image → Claude Code saves it to `~/.claude/image-cache/` +2. `UserPromptSubmit` hook fires → CC-Vision calls multimodal API → injects text description via `additionalContext` +3. **Claude Code sends BOTH the text description AND the original raw image to the main model** +4. If the main model doesn't support images → API error + +The hook can **add** context (`additionalContext`) but cannot **remove** the raw image from the request. + +## Observed Behavior + +- **Claude's native models** (Claude 3.5 Sonnet, etc.): Work fine — these models support images natively, so even if Claude Code sends the raw image, the model handles it gracefully. +- **Custom models via `ANTHROPIC_BASE_URL`** (e.g., DeepSeek, Qwen-Text, GLM via internal gateways): The main model receives the raw image and may error out with messages like "model may not exist or you may not have access to it". + +## Tested Environment + +- Claude Code version: 2.1.206 +- Main model: Custom text-only model via internal API gateway +- Vision model: Multimodel model via same gateway +- Platform: Windows 11 + +## Potential Workarounds + +1. **Use a vision-capable main model**: If your gateway supports a model that handles both text and images, use it as the main model. +2. **API-level image stripping**: Configure your API gateway to strip image content blocks before forwarding to text-only models. +3. **Proxy-based stripping**: Run a local proxy that intercepts API requests and removes image content blocks before forwarding to the main model. + +## Impact + +This limitation means CC-Vision's core value proposition ("the main model never sees pixels") may not hold in all environments. The hook successfully provides text descriptions, but cannot prevent Claude Code from also sending the raw image. + +## Recommendations + +1. **Document this limitation** in the README to set correct expectations +2. **Test with the user's actual model/gateway setup** before assuming CC-Vision will work +3. **Consider adding a `stripImages` hook configuration option** if Claude Code's hook system supports it in future versions