team-attention/google-search

Google Search (chromux)

Search Google and optionally extract full page content using a real Chrome browser via chromux. Unlike WebSearch, this uses an actual Chrome instance — same results a human would see, with JavaScript-rendered content and no bot detection.

Runtime Surface

Claude Code

• Use the bundled chromux search script and fall back to WebSearch when chromux is unavailable.

Codex

• Use Bash-first chromux operations. Do not add Hoyeon MCP for v1.
• Resolve the script relative to the Hoyeon plugin root: skills/google-search/vendor/web-search.mjs.
• If chromux is unavailable, use the current Codex web search surface when available and state that enrichment/body/comment extraction is degraded.

When to Use

• User asks to search Google or the web for something
• Need site: operator to search within a specific domain
• Need time-filtered results (past day/week/month/year)
• Need full article body and comments, not just snippets
• WebSearch gives poor results and real browser search would help

Prerequisites

Requires chromux CLI installed. Launch headless Chrome before use:

chromux launch default --headless 2>/dev/null || true

This starts Chrome without a visible window. Skips if already running.

Usage

node ${baseDir}/vendor/web-search.mjs "<query>" [options]

Options

| Flag | Description | Default | |------|-------------|---------| | --site <domain> | Add site: filter (e.g. dev.to, stackoverflow.com) | none | | --time <d\|w\|m\|y> | Time filter: day, week, month, year | none (all time) | | --count <N> | Max results | 10 | | --no-enrich | Skip page visits, return Google snippets only (faster) | enrichment on | | --comments <N> | Max comments to extract per page | 5 | | --body <N> | Max body chars to extract per page | 500 | | --json | Output raw JSON instead of text | text | | --check | Verify chromux is available | - |

Examples

Basic search:

node ${baseDir}/vendor/web-search.mjs "react server components best practices" --count 5

Site-specific search:

node ${baseDir}/vendor/web-search.mjs "authentication patterns" --site stackoverflow.com --count 10

Quick search (snippets only, no page visits):

node ${baseDir}/vendor/web-search.mjs "bun vs deno 2024" --no-enrich --count 10

Time-filtered search:

node ${baseDir}/vendor/web-search.mjs "openai o3 release" --time w --count 5

Full content extraction with JSON output:

node ${baseDir}/vendor/web-search.mjs "claude code tips" --site dev.to --comments 5 --body 1000 --json

Output Format

Text mode (default)

[1] Article Title Here
    URL: https://example.com/article
    Author: John Doe
    Tags: javascript, react
    Body: First 500 chars of article body...
    Comments (3):
      1. commenter1: Comment text here...
      2. commenter2: Another comment...

[2] Another Article
    URL: https://example.com/other
    ...

JSON mode (--json)

Returns an array of objects:

[
  {
    "title": "Article Title",
    "url": "https://example.com/article",
    "snippet": "Google search snippet",
    "author": "John Doe",
    "tags": ["javascript", "react"],
    "body": "Full article body text...",
    "comments": [
      {"author": "commenter1", "text": "Comment text..."}
    ]
  }
]

Fields like author, tags, body, comments are only present when enrichment is enabled. The enrichment extracts content using site-specific JS extractors for Dev.to and Lobsters, with a generic fallback for other sites.

Performance Notes

• No enrichment (--no-enrich): ~3-5 seconds (Google search only)
• With enrichment: ~2-3 seconds per result page (sequential visits)
• For 10 results with enrichment: ~25-35 seconds total
• Use --no-enrich when you only need URLs and snippets
• Use --count to limit results when enrichment is on

Error Handling

| Situation | Behavior | |-----------|----------| | chromux not installed | --check returns available: false | | Google CAPTCHA | Returns 0 results, retry later | | Page load timeout during enrichment | Skips that URL, continues with others | | No results found | Returns empty array/output |

Fallback

If chromux is unavailable, fall back to the built-in WebSearch tool.