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

# WebSearch

> Web search fallback for third-party providers

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

<Tabs>
  <Tab title="Dark Theme">
    <Frame>
      <img src="https://mintcdn.com/ccs-7e541244/ZIh-b3XKOoSIE-qm/assets/screenshots/websearch.webp?fit=max&auto=format&n=ZIh-b3XKOoSIE-qm&q=85&s=a7c221c86fb69f8a40fd004b28dfb502" alt="WebSearch Configuration - Dark" width="4336" height="2806" data-path="assets/screenshots/websearch.webp" />
    </Frame>
  </Tab>

  <Tab title="Light Theme">
    <Frame>
      <img src="https://mintcdn.com/ccs-7e541244/ZIh-b3XKOoSIE-qm/assets/screenshots/websearch-light.webp?fit=max&auto=format&n=ZIh-b3XKOoSIE-qm&q=85&s=133e84ddab7e1385e86b577a97949f6e" alt="WebSearch Configuration - Light" width="4336" height="2806" data-path="assets/screenshots/websearch-light.webp" />
    </Frame>
  </Tab>
</Tabs>

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

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

## Setup

<Steps>
  <Step title="Install Gemini CLI">
    ```bash theme={null}
    npm install -g @google/gemini-cli
    ```
  </Step>

  <Step title="Authenticate">
    Run once to complete OAuth:

    ```bash theme={null}
    gemini
    ```
  </Step>

  <Step title="Verify">
    Check that websearch works:

    ```bash theme={null}
    ccs codex "search for the latest TypeScript features"
    ```
  </Step>
</Steps>

## Provider Details

<AccordionGroup>
  <Accordion title="Gemini CLI (Recommended)">
    * **Auth**: Free Google OAuth
    * **Limit**: 1000 requests/day
    * **Quality**: Excellent search relevance
    * **Setup**: `gemini` to authenticate via browser
  </Accordion>

  <Accordion title="OpenCode">
    * **Auth**: Free OAuth
    * **Limit**: Varies
    * **Quality**: Good for code-related searches
    * **Setup**: Follow installer prompts
  </Accordion>

  <Accordion title="Grok CLI">
    * **Auth**: Requires `XAI_API_KEY`
    * **Limit**: Based on API plan
    * **Quality**: Real-time web access
    * **Setup**: Set env var and install
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Search not working">
    Verify CLI tools are installed:

    ```bash theme={null}
    which gemini opencode grok
    ```
  </Accordion>

  <Accordion title="Auth errors">
    Re-authenticate the failing tool:

    ```bash theme={null}
    gemini  # Opens browser for OAuth
    ```
  </Accordion>

  <Accordion title="Slow responses">
    Switch to a faster fallback:

    ```yaml theme={null}
    websearch:
      providers:
        gemini:
          model: gemini-2.0-flash-lite
    ```
  </Accordion>
</AccordionGroup>

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