ccs/docs/websearch.md

WebSearch Configuration Guide

Last Updated: 2026-03-23

CCS provides automatic web search for third-party profiles that cannot access Anthropic's native WebSearch API.

How WebSearch Works

Native Claude Accounts

Native Claude subscription accounts still use Anthropic's server-side WebSearch directly.

Third-Party Profiles

Third-party profiles cannot execute Anthropic's server-side WebSearch because the tool never reaches their backend. CCS now solves that by intercepting WebSearch and running real local search providers directly.

Architecture

┌──────────────────────────────────────────────────────────────┐
│                   Claude Code CLI                           │
│                                                              │
│  WebSearch Tool Request                                      │
│       │                                                      │
│       ├── Native Claude Account? → Anthropic WebSearch API  │
│       │                                                      │
│       └── Third-party Profile? → PreToolUse Hook            │
│                                   │                          │
│                                   ├── 1. Exa Search API      │
│                                   ├── 2. Tavily Search API   │
│                                   ├── 3. Brave Search API    │
│                                   ├── 4. DuckDuckGo HTML     │
│                                   └── 5. Legacy CLI fallback │
│                                      (Gemini/OpenCode/Grok)  │
└──────────────────────────────────────────────────────────────┘

Why This Changed

The previous design asked another model CLI to perform web search and summarize the answer. That was brittle:

• CLI syntax changed upstream
• auth state varied per tool
• prompt/tool behavior drifted across releases

The new flow matches the goclaw model more closely: web search is treated as a first-class deterministic capability, not an LLM-to-LLM workaround.

Providers

Provider	Type	Setup	Default	Notes
Exa	HTTP API	EXA_API_KEY	No	High-quality API search with extracted content
Tavily	HTTP API	TAVILY_API_KEY	No	Agent-oriented search API
DuckDuckGo	HTML fetch	None	Yes	Built-in zero-setup fallback
Brave Search	HTTP API	BRAVE_API_KEY	No	Cleaner snippets and metadata
Gemini CLI	Legacy CLI	npm i -g @google/gemini-cli	No	Optional compatibility fallback
OpenCode	Legacy CLI	curl -fsSL https://opencode.ai/install | bash	No	Optional compatibility fallback
Grok CLI	Legacy CLI	npm i -g @vibe-kit/grok-cli + GROK_API_KEY	No	Optional compatibility fallback

Configuration

Via Dashboard

Open ccs config → Settings → WebSearch.

• Enable Exa, Tavily, Brave, or DuckDuckGo in the backend chain
• Export the matching API key first for Exa, Tavily, or Brave
• Review whether any legacy fallback CLIs are still enabled in config

Via Config File

Edit ~/.ccs/config.yaml:

websearch:
  enabled: true
  providers:
    exa:
      enabled: false
      max_results: 5
    tavily:
      enabled: false
      max_results: 5
    duckduckgo:
      enabled: true
      max_results: 5
    brave:
      enabled: false
      max_results: 5
    gemini:
      enabled: false
      model: gemini-2.5-flash
      timeout: 55
    opencode:
      enabled: false
      model: opencode/grok-code
      timeout: 90
    grok:
      enabled: false
      timeout: 55

Environment Variables

Variable	Description
EXA_API_KEY	Enables Exa when providers.exa.enabled: true
TAVILY_API_KEY	Enables Tavily when providers.tavily.enabled: true
BRAVE_API_KEY	Enables Brave Search when providers.brave.enabled: true
GROK_API_KEY	Required only for legacy Grok CLI fallback
CCS_WEBSEARCH_SKIP	Skip hook entirely
CCS_DEBUG	Verbose hook logging

Troubleshooting

WebSearch says "Ready (DuckDuckGo)"

That is expected. DuckDuckGo is the default zero-setup backend.

Exa, Tavily, or Brave is enabled but not ready

Export the matching API key in the environment that launches CCS, then refresh status:

export EXA_API_KEY="your-api-key"
# or: export TAVILY_API_KEY="your-api-key"
# or: export BRAVE_API_KEY="your-api-key"
ccs config

I still want Gemini/OpenCode/Grok fallback

Those providers remain supported, but they are no longer the primary path. Enable them explicitly in config.yaml if you want them as last-resort fallback.

WebSearch returns no results

1. Check websearch.enabled: true
2. Keep DuckDuckGo enabled unless you have a strong reason to disable it
3. If using Exa, Tavily, or Brave, verify the matching API key
4. Run with CCS_DEBUG=1 for hook logs

Security Considerations

• API keys stay in environment variables, not in dashboard state
• Never commit API keys to version control
• Use shell profile or .env tooling with proper permissions