Image Analysis Tools
Relevant source files
The following files were used as context for generating this wiki page:
The Image Analysis Tools within the CCS project provide a mechanism to intercept file-read operations involving images and PDFs, routing them through vision-capable AI models. Instead of providing raw binary data to a CLI assistant, these tools generate detailed textual descriptions of the visual content, effectively enabling assistants that lack direct vision access to "see" documents and images.
This system operates primarily via a PreToolUse hook that triggers when the Read tool is invoked on supported file types. It leverages CLIProxy providers to perform the actual analysis, ensuring that context windows are not overwhelmed by raw image data while maintaining high accuracy in text extraction and visual element description.
Sources: src/commands/config-image-analysis-command.ts:161-167, tests/e2e/image-analyzer-hook.e2e.test.ts:25-30
Architecture and Data Flow
The image analysis workflow is a multi-step interception process. When a user-facing CLI (like Claude Code) attempts to read a file, the CCS hook evaluates the file extension and size. If the file is a supported image or PDF, the hook blocks the direct read and instead makes a request to a configured vision model via CLIProxy.
The diagram shows the decision logic used by the CCS hook to determine when to trigger a vision-based analysis versus a standard file read.
Sources: tests/e2e/image-analyzer-hook.e2e.test.ts:311-325, src/commands/config-image-analysis-command.ts:161-167
Component Interaction
The analysis relies on several integrated components:
- CCS Hook (
image-analyzer-transformer.cjs): The execution entry point that detectsReadoperations. - CLIProxy: Acts as the bridge to upstream providers (Gemini, Codex, Kiro, etc.) to handle authentication and request formatting.
- Unified Config: Stores user preferences for models, timeouts, and fallback backends.
This sequence illustrates the communication path from the initial tool invocation to the final text injection.
Sources: tests/e2e/image-analyzer-hook.e2e.test.ts:46-90, tests/e2e/image-analyzer-hook.e2e.test.ts:474-500
Configuration and CLI Management
The ccs config image-analysis command allows users to manage the behavior of the vision system. Configuration is stored in ~/.ccs/config.yaml under the image_analysis section.
CLI Options and Features
| Option | Description |
|---|---|
--enable / --disable | Toggles the interception of image/PDF reads. |
--timeout <seconds> | Sets the maximum time allowed for the vision model to respond (default 60s). |
--set-model <p> <m> | Maps a specific provider (e.g., agy) to a vision model (e.g., gemini-3-flash). |
--set-fallback <b> | Defines which backend to use if the primary provider lacks a vision mapping. |
--set-profile-backend | Maps specific CCS profile aliases to dedicated backends. |
Sources: src/commands/config-image-analysis-command.ts:98-112, src/commands/config-image-analysis-command.ts:145-155, tests/unit/management/checks/image-analysis-check.test.ts:100-105
Default Provider Models
The system includes pre-configured defaults for various providers:
- agy:
gemini-3-1-flash-preview - gemini:
gemini-3-flash-preview - codex:
gpt-5.1-codex-mini - kiro:
kiro-claude-haiku-4-5
Sources: tests/e2e/image-analyzer-hook.e2e.test.ts:33-35, src/commands/config-image-analysis-command.ts:125-127
Analysis Prompts and Specifications
The tools utilize specialized prompts to guide the vision models in extracting useful information for developers. These prompts are divided into two main categories:
General Image Analysis
Used for standard images, UI screenshots, and visual elements. The model is instructed to include:
- Overall purpose and content.
- Verbatim text transcription.
- Visual elements (diagrams, UI components, icons).
- Layout and hierarchy.
- Actionable information (buttons, links, code snippets).
Sources: lib/prompts/image-analysis-default.txt:1-12
Document and PDF Analysis
Optimized for technical documents and PDFs, emphasizing structure:
- Tables: Formatted as Markdown tables.
- Structure: Preservation of lists, bullet points, and section organization.
- Metadata: Visible title, type, and document structure.
- Technical Content: Precise extraction of code blocks and flowcharts.
Sources: lib/prompts/image-analysis-document.txt:1-12
Technical Constraints and Validation
To ensure performance and reliability, several constraints are enforced by the image-analyzer-hook:
- File Size Limit: Files exceeding 10MB are blocked with a
permissionDecisionReasonof "File too large" to prevent proxy timeouts or payload issues. - File Type Filtering: Only specific extensions trigger analysis. Non-image files (e.g.,
.ts,.md,.json,.txt) are passed through to the native disk read operation. - Environment Overrides:
CCS_IMAGE_ANALYSIS_SKIP=1: Forces the hook to bypass analysis.CCS_PROFILE_TYPE=account: Disables analysis as account-based profiles are currently optimized for Claude-native flows.
- Connectivity: If CLIProxy is unavailable on the configured port, the hook blocks the request with a "CLIProxy unavailable" error to prevent Claude from attempting to process raw binary image data as text, which would cause context overflow.
Sources: tests/e2e/image-analyzer-hook.e2e.test.ts:311-325, tests/e2e/image-analyzer-hook.e2e.test.ts:355-385, tests/e2e/image-analyzer-hook.e2e.test.ts:440-455
Conclusion
Image Analysis Tools bridge the gap between text-only AI interactions and visual data. By intercepting file reads, validating technical constraints, and leveraging specialized prompts, the system ensures that vision-capable models provide high-quality textual context to the CLI assistant, maintaining efficiency and preventing context corruption.