ccs/docs/image-analysis.md

Image Analysis Configuration Guide

CCS provides first-class image and PDF analysis for third-party Claude launches that do not have reliable native vision support.

How Image Analysis Works

Native Claude accounts keep Anthropic's own vision flow.

Third-party profiles now use a CCS-managed local MCP tool named ImageAnalysis when the runtime is available. CCS also appends a short steering hint so Claude prefers that tool over Read for local image and PDF files.

Healthy Claude-target launches suppress the legacy CCS Read hook so MCP stays authoritative. If the managed runtime cannot be provisioned, CCS keeps the old Read hook available only as a compatibility fallback when that path is still viable. If runtime/auth/proxy readiness is degraded beyond that, CCS falls back to native Read instead of failing the whole launch.

Routing Model

ImageAnalysis requests go straight to the CCS-managed provider route:

Claude -> ccs-image-analysis MCP -> CCS provider route -> /api/provider/<backend>/v1/messages

Important:

• CCS does not relay image analysis through Claude Code, another CLI, or a second model wrapper.
• For bridge-backed settings profiles, CCS resolves the backend and provider path before launch.
• CCS avoids leaking a profile's ordinary third-party ANTHROPIC_BASE_URL or token into image analysis unless that profile is explicitly using a CLIProxy bridge.

Profile Behavior

Profile Type	Image Method
Claude default / account	Native Claude vision / native Read
Third-party settings / CLIProxy / Copilot	CCS local ImageAnalysis MCP tool when ready
Third-party when MCP provisioning fails but provider-backed analysis is still viable	Legacy CCS Read hook fallback
Third-party when runtime/auth/proxy is unavailable	Native Read fallback

Configuration

Configure via dashboard (Settings -> Image) or ~/.ccs/config.yaml:

image_analysis:
  enabled: true
  timeout: 60
  fallback_backend: agy
  provider_models:
    agy: gemini-3-1-flash-preview
    codex: gpt-5.1-codex-mini
    ghcp: claude-haiku-4.5

Useful commands:

ccs config image-analysis
ccs config image-analysis --enable
ccs config image-analysis --disable
ccs config image-analysis --set-fallback agy
ccs config image-analysis --set-profile-backend glm agy
ccs config image-analysis --clear-profile-backend glm

Prompt Templates

CCS installs editable prompt templates at:

~/.ccs/prompts/image-analysis/

Templates:

• default.txt
• screenshot.txt
• document.txt

CCS automatically selects screenshot for screenshot-like filenames, document for PDFs, and default otherwise.

Runtime Environment

Key runtime env vars:

Variable	Purpose
CCS_IMAGE_ANALYSIS_SKIP	Disable image analysis for the current launch
CCS_IMAGE_ANALYSIS_SKIP_HOOK	Suppress only the legacy CCS Read hook while keeping MCP ImageAnalysis 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 image-analysis model
CCS_DEBUG	Verbose runtime logging

Self-Heal

CCS now auto-heals stale managed image-analysis state in three places:

• Healthy Claude launches remove stale CCS-managed image Read hooks from the active profile settings before launch.
• Settings -> Image save/provisioning repairs managed MCP runtime files, syncs managed MCP entries into isolated Claude config dirs, and cleans stale CCS-managed image hooks from ~/.ccs/*.settings.json.
• ccs doctor --fix repairs invalid image-analysis config, removes stale CCS-managed image hooks, and resyncs managed ccs-image-analysis MCP entries into isolated configs.

Troubleshooting

Claude still uses Read

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

ImageAnalysis is not exposed

• Verify CLIProxy auth for the resolved backend
• Verify the local or remote CLIProxy target is reachable
• Check ~/.claude.json and inherited account configs for ccs-image-analysis

I need to prove requests are going directly to the provider route

Run with CCS_DEBUG=1 and inspect the resolved runtime path. The request target should be provider-scoped, for example:

/api/provider/agy/v1/messages