gemini-deep-research
Deep internet research via Gemini Advanced (gemini.google.com) Deep Research mode. Runs a 5-30 minute multi-source web investigation, exports the report as a Google Doc, moves it to Sidekick Home, and saves a local markdown copy. Auto-retries on server errors. Use when: you need deep open-web research on a topic, emerging trends, or comprehensive surveys across many sources. NOT for: quick lookups (use Tavily), source-grounded synthesis from specific documents (use notebooklm-research).
Resources
3Install
npx skillscat add ot1-roy/gemini-deep-research-skill Install via the SkillsCat registry.
SKILL.md
Gemini Deep Research Skill — v1.0
When to Use
- "Do a deep research on X" / "What's the latest on X across the web"
- Comprehensive topic surveys (market analysis, tech landscape, scientific advances)
- When you need 50-200 sources synthesized, not just a quick answer
- Open territory — no pre-existing sources; let Gemini find them
When NOT to Use
| Situation | Use Instead |
|---|---|
| Quick facts | web_search (Brave) or tavily_search |
| AI-synthesized summary | tavily_search |
| Research FROM specific sources | notebooklm-research |
| Already have articles/PDFs | Upload directly to NotebookLM |
Research Stack Position
| Tier | Tool | Time | Best For |
|---|---|---|---|
| 1 | Brave web_search | ~2s | Quick facts |
| 2 | Tavily | ~30s | AI-synthesized answers |
| 3 | notebooklm-research | 2-5 min | Source-grounded synthesis |
| 4 | gemini-deep-research | 5-30 min | Deep open-web investigation |
Prerequisites
- Auth:
~/.notebooklm/storage_state.json(Roy's Google session with Gemini Advanced)- If expired:
~/clawd/skills/quick-learn/.venv/bin/notebooklm login
- If expired:
- Python venv:
~/clawd/skills/quick-learn/.venv(has Playwright + chromium) - gog CLI: authenticated as
roy.hua@gmail.com(for Drive export)
Usage
# Basic
~/clawd/skills/quick-learn/.venv/bin/python3 \
~/clawd/skills/gemini-deep-research/gemini_deep_research.py \
"your research topic"
# Custom output dir
~/clawd/skills/quick-learn/.venv/bin/python3 \
~/clawd/skills/gemini-deep-research/gemini_deep_research.py \
"your topic" --output-dir ~/clawd/research
# Debug (show browser window)
~/clawd/skills/quick-learn/.venv/bin/python3 \
~/clawd/skills/gemini-deep-research/gemini_deep_research.py \
"your topic" --no-headlessOutput
- Markdown report:
~/clawd/research/YYYYMMDD-HHMMSS-gemini-[slug].md - Google Doc: Saved to Sidekick Home (Projects/ folder) + linked in markdown header
- Typical size: 50-100KB, 200-500 lines for a 15-30 min research
Known Behaviors & Limits
- Rate limit: Gemini Pro allows max 3 concurrent Deep Research tasks
- Exit code 2 = rate limited; wait 5-15 min for other tasks to finish
- Server issues (~20%): Auto-retries up to 2 times with fresh browser context
- Off-topic reports (~1%): Sanity check runs; if mismatch detected, report saved with warning header
- Research time: 5-30 min depending on topic complexity
Exit Codes
| Code | Meaning |
|---|---|
| 0 | Success — report saved |
| 1 | Error (auth failed, timeout, export failed) |
| 2 | Rate limited — wait and retry |
Auth Refresh
~/clawd/skills/quick-learn/.venv/bin/notebooklm loginInstall
npx skillscat add ot1-roy/gemini-deep-research-skill Install via the SkillsCat registry.