gemini-deep-research
Run Gemini Deep Research via browser automation on a persistent Chrome (CDP port 9222). Use for comprehensive AI research reports. TRIGGERS - Gemini research, deep research, research report.
How do I install this agent skill?
npx skills add https://github.com/terrylica/cc-skills --skill gemini-deep-researchIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill automates Gemini Deep Research by controlling a local Chrome browser via its remote debugging port. It contains 'self-evolving' instructions that direct the AI agent to update the skill's own documentation and logic based on its performance. This creates a potential surface for indirect prompt injection, where malicious or misleading information found during research could influence the agent to modify the skill's instructions in harmful ways.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
Gemini Deep Research
Run long-form research queries through Google's Gemini Deep Research via browser automation (Playwright CDP). Produces 40k+ char markdown reports with source citations.
Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.
Prerequisites
- Chrome with debug port: Must be running with
--remote-debugging-port=9222 - Gemini Advanced subscription: Logged into gemini.google.com in the debug Chrome
- playwright-core:
bun add -g playwright-core(or project-local) - Runtime: Use
npx tsx(notbun run) — Bun's CDP connectOverCDP times out; Node.js connects in <1s
Launch Chrome (if not running)
Use the shared port script from the chrome-profiles plugin (the SSoT for browser routes). It pins a separate profile, which Chrome 136+ requires for a debug port, and down closes exactly that port:
CHROME_DEBUG_PROFILE="$HOME/.local/share/gemini-research-profile" \
bash "$(cc-plugin-root chrome-profiles)/scripts/chrome-debug-port-control.sh" up
Then open https://gemini.google.com/app in that window and log in once with a Gemini Advanced account; the profile keeps the login across reboots. Run … down when finished.
Usage
CLI (direct)
# Health check — verify Chrome CDP + Gemini login
npx tsx {{skill_dir}}/scripts/research.ts --health
# Basic research (runs preflight automatically)
npx tsx {{skill_dir}}/scripts/research.ts "your research query"
# Save to specific file
npx tsx {{skill_dir}}/scripts/research.ts \
--output /tmp/report.md \
--timeout 45 \
"comprehensive analysis of quantum computing error correction 2025-2026"
# Auto-save to directory (creates {date}-{slug}.md)
npx tsx {{skill_dir}}/scripts/research.ts \
--output-dir ~/.claude/automation/gemini-deep-research/output \
"your query"
# Without auto-confirming plan (lets you review first)
npx tsx {{skill_dir}}/scripts/research.ts --no-confirm "query"
Programmatic (import)
import { GeminiDeepResearchClient } from "{{skill_dir}}/scripts/client.js";
const client = new GeminiDeepResearchClient({
cdpUrl: "http://127.0.0.1:9222",
maxResearchTimeMs: 30 * 60 * 1000,
autoConfirm: true,
onProgress: (msg) => console.log(msg),
});
await client.init();
const result = await client.research("your query");
// result.report — full markdown report (40k+ chars)
// result.plan — research plan text
// result.completed — boolean
// result.durationMs — execution time
// result.shareLink — Gemini share URL (if Firecrawl enabled)
await client.close();
Preflight
Every research run starts with an automatic preflight health check that verifies:
- Chrome CDP reachable on configured port
- Browser connection via WebSocket succeeds
- Gemini page open at gemini.google.com
- Login state OK (not showing sign-in wall)
If any check fails, research aborts with a clear error message. Use --no-preflight to skip.
Automation Flow
Preflight (CDP + login check) → abort if unhealthy
↓
Chrome CDP:9222 → Navigate gemini.google.com/app
↓
Tools button → Deep Research drawer item → Active chip verification
↓
Type query (30ms/char) → Send button (or Enter fallback)
↓
Wait for research plan (~18-120s) → Extract plan text
↓
Auto-confirm "Start research" (or manual)
↓
Poll completion: mic button + text stability (5s intervals, 30min max)
↓
Extract report (longest .markdown element) → Optional share link + Firecrawl
Debug Probes
When selectors break (Google updates Gemini UI), use the probe scripts:
# Check Chrome connectivity
bun run {{skill_dir}}/scripts/probes/dom-inspector.ts status
# Test all selectors against live DOM
bun run {{skill_dir}}/scripts/probes/dom-inspector.ts selectors
# Full DOM inspection
bun run {{skill_dir}}/scripts/probes/dom-inspector.ts probe
# Monitor active research execution
bun run {{skill_dir}}/scripts/probes/research-monitor.ts confirm-and-monitor
# Check research completion + extract share link
bun run {{skill_dir}}/scripts/probes/share-link.ts status
bun run {{skill_dir}}/scripts/probes/share-link.ts extract
Selector Registry
All CSS selectors live in scripts/selectors.ts. When Google updates the Gemini UI:
- Run
dom-inspector.ts selectorsto identify broken selectors - Run
dom-inspector.ts probeto inspect current DOM - Update
selectors.tswith new selectors - Re-test with
dom-inspector.ts selectors
Selectors last verified: 2026-03-13 (Tools button: now button.toolbox-drawer-button, aria-label removed)
Key Files
| File | Purpose |
|---|---|
scripts/research.ts | Unified CLI entrypoint |
scripts/client.ts | GeminiDeepResearchClient class |
scripts/selectors.ts | CSS selector registry (13 groups with fallbacks) |
scripts/probes/dom-inspector.ts | DOM probing (5 commands) |
scripts/probes/research-monitor.ts | Research execution monitor |
scripts/probes/share-link.ts | Share link extraction |
Options Reference
| Option | Default | Description |
|---|---|---|
cdpUrl | http://127.0.0.1:9222 | Chrome CDP endpoint |
maxResearchTimeMs | 1800000 (30 min) | Max wait for research completion |
pollIntervalMs | 5000 (5s) | How often to check for completion |
autoConfirm | true | Auto-click "Start research" on plan |
enableFirecrawl | false | Extract share link + scrape via Firecrawl |
firecrawlUrl | https://api.firecrawl.dev | Public Firecrawl API base (no key needed) |
--no-preflight | (preflight runs) | Skip automatic health check before research |
Completion Detection
Research completion is detected via three signals:
- Mic button visible —
button[data-node-type="speech_dictation_mic_button"]reappears - Report text > 500 chars — longest
.markdown.markdown-main-panelelement - Text stability — 3 consecutive identical text lengths (15s total)
The spinner may remain visible as a stale artifact after completion — the mic button is the primary signal.
Post-Execution Reflection
After this skill completes, check before closing:
- Did the command succeed? — If not, fix the instruction or error table that caused the failure.
- Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
- Was a workaround needed? — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.
Only update if the issue is real and reproducible — not speculative.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/terrylica/cc-skills/gemini-deep-research">View gemini-deep-research on skillZs</a>