python scripts/run.py search.py --query "..." --debug --save

Other Flags

--show-browser - Show browser window (for CAPTCHA solving)

python scripts/run.py search.py --query "..." --show-browser

--output <path> - Custom output file path

python scripts/run.py search.py --query "..." --output result.md

--json - Include JSON metadata in output

python scripts/run.py search.py --query "..." --output result.md --json

Query Optimization Strategy

CRITICAL: Always optimize user queries before execution. Google AI Mode's quality depends on query precision.

Optimization Template

[Technology/Topic] [Version] [Year] ([Specific Aspect 1], [Aspect 2], [Aspect 3]). [Output format request].

Optimization Rules

1. Include Current Year (2026) for up-to-date results
2. Use parentheses to list specific aspects needed
3. Request structured output (tables, comparisons, categorized lists)
4. Include version numbers for library/framework queries

Examples

| User Query | Optimized Query | |-----------|----------------| | "React hooks" | "React hooks best practices 2026 (useState, useEffect, custom hooks, common pitfalls). Provide code examples." | | "What's new in Rust?" | "Rust 1.75 new features 2026 (async traits, impl Trait improvements, const generics, stabilized APIs). Include migration guide and code examples." | | "PostgreSQL vs MySQL performance?" | "PostgreSQL vs MySQL performance comparison 2026 (query optimization, indexing strategies, concurrent writes, JSON handling, scaling patterns). Provide benchmark data and use case recommendations." | | "How to handle errors in Go?" | "Go error handling patterns 2026 (error wrapping, custom errors, sentinel errors, panic vs error, testing error cases). Provide code examples and best practices comparison." | | "Learn FastAPI basics" | "FastAPI tutorial 2026 (routing, dependency injection, async endpoints, request validation with Pydantic, OpenAPI documentation, testing). Include step-by-step implementation guide." |

Note: If user provides an already detailed query with version numbers and requirements, use it as-is.

Workflow

1. Receive user request
2. Optimize query using template above
3. Inform user: "Searching for: '[optimized query]'"
4. Execute search with --save --debug flags
5. Return results with inline citations [1][2][3]

Script Execution

CRITICAL: Always use the run.py wrapper. Direct script execution will fail.

Basic Search

python scripts/run.py search.py --query "Your search query"

Recommended Usage

python scripts/run.py search.py --query "..." --save --debug

The run.py wrapper automatically:

• Creates .venv on first run
• Installs dependencies (patchright, beautifulsoup4, html-to-markdown)
• Activates virtual environment
• Executes search script
• Installs Google Chrome (not Chromium) for anti-detection

How It Works

1. Persistent Browser Context: Uses saved browser profile at ~/.cache/google-ai-mode-skill/chrome_profile to preserve cookies/session between searches
2. Eliminates CAPTCHAs: Persistent context means Google recognizes the browser → rarely triggers CAPTCHA
3. AI Content Detection: Waits for Google AI Overview to appear on page
4. Citation Extraction: Injects JavaScript to extract source links from AI response
5. Markdown Conversion: Converts HTML to markdown with inline citations [1][2][3]
6. Fast Results: Typical search completes in 5-7 seconds (no CAPTCHA)

CAPTCHA Handling

With persistent context, CAPTCHAs are rare. If encountered:

1. Detection: Multi-layer check (URL /sorry/index, page text, content length)
2. Automatic Handling: If CAPTCHA detected in headless mode → script returns CAPTCHA_REQUIRED error
3. Manual Solution: Re-run with --show-browser flag, solve CAPTCHA in browser, script continues automatically

Note: After CAPTCHA is solved once, persistent context preserves the session → future searches won't require CAPTCHA.

Output Format

Returns markdown with inline citations and source list. Example:

React 18 introduces concurrent features including Suspense for data fetching[1],
automatic batching for state updates[2], and transitions for non-urgent updates[3].

---

## Sources:

[1] React 18 Release Notes
https://react.dev/blog/2022/03/29/react-v18

[2] Automatic Batching Explained
https://github.com/reactwg/react-18/discussions/21

[3] Transitions API Documentation
https://react.dev/reference/react/useTransition

Common Use Cases

Finding Library Documentation

python scripts/run.py search.py --query "Prisma ORM 2026 (schema definition, migrations, client API, relation queries, transactions). Include TypeScript examples." --save --debug

Getting Coding Examples

python scripts/run.py search.py --query "WebSocket implementation Node.js 2026 (server setup, client connection, message handling, authentication, reconnection logic). Production-ready code examples." --save

Technical Comparisons

python scripts/run.py search.py --query "GraphQL vs REST API 2026 (performance, caching, tooling, type safety, learning curve). Comparison table with use case recommendations." --save

Best Practices Research

python scripts/run.py search.py --query "Microservices security patterns 2026 (API gateway authentication, service mesh, mutual TLS, secret management, observability). Architecture diagrams and implementation guide." --save --debug

Troubleshooting

| Issue | Solution | |-------|----------| | ModuleNotFoundError | Use run.py wrapper, never execute scripts directly | | CAPTCHA every time | First-time setup: solve CAPTCHA once with --show-browser, then persistent context preserves session | | No AI overview found | Rephrase query with more specificity using optimization template | | Browser fails to start | Verify internet connection and Chrome installation | | Need detailed logs | Use --debug flag - log saved to logs/ folder | | AI Mode not available | Your region/country doesn't support Google AI Mode. Use a proxy/VPN to access from supported regions (US, UK, Germany, etc.) |

Exit Codes:

• 0 - Success
• 1 - General error
• 2 - CAPTCHA required (retry with --show-browser)
• 3 - Browser closed by user
• 4 - AI Mode not available in region (use proxy/VPN)
• 130 - User interrupted (Ctrl+C)

Best Practices

1. Always optimize queries - Specificity determines result quality
2. Use --save --debug for important searches - Preserves results and provides audit trail
3. Include version numbers for library/framework queries
4. Request structured output - Tables and comparisons improve usability
5. Solve CAPTCHA once - Persistent context eliminates future CAPTCHAs
6. Verify citations - Check provided sources for accuracy

Installation • Quick Start • How It Works • MCP Alternative

📋 Last Updates (2026-01-08)

v2.0 - Multi-Language & Detection Overhaul

✅ 4-Stage Completion Detection - SVG thumbs-up → aria-label → text → 40s timeout ✅ Multi-Language Support - Works in DE/EN/NL/ES/FR/IT browser locales ✅ 87% Faster - Average 4s detection (was 30s+) ✅ AI Mode Availability Check - Detects region restrictions with proxy suggestion ✅ 17 Citation Selectors - Language-agnostic fallback chain ✅ 15 Cutoff Markers - Cleaner content extraction across languages

v1.5 - Persistent browser profile, CAPTCHA elimination v1.0 - Initial release with basic Google AI Mode integration

⚠️ Important: Local Claude Code Only

This skill works ONLY with local Claude Code installations, NOT in the web UI.

The web UI runs skills in a sandbox without network access, which this skill requires for browser automation. You must use Claude Code locally on your machine.

What This Is

A Claude Code skill that connects your agent to Google AI Mode—Google's AI-powered search that synthesizes information from dozens of web sources into a single, cited answer.

Instead of Claude reading page after page, Google does the heavy lifting. Claude gets one clean, structured response with inline citations.

The advantage: Free, token-efficient research with grounded sources. No API keys needed.

How It Works

Claude asks a question
         ↓
Skill launches stealth browser
         ↓
Google AI Mode searches & synthesizes dozens of sources
         ↓
Skill extracts AI answer + citations
         ↓
Converts to clean Markdown with [1][2][3] references
         ↓
Claude receives final answer

The key difference:

Traditional web research:

• Claude searches Google → gets 10 links
• Claude reads 5-10 full pages → thousands of tokens consumed
• Claude synthesizes manually → risks missing details or hallucinating
• You pay for all those tokens

With this skill:

• Google AI Mode searches + synthesizes → one request
• Claude receives one clean, cited answer → minimal tokens
• Google's sources are preserved → verifiable, grounded
• It's free (uses public Google Search)

Why This Matters

Google AI Mode (the udm=50 parameter) makes Google search work like a research assistant. It:

• Reads and analyzes dozens of websites automatically
• Synthesizes findings into structured answers
• Cites every claim with source links
• Handles follow-up context across queries

Claude gets the benefits without doing the work—or burning the tokens.

Installation

The simplest installation ever:

# 1. Create skills directory (if it doesn't exist)
mkdir -p ~/.claude/skills

# 2. Clone this repository
cd ~/.claude/skills
git clone https://github.com/PleasePrompto/google-ai-mode-skill google-ai-mode

# 3. That's it! Open Claude Code and say:
"What are my skills?"

When you first use the skill, it automatically:

• Creates an isolated Python environment (.venv)
• Installs all dependencies including Google Chrome
• Sets up browser automation with persistent profile
• Everything stays contained in the skill folder

Note: The setup uses real Chrome (not Chromium) for cross-platform reliability, consistent browser fingerprinting, and better anti-detection with Google services.

Quick Start

1. Check your skills

Say in Claude Code:

"What skills do I have?"

Claude will list your available skills including Google AI Mode.

2. Start researching

"Search Google AI Mode for: Next.js 15 App Router best practices"

"What are the new features in Astro 4.0?"

"Research React Server Components"

Claude will automatically use the skill to query Google AI Mode and return a clean, cited answer.

3. Get better results

Be specific with your queries:

Instead of: "React hooks" Try: "React hooks best practices 2026 (useState, useEffect, custom hooks). Include code examples."

Instead of: "PostgreSQL features" Try: "PostgreSQL 16 JSON features and performance improvements 2026"

First Run: CAPTCHA Handling

On your first query, Google may show a CAPTCHA to verify you're human. This is normal when the browser profile is created.

If Claude reports a CAPTCHA error:

1. Tell Claude: "Run that search with visible browser"
2. The browser will open visibly
3. Solve the CAPTCHA manually
4. The skill continues automatically
5. Next queries will work smoothly without CAPTCHAs

After the first CAPTCHA, searches typically run smoothly. The skill uses a persistent browser profile to eliminate future CAPTCHAs.

How the Skill Works

This is a Claude Code Skill—a local folder containing instructions and scripts that Claude Code can use when needed. Unlike the MCP server version, this runs directly in Claude Code without needing a separate server.

Key Differences from MCP Server

| Feature | This Skill | MCP Server | |---------|------------|------------| | Protocol | Claude Skills | Model Context Protocol | | Installation | Clone to ~/.claude/skills | claude mcp add ... | | Compatibility | Claude Code only (local) | Claude Code, Codex, Cursor, Cline, etc. | | Language | Python | TypeScript | | Browser Profile | Persistent (eliminates CAPTCHAs) | Per-request context | | Distribution | Git clone | npm package |

Architecture

~/.claude/skills/google-ai-mode/
├── SKILL.md              # Instructions for Claude
├── scripts/              # Python automation scripts
│   ├── run.py            # Universal venv wrapper
│   ├── search.py         # Main search implementation
│   ├── browser_utils.py  # Browser automation
│   └── config.py         # Configuration
├── .venv/                # Isolated Python environment (auto-created)
└── results/              # Saved search results (optional)

When Claude needs web research:

1. Loads the skill instructions from SKILL.md
2. Runs the Python search script via run.py wrapper
3. Opens browser with persistent profile (Chrome)
4. Extracts AI answer + citations from Google
5. Returns clean Markdown to Claude
6. Claude uses that knowledge to help with your task

Core Features

Source-Grounded Responses: Google AI Mode synthesizes information from dozens of sources with inline citations. Every claim is backed by a source link.

Direct Integration: No copy-paste between browser and editor. Claude queries and receives answers programmatically.

Persistent Browser Profile: After solving the first CAPTCHA (if any), the browser profile is saved. Future searches run smoothly without interruption.

Zero Configuration: Works out of the box. No API keys, no external services, no configuration files needed.

Self-Contained: Everything runs in the skill folder with an isolated Python environment. No global installations.

Token Efficient: One query returns one synthesized answer instead of Claude reading 5-10 full pages.

Troubleshooting

Skill not found:

# Make sure it's in the right location
ls ~/.claude/skills/google-ai-mode/
# Should show: SKILL.md, scripts/, requirements.txt, etc.

Repeated CAPTCHAs:

If Google keeps showing CAPTCHAs:

• Tell Claude: "Use visible browser for this search"
• Add 10-30 second delays between searches
• Make sure the persistent profile isn't corrupted

Browser won't launch:

Clear the browser profile:

# Linux/macOS
rm -rf ~/.cache/google-ai-mode-skill/chrome_profile

# Windows
rmdir /s "%LOCALAPPDATA%\google-ai-mode-skill\chrome_profile"

Dependencies issues:

# Manual reinstall if needed
cd ~/.claude/skills/google-ai-mode
rm -rf .venv
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
pip install -r requirements.txt
python -m patchright install chrome

Wrong language results:

The skill fo