AI Research Browser

AI Research Browser

Use this skill when the user wants Hermes to run AI chat, Deep Research, or Agent flows through an installed browser profile, especially Brave or Comet/Komet.

The helper CLI is:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py

Default Intent Routing

If the user only says "Starte Deep Research", "start Deep Research", or asks for Deep Research without naming a provider/browser, route the plan to Gemini Deep Research in Comet first:

• browser: comet
• profile: work
• provider: google / gemini
• mode: deep-research
• preferred Comet live-CDP port: 9333 only when owner/profile verification proves it is Comet
• first action: real-session-preflight or workflow-run without --submit

Do not choose Brave, ChatGPT, sibling, clone, or a broad provider suite for this ambiguous prompt unless the user explicitly names that target or Comet/Gemini is blocked and an explicit fallback is allowed. If port 9333 is occupied by VS Code, Code Helper, another browser, or any non-CDP listener, do not treat that port as Comet and do not ask the user to use it; run restart recovery dry-run so the CLI can allocate a free CDP port for the real Comet profile. A safe first command is:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py real-session-preflight \
  --browser comet \
  --profile work \
  --provider google \
  --port 9333 \
  --output /tmp/hermes-comet-gemini-preflight.json

If the preflight returns port_collision.detected=true, immediately produce a safe recovery plan instead of blocking on the occupied port. If the same preflight also reports an attach_port from alternate_cdp.found=true, use that port directly and skip restart recovery:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py browser-cdp-recover \
  --browser comet \
  --profile work \
  --provider google \
  --port 9333 \
  --dry-run \
  --output /tmp/hermes-comet-gemini-recover.json

What It Does

• Discovers installed Chromium-family browsers: Brave, Comet/Komet, Google Chrome, Microsoft Edge, Opera, and ChatGPT Atlas.
• Reads Chromium profile metadata from Local State and Preferences, including profile directory, display name, and visible account email when available.
• Resolves profile aliases such as work by exact profile/account match first, then by a Work/Arbeit name match.
• Produces launch arguments for headless or background runs with --remote-debugging-port, --user-data-dir, and --profile-directory.
• Starts launchable browsers hidden in the background via macOS open -g -j, with optional true headless mode and a dry-run JSON plan before execution.
• Supports provider modes for ChatGPT chat, ChatGPT Deep Research, ChatGPT Agent, Gemini chat, Gemini Deep Research, Gemini Agent, Claude chat/research/artifacts, Perplexity research, and Grok/Grog research.
• Builds a full browser x profile x provider x feature test matrix for systematic E2E runs.
• Provides an interactive wizard that lets a human choose the installed browser, profile, provider, and feature before launching or testing.
• Archives existing provider chats into a local cache so later runs can continue from cached transcripts or intentionally refresh by scraping again.
• Reopens cached/existing chat URLs with workflow-followup, optionally sends a follow-up such as "Fass zusammen" only when --submit is present, exports Markdown, and refreshes the local cache.
• Attaches local files/images to workflow-run and workflow-followup when the provider exposes a visible file input, and records no-file-input instead of guessing when the upload path is hidden.
• Discovers installed SaveAI / AI Exporter extension manifests and can copy/load selected extensions into temporary profile clones for export-oriented tests.
• Reverse-engineers installed SaveAI / AI Exporter capabilities, including supported provider hosts, Markdown/PDF/JSON/image export actions, Notion sync actions, and local Notion session evidence without cookie values.
• Extracts visible provider account, plan/subscription, model, quota, and usage text when a real UI snapshot is supplied.
• Scans local profile site data for provider session evidence without reading or emitting cookie values.
• Runs a real-session preflight that checks CDP reachability, default-port ownership, already-running browsers without remote debugging, and provider session evidence before any paid workflow is claimed as usable.
• Runs Agent Browser backed E2E probes against a CDP-enabled browser profile and records provider inventory artifacts.
• Runs an Agent Browser live suite against a real CDP-enabled browser session and can fail hard when the page is signed out or blocked.
• Runs workflow-live-run against a real CDP-enabled background browser session, opens only a new automation tab, leaves existing tabs/windows alone, and leaves long-running Deep Research/Agent tabs open for later follow-up/export.
• Runs workflow-sibling-run against a persistent sibling automation profile: a separate --user-data-dir launched offscreen/headful with CDP, so active user windows are not closed, relaunched, or navigated.
• Fills a provider composer through Agent Browser, optionally submits the prompt, exports the visible output, and saves it into the local chat cache.
• Builds a focused primary feature suite for ChatGPT chat/model selection, ChatGPT Deep Research, ChatGPT Agent, Gemini Deep Research, Claude Opus, Grok chat/research, and Perplexity chat/research.
• Runs Agent Browser against disposable browser-profile clones and records signed-out-or-wall when the cloned session hits login or anti-automation pages.
• Exposes provider-specific probe hints for account menus, model selectors, tool controls, and usage/limit text.
• Lists automation backends such as Playwright/CDP, Codex Computer Use, Peekaboo, Unbrowser Local, CloakBrowser, OpenAI CUA/Operator, Claude Computer Use, Gemini Computer Use, Stagehand, Browser-Use, and Hyperbrowser.
• Lists Peter Steinberger's Oracle 0.13 as an optional consult/backend layer for multi-model review, browser-session reattach, long-running Deep Research/Agent supervision, attachment readiness, and session artifacts. workflow-run defaults to Oracle assist artifacts for long-run observability, but local guards still decide whether anything is submitted.
• Lists selectable model/tool catalogs for ChatGPT, Gemini/Google, Claude/Anthropic, Perplexity, and Grok/xAI.
• Marks profiles as signed-in-hidden when browser metadata indicates account/session state but no email is exposed.
• Reports app_exists, binary_exists, and user_data_exists so stale browser profile data is not confused with a launchable installed browser.
• Records E2E evidence as a status.json plus screenshot path, so a human can verify whether the provider UI actually entered the requested mode.

Safety Rule

Do not quit or relaunch the user's already-open browser without explicit permission. If a browser is already running without --remote-debugging-port, run preflight and report the blocker. Prefer launch-background --dry-run or launch-all-background --dry-run before execution, so the user can see whether the run will attach, launch hidden, or be blocked. For live UI checks, use Computer Use against the existing window and record screenshots locally.

For Agent Browser "truth" checks, prefer agent-browser-live-suite --assert-login against a known real CDP port. Do not trust agent-browser --auto-connect unless the captured provider UI proves the intended profile/account is logged in; auto-connect can attach to a signed-out clone or the wrong Chromium instance.

For actual Deep Research or Agent execution in a standing background browser, prefer workflow-live-run or workflow-orchestrate --live-cdp --port <port>. These commands require real-session-preflight.can_attach=true; if the browser is already running without remote debugging, they report the blocker instead of closing or relaunching the user's browser.

When the running browser is not CDP-attachable and must not be closed, use workflow-sibling-run. It never starts a second process on the original profile directory; it seeds or reuses a dedicated sibling profile, removes only stale locks there, launches the browser offscreen/headful with a fresh CDP port, and optionally closes only that launched sibling process with --close-after. Treat hot-cloned provider sessions as provisional: if Google, ChatGPT, or another provider shows Anmelden/sign-in after clone seeding, record signed-out-or-wall and seed a persistent sibling profile with a real one-time login instead of claiming the workflow worked.

Use sibling-profile-init for that one-time setup. It opens the separate automation profile visibly so the user can complete login, DBSC/device-bound checks, consent, or provider challenges inside the sibling profile. Future workflow-sibling-run calls then reuse the same --sibling-user-data in the background.

Do not commit private screenshots that contain account names, chat history, or private prompts to a public repository. Keep them as local artifacts unless the user explicitly asks for a sanitized export.

Commands

Discover browsers, profiles, providers, modes, and known model labels:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py discover

Build the full test matrix:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py matrix --json --backend playwright-cdp

List automation backends:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py backends

Build an Oracle 0.13 dry-run/reattach plan for a real CDP browser session:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py oracle-plan \
  --prompt "Review the current failed E2E browser workflow." \
  --remote-chrome 127.0.0.1:9223 \
  --research-depth deep \
  --model gpt-5.5-instant \
  --browser-attachment-timeout 240

For long ChatGPT/Gemini browser workflows, workflow-run can include Oracle evidence without bypassing local guards:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py workflow-run \
  --browser brave \
  --profile work \
  --provider chatgpt \
  --mode agent \
  --prompt "Analysiere kurz, warum Oracle-Reattach im aktuellen CLI-Flow stabiler sein soll." \
  --oracle-mode assist \
  --submit \
  --allow-paid-quota-use

Use --oracle-mode runner only after the normal local guards pass. Oracle runner mode is blocked by the CLI when login, visible account, plan, feature, screenshot, rate-limit, or ChatGPT model-safety checks fail. For ChatGPT tests, the guard blocks Pro/Extended Pro/GPT-5.5 Pro selections before typing; use non-Pro Thinking, Agent, or Deep Research instead.

Focused Oracle E2E smoke is opt-in only:

AI_RESEARCH_BROWSER_E2E=1 \
python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py oracle-e2e-smoke \
  --browser brave \
  --profile work \
  --provider chatgpt \
  --mode thinking \
  --cdp-port 9223

Plan CloakBrowser Manager locally without storing proxy secrets in artifacts:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py cloakbrowser-manager-plan --port 18080
AI_RESEARCH_BROWSER_PROXY_FILE=~/.config/ai-research-browser/proxies.txt \
python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py cloakbrowser-preflight

CloakBrowser provider workflows require a manually logged-in profile plus a verified account baseline. workflow-run --backend cloakbrowser blocks before any UI typing unless --account-baseline points to that proof. Keep proxy files local, mode 0600, and never commit them.

List installed SaveAI / AI Exporter extension copies:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py extensions --ai-exporter

Inspect SaveAI / AI Exporter export and Notion-sync readiness:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py ai-exporter-capabilities \
  --output /tmp/hermes-ai-exporter-capabilities.json

The capability command reports supported providers, extension actions such as exportFullMarkdown, copyFullMarkdown, openFullNotionExport, and saveFullChatsToNotion, and whether Notion site cookies indicate a logged-in workspace. Treat Notion sync as an external write: export/cache locally first, then perform Notion sync only when the user requested that write.

Generate the current Unbrowser Local command plan:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py unbrowser-plan \
  --url https://gemini.google.com/app?hl=de \
  --prompt "Extract the visible provider state"

Run the current Unbrowser Local MCP stdio probe:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py unbrowser-mcp-probe \
  --url https://www.unbrowser.ai/ \
  --tool quick_fetch \
  --profile core \
  --artifact-root /tmp/hermes-unbrowser-mcp-probe \
  --output /tmp/hermes-unbrowser-mcp-probe.json

The probe starts npx -y @unbrowser/local --profile=<profile>, sends JSON-RPC initialize/tools calls over stdio, and writes events.json plus status.json. Use it for public-page extraction and Unbrowser capability checks. Keep paid provider workflows in workflow-run/workflow-followup, where browser profile, provider mode, account state, screenshots, and confirmation controls are recorded.

List model and tool catalogs:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py models
python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py models --provider anthropic
python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py models --provider google

The provider catalog should preserve common user aliases:

• google / google-gemini -> Gemini
• anthropic / entropic -> Claude
• grog / xai -> Grok

Keep provider model labels broad enough for the UI picker and exact enough for E2E assertions. Current examples include ChatGPT GPT-5.5 Pro, Gemini Complex / Thinking with 3 Pro, Perplexity Sonar Deep Research, and Grok Grok 4.1 Fast Reasoning.

Save the matrix for a later E2E run:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py matrix \
  --json \
  --output /tmp/ai-research-browser-matrix.json

Build the focused primary feature suite:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py feature-suite \
  --providers chatgpt,gemini,anthropic \
  --json \
  --output /tmp/hermes-ai-feature-suite-plan.json

Run Agent Browser against disposable profile clones:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py agent-browser-suite \
  --providers chatgpt,gemini,anthropic \
  --artifact-root /tmp/hermes-ai-research-agent-browser-e2e \
  --clone-root /tmp/hermes-ai-research-agent-browser-clones

Use --plan-only to inspect the queue first, --max-runs 1 for a smoke test, and --timeout 15 when a cloned browser is flaky. Treat signed-out-or-wall and timeout as real failed-login/automation-wall findings, not as success. For final account, plan, model, and quota proof, verify with a real running browser through Computer Use or a hidden CDP launch.

Before starting Gemini Deep Research or any paid workflow that must reuse the real account, run the real-session preflight. For an ambiguous "Starte Deep Research" request, prefer Comet/Gemini first:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py real-session-preflight \
  --browser comet \
  --profile work \
  --provider google \
  --port 9333 \
  --output /tmp/hermes-real-session-preflight-comet-gemini.json

real-session-preflight reports can_attach, attach_port, CDP endpoint attempts, port owner, running-browser blockers, port_collision, alternate_cdp, and provider session evidence. Port 9333 is only the preferred Comet port; if it belongs to VS Code, Code Helper, another browser, or any non-CDP listener, first use a discovered attach_port from the running Comet process if available, otherwise use browser-cdp-recover --dry-run and the recovered free port instead of treating the occupied port as Comet. If a disposable clone lands on a sign-in page while the real profile still has local provider session evidence, workflow runs are marked real-session-required. Do not claim Gemini Deep Research, ChatGPT Agent, or ChatGPT Deep Research started until a real CDP-enabled browser session or a dedicated minimized browser window confirms the provider UI state.

The profile alias work resolves by exact directory/name/account first, then by Work/Arbeit labels, and finally to the only discovered profile when a browser has exactly one local profile. This lets single-profile Comet/Komet setups run through --profile work without hard-coding a machine-specific directory name.

Run fixed provider workflows from a temporary profile clone:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py workflow-plan \
  --browser brave \
  --profile work \
  --provider chatgpt \
  --mode agent \
  --prompt "Custom prompt" \
  --submit \
  --confirm-start

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py workflow-run \
  --browser comet \
  --profile work \
  --provider google \
  --mode deep-research \
  --prompt "Custom Deep Research prompt" \
  --submit \
  --confirm-start \
  --cache

Run the same workflow through a persistent offscreen sibling profile:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py workflow-sibling-run \
  --browser comet \
  --profile work \
  --provider google \
  --mode deep-research \
  --prompt "Custom Deep Research prompt" \
  --submit \
  --confirm-start \
  --cache

Use --sibling-user-data <dir> for an explicit automation profile, --refresh-sibling to re-seed it from the source profile, and --close-after for smoke tests. Omit --submit for setup/dry-runs and do not claim Deep Research/Agent started unless the status artifacts show the provider UI was logged in and the requested mode was visible.

Initialize a fresh sibling profile for manual provider login:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py sibling-profile-init \
  --browser comet \
  --profile work \
  --provider google \
  --sibling-user-data ~/.cache/ai-research-browser/sibling-profiles/comet-google/user-data

If the workflow later reports real-session-required, the UI evidence contradicted local cookie/session evidence. Treat that as a required manual login/challenge step in the sibling profile, not as a started provider workflow.

Run the complete orchestrated evidence path for Gemini/ChatGPT/Perplexity/Grok workflows:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py workflow-orchestrate \
  --browser brave \
  --profile work \
  --provider google \
  --mode deep-research \
  --prompt "Custom Deep Research prompt" \
  --unbrowser \
  --unbrowser-session \
  --include-ai-exporter \
  --followup \
  --notion-sync \
  --output /tmp/hermes-gemini-orchestrate.json

workflow-orchestrate runs real-session preflight, optional Unbrowser Local MCP proof, optional Unbrowser session_management list/health, SaveAI / AI Exporter capability parsing, the Agent Browser workflow, optional "Fass zusammen" follow-up, and a Notion export eligibility plan. It does not quit or relaunch existing browsers. Notion sync remains ineligible unless --allow-external-write is set and a local exportable output exists.

Check Unbrowser saved session state directly:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py unbrowser-session \
  --action health \
  --domain gemini.google.com \
  --session-profile default \
  --output /tmp/hermes-unbrowser-gemini-session.json

Use Unbrowser session checks as supporting evidence only. A paid or long-running provider workflow still needs a real CDP/browser proof before Hermes claims that Deep Research or Agent actually started.

Attach an image or file when the provider exposes a file input:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py workflow-run \
  --browser brave \
  --profile work \
  --provider google \
  --mode chat \
  --prompt "Analyze the attached image." \
  --attachment /tmp/example-image.png \
  --cache

Attachment upload uses CDP DOM.setFileInputFiles against the temporary clone only. The workflow first opens known upload menus such as Gemini's Menü „Datei hochladen“ öffnen; if the provider changes the menu or still hides the file input, the workflow records no-file-input for E2E evidence.

Run the focused workflow suite for the main agentic/research features:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py workflow-suite \
  --browsers brave \
  --profile work \
  --submit \
  --confirm-start \
  --continue-on-failure \
  --cache

The default suite covers ChatGPT Agent, ChatGPT Deep Research, Gemini Deep Research, Perplexity Research, Grok Research/DeepSearch, and Claude Research/Search. Use --plan-only before a long run, --max-runs 1 for smoke tests, --features provider:mode for a hand-picked queue, and --all-features for every workflow mode implemented by the script.

workflow-run --strategy auto is real-session first: it attaches only to a verified live CDP session or produces a restart-recovery plan when explicitly allowed. It does not silently launch disposable profile clones or sibling profiles for real ChatGPT/Gemini E2E; use --strategy diagnostic-clone, workflow-sibling-run, or --allow-sibling-fallback only when that isolation path is intentionally being tested. Before any UI typing, the workflow checks paid-quota permission, active cooldowns in --rate-limit-state, login/account/plan/model/feature evidence, and screenshots. If a provider rate-limit, CAPTCHA, challenge, or wait message was detected earlier, single workflow commands return status=rate-limited with pause_required/resume_after instead of retrying. Confirmation must use exact visible controls; do not let generic labels such as Start match dictation, voice, or unrelated UI. If no exact start/research control or running marker appears, keep the status at submitted.

After a long Deep Research run has produced a chat URL, send a follow-up summary request and export/cache the current chat:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py workflow-followup \
  --browser brave \
  --profile work \
  --provider google \
  --chat-url https://gemini.google.com/app/example \
  --prompt "Fass den Deep-Research-Report kompakt zusammen." \
  --include-ai-exporter \
  --attachment /tmp/context-note.pdf \
  --cache \
  --export-markdown /tmp/gemini-followup.md

Use the interactive picker:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py wizard --headful

Preview a hidden background launch for one browser:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py launch-background \
  --browser opera \
  --profile Default \
  --provider google \
  --mode deep-research \
  --model "Thinking with 3 Pro" \
  --dry-run

Preview hidden background launches for every launchable browser:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py launch-all-background \
  --provider chatgpt \
  --mode agent \
  --model "GPT-5.5 Pro" \
  --dry-run

Remove --dry-run only when you actually want to start the background sessions. Use --headless for zero-window browser processes; otherwise the CLI uses hidden macOS app launches and an osascript hide guard.

Capture account/login/quota status from visible provider UI text:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py accounts \
  --browser brave \
  --profile work \
  --provider chatgpt \
  --text-file /tmp/chatgpt-visible-text.txt

Build a local-only account/subscription audit across every discovered browser/profile/provider:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py account-audit \
  --output /tmp/ai-account-audit.json

account-audit reports session_evidence for ChatGPT, Gemini/Google, Claude/Anthropic, Grok/xAI, Perplexity, and OpenRouter. Treat likely-logged-in as a strong local session indicator, but still use e2e-probe or a visible UI capture for exact account email, subscription name, and remaining quota.

Parse already captured provider UI text files named <browser>-<profile>-<provider>.txt:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py account-audit \
  --text-dir /tmp/ai-provider-ui-text \
  --output /tmp/ai-account-audit.json

Treat account-audit JSON as private local evidence: it may contain names, emails, subscription labels, model names, and remaining Deep Research/Agent usage. Do not commit it.

List provider-specific probe hints:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py probe-specs
python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py probe-specs --provider anthropic

Run a real Agent Browser/CDP E2E probe:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py e2e-probe \
  --artifact-root /tmp/hermes-ai-research-e2e \
  --browser chrome \
  --profile "Profile 2" \
  --provider chatgpt \
  --mode chat \
  --cdp-port 9224 \
  --open-controls

Parse a captured UI snapshot without touching a browser:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py e2e-probe \
  --artifact-root /tmp/hermes-ai-research-e2e \
  --browser opera \
  --profile Default \
  --provider anthropic \
  --mode chat \
  --text-file /tmp/opera-claude-visible-text.txt

Generate Oracle fetch/show commands:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py oracle-plan \
  -p "Review the provider E2E probes" \
  --file "skills/software-development/ai-research-browser/**" \
  --cdp-port 9224 \
  --deep-research

Parse visible existing chat names from a sidebar/list:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py parse-chats \
  --provider chatgpt \
  --text-file /tmp/chat-sidebar-visible-text.txt

Save a current conversation transcript into the cache:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py save-chat \
  --browser brave \
  --profile Default \
  --provider chatgpt \
  --chat-url https://chatgpt.com/c/example \
  --title "Existing research chat" \
  --text-file /tmp/chat-transcript.txt

Reuse cached chat data when available:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py chat-cache \
  --browser brave \
  --profile Default \
  --provider chatgpt \
  --chat-url https://chatgpt.com/c/example \
  --include-text

Force a fresh scrape/update:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py chat-cache \
  --browser brave \
  --profile Default \
  --provider chatgpt \
  --chat-url https://chatgpt.com/c/example \
  --text-file /tmp/fresh-chat-transcript.txt \
  --refresh

List the cache:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py list-chats

Check whether a browser/profile can be launched for CDP automation:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py preflight \
  --browser comet \
  --profile work

Build a hidden/headless launch command for ChatGPT Deep Research:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py launch-args \
  --browser brave \
  --profile work \
  --provider chatgpt \
  --mode deep-research \
  --model GPT-5.5

Use --headful when you need to see the browser or when a provider blocks headless mode. Model selection is recorded in the launch plan as model_selection: select-in-provider-ui; a real E2E must verify the model picker visibly selected that model.

Verify captured UI text against expected mode markers:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py verify-text \
  --provider chatgpt \
  --mode deep-research \
  --text-file /tmp/chatgpt-visible-text.txt

Record an E2E result with a screenshot path:

python3 skills/software-development/ai-research-browser/scripts/ai_research_browser.py record-e2e \
  --artifact-root /tmp/hermes-ai-research-e2e \
  --browser brave \
  --profile work \
  --provider chatgpt \
  --mode deep-research \
  --status verified \
  --screenshot /tmp/chatgpt-deep-research.png \
  --text-file /tmp/chatgpt-visible-text.txt \
  --note "Deep Research was selected in the ChatGPT tools menu."

E2E Workflow

1. Run discover and choose an installed browser and profile.
2. Run preflight before attempting CDP/headless control.
3. If preflight is clean, launch with the generated launch-args; otherwise use Computer Use against the existing browser window.
4. Navigate to the provider:
   • ChatGPT: https://chatgpt.com/
   • Gemini: https://gemini.google.com/app?hl=de
   • Claude: https://claude.ai/new
   • Perplexity: https://www.perplexity.ai/
   • Grok: https://grok.com/
5. Select the requested mode in the provider UI.
6. Capture a real screenshot of the browser tab.
7. Extract visible UI text from Accessibility or the page.
8. Run verify-text and record-e2e.
9. Report whether the mode was truly started, only selected, blocked, or failed.

Provider Notes

ChatGPT Deep Research is selected through the tools menu. A valid E2E needs to show the composer in Deep Research mode or a started research report.

ChatGPT Agent is selected through the tools menu or mode chip. A valid E2E needs to show the composer/task area in Agent mode or an active agent run.

Gemini Deep Research may be labeled Deep Research, Recherche starten, or Start research depending on locale and account state.

Gemini Agent availability varies by account and region. Record the visible account/model/quota text when it is shown.

Claude research and artifacts availability varies by account and current UI. A valid E2E should capture the visible mode marker, generated artifact panel, or sources/search state.

Grok may be typed as grok or grog in the CLI. Availability of research modes depends on the account and current Grok UI.

Design Notes

This follows the same shape that makes Peter Steinberger's Peekaboo and Oracle useful for agents: separate discovery/snapshot JSON from actions, print a browser-control plan before touching a shared desktop, and avoid profile races by reusing reachable browser state or reporting blockers. The matrix command is the snapshot, while wizard, launch-args, launch-background, launch-all-background, verify-text, and record-e2e are the action/evidence layer.

If a user says "Oracle" in this context, check Peter Steinberger's steipete/oracle pattern first: API mode when possible, browser mode only with an explicit control plan, remote/reachable browser reuse, auto-reattach, Deep Research, and session artifacts. The CLI exposes Oracle as oracle for consult/code-review help and long-running session capture, and oracle-plan prints dry-run/status/session commands. It exposes OpenAI CUA as openai-cua, but keeps local logged-in browser profiles under playwright-cdp, computer-use, agent-browser, or peekaboo.

Testing

Run unit tests from the repository root:

python3 -m unittest discover -s skills/software-development/ai-research-browser/tests -p 'test_*.py'