WebSearch Fallback

Third-party profiles cannot use Anthropic’s native WebSearch. CCS provides automatic web search via CLI tools with intelligent fallback.

Overview

CCS intercepts WebSearch requests from Claude Code and routes them through available CLI tools.

Dark Theme
Light Theme

How It Works

Profile Type	WebSearch Method
Claude (native)	Anthropic WebSearch API
Third-party profiles	CLI Tool Fallback Chain

Fallback Chain

CCS tries tools in priority order until one succeeds:

Priority	Tool	Auth	Install
1st	Gemini CLI	OAuth (free)	`npm install -g @google/gemini-cli`
2nd	OpenCode	OAuth (free)	`curl -fsSL https://opencode.ai/install \| bash`
3rd	Grok CLI	API Key	`npm install -g @vibe-kit/grok-cli`

Configuration

Configure via dashboard (Settings page) or ~/.ccs/config.yaml:

websearch:
  enabled: true                    # Enable/disable (default: true)
  providers:
    gemini:
      enabled: true                # Use Gemini CLI (default: true)
      model: gemini-2.5-flash      # Model to use
    opencode:
      enabled: true                # Use OpenCode as fallback
    grok:
      enabled: false               # Requires XAI_API_KEY

CCS resolves one configuration snapshot for each new Claude launch. Provisioning, hook environment, and steering for that launch all use the same snapshot; a later config edit does not change the already prepared session. If you set websearch.enabled: false, third-party Claude launches still keep native WebSearch disallowed. CCS omits its steering prompt and marks the managed hook to skip execution for that launch, so no active WebSearch hook state or provider fallback runs.

Setup

Install Gemini CLI

npm install -g @google/gemini-cli

Authenticate

Run once to complete OAuth:

gemini

Verify

Check that websearch works:

ccs codex "search for the latest TypeScript features"

Provider Details

Gemini CLI (Recommended)

Auth: Free Google OAuth
Limit: 1000 requests/day
Quality: Excellent search relevance
Setup: gemini to authenticate via browser

OpenCode

Auth: Free OAuth
Limit: Varies
Quality: Good for code-related searches
Setup: Follow installer prompts

Grok CLI

Auth: Requires XAI_API_KEY
Limit: Based on API plan
Quality: Real-time web access
Setup: Set env var and install

Troubleshooting

Search not working

Verify CLI tools are installed:

which gemini opencode grok

Auth errors

Re-authenticate the failing tool:

gemini  # Opens browser for OAuth

Slow responses

Switch to a faster fallback:

websearch:
  providers:
    gemini:
      model: gemini-2.0-flash-lite

Gemini CLI is recommended - free OAuth authentication with 1000 requests/day. Just run gemini once to authenticate via browser.

Getting Started

Providers

Features

Tutorials

WebSearch

WebSearch Fallback

Overview

How It Works

Fallback Chain

Configuration

Setup

Provider Details

Troubleshooting

​WebSearch Fallback

​Overview

​How It Works

​Fallback Chain

​Configuration

​Setup

​Provider Details

​Troubleshooting

WebSearch Fallback

Overview

How It Works

Fallback Chain

Configuration

Setup

Provider Details

Troubleshooting