claude-ai-deep-research

Standalone Invocation

If invoked directly via /claude-ai-deep-research, spawn the browser-researcher agent:

Agent(
  subagent_type="browser-researcher",
  name="claude-ai-researcher",
  prompt="skill_path: <skill-path>/SKILL.md\nresearch_prompt: <from user>\noutput_path: <from user or .work/claude-ai-report.md>\ncaller: <your name>",
  run_in_background=true
)

Then relay messages between user and agent via SendMessage. If loaded by browser-researcher via Read, ignore this section.

Platform Configuration

• backend: playwright-cli (default — headless via persistent profile)
• url: https://claude.ai/new
• submit_method: click_send_button (IMPORTANT: Enter = newline on claude.ai)
• plan_review: informational (research auto-starts, plan shown for transparency)
• hard_timeout: 65 (session hard cap — shorter than other platforms)
• completion_signal: button Copy

Playwright-CLI Backend (default)

All browser interaction is encapsulated in a stateful Python driver. The agent calls it via Bash; no Chrome MCP tools are loaded. The driver keeps a named playwright-cli session (claude-ai-research) backed by a persistent Chromium profile at ~/.cache/playwright-claude-ai-profile, so one-time headed SSO login unlocks every subsequent headless run.

Driver path: scripts/pw-driver.py (next to this file).

Exit codes: 0 ok · 10 login required · 20 timeout · 30 extraction failure · 40 DOM mismatch.

Phase → subcommand mapping

Phase	Command
Login check	python3 {skill_dir}/scripts/pw-driver.py status
One-time headed login	python3 {skill_dir}/scripts/pw-driver.py login (user runs in their terminal)
Submit + Research mode	python3 {skill_dir}/scripts/pw-driver.py start-research --prompt-file=<path>
Plan capture	python3 {skill_dir}/scripts/pw-driver.py wait-plan --timeout=120
Completion polling	python3 {skill_dir}/scripts/pw-driver.py wait-complete --timeout=3900
Report extraction	python3 {skill_dir}/scripts/pw-driver.py extract --output=<path>
Shutdown	python3 {skill_dir}/scripts/pw-driver.py close

Agent workflow

1. Prepare prompt file: strip newlines → single paragraph. Write the cleaned prompt to a temp file (e.g. .work/claude-ai-prompt.txt). The driver expects a file path, not inline text, to avoid shell-escaping pitfalls on long prompts.

2. Login check: run status. Exit 0 = logged in, proceed. Exit 10 = send LOGIN_REQUIRED to caller with instructions: ask the user to run python3 ~/.claude/skills/claude-ai-deep-research/scripts/pw-driver.py login in their terminal and reply LOGIN_DONE when finished. Re-run status.

3. Start research: run start-research --prompt-file=<path>. This opens claude.ai/new, activates Research mode, dismisses connectors dialog, types the prompt, clicks Send message. Leaves the session open. On exit 40 (DOM mismatch): send ERROR: — claude.ai UI likely changed.

4. Plan capture: run wait-plan --timeout=120. stdout = plan text. Send PLAN_READY: <plan> to caller. Since plan review is informational, also send RESEARCH_STARTED immediately and continue to step 5 unless the caller sends REVISE: within 30 seconds. (Stop/restart protocol is not yet wired into the driver — if a revise is needed in this pass, send ERROR: and let the caller restart the whole flow.)

5. Wait for completion: run wait-complete --timeout=3900. The driver streams RESEARCH_PROGRESS: Nm elapsed lines to stdout every ~5 min; relay each line to the caller as a RESEARCH_PROGRESS: SendMessage. When the driver prints RESEARCH_COMPLETE: Nm elapsed, the report is ready. Exit 20 = hard timeout — send ERROR: to caller.

   Important: use a single long-running Bash call with a generous timeout (3960s) for this step. Don't poll in a loop from the agent — the driver does the polling internally.

6. Extract report: run extract --output=<caller_output_path>. Exit 0 + stdout showing size in bytes → success. Exit 30 → send ERROR: Extraction failed to caller.

7. Verify: wc -c <output_path> — confirm >1000 bytes.

8. Send RESEARCH_COMPLETE: Report saved to <path> (<size> bytes, <lines> lines).

9. Close the session only when the caller signals DONE or EXIT. Leaving the session open allows follow-up queries to reuse the tab.

Failure modes

• Exit 10 (login required) — trigger the headed-login protocol above.
• Exit 40 (DOM mismatch) — an aria-named element was not found. claude.ai likely changed its UI. Send ERROR: with stderr so the user can update the driver's JS helpers.
• Exit 20 (timeout) — hard cap reached. Report to caller and close.
• Exit 30 (extraction) — the report selector didn't find enough content. Can be retried once (re-run extract); if it fails again, send ERROR:.

Platform Quirks

• Enter = newline: Unlike other platforms, pressing Enter in claude.ai adds a newline. The driver clicks "Send message" button.
• Connectors dialog: Appears on EVERY research start. The driver dismisses it automatically with "Disable all tools" → "Confirm".
• Artifact panel: Research reports render in a document/artifact panel. The driver clicks "Open artifact" before extraction.
• Plan auto-executes: Research starts immediately after prompt submission (plan_review: informational). No approval gate needed.