Agent Browser Electron

Agent Browser Electron

Overview

Inspect Electron renderer windows reliably when agent-browser alone is not enough to tell which CDP target maps to which visible app window.

Prefer raw CDP target discovery over guessing from tab list, then use agent-browser --cdp <port> tab stable tab IDs to interact with the renderer target you want.

Preserve Window Roles

Before navigation, identify each relevant window's business role and the action that opens it. Inspect the app's window factories and open handlers when the role is unclear. Correlate those roles with CDP targets before interaction.

A renderer route does not define the complete window. Window creation also establishes mouse handling, focus, transparency, IPC handlers, and lifecycle behavior. Loading another route does not transfer those responsibilities.

• Keep the main stage in its main window. Do not replace it with settings or chat through open, goto, location.hash, router calls, or loadURL.
• Open the target window through the app UI. For diagnostic access, use its existing Electron open handler when UI access fails. Report that distinction in the results.
• Enumerate CDP targets again after the window opens. Attach to that window, then navigate within its business role.
• If clicks fail, inspect the target window and its mouse or focus behavior. Do not bypass the failure through navigation in another window.
• After the interaction, verify that the main stage remains intact and that the target window accepts input. Programmatic activation alone does not prove that user clicks work.

Why Raw CDP Discovery

Use raw CDP target discovery because agent-browser is operating as a convenience layer on top of Chrome DevTools Protocol, and that layer can hide or flatten details that matter in Electron.

Raw /json/list is the source of truth for CDP target discovery because it exposes Chromium's target inventory without extra interpretation. It is not the same thing as Electron's BrowserWindow.getAllWindows().

In Electron, that distinction matters because:

• multiple BrowserWindow instances can share the same URL
• some windows are created lazily and appear only after an app action
• a visible Electron window is inspectable only after its renderer/webContents exists and is exposed as a CDP target
• detached DevTools pages and workers add noise
• agent-browser tab list may show only a subset of targets or present them with reduced metadata
• session state inside agent-browser can keep you attached to a previous renderer unless you reset and verify

In practice, the higher-level tab list view is useful for quick browsing, but not reliable enough for window-to-target mapping when:

• two Electron windows both look like http://localhost:5173/#/
• the title is empty or collapsed
• a chat or settings window exists in CDP but is not obvious in the simplified tab output

Use curl http://127.0.0.1:<port>/json/list first whenever correct target selection matters. Treat agent-browser as the interaction client after target discovery, not as the only discovery source.

If /json/list does not contain a window that the user says exists, do not assume agent-browser hid it. First consider that the window may not have been created yet, may not have loaded a renderer route yet, or may not currently be exposed as a CDP target. Trigger the window from the app UI or Electron main-process action, then enumerate /json/list again.

Workflow

1. Confirm the app exposes a CDP port.

The CDP port is project- and run-command-specific. Do not assume 9222, 9250, or any other value is universal. If an Electron process is running but no CDP port responds, tell the user to relaunch the app with the project's remote-debug environment variables or launch flags.

For AIRI stage-tamagotchi on POSIX shells:

APP_REMOTE_DEBUG=true APP_REMOTE_DEBUG_PORT=9250 pnpm dev:tamagotchi

For Windows PowerShell:

$env:APP_REMOTE_DEBUG = "true"
$env:APP_REMOTE_DEBUG_PORT = "9250"
pnpm dev:tamagotchi

For Windows Git Bash:

APP_REMOTE_DEBUG=true APP_REMOTE_DEBUG_PORT=9250 pnpm dev:tamagotchi

Adjust the port to match what the user actually started. If the project uses a different mechanism, inspect its Electron launch code before giving command advice.

2. Identify the target window's role and ensure that the window exists.

If the app uses lazy window creation, agent-browser cannot inspect a window that has not been created yet. Open it from the app UI or trigger its Electron-side open handler first.

3. Inspect raw CDP targets instead of trusting agent-browser --cdp <port> tab.

curl -sS http://127.0.0.1:<port>/json/list

Read these fields:

• title
• url
• type
• webSocketDebuggerUrl

Use /json/version if you need to confirm the port is a Chromium/Electron CDP endpoint or need the browser-level debugger URL:

curl -sS http://127.0.0.1:<port>/json/version

4. Match the target to the Electron window.

Common patterns:

• Distinct route: chat may be http://localhost:5173/#/chat while the main window is http://localhost:5173/#/.
• Distinct title: Electron window titles may surface in the target list.
• Duplicate URLs: two windows may both report http://localhost:5173/#/; in that case use screenshots, snapshots, and Electron app knowledge to disambiguate.
• Hidden noise: worker targets and detached DevTools targets are not your app window.

5. List the targets through agent-browser and switch with stable tab IDs.

agent-browser --cdp <port> tab
agent-browser --cdp <port> tab t2

Do not use positional integers. If agent-browser tab prints [t2], switch with tab t2.

6. Verify the target immediately.

agent-browser --cdp <port> get url
agent-browser --cdp <port> get title
agent-browser --cdp <port> snapshot -i

7. If stable tab switching is not enough, reset session state and reconnect.

agent-browser close --all
agent-browser connect <webSocketDebuggerUrl>
agent-browser get url

If needed:

agent-browser --cdp <port> screenshot /tmp/electron-target.png --annotate
agent-browser --cdp <port> console
agent-browser --cdp <port> errors