Deep Research Loop

Automated iterative research using Gemini Deep Research and Claude Code.

You write structured research questions. Gemini Deep Research investigates them across the web. Claude analyzes which questions got thorough answers and which have gaps. Targeted follow-up prompts are generated for the gaps. The loop repeats until coverage converges.

What used to be a manual copy-paste workflow becomes a self-closing convergence loop.

Why This Exists

When you're about to build something complex, the difference between "I think I know how this works" and "I've systematically researched every angle" is enormous. But thorough research is tedious:

1. Write good questions (hard — requires knowing what you don't know)
2. Feed them to a research tool (manual, slow)
3. Read the results and figure out what's still missing (the real skill)
4. Write better follow-up questions targeting the gaps
5. Repeat until you're confident

Steps 2-5 are what this tool automates. Step 1 is assisted by the research prompt skill. Step 3 is where Claude's semantic understanding matters — Gemini's response sections rarely map 1:1 to your original questions, so gap analysis requires reading for meaning, not matching keywords.

How It Works

                        ┌──────────────────────┐
                        │   Research Prompt     │
                        │   (structured         │
                        │    questions)          │
                        └──────────┬───────────┘
                                   │
                    ┌──────────────▼──────────────┐
                    │   Gemini Deep Research       │
                    │   API ($2-5) or Browser ($0) │
                    │   (~10-20 min per round)     │
                    └──────────────┬───────────────┘
                                   │
                    ┌──────────────▼──────────────┐
                    │   Gap Analysis (Claude)      │
                    │   Per-question scoring:       │
                    │   covered / partial / missing │
                    └──────────────┬───────────────┘
                                   │
                          ┌────────▼────────┐
                          │  Coverage ≥ 85% │──── yes ───▶ Synthesize
                          │  OR 3 rounds?   │              final doc
                          └────────┬────────┘
                                   │ no
                    ┌──────────────▼──────────────┐
                    │   Follow-Up Prompt           │
                    │   (targets only gaps,        │
                    │    references prior findings) │
                    └──────────────┬───────────────┘
                                   │
                                   └───────── loops back ─┘

Two Backends: API or Browser

	API Client (gemini_client.py)	Browser Client (gemini_browser.py)
Cost	~$2-5 per round	Free
Setup	API key only	One-time Google login
Speed	~1-5 min	~10-20 min
Reliability	Stable (official API)	May break if Gemini UI changes
Chaining	Yes (--chain flag)	No (each run is independent)
Headless	Always	Yes (after first login)
Best for	CI/automation, high volume	Personal use, cost-sensitive

Use the API client for reliability and speed. Use the browser client when you don't want to pay.

Quick Start

Prerequisites

• Python 3.9+
• Claude Code (for the automated loop — optional)

Install

git clone https://github.com/Relic-Studios/deep-research-loop.git
cd deep-research-loop
pip install -r requirements.txt

For the API client:

cp .env.example .env
# Edit .env and add your GEMINI_API_KEY
# Get one at: https://aistudio.google.com/apikey

For the browser client:

playwright install chromium
python gemini_browser.py login
# Sign into your Google account in the browser that opens
# Navigate to gemini.google.com and verify you're logged in
# Close the browser when done — session is saved automatically

Note: Deep Research via the browser requires Gemini Advanced (Google One AI Premium). Without it, prompts will get regular Gemini responses instead of full multi-source research reports. The API client works regardless.

Install the Claude Code Skills (optional)

Copy the skill files into your Claude Code project:

cp skills/research-prompt.md /path/to/your/project/.claude/prompts/
cp skills/deep-research.md /path/to/your/project/.claude/prompts/

Then update the file paths in deep-research.md to point to where you cloned this repo (the gemini_client.py or gemini_browser.py path and output directory).

Usage

With Claude Code (recommended)

/deep-research "how to implement vector similarity search in SQLite"

Or point it at an existing research prompt:

/deep-research prompts/my-topic.md

Claude will:

1. Generate a structured research prompt (or load yours)
2. Submit it to Gemini Deep Research
3. Wait for results
4. Analyze which questions were thoroughly answered
5. Generate targeted follow-up prompts for gaps
6. Loop until coverage hits 85% or 3 rounds
7. Synthesize everything into a unified research document

Standalone — API Client

export GEMINI_API_KEY=your-key-here

# Submit and wait for results
python gemini_client.py run prompts/my-topic.md --output output/my-topic/round-1.md

# Submit only (returns immediately with interaction ID)
python gemini_client.py submit prompts/my-topic.md

# Poll a running interaction
python gemini_client.py poll <interaction-id>

# Chain a follow-up (Gemini retains context from prior round)
python gemini_client.py run prompts/follow-up.md \
    --output output/my-topic/round-2.md \
    --chain <interaction-id-from-round-1>

Standalone — Browser Client (free)

# First time: sign into Google
python gemini_browser.py login

# Run research (headless after login)
python gemini_browser.py run prompts/my-topic.md --output output/my-topic/round-1.md

# Run with visible browser (for debugging)
python gemini_browser.py run prompts/my-topic.md --visible

Options

API Client (gemini_client.py):

Flag	Default	Description
--output, -o	none	Write research text to this file
--timeout	3600	Max wait time in seconds
--poll-interval	15	Seconds between status checks
--chain	none	Previous interaction ID for follow-up context

Browser Client (gemini_browser.py):

Flag	Default	Description
--output, -o	none	Write research text to this file
--timeout	1800	Max wait time in seconds
--visible	false	Show browser window

Both output JSON to stdout with the same structure:

{
  "status": "completed",
  "text": "research report content...",
  "elapsed_seconds": 64
}

Project Structure

deep-research-loop/
├── gemini_client.py          # API client — fast, paid ($2-5/query)
├── gemini_browser.py         # Browser client — free, uses Playwright
├── requirements.txt          # requests + playwright
├── .env.example              # API key template (for API client)
├── skills/
│   ├── research-prompt.md    # Skill: generate research questions
│   └── deep-research.md      # Skill: orchestrate the full loop
├── examples/
│   └── vector-search-sqlite.md   # Example research prompt
├── prompts/                  # Your research prompts go here
│   └── (your-topic.md)
└── output/                   # Research artifacts (gitignored)
    └── <slug>/
        ├── round-1-response.md
        ├── round-1-coverage.json
        ├── round-2-prompt.md
        ├── round-2-response.md
        └── SYNTHESIS.md

Research Prompt Format

The quality of your research depends on the quality of your questions. The /research-prompt skill helps generate these, but here's the format:

# Research Prompt: <Title>

## Objective
What are we researching and why. **Core question in bold.**

## Context
### Current State / Pain Point
What exists today. Be specific — reference actual code, numbers, constraints.

### What We Want
High-level desired capabilities.

## Key Questions
### 0. <Topic Area>
0a. **<Specific sub-question>**
    - Concrete investigation demand
    - "How does <production system> handle this?"

### 1. <Next Topic Area>
1a. **<Sub-question>**
    - ...

## Desired Output
- Shape of expected answers (comparison matrix, architecture, benchmarks, roadmap)

Rules: Questions only — no answers, no recommendations. Be specific, not vague. Ground in context. Include "how do others do it" and scale questions.

See examples/vector-search-sqlite.md for a complete example.

How Gap Analysis Works

This is the core intelligence of the loop. After each Gemini round, Claude scores every question from the registry:

Score	Meaning	Threshold
COVERED (1.0)	Substantive answer with depth, specifics, citations	Actionable
PARTIAL (0.5)	Mentioned but shallow, missing specifics or sub-parts	Needs follow-up
MISSING (0.0)	Not addressed at all	Full question in follow-up

Convergence formula: (covered * 1.0 + partial * 0.5) / total_questions

The loop stops when coverage reaches 85% with no MISSING questions, or after 3 rounds maximum (cost safety cap).

Why Claude does this instead of code: Gemini organizes its response by its own logic, not by your question numbering. Question 2a about "context curation" might be answered in Gemini's Section 4 about "Domain-Scoped Memory Projection." Semantic understanding is required to determine whether a question was actually answered.

Cost & Time

API Client:

	Per Round	Typical (2 rounds)	Maximum (3 rounds)
Cost	~$2-5	~$4-10	~$6-15
Time	~1-5 min	~5-10 min	~10-15 min

Browser Client:

	Per Round	Typical (2 rounds)	Maximum (3 rounds)
Cost	$0	$0	$0
Time	~10-20 min	~25-40 min	~45-60 min

Architecture

The tool splits intelligence deliberately:

• Gemini Deep Research does what it's best at — finding, synthesizing, and citing sources across the internet. It runs autonomously for minutes per query, checking dozens of sources.

• Claude (via Claude Code) does what it's best at — understanding whether a response actually answers a question, identifying what's missing, and generating precise follow-up questions that target only the gaps.

• The Python clients are just plumbing — submit a prompt, wait for results, return JSON. Zero AI logic. ~150-200 lines of code each.

This means the gap analysis quality scales with the orchestrating model's capability. As Claude gets smarter, the research gets more thorough — the plumbing stays the same.

Adapting for Your Project

The skills reference file paths (prompts/, output/, gemini_client.py) that assume you're running from this repo's root. If you install the skills into a different project:

1. Update the client path in deep-research.md to wherever you cloned this repo
2. Update the output directory path
3. Choose which client to use (API or browser) and update the commands accordingly

The Python clients have zero dependencies on the skill files — they're standalone tools that work with any prompt file.

License

MIT