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.