Skip to main content

​
Image Analysis

CCS provides first-class image and PDF analysis for third-party launches that do not have reliable native vision support. Native Claude accounts keep Anthropic’s built-in image flow; third-party routes get a CCS-managed local ImageAnalysis MCP tool when the runtime is healthy. Supported file types include common image formats such as .jpg, .png, .webp, .gif, .heic, .bmp, .tiff, plus .pdf.

​
Overview

The current routing model is MCP-first: 
Claude -> ccs-image-analysis MCP -> CCS provider route -> /api/provider/<backend>/v1/messages
CCS also appends a short steering hint so Claude prefers ImageAnalysis over raw Read for local images and PDFs.

​
Launch Behavior

Profile typeBehavior
Claude default / accountNative Claude vision or native Read
Third-party settings, CLIProxy, CopilotManaged ImageAnalysis MCP when ready
Third-party with degraded MCP but usable provider-backed analysisLegacy CCS Read hook compatibility fallback
Third-party with runtime/auth/proxy failureNative Read fallback
Healthy Claude-target launches suppress the legacy CCS image Read hook so the managed MCP tool stays authoritative.

​
Quick Start

# Inspect current image-analysis state
ccs config image-analysis

# Enable or disable globally
ccs config image-analysis --enable
ccs config image-analysis --disable

# Increase timeout for large documents
ccs config image-analysis --timeout 120

# Set provider-specific models
ccs config image-analysis --set-model agy gemini-3-1-flash-preview
ccs config image-analysis --set-model codex gpt-5.1-codex-mini

# Pick a fallback backend for bridge-backed profiles
ccs config image-analysis --set-fallback agy

# Override the backend for a specific settings profile
ccs config image-analysis --set-profile-backend glm agy
ccs config image-analysis --clear-profile-backend glm

​
Configuration

image_analysis:
  enabled: true
  timeout: 60
  fallback_backend: gemini
  provider_models:
    agy: gemini-3-1-flash-preview
    codex: gpt-5.1-codex-mini
  profile_backends:
    glm: agy

​
Prompt Templates

CCS installs editable prompt templates under: 
~/.ccs/prompts/image-analysis/
Templates:
  • default.txt
  • screenshot.txt
  • document.txt
CCS automatically selects the screenshot template for screenshot-like filenames, the document template for PDFs, and the default template otherwise.

​
What CCS Repairs Automatically

CCS now self-heals stale managed image-analysis state in three places:
  1. Healthy Claude-target launches remove stale CCS-managed image hooks from the active profile settings before launch.
  2. Saving or provisioning from Settings -> Image repairs the managed MCP runtime files, syncs the ccs-image-analysis entry into isolated Claude configs, and removes stale CCS-managed hooks from ~/.ccs/*.settings.json.
  3. ccs doctor --fix repairs invalid image-analysis config, removes stale CCS-managed hooks, and resyncs the managed MCP entry into isolated configs.

​
Runtime Details

Key runtime environment variables:
VariablePurpose
CCS_IMAGE_ANALYSIS_SKIPDisable image analysis for the current launch
CCS_IMAGE_ANALYSIS_SKIP_HOOKSuppress only the legacy Read hook while keeping MCP available
CCS_IMAGE_ANALYSIS_RUNTIME_BASE_URLExplicit CCS runtime base URL
CCS_IMAGE_ANALYSIS_RUNTIME_PATHProvider route such as /api/provider/agy
CCS_IMAGE_ANALYSIS_RUNTIME_API_KEYExplicit CCS runtime auth key
CCS_IMAGE_ANALYSIS_MODELForce a single model for the launch
CCS_DEBUGVerbose runtime logging

​
Troubleshooting

​
Claude still uses Read

  • Confirm ccs config image-analysis still shows enabled: true
  • Check the active profile resolves to a usable backend
  • Run ccs doctor --fix to repair stale managed hooks or missing MCP sync
  • Run with CCS_DEBUG=1 to inspect runtime preparation

​
ImageAnalysis is not exposed

  • Verify the resolved backend is authenticated
  • Verify the local or remote CLIProxy target is reachable
  • Check inherited Claude config directories for the managed ccs-image-analysis MCP entry

​
The wrong backend or model is being used

  • Inspect fallback_backend and profile_backends in ccs config image-analysis
  • Check whether the profile is bridge-backed or using a direct CLIProxy provider
  • Set an explicit provider model with --set-model if the default is not what you want

​
I need proof that requests go directly to the provider route

Run with CCS_DEBUG=1 and inspect the resolved runtime path. It should target a provider-scoped route such as: 
/api/provider/agy/v1/messages