deep-research

Drives your authenticated claude.ai Deep Research session via Playwright. Submit a prompt, walk away, come back to a saved markdown report — no copy-paste, no babysitting.

The browser profile is persisted on disk, so you log into claude.ai once and every subsequent run reuses the session.

The CLI is deep-research. claude-research is a legacy alias that still works.

---

What it does

Given a prompt, the tool:

1. Launches Chromium (offscreen-headed) with your saved claude.ai session.
2. Opens a new chat, toggles Research mode, submits the prompt.
3. Polls the tab until the research run finishes (5–30+ minutes). If claude.ai asks clarifying questions before kicking off, the run pauses (status awaiting_clarification) — answer with deep-research answer <id> "..." and the run resumes.
4. Triggers Claude.ai's own artifact Download as Markdown link — captures the canonical export.
5. Renames the file to the chat title Claude assigns, sanitized for filesystem safety (smart quotes, slashes, emoji, Windows reserved names — all handled).
6. Writes a .json sidecar with prompt, chat URL, timing, and extraction method for audit.

Multiple tasks in parallel via batch. State persists in state.json so status/retry survive crashes.

Install

Requires Python 3.10+ and uv (or pip).

git clone https://github.com/zamabama/claude-code-deep-research.git ~/.claude/tools/deep-research
cd ~/.claude/tools/deep-research
uv venv --python 3.13
uv pip install -e .
uv run playwright install chromium

Add to your shell so the deep-research command is on PATH:

# ~/.zshrc
export PATH="$HOME/.claude/tools/deep-research/.venv/bin:$PATH"

Install the Claude Code skill (optional)

If you use Claude Code and want it to recognise prompts like "deep research X" and drive this CLI for you, install the bundled skill:

mkdir -p ~/.claude/skills
ln -s ~/.claude/tools/deep-research/skill ~/.claude/skills/deep-research

Open a fresh Claude Code session and ask for "a deep research report on …" — it'll discover the skill, call deep-research run, and save the report to ./research/reports/.

First-run login (one time)

deep-research login

A Chromium window opens. Log into claude.ai normally (email + 2FA + whatever else). Once you land on the chat page, the command exits and saves your session to ~/.claude/tools/deep-research/profile/.

You will not need to do this again unless your session expires.

Use

# Single prompt, default location ./research/reports/<chat-title>.md
deep-research run --prompt "Survey the state of AI image-to-3D in 2026."

# Specific output path
deep-research run --prompt "..." --output ./reports/topic.md

# From a longer prompt file
deep-research run --prompt-file ./prompt.md --output-dir ./reports/

# See progress / past tasks
deep-research status
deep-research status --task <id>

# Failed? Try again with the same prompt
deep-research retry <id>

# Multiple in parallel (one process, threading model — works for ≤2 reliably)
deep-research batch ./batch.yaml

# Multiple in parallel (recommended for >1 — fan out separate processes
# with isolated profile copies)
for i in 1 2 3; do
  cp -R ~/.claude/tools/deep-research/profile /tmp/cdr-profile-$i
done
DEEP_RESEARCH_PROFILE_DIR=/tmp/cdr-profile-1 deep-research run --prompt-file q1.md --output-dir ./reports/ &
DEEP_RESEARCH_PROFILE_DIR=/tmp/cdr-profile-2 deep-research run --prompt-file q2.md --output-dir ./reports/ &
DEEP_RESEARCH_PROFILE_DIR=/tmp/cdr-profile-3 deep-research run --prompt-file q3.md --output-dir ./reports/ &
wait

Clarifying questions

Sometimes claude.ai asks back before kicking off the research. The tool detects this and pauses:

$ deep-research run --prompt "..."
[abc123 awaiting_clarification] CLARIFICATION_NEEDED: Are you looking at US or global market data? What's the timeframe?

Answer it:

deep-research answer abc123 "Global market. 2024-2026 only — flag any older sources."

The run picks the answer up within ~5s, types it into the chat, sends, and resumes polling for the artifact. Multi-turn (claude.ai asks again after your answer) works the same way.

batch.yaml

parallel: 3                      # max concurrent (hard cap 5)
output_dir: ./research/reports/
tasks:
  - id: lovart-tech
    prompt: "Lovart.ai canvas rendering — Konva, PixiJS, custom WebGL?"
    output: lovart_tech.md
  - id: konva-survey
    prompt-file: ./prompts/konva_sdks.md
    output: konva_sdks.md

Where things live

~/.claude/tools/deep-research/
├── profile/                <- Playwright user data (cookies, auth) — gitignored
├── state.json              <- task ledger — gitignored
├── src/deep_research/      <- the Python package
└── scripts/sync_to_mac_setup.sh

Reports default to ./research/reports/<sanitized-chat-title>.md in whatever directory you run from.

Failure modes & recovery

Symptom	What to do
AuthExpired	deep-research login
SelectorNotFound	Claude.ai shipped a UI change. Re-run with --headed to inspect, then update src/deep_research/selectors.py and bump SELECTORS_VERSION in config.py.
Timeout	The run took longer than --timeout (default 60 min). Bump it: --timeout 120. Also check deep-research status --task <id> for a stuck-in-clarification state.
Rate limit	Claude.ai limits reached on your account. Wait, then deep-research retry <id>.

TOS / scope

This automates your own claude.ai session for your own personal productivity. It uses the user-data-dir model where Chromium drives the browser using cookies you set yourself by signing in. It does not bypass auth, does not share sessions across users, and does not scrape any account other than the operator's. If Anthropic ships an official Deep Research API, the workflow layer is small enough to retarget at it.

Tests

cd ~/.claude/tools/deep-research
uv run pytest

Unit tests cover filename sanitization, state-store atomicity, selector fallbacks, and the clarifying-question detection heuristic. End-to-end testing requires a logged-in profile and a real claude.ai run — that part is manual.