tiennm99/ccs
1
0 Fork 0
mirror of https://github.com/tiennm99/ccs.git synced 2026-10-16 06:14:17 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(readme): route user guides to canonical docs

Browse Source
This commit is contained in:
Tam Nhu Tran committed 2026-07-26 09:35:42 -04:00
1 parent fd45c51ed0
commit deb1ed0e67
3 files changed
+56 -378
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/image-analysis.md
+6 -117
View File
@@ -1,119 +1,8 @@
# Image Analysis Configuration Guide
# Image Analysis
CCS provides first-class image and PDF analysis for third-party Claude launches that do not have reliable native vision support.
User setup, routing behavior, and troubleshooting live in the canonical
[Image Analysis guide](https://docs.ccs.kaitran.ca/features/ai/image-analysis).
## 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:
```text
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`:
```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:
```bash
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:
```text
~/.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:
```text
/api/provider/agy/v1/messages
```
Contributor implementation contracts are enforced by the source and focused
tests under `src/utils/image-analysis/`, `src/utils/hooks/`, and
`src/web-server/routes/`.