Skip to main content

​
Image Analysis

CCS automatically analyzes images and PDFs via CLIProxy vision models before Claude processes them. This prevents context overflow and provides structured text descriptions instead of raw visual data.

​
Overview

When Claude’s Read tool targets an image or PDF file, CCS intercepts the request and:
  1. Sends file to CLIProxy vision API
  2. Vision model analyzes and returns text description
  3. Claude receives description instead of raw image data
Supported File Types:
  • Images: .jpg, .jpeg, .png, .gif, .webp, .heic, .bmp, .tiff
  • Documents: .pdf

​
Quick Start

Image analysis is enabled by default for all CLIProxy providers. 
# Just use Claude normally with images
ccs gemini "analyze this screenshot"
# → CCS automatically analyzes image before Claude sees it

# Check current configuration
ccs config image-analysis

# Disable if needed
ccs config image-analysis --disable

​
Configuration

​
Enable/Disable

# Enable image analysis
ccs config image-analysis --enable

# Disable image analysis
ccs config image-analysis --disable

​
Timeout Settings

Default timeout is 60 seconds. Adjust for complex documents: 
# Set 2 minute timeout for large PDFs
ccs config image-analysis --timeout 120
Valid range: 10-600 seconds

​
Provider Models

Each provider can use a different vision model: 
# Set model for specific provider
ccs config image-analysis --set-model agy gemini-2.5-pro
ccs config image-analysis --set-model gemini gemini-2.5-flash
ccs config image-analysis --set-model codex gpt-5.1-codex-mini
Default Models:
ProviderDefault Model
agygemini-2.5-flash
geminigemini-2.5-flash
codexgpt-5.1-codex-mini
kirokiro-claude-haiku-4-5
ghcpclaude-haiku-4.5
claudeclaude-haiku-4-5-20251001

​
Provider Support

​
Enabled Providers

Image analysis works with all CLIProxy OAuth providers and settings-based profiles: CLIProxy OAuth Providers:
  • Antigravity (agy)
  • Gemini (gemini)
  • Codex (codex)
  • Kiro (kiro)
  • GitHub Copilot (ghcp)
  • Qwen (qwen)
  • iFlow (iflow)
Settings-Based Profiles:
  • GLM (glm)
  • Kimi for Coding (km)
  • Custom API profiles
Available since v7.39.0 - Settings-based profiles now receive image analysis environment variables, previously only available to CLIProxy OAuth profiles.

​
Skipped Providers

Claude Subscription accounts: Image analysis is automatically skipped for Claude Sub accounts to avoid conflicts with native image support. Profile Type Detection:
  • Account profiles (isolated instances) → Skip
  • Default profiles (CLI execution) → Skip
  • CLIProxy profiles → Analyze

​
ANTHROPIC_MODEL Fallback

When image analysis is enabled but no vision model is configured for the current provider, CCS falls back to the ANTHROPIC_MODEL environment variable. Example: 
export ANTHROPIC_MODEL="gemini-2.5-pro"
ccs agy "analyze this image"
# → Uses gemini-2.5-pro even if not in provider_models config

​
How It Works

​
Hook Architecture

CCS injects a PreToolUse hook into Claude’s settings: 
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Read",
      "hooks": [{
        "type": "command",
        "command": "node image-analyzer-transformer.cjs",
        "timeout": 65000
      }]
    }]
  }
}
Hook Location: ~/.ccs/hooks/image-analyzer-transformer.cjs

​
Execution Flow

  1. Claude calls Read tool with file path
  2. Hook checks file extension (.jpg, .pdf, etc.)
  3. If image/PDF:
    • Reads file (max 10MB)
    • Sends to http://127.0.0.1:8317/v1/messages (CLIProxy)
    • Receives text description
    • Returns description to Claude
  4. If not image/PDF:
    • Returns exit code 0 (pass-through)
    • Claude executes Read tool normally

​
Environment Variables

The hook reads these variables (set by CCS automatically):
VariablePurpose
CCS_IMAGE_ANALYSIS_ENABLEDEnable/disable feature (1/0)
CCS_IMAGE_ANALYSIS_PROVIDER_MODELSProvider:model mapping
CCS_CURRENT_PROVIDERCurrent CLIProxy provider
CCS_IMAGE_ANALYSIS_TIMEOUTTimeout in seconds
CCS_PROFILE_TYPEProfile type (account/default skip)
ANTHROPIC_MODELFallback model if provider not configured
CCS_DEBUGEnable debug output (1/0)

​
Configuration File

Settings stored in ~/.ccs/config.yaml: 
image_analysis:
  enabled: true
  timeout: 60
  provider_models:
    agy: gemini-2.5-flash
    gemini: gemini-2.5-flash
    codex: gpt-5.1-codex-mini

​
Troubleshooting

​
Analysis Not Happening

Check status: 
ccs config image-analysis
# → Shows enabled/disabled, timeout, provider models
Common issues:
  • Feature disabled → Run ccs config image-analysis --enable
  • Wrong profile type → Only works with CLIProxy providers
  • CLIProxy not running → Check ccs doctor

​
Analysis Timeout

Error: “Image analysis timeout after 60s” Solutions: 
# Increase timeout for large files
ccs config image-analysis --timeout 180

# Check CLIProxy status
ccs cliproxy status

​
Wrong Model Used

Check provider model: 
ccs config image-analysis
# → Lists provider_models mapping
Update model: 
ccs config image-analysis --set-model gemini gemini-2.5-pro

​
Debug Mode

Enable verbose logging to see hook execution: 
export CCS_DEBUG=1
ccs gemini "analyze this image"
# → Hook logs appear in stderr
Log locations:
  • Hook logs → stderr (when CCS_DEBUG=1)
  • CLIProxy logs → ~/.ccs/logs/cliproxy/

​
Security Considerations

File Size Limit: 10MB maximum per file Local Only: CLIProxy runs on 127.0.0.1:8317 (no external access) API Key: Uses internal CCS-managed key (no user credentials exposed)