Skip to content

feat(browser): attach to a running Chrome session via direct CDP #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
seichris merged 2 commits into from
Mar 26, 2026
Merged

feat(browser): attach to a running Chrome session via direct CDP #6

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c8972e7
feat(browser): attach to running browsers via direct CDP
dedene Mar 19, 2026
5ca4887
Fix attach-running validation and docs
seichris Mar 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,14 @@

## Unreleased

### Added

- Browser: add `--browser-attach-running` to reuse a local already-running signed-in Chrome through Chrome’s local remote-debugging toggle. Oracle opens a dedicated tab, stores attach metadata for reattach, and leaves the browser itself untouched.

### Docs

- Browser: document the new attach-running workflow and add a manual smoke test for the direct attach path.

## 0.9.0 — 2026-03-08

### Changed
Expand Down
15 changes: 8 additions & 7 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -211,9 +211,10 @@ oracle --engine browser \
| `--chatgpt-url <url>` | Target a ChatGPT workspace/folder (browser). |
| `--browser-model-strategy <select\|current\|ignore>` | Control ChatGPT model selection in browser mode (current keeps the active model; ignore skips the picker). |
| `--browser-manual-login` | Skip cookie copy; reuse a persistent automation profile and wait for manual ChatGPT login. |
| `--browser-attach-running` | Reuse your current local browser session through local `DevToolsActivePort` discovery; Oracle opens a dedicated tab instead of launching Chrome (defaults to `127.0.0.1:9222`, or combine with `--remote-chrome 127.0.0.1:<port>` to hint a different local loopback endpoint). |
| `--browser-thinking-time <light\|standard\|extended\|heavy>` | Set ChatGPT thinking-time intensity (browser; Thinking/Pro models only). |
| `--browser-port <port>` | Pin the Chrome DevTools port (WSL/Windows firewall helper). |
| `--browser-inline-cookies[(-file)] <payload \| path>` | Supply cookies without Chrome/Keychain (browser). |
| `--browser-inline-cookies[(-file)] <payload \| path>` | Supply cookies without Chrome/Keychain (browser). |
| `--browser-timeout`, `--browser-input-timeout` | Control overall/browser input timeouts (supports h/m/s/ms). |
| `--browser-recheck-delay`, `--browser-recheck-timeout` | Delayed recheck for long Pro runs: wait then retry capture after timeout (supports h/m/s/ms). |
| `--browser-reuse-wait` | Wait for a shared Chrome profile before launching (parallel browser runs). |
Expand All @@ -229,7 +230,7 @@ oracle --engine browser \
| `--files-report` | Print per-file token usage. |
| `--dry-run [summary\|json\|full]` | Preview without sending. |
| `--remote-host`, `--remote-token` | Use a remote `oracle serve` host (browser). |
| `--remote-chrome <host:port>` | Attach to an existing remote Chrome session (browser). |
| `--remote-chrome <host:port>` | Attach to an existing remote Chrome session (browser), or when combined with `--browser-attach-running` use a local loopback host:port hint such as `127.0.0.1:63332`. |
| `--youtube <url>` | YouTube video URL to analyze (Gemini browser mode). |
| `--generate-image <file>` | Generate image and save to file (Gemini browser mode). |
| `--edit-image <file>` | Edit existing image with `--output` (Gemini browser mode). |
Expand All @@ -255,11 +256,11 @@ See [docs/configuration.md](docs/configuration.md) for precedence and full schem

Advanced flags

| Area | Flags |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Browser | `--browser-manual-login`, `--browser-thinking-time`, `--browser-timeout`, `--browser-input-timeout`, `--browser-recheck-delay`, `--browser-recheck-timeout`, `--browser-reuse-wait`, `--browser-profile-lock-timeout`, `--browser-auto-reattach-delay`, `--browser-auto-reattach-interval`, `--browser-auto-reattach-timeout`, `--browser-cookie-wait`, `--browser-inline-cookies[(-file)]`, `--browser-attachments`, `--browser-inline-files`, `--browser-bundle-files`, `--browser-keep-browser`, `--browser-headless`, `--browser-hide-window`, `--browser-no-cookie-sync`, `--browser-allow-cookie-errors`, `--browser-chrome-path`, `--browser-cookie-path`, `--chatgpt-url` |
| Run control | `--background`, `--no-background`, `--http-timeout`, `--zombie-timeout`, `--zombie-last-activity` |
| Azure/OpenAI | `--azure-endpoint`, `--azure-deployment`, `--azure-api-version`, `--base-url` |
| Area | Flags |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Browser | `--browser-manual-login`, `--browser-attach-running`, `--browser-thinking-time`, `--browser-timeout`, `--browser-input-timeout`, `--browser-recheck-delay`, `--browser-recheck-timeout`, `--browser-reuse-wait`, `--browser-profile-lock-timeout`, `--browser-auto-reattach-delay`, `--browser-auto-reattach-interval`, `--browser-auto-reattach-timeout`, `--browser-cookie-wait`, `--browser-inline-cookies[(-file)]`, `--browser-attachments`, `--browser-inline-files`, `--browser-bundle-files`, `--browser-keep-browser`, `--browser-headless`, `--browser-hide-window`, `--browser-no-cookie-sync`, `--browser-allow-cookie-errors`, `--browser-chrome-path`, `--browser-cookie-path`, `--chatgpt-url` |
| Run control | `--background`, `--no-background`, `--http-timeout`, `--zombie-timeout`, `--zombie-last-activity` |
| Azure/OpenAI | `--azure-endpoint`, `--azure-deployment`, `--azure-api-version`, `--base-url` |

Remote browser example

Expand Down
13 changes: 12 additions & 1 deletion bin/oracle-cli.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,6 +125,7 @@ interface CliOptions extends OptionValues {
browserChromeProfile?: string;
browserChromePath?: string;
browserCookiePath?: string;
browserAttachRunning?: boolean;
chatgptUrl?: string;
browserUrl?: string;
browserTimeout?: string;
Expand Down Expand Up @@ -460,6 +461,12 @@ program
"Explicit Chrome/Chromium cookie DB path for session reuse.",
),
)
.addOption(
new Option(
"--browser-attach-running",
"Attach to a running local browser session instead of launching Chrome (defaults to 127.0.0.1:9222; combine with --remote-chrome 127.0.0.1:<port> to hint a different local loopback port).",
),
)
.addOption(
new Option(
"--chatgpt-url <url>",
Expand Down Expand Up @@ -609,7 +616,7 @@ program
.addOption(
new Option(
"--remote-chrome <host:port>",
"Connect to remote Chrome DevTools Protocol (e.g., 192.168.1.10:9222 or [2001:db8::1]:9222 for IPv6).",
"Connect to remote Chrome DevTools Protocol, or when combined with --browser-attach-running use a local loopback host:port as the attach hint.",
),
)
.addOption(
Expand Down Expand Up @@ -2091,6 +2098,10 @@ function printDebugHelp(cliName: string): void {
["--browser-chrome-profile <name>", "Reuse cookies from a specific Chrome profile."],
["--browser-chrome-path <path>", "Point to a custom Chrome/Chromium binary."],
["--browser-cookie-path <path>", "Use a specific Chrome/Chromium cookie store file."],
[
"--browser-attach-running",
"Attach to your current Chrome session through its local remote debugging toggle.",
],
["--browser-url <url>", "Alias for --chatgpt-url."],
["--browser-timeout <ms|s|m>", "Cap total wait time for the assistant response."],
["--browser-input-timeout <ms|s|m>", "Cap how long we wait for the composer textarea."],
Expand Down
Loading