god-search

Free/no-key search sidecar for AI agents. Multi-engine local search over browser-backed public engines and public JSON APIs, with optional provider keys. MCP, HTTP, and CLI.

$ god-search "rust async runtime" --limit 3

  ✓ ddg  ✓ bing  ✓ google  ✓ reddit  ✓ github  ✓ stackoverflow  ✓ wiki
  ⚡ fast-path results · cache-aware merge

  #1  score=28  doc.rust-lang.org
      Async in Rust — official async/await guide

  #2  score=21  tokio.rs
      Tokio — An asynchronous runtime for Rust

  #3  score=18  rust-lang.github.io
      Asynchronous Programming in Rust — async book

Why god-search

• No required API keys by default - built around CloakBrowser search adapters and public JSON APIs
• Agent search sidecar - run it once beside Codex, Claude Code, Cursor, OpenCode, Hermes, or your own agent
• Multi-engine by default - DDG, Bing, Google, Reddit, GitHub, Stack Overflow, Hacker News, npm, and Wikipedia without credentials; Brave is available as opt-in scrape/API mode
• Fast-path and settled responses - return fast user-visible results by default, or use --settled / settled benchmark mode when an agent needs every background engine to finish
• Compact agent output - CLI, HTTP, and MCP surfaces return small, merge-ranked result objects instead of page dumps
• Transparent degradation - challenged or rate-limited engines are reported as degraded instead of being hidden
• Optional paid/provider keys - add Brave API or other providers when you want more quota or fewer public-engine constraints

Honest Scope

god-search is designed to become the best free/no-key agent search sidecar, but the benchmark evidence is not strong enough to claim "best" yet.

What is true today:

• It works locally without mandatory API keys.
• It gives agents one CLI/HTTP/MCP contract for search, extraction, health, and caching.
• It can be cheaper and easier to run than a paid search API for many agent workflows.
• It degrades openly when public engines challenge, rate-limit, or fail.

What is not true:

• It is not an unlimited search API. Public engines can throttle, CAPTCHA, change markup, or block automation.
• It is not proven to beat every paid provider. Current qrels are shallow and must be expanded before public leaderboard claims.
• It is not fully public-release hardened. Browser resilience, authenticated provider support, degradation metadata, CI, and release polish remain on the roadmap.

Benchmark Status

Current positioning: free/no-key, local, agent-native search and extraction sidecar with optional provider keys, caching, compact responses, and transparent degradation.

Do not claim "best" or "unlimited" from the current benchmark. The latest no-key live run is useful engineering evidence for the no-key sidecar direction, but the qrels are still shallow: coverage is 0.337 at depth 20, and unjudged URLs are scored as 0.

Latest no-key live snapshot, generated by node benchmark/run.js --no-key --qrels benchmark/runs/latest-no-key/qrels.auto.tsv and written to benchmark/runs/latest-no-key/:

| System | Profile | Valid | nDCG@10 | Strict nDCG@10 | MRR@10 | P@5 | Recall@20 | p95 ms | Errors | |---|---|---:|---:|---:|---:|---:|---:|---:|---:| | god-search-default-fast | fast/user-visible | 1.000 | 0.722 | 0.511 | 0.962 | 0.600 | 0.745 | 1517 | 0 | | god-search-default-settled | settled/full | 1.000 | 0.673 | 0.495 | 0.904 | 0.515 | 0.769 | 3507 | 0 |

Provider/API baselines are skipped in the latest snapshot because no paid/API keys were set. Use npm run benchmark:live with keys only when you want a paid-provider comparison.

Latest offline fixture regression, generated by npm run benchmark and written to benchmark/runs/latest-offline/: nDCG@10 0.980, MRR@10 1.000, P@5 0.623, Recall@20 1.000.

Next proof step: judge benchmark/runs/latest-no-key/blind-judging-pool.jsonl, convert it with benchmark/scripts/pool-to-qrels.js --base benchmark/fixtures/qrels.tsv, then rerun npm run benchmark:no-key against the expanded qrels before making stronger quality claims.

Simplest Powerful Plan

The current target is the best free/no-key search sidecar for agents. Paid provider keys stay optional and are not part of the default quality claim.

Current no-key score:

• Fast profile: nDCG@10 0.722, Strict nDCG@10 0.511, MRR@10 0.962, P@5 0.600, Recall@20 0.745, p95 1517ms, errors 0
• Settled profile: nDCG@10 0.673, Strict nDCG@10 0.495, MRR@10 0.904, P@5 0.515, Recall@20 0.769, p95 3507ms, errors 0
• Offline fixture regression: nDCG@10 0.980, MRR@10 1.000, P@5 0.623, Recall@20 1.000

The live score is conservative because the qrels are shallow: only 0.337 of depth-20 qrels are covered, and unjudged results count as zero. The next optimization work should use judged failures, not guesses.

Next actions, in order:

1. Judge benchmark/runs/latest-no-key/blind-judging-pool.jsonl and convert it to pooled qrels.
2. Rerun npm run benchmark:no-key and compare fast vs settled profiles.
3. Tune the largest judged miss categories, especially docs coverage and unjudged-result handling.
4. Expand the no-key benchmark beyond the current 26-query proof set before making public quality claims.
5. Add only high-signal free verticals where they improve measured results, such as arXiv for papers, PyPI for Python packages, and MDN/package docs for developer documentation.

Do not add more engines just to increase engine count. Every new source should improve judged nDCG@10, MRR@10, or useful success without increasing silent failures.

Roadmap

• Expand pooled benchmark judgments until the "best free/no-key agent search sidecar" claim can be proven or rejected.
• Harden browser-engine retries, isolation, and circuit breaking under repeated agent workloads.
• Add authenticated provider paths where they materially improve quota or reliability.
• Make degradation metadata precise enough for agents to decide whether to trust, wait, retry, or fall back.
• Add CI, release checks, and public contribution docs before calling the repo fully public-ready.

Requirements

• Node.js 18+
• Linux / macOS (CloakBrowser headless Chromium)

Install

npm install -g god-search   # npm
pnpm add -g god-search      # pnpm
bun install --global god-search  # bun

# no install needed
npx god-search "your query"
bunx god-search "your query"

Quick Start

god-search "rust async runtime"

{
  "query": "rust async runtime",
  "results": [
    {
      "title": "Tokio",
      "url": "https://tokio.rs",
      "snippet": "Tokio is an asynchronous runtime for Rust...",
      "score": 21,
      "engines": ["ddg", "bing", "google"],
      "rank": 1
    }
  ],
  "total": 10
}

# Only the fields you need
god-search "rust async runtime" --limit 5 --fields=title,url,score

# Wait for background browser/API engines before returning
god-search "rust async runtime" --settled --limit 5

# Extract full page text
god-search extract https://tokio.rs

HTTP Daemon

Start once — browser stays warm, all searches reuse it:

god-search serve
# ✓ listening on http://127.0.0.1:3847

# Search
curl -s http://127.0.0.1:3847/search \
  -H 'Content-Type: application/json' \
  -d '{"query":"rust async runtime","limit":5}'

# Extract full page text
curl -s http://127.0.0.1:3847/extract \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://tokio.rs"}'

# Health check
curl -s http://127.0.0.1:3847/health

# OpenAPI contract
curl -s http://127.0.0.1:3847/openapi.json

Auto-start on login

mkdir -p ~/.config/systemd/user
curl -sO https://raw.githubusercontent.com/crackion-com/god-search/main/god-search.service
mv god-search.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now god-search

CLI Reference

| Command | Description | |---|---| | god-search "query" | Search — compact JSON to stdout | | god-search "query" --limit N | Limit results (default: 10) | | god-search "query" --fields=title,url,score | Return only specified fields | | god-search "query" --verbose | Include engine stats + elapsed time | | god-search extract <url> | Extract clean text from any URL | | god-search serve | Start HTTP daemon on port 3847 | | god-search mcp | Start MCP stdio server |

Hermes

Use god-search with Hermes as an MCP server, not as web.backend.

mcp_servers:
  god_search:
    command: "node"
    args: ["/absolute/path/to/god-search/index.js", "mcp"]
    tools:
      include: [god_search, god_extract, god_health]

Then enable the mcp-god_search toolset in Hermes and reload MCP.

Why this is the right integration:

• Hermes built-in web.backend only supports firecrawl, parallel, tavily, and exa
• god-search already exposes a clean MCP surface and a simple HTTP JSON contract
• this keeps god-search as a local search sidecar instead of forcing Hermes core changes

AI Agents (Codex, Claude Code, Cursor, OpenCode)

god-search is built for agents. There are now three supported integration modes:

• MCP for agents that want typed tools
• HTTP for agents that want a low-friction JSON API
• CLI for shell-driven agents and human debugging

The HTTP daemon keeps the browser warm and avoids starting a new browser for each request.

# Search
curl -s http://127.0.0.1:3847/search \
  -H 'Content-Type: application/json' \
  -d '{"query":"anthropic claude api","limit":5}'

# Extract a page
curl -s http://127.0.0.1:3847/extract \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://docs.anthropic.com"}'

# Add god-search as an agent skill (one-time)
cp node_modules/god-search/SKILL.md .claude/rules/god-search.md
# or
cp node_modules/god-search/SKILL.md .cursor/skills/god-search.md

If daemon is down: systemctl --user start god-search

MCP

{
  "mcpServers": {
    "god-search": {
      "command": "god-search",
      "args": ["mcp"]
    }
  }
}

MCP tools:

• god_search
• god_extract
• god_health

HTTP

HTTP routes:

• GET /health
• GET /openapi.json
• POST /search
• POST /extract

/health returns daemon, cache, browser, and runtime state. /openapi.json exposes the machine-readable contract for HTTP clients.

Engines

| Engine | Type | Best for | |---|---|---| | DuckDuckGo | CloakBrowser | Fast general results | | Brave | CloakBrowser or Brave Search API | Technical queries. Challenge-prone in scrape mode, disabled by default in merged search | | Bing | CloakBrowser | Broad coverage | | Google | CloakBrowser | Highest quality (CAPTCHA-prone) | | Reddit | JSON API | Community discussions | | GitHub | JSON API | Code & repositories | | Wikipedia | JSON API | Definitions & facts |

Brave is available but not included in the default merged engine set unless you explicitly enable it:

GOD_SEARCH_ENABLE_BRAVE=true

If you want Brave without bot-detection issues, set a Brave Search API key and let auto mode use the official API:

BRAVE_SEARCH_API_KEY=...
GOD_SEARCH_BRAVE_MODE=auto   # auto | api | scrape

When BRAVE_SEARCH_API_KEY is present, auto mode prefers:

https://api.search.brave.com/res/v1/web/search

Source:

• Brave Search API docs: https://brave.com/search/api/

How It Works

query → 6 engines fire in parallel (default — Brave disabled unless GOD_SEARCH_ENABLE_BRAVE=true)
         ├── Reddit ────┐
         ├── Wikipedia ─┤  fast path: JSON API engines
         ├── GitHub ────┘  fast-path: quality-aware (intent + confidence + elapsed)
         ├── DDG ───────── background: CloakBrowser, finish + update cache
         ├── Bing ───────── background: CloakBrowser, finish + update cache
         └── Google ──────── background: CloakBrowser, finish + update cache

         [+ Brave]  opt-in: GOD_SEARCH_ENABLE_BRAVE=true (scrape) or BRAVE_SEARCH_API_KEY=... (API)

results → cross-engine boost (+4/+8/+12 for shared URLs)
        → domain diversity (max 2 per domain)
        → score sort → return top N

• LRU-TTL cache — 256 entries, 10min TTL; recent merged results are reused when available
• Browser isolation — withBrowserPage() throttles to 2 concurrent CloakBrowser pages, prevents crashes
• Auto-reconnect — browser restarts automatically on disconnect

MCP (opt-in)

For environments that require typed tool discovery, use the MCP server above.

Runtime Configuration

god-search can be tuned without code edits:

GOD_SEARCH_HOST=127.0.0.1
GOD_SEARCH_PORT=3847
GOD_SEARCH_CACHE_TTL_MS=600000
GOD_SEARCH_CACHE_MAX_ENTRIES=256
GOD_SEARCH_FAST_PATH_MS=2000
GOD_SEARCH_FAST_PATH_MAX_MS=4500
GOD_SEARCH_FAST_PATH_POLL_MS=100
GOD_SEARCH_FAST_PATH_MIN_ENGINES=4
GOD_SEARCH_MAX_NAV=2
GOD_SEARCH_PREWARM_BROWSER=false
GOD_SEARCH_SEARCH_TIMEOUT_MS=10000
GOD_SEARCH_API_TIMEOUT_MS=8000
GOD_SEARCH_EXTRACT_TIMEOUT_MS=15000
GOD_SEARCH_MAX_CONTENT_CHARS=50000
GOD_SEARCH_MCP_HEALTH_TOOL=true
GOD_SEARCH_ENABLE_BRAVE=false
GOD_SEARCH_BRAVE_MODE=auto
BRAVE_SEARCH_API_KEY=
GOD_SEARCH_BRAVE_COUNTRY=us
GOD_SEARCH_BRAVE_SEARCH_LANG=en

The sample god-search.service now supports an optional environment file:

~/.config/god-search.env

License

MIT © crackion