> deep-research v0.61.2 · Python 3.12+ · MIT

Deep Research

A command-line tool and self-hosted web workstation for Google's Gemini Deep Research agent.

Launch autonomous research, watch it think, then read, annotate, search, compare and listen to the cited reports it produces. Bring in your own and public data, and test a report's claims with real computations on an HPC cluster. Everything lives in a local SQLite history on your own machine.

View on GitHub Release v0.61.2 Get started

# Install the CLI globally
$ uv tool install git+https://github.com/charles-forsyth/deep-research.git

# Save your API key (stored in ~/.config/deepresearch/.env)
$ deep-research auth login

# Run your first research task
$ deep-research "The history of the internet" --stream

# Open the workstation
$ deep-research dashboard --start
  # then browse to http://localhost:7420

The report reader: a cited report with numbered citation markers, an amber flag on an uncited paragraph, and a details panel listing cost, word count and cited domains

01 / What it does

A research engine and a workstation around it

The CLI runs the Gemini Deep Research agent (deep-research-preview-04-2026, or the Max agent), which plans, searches, reads and writes a cited report. The dashboard turns every report you have run into a library you keep building on.

Research engine (CLI)

Recursive research

--depth and --breadth run a gap analysis that spawns parallel sub-research, then synthesize one final report. deep-research estimate prices it first with no API calls.

Your own documents

Upload files or whole folders. They go to a temporary File Search Store that the agent searches first, and are cleaned up afterwards.

Headless runs

start runs survive closing the terminal, with PID tracking and honest crash detection. Streams reconnect automatically with exponential backoff.

Follow-ups and search

Ask follow-up questions on any past session, run semantic search across your whole history, and export to Markdown, JSON, CSV or HTML. Every command takes --json.

Research workstation (web dashboard)

Launch and watch

Templates, depth and breadth sliders, a live cost estimate and drag-and-drop uploads. Then a live timeline of agent thoughts, sub-task lanes, elapsed time and actual cost.

Read with citation cards

A typeset reader with outline, find and grouped sources. Hover or tap [cite: 12] to see the claim and its source. Uncited paragraphs with figures are flagged.

Annotate and collect

Highlights, notes and Markdown notebooks with cited quotes. A brief builder turns a report or notebook into an executive brief, slide outline or email.

Listen

Read any report aloud in the browser's voice, or export an MP3 in a Gemini voice: the full text or an AI-written 2-3 minute spoken summary.

Lab runs on a Slurm cluster

Turn a claim in a report into a real computation. Gemini drafts a plan and job script; a referee pass checks it; you review and edit it, with a worst-case cost, before anything is submitted.

Data sources and open data

Register web datasets, Google Drive, GCS, S3 buckets and local folders once. "Find open datasets" searches Data.gov, Zenodo, Hugging Face, AWS Open Data and more, offering only free sources.

Re-run, compare, map

Repeat a question later and see what changed, source by source. A research map places every report by topic similarity, clustered and clickable.

Projects and workspaces

One project per grant, paper or thesis, with summaries, "Ask this project", briefs, exports and a claims board. Separate workspaces export to and import from a .zip.

02 / Screenshots

The workstation

Three panes: archive on the left, tabbed work in the center, an inspector on the right. Shown here cropped to the work area. On phones the side panes become slide-out drawers.

A Lab run result attached to a report: a phylodynamics job with its step bar from plan to done, the question tested, the result and key numbers — **Lab run results on a report.** The outcome is attached as a note; the report itself is never edited.

A report on fan scaling laws with formulas shown as plain readable text and numbered citations — **Readable math.** LaTeX in reports is shown as plain text, with no math library to download.

The Lab runs table listing each run with status, what it tests, its report, where it ran, maximum cost and last update — **Every Lab run** in one table, with its outcome and worst-case cost.

The Data sources page listing registered sources by name, kind, status, file count, size and location — **Data sources.** Register once; use in research, follow-ups and Lab runs.

Find open datasets: a search for daily weather station data returning NOAA datasets from AWS Open Data with add-as-source buttons — **Find free open datasets** across Data.gov, Zenodo, AWS Open Data and Earth Engine.

Compare view of two runs of the same question side by side, with sources only in the older run, new in the newer run, and in both — **Compare two runs.** See what changed, source by source.

The research map: 149 reports drawn as colored dots linked by similarity, forming topic clusters — **Research map.** Every report placed by topic similarity.

The New deep research form with templates, depth and breadth sliders, optional uploads and data sources, and a cost estimate before launch — **Launch with a cost estimate.** Templates, depth and breadth, uploads and data sources.

The dashboard on a phone showing a report with its metadata card and an amber-flagged uncited paragraph — **Mobile.** Works on phones and tablets.

03 / How it works

Small parts, local state

The dashboard adds no Python dependencies: it is a standard-library ThreadingHTTPServer serving vanilla JavaScript (with vendored marked and DOMPurify). Runs launched from it are ordinary background sessions: they appear in deep-research list and keep going if the dashboard restarts.

deep-research CLIargparse, --json

Dashboardstdlib HTTP + vanilla JS

DeepResearchAgentcore/agent.py, thread pools

SQLite historyhistory.db, WAL mode

Gemini Deep ResearchInteractions API

File Search Storetemporary uploads

Gemini Flash / TTSbriefs, embeddings, audio, Lab planner

Slurm clusterLab runs: ssh, sbatch

Data sourcesweb, buckets, Drive, folders

A Lab run, step by step

1
Plan. Gemini suggests computations and writes a plan and job script against the cluster's own catalog of modules and containers.
2
Referee. A second AI pass flags tests that could never fail or never pass. A flawed plan is revised and checked again, up to two rounds; the best version the referee saw is kept.
3
You review. Edit the plan with its worst-case cost in view. Nothing is submitted until you submit it.
4
Pilot, then run. A short pilot runs first on an always-on warm node; a failed pilot is repaired by the AI and retried.
5
Verdict. Outputs and figures are fetched and the result is judged confirmed, refuted, inconclusive or broken, from checks the job writes.

If a website blocks the cluster (403/429), "Fetch on this laptop" downloads the files locally, stages them as a data source and rewires the plan to read them.

04 / Design principles

Safe by default

Nothing runs without review

Lab plans are drafts until a person submits them. AI fixes and referee rounds only ever produce another draft.

Evidence over claims

Lab outcomes come from checks the job writes, not from the write-up. Refuted and broken results are shown as such.

Additive storage

Migrations only add tables and columns. Your main library's data is never moved or rewritten by new features.

Cheap models by default

Everything except the Deep Research agent uses Gemini Flash. Free open data only: requester-pays buckets are refused.

Keyboard-first

Ctrl+K command palette, find and save shortcuts. Dialogs never confirm on a stray Enter, and Escape closes them.

Tests and spec move together

A CI test fails when an API route, setting, module or command is missing from the specification.

Security: the dashboard has no login. Anyone who can reach the port can read your research and start runs on your API key, so it listens on 127.0.0.1 (this machine only) by default. To reach it from another machine on a network you trust, pass --host 0.0.0.0 --allow-remote, or use an SSH tunnel.

05 / Quick start

Install and run

Requirements: Python 3.12+, uv, and a Gemini API key on a paid tier (the Deep Research agent is not available on the free tier). ffmpeg is optional, for MP3 audio export.

Quick start

# Install the CLI globally
uv tool install git+https://github.com/charles-forsyth/deep-research.git

# Save your API key (stored in ~/.config/deepresearch/.env)
deep-research auth login

# Run your first research task
deep-research "The history of the internet" --stream

# Open the workstation
deep-research dashboard --start        # then browse to http://localhost:7420

Command line

deep-research estimate "State of solid-state batteries" --depth 2 --breadth 3   # no API calls
deep-research research "State of solid-state batteries" --depth 2 --breadth 3
deep-research research "Summarize the key findings" --upload ./papers/ --stream
deep-research start "Detailed analysis of quantum computing"   # background
deep-research list                    # recent sessions
deep-research followup 12 "Explain the error correction part simply"
deep-research search "What did I find about error correction?"
deep-research list --json             # any command: one JSON document on stdout

Web dashboard

deep-research dashboard --start                       # background on 127.0.0.1:7420
deep-research dashboard --status                      # PID and URLs
deep-research dashboard --restart
deep-research dashboard --stop
deep-research dashboard --foreground --port 8080      # run in the terminal

What it costs

The Deep Research agent is billed by Google at Gemini 3.1 Pro token rates plus Google Search grounding. Google's guidance works out to about $1 per agent run; measured runs have ranged from $0.37 to $2.04. Recursive runs multiply that by the number of agents (1 + breadth + breadth^2 ...), so run deep-research estimate first. The dashboard shows the estimate before launch and the actual cost afterwards. Lab plans with two referee rounds are typically $0.25-0.35; briefs and comparisons usually cost under a cent. Prices change: check Gemini API pricing.

06 / Links

Documentation

READMEFeatures, usage, configuration System specificationEvery route, setting and command ArchitecturePieces, layers, principles Dashboard designThe workstation's ideas and layout ChangelogRelease notes for every version RoadmapNext up and longer term ContributingDev setup and checks IssuesBugs and ideas LicenseMIT

This is an independent project and is not affiliated with or endorsed by Google.