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 type	Behavior
Claude `default` / `account`	Native Claude vision or native `Read`
Third-party settings, CLIProxy, Copilot	Managed `ImageAnalysis` MCP when ready
Third-party with degraded MCP but usable provider-backed analysis	Legacy CCS `Read` hook compatibility fallback
Third-party with runtime/auth/proxy failure	Native `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:

Healthy Claude-target launches remove stale CCS-managed image hooks from the active profile settings before launch.
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.
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:

Variable	Purpose
`CCS_IMAGE_ANALYSIS_SKIP`	Disable image analysis for the current launch
`CCS_IMAGE_ANALYSIS_SKIP_HOOK`	Suppress only the legacy `Read` hook while keeping MCP available
`CCS_IMAGE_ANALYSIS_RUNTIME_BASE_URL`	Explicit CCS runtime base URL
`CCS_IMAGE_ANALYSIS_RUNTIME_PATH`	Provider route such as `/api/provider/agy`
`CCS_IMAGE_ANALYSIS_RUNTIME_API_KEY`	Explicit CCS runtime auth key
`CCS_IMAGE_ANALYSIS_MODEL`	Force a single model for the launch
`CCS_DEBUG`	Verbose 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

Getting Started

Providers

Features

Tutorials

Image Analysis

Image Analysis

Overview

Launch Behavior

Quick Start

Configuration

Prompt Templates

What CCS Repairs Automatically

Runtime Details

Troubleshooting

Claude still uses `Read`

ImageAnalysis is not exposed

The wrong backend or model is being used

I need proof that requests go directly to the provider route

​Image Analysis

​Overview

​Launch Behavior

​Quick Start

​Configuration

​Prompt Templates

​What CCS Repairs Automatically

​Runtime Details

​Troubleshooting

​Claude still uses Read

​ImageAnalysis is not exposed

​The wrong backend or model is being used

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

​Related

Image Analysis

Overview

Launch Behavior

Quick Start

Configuration

Prompt Templates

What CCS Repairs Automatically

Runtime Details

Troubleshooting

Claude still uses `Read`

ImageAnalysis is not exposed

The wrong backend or model is being used

I need proof that requests go directly to the provider route

Related