Match websearch transformer format:
- Header: [Image Analysis via CLIProxy]
- Metadata: File name, size in KB, model used
- Separator lines for better readability
- Footer instruction for Claude
Intercept Read tool calls for image/PDF files and route through CLIProxy
with gemini-2.5-flash for vision analysis. Returns text descriptions
instead of blocking, enabling Claude to "see" images via proxy.
Key changes:
- Add image-analyzer-transformer.cjs hook script
- Add ImageAnalysisConfig type and loader
- Add hook installer and profile injector
- Add prompt templates for analysis customization
- Add e2e test suite (excluded from normal CI runs)
- Configure test:e2e script for manual testing
Environment variables:
- CCS_IMAGE_ANALYSIS_ENABLED: Enable/disable (default: 1)
- CCS_IMAGE_ANALYSIS_MODEL: Vision model (default: gemini-2.5-flash)
- CCS_IMAGE_ANALYSIS_TIMEOUT: Timeout in seconds (default: 60)
- CCS_CLIPROXY_API_KEY: API key for CLIProxy auth
- CCS_CLIPROXY_PORT: CLIProxy port (default: 8317)
Closes#426
Match WebSearch hook pattern:
- ENABLED by default for settings/cliproxy profiles
- DISABLED for native Claude accounts (account/default)
- User can override via config: hooks.block_image_read.enabled: false
This ensures CCS CLI users get context protection out-of-the-box
while native Claude subscription users are unaffected.
Add PreToolUse hook that intercepts Read tool calls on image files
(.png, .jpg, .webp, etc.) and blocks them with helpful message.
This prevents context exhaustion when image generation skills
produce multiple files and the agent tries to read them (each
image can consume 100K+ tokens).
Configuration:
- Enable via config.yaml: hooks.block_image_read.enabled: true
- Or env var: CCS_BLOCK_IMAGE_READ=1
Hook integration:
- lib/hooks/block-image-read.cjs - the hook script
- src/utils/hooks/image-read-block-hook-env.ts - config loader
- Integrated into all spawn locations (ccs.ts, shell-executor,
cliproxy-executor)
Closes#426
On Windows, globally installed CLI tools via npm/pnpm are .cmd/.bat
batch files, not real .exe executables. Node.js spawnSync() without
the shell option cannot execute these files and returns ENOENT error.
Changes:
- Extract isWindows as a global constant at file top
- Add shell: isWindows to all CLI execution spawnSync calls
- Remove duplicate isWindows declaration in isCliAvailable()
Fixes#378
Co-authored-by: Cursor <cursoragent@cursor.com>
Fixes#273
The websearch-transformer hook used hardcoded 'which' command which doesn't
exist on Windows. Now uses process.platform detection to choose 'where' on
Windows and 'which' on Unix systems.
Previously, WebSearch status showed "Ready (Gemini)" when the CLI binary
was installed, misleading users who hadn't authenticated yet.
Changes:
- Add isGeminiAuthenticated() to check ~/.gemini/oauth_creds.json
- Add 'needs_auth' state to WebSearchReadiness type
- Show warning "[!] Gemini: run 'gemini' to login" when not authenticated
- Fix incorrect 'gemini auth login' references (no such command exists)
- Update docs with correct npm install and authentication instructions
WebSearch hook was blocking native Claude accounts (ccs ck, default)
with "No Providers Enabled" message instead of passing through to
server-side WebSearch.
Changes:
- Add shouldSkipHook() detection for account/default profile types
- Fix blocking bug: exit(0) when no providers enabled instead of blocking
- Pass CCS_PROFILE_TYPE and CCS_WEBSEARCH_SKIP env vars for profile-aware behavior
- Add profile type signals to settings, cliproxy, account, and default execution paths
- Add model field to Gemini/OpenCode WebSearch providers
- Config.yaml now explicitly stores model (gemini-2.5-flash, opencode/grok-code)
- UI: blur-to-save for model inputs (no save on every keystroke)
- UI: collapsible install hints inside provider cards
- UI: left accent border for enabled providers (better light theme contrast)
- Hook: use systemMessage for info-styled confirmation
- Hook: cleaner result format without defensive "NOT an error" language
- Hook timeout now computed from max provider timeout + 30s buffer
- Removes hardcoded HOOK_TIMEOUT_SECONDS constant
- ensureHookConfig() now updates timeout when it changes
- Default OpenCode model changed from gpt-5-nano to grok-code
- Default OpenCode timeout changed from 60s to 90s
- Single source of truth: config.yaml controls all timeouts
- Add SHARED_INSTRUCTIONS constant with 7 quality guidelines applied to ALL providers
- Refactor PROVIDER_CONFIG to use toolInstruction (provider-specific) and quirks (optional)
- Add buildPrompt() function to combine shared + provider-specific instructions
- Gemini: google_web_search tool instruction
- OpenCode: built-in capabilities instruction
- Grok: web search + X/Twitter quirk for real-time events
DRY improvement: shared guidelines now maintained in one place
Major refactor of WebSearch hook to:
1. **Respect config.yaml settings**: Hook now reads CCS_WEBSEARCH_GEMINI,
CCS_WEBSEARCH_OPENCODE, CCS_WEBSEARCH_GROK env vars to determine which
providers to use. Only enabled AND installed providers are tried.
2. **Consolidate prompts/models**: Added PROVIDER_CONFIG section at top of
hook file for easy prompt engineering:
- gemini: model + prompt template
- opencode: model (overridable via env) + prompt template
- grok: model + prompt template
3. **Pass provider states via env**: Updated getWebSearchHookEnv() to pass
individual provider enabled states as env vars.
Breaking change: Hook no longer falls back to all installed CLIs. It now
strictly respects config.yaml settings.
Add automatic fallback chain (Gemini -> OpenCode -> Grok) when multiple
WebSearch CLI providers are available. The hook now tries each provider
in order until one succeeds.
Changes:
- Update websearch-transformer.cjs with tryOpenCodeSearch() and tryGrokSearch()
- Implement fallback chain logic in processHook()
- Add outputAllFailedMessage() for when all providers fail
- Update outputNoToolsMessage() with all three install options
- Update config.yaml comments to document OpenCode and fallback behavior
- Add Grok CLI detection (grok-4-cli by lalomorales22) alongside Gemini CLI
- Add WebSearch health check group to health-service.ts
- Update settings UI to show both Gemini and Grok CLI providers
- Add detailed install hints when no WebSearch CLI is installed
- Update API routes to return grokCli status
- Both CLI and dashboard users now see clear installation guidance
Providers:
- Gemini CLI: FREE tier (1000 req/day), no API key needed
- Grok CLI: Requires xAI API key (XAI_API_KEY), web + X search
kaitranntt