> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ccs.kaitran.ca/llms.txt
> Use this file to discover all available pages before exploring further.

# Image Analysis

> MCP-first image and PDF analysis for third-party CCS launches

# 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:

```text theme={null}
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

```bash theme={null}
# 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

```yaml theme={null}
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:

```text theme={null}
~/.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:

| 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:

```text theme={null}
/api/provider/agy/v1/messages
```

## Related

* [CLIProxy API](/features/proxy/cliproxy-api)
* [WebSearch](/features/ai/websearch)