Gemini Research

Deep web research using Gemini CLI with Google Search grounding. Cost-effective alternative to expensive research APIs.

Overview

Leverage Gemini CLI's built-in Google Search grounding (google_web_search) to fetch real-time information with citations. Returns structured JSON for Claude to analyze and synthesize.

Key advantages:

•Free tier: 60 requests/min, 1000/day
•1M-token context window (Gemini 2.5 Pro)
•Built-in Google Search grounding
•Structured JSON output with citations
•Real-time data (news, docs, tutorials)

Prerequisites

Gemini CLI installed:

bash

npm install -g @google/gemini-cli

Authentication: First run requires Google login (any account works):

bash

gemini -p "test" --output-format json

Follow browser auth flow. Free Code Assist license included.

Verify installation:

bash

gemini --version

Usage

When user asks to:

•"Research X using Google Search"
•"Find real-world examples of X"
•"Get latest information about X"
•"Deep research on X with sources"

Run the skill wrapper with appropriate mode.

⚠️ CRITICAL WORKFLOW STEP

EVERY TIME this skill runs, Claude MUST complete these steps:

•Wait for research to complete - Script outputs markdown file path
•Read the generated markdown file - Use Read tool on the path shown
•Analyze the research findings - Extract key learnings, patterns, recommendations
•Append Claude's Analysis section - Use Edit tool to replace the placeholder
•Present findings to user - Summarize the analysis in chat

This is NOT optional. The markdown file contains a placeholder section that MUST be populated. Skipping this step leaves incomplete documentation.

Example Analysis Format

Your analysis should include:

•Key Learnings: 3-5 main takeaways from the research
•Recommendations: Practical advice based on findings
•Next Steps: Suggested actions or areas for further investigation
•Relevance: How findings apply to the specific context

Concrete Example

After research completes and you read the markdown file at docs/research/google/20250111123456-topic.md:

Use Edit tool to replace placeholder:

markdown

old_string: ## Claude's Analysis

_This section will be populated by Claude after analyzing the research findings._


new_string: ## Claude's Analysis

### Key Learnings
- Main finding 1 with context and implications
- Main finding 2 showing clear patterns across sources
- Main finding 3 connecting to broader best practices

### Recommendations
- Actionable advice based on finding 1
- Practical suggestion derived from finding 2
- Trade-off to consider from contradictory sources

### Next Steps
- Specific area to investigate further if needed
- Potential application to current project/context

Then present summary to user in chat response.

Research Modes

1. Quick Research (default)

Fast overview with 5-8 sources.

bash

bash plugins/knowledge-work/skills/gemini-research/scripts/research.sh "your query here"

Output:

•JSON: gemini-research-output.json (for backward compatibility)
•Markdown: docs/research/google/<timestamp>-<topic>.md (human-readable)

JSON structure:

•queries_used: Search queries executed
•sources: Array of {title, url}
•key_points: Main findings (5-8 bullets)
•quotes: Array of {text, source_url}
•summary: 3-5 sentence brief

Example:

bash

bash plugins/knowledge-work/skills/gemini-research/scripts/research.sh "TypeScript error handling patterns 2025"

2. Deep Research

Comprehensive analysis with 10-15 sources, contradictions identified.

bash

bash plugins/knowledge-work/skills/gemini-research/scripts/research.sh "your query" deep

Output: Extended JSON with:

•All quick mode fields
•contradictions: Conflicting info found
•consensus: Widely-agreed points
•gaps: Areas needing more data

Example:

bash

bash plugins/knowledge-work/skills/gemini-research/scripts/research.sh "React Server Components best practices" deep

3. Code Examples

Focus on practical code snippets and real-world implementations.

bash

bash plugins/knowledge-work/skills/gemini-research/scripts/research.sh "your query" code

Output: Code-focused JSON with:

•sources: Prioritize GitHub, Stack Overflow, official docs
•code_snippets: Array of {language, code, source_url, description}
•patterns: Common implementation patterns
•libraries: Recommended tools/packages
•gotchas: Known pitfalls with solutions

Example:

bash

bash plugins/knowledge-work/skills/gemini-research/scripts/research.sh "Playwright headless browser automation" code

Workflow

Integration with Deep-Research Agent

The deep-research agent can orchestrate multiple research sources in parallel:

•Local codebase (Explorer agent)
•Web search (existing deep-research)
•Gemini research (this skill) ← NEW
•GitHub code search (future)

Combine all sources for comprehensive context.

Output Format

Quick Mode

json

{
  "queries_used": ["typescript error handling 2025", "typescript custom errors"],
  "sources": [
    {"title": "TypeScript Handbook: Error Handling", "url": "https://..."},
    {"title": "Modern Error Handling in TS", "url": "https://..."}
  ],
  "key_points": [
    "Use typed errors extending Error class",
    "Avoid throwing strings or plain objects",
    "Leverage exhaustive type checking"
  ],
  "quotes": [
    {
      "text": "TypeScript 5.0 introduced better error inference",
      "source_url": "https://..."
    }
  ],
  "summary": "Modern TypeScript error handling favors typed custom errors over generic Error. Key patterns include discriminated unions for error types and exhaustive checking for safety."
}

Deep Mode

Adds:

json

{
  "contradictions": ["Some sources recommend Error subclassing, others favor plain objects with type guards"],
  "consensus": ["All sources agree: avoid throwing strings"],
  "gaps": ["Limited guidance on async error handling in React Server Components"]
}

Code Mode

Adds:

json

{
  "code_snippets": [
    {
      "language": "typescript",
      "code": "class ValidationError extends Error { constructor(public field: string) { super(`Invalid: ${field}`); } }",
      "source_url": "https://...",
      "description": "Custom error with field context"
    }
  ],
  "patterns": ["Custom error classes", "Error discriminated unions"],
  "libraries": ["zod (validation)", "neverthrow (Result types)"],
  "gotchas": [
    {
      "issue": "Error.prototype breaks after compilation",
      "solution": "Set prototype manually: Object.setPrototypeOf(this, ValidationError.prototype)"
    }
  ]
}

Error Handling

Missing API auth:

code

Error: Not authenticated. Run: gemini -p "test"

Solution: Run gemini once manually to auth.

Rate limits (60/min or 1000/day):

code

Error: Rate limit exceeded

Solution: Wait 1 minute or try next day. Consider Perplexity/Tavily MCP for higher limits.

No results:

json

{"error": "No results found", "suggestion": "Rephrase query or try different keywords"}

Gemini CLI not installed:

code

Error: gemini command not found

Solution: npm install -g @google/gemini-cli

Configuration

Customize prompts: Edit templates in scripts/research.sh:

•QUICK_TEMPLATE
•DEEP_TEMPLATE
•CODE_TEMPLATE

Change output location:

•JSON (temp): gemini-research-output.json (current directory)
•Markdown (permanent): docs/research/google/<timestamp>-<topic>.md

Customize via OUTPUT_FILE and RESEARCH_DIR variables in script.

Performance

•Quick mode: ~5-10 seconds (5-8 sources)
•Deep mode: ~10-20 seconds (10-15 sources)
•Code mode: ~8-15 seconds (code-focused)

Speed depends on:

•Query complexity
•Number of sources
•Network latency
•Gemini API load

Comparison with Alternatives

Feature	gemini-research	Perplexity API	Tavily API	WebSearch (Claude)
Cost	Free (1000/day)	$$ Paid	$$ Paid	Free (limited)
Citations	✅ URLs	✅ URLs	✅ URLs	✅ Titles only
Rate limit	60/min, 1000/day	Higher (paid)	Higher (paid)	Lower
Output format	JSON	JSON	JSON	Text
Code examples	✅ Via mode	❌	❌	❌
Setup	CLI install	API key	API key	Built-in

Tips

Force Google Search grounding: Prompts explicitly say "Use google_web_search" to ensure tool usage.

Demand citations: All prompts require URLs + quotes for verifiability.

JSON for easy parsing: --output-format json enables programmatic analysis by Claude.

Chain research: Run multiple queries, Claude synthesizes results.

Example chaining:

bash

# 1. Get overview
bash scripts/research.sh "React Server Components" quick

# 2. Get code examples
bash scripts/research.sh "RSC data fetching patterns" code

# 3. Claude combines both JSONs for implementation

Advanced: Integration Points

With Deep-Research Agent

plugins/development-lifecycle/agents/deep-context-gatherer.md can orchestrate:

markdown

1. Run local codebase search (Grep, Glob)
2. Run Gemini research (this skill)
3. Run GitHub code search (future)
4. Synthesize all sources
5. Return unified context

With Feature Development

/commands/develop-feature.md can include research phase:

markdown

Phase 1: Research
- Ask user for topic
- Run gemini-research skill
- Extract patterns from JSON
- Proceed to planning

Troubleshooting

Tool call flakiness: Gemini CLI sometimes ignores tool hints. Solution: Make prompts explicit ("Use google_web_search to...").

Missing URLs: If JSON lacks source URLs, check prompt template includes "with citations and URLs".

Empty results: Try broader query or different keywords. Gemini may filter very niche topics.

JSON parsing errors: Gemini occasionally returns markdown-wrapped JSON. Script uses jq to extract.

Notes

•Free tier may train on data (check Google's terms)
•Personal Google account sufficient (no paid plan needed)
•For production/high-volume: consider Perplexity/Tavily MCP
•
Outputs:
- •JSON: gemini-research-output.json (temp, for backward compatibility)
- •Markdown: docs/research/google/<timestamp>-<topic>.md (permanent, human-readable)
•Script uses --output-format json for structured data
•Markdown includes placeholder for Claude's analysis section
•Claude must read markdown and append synthesis after research completes