electron-agent-bridge
    Preparing search index...

    electron-agent-bridge

    electron-agent-bridge

    npm CI License: MIT

    Let AI agents, scripts and tests see and drive any Electron app: its pages, IPC, logs, network, state and main process. One bridge, three ways in: an MCP server for agents (Claude Code and other MCP hosts), the eab CLI, and a typed Node API, plus YAML flows for tests.

    • See the app the way a user does. Compact accessibility snapshots with stable refs (button "Save" [e12]), deltas of what changed, frames, views, webviews and offscreen windows, screenshots; console and network of workers and service workers too.
    • Act like a user. Trusted clicks, typing, filling forms, keys, drag and drop, uploads, with auto-waiting and errors that say why (OCCLUDED by dialog "Confirm"), plus what the app did in response: dialogs, toasts, console errors, failed requests, IPC.
    • See inside. IPC on both sides with request/response correlation, renderer and main logs, crashes, network metadata, Redux / Zustand / MobX state, application menus, native dialogs.
    • Safe by default. Off unless EAB_ENABLE=1; refuses packaged builds unless opted in; local socket plus token; capability tiers (eval never by default); secrets redacted; page content marked untrusted for agents.

    Electron 35+ on Windows, macOS and Linux.

    Integrated (the app imports the bridge, which does nothing unless enabled):

    npm install --save-dev @electron-agent-bridge/electron @electron-agent-bridge/mcp
    
    // First line of the app's main entry.
    import '@electron-agent-bridge/electron/register';
    EAB_ENABLE=1 npm start        # start the app with the bridge on
    npx eab list # running apps the bridge can reach
    npx eab snapshot # what the focused window shows

    Launch (no code change; the launcher injects the bridge into an unmodified, unfused app):

    npx eab launch ./node_modules/.bin/electron -- .
    

    For agents: add the MCP server to your MCP host, e.g. claude mcp add eab -- npx -y @electron-agent-bridge/mcp (or npx eab-mcp where @electron-agent-bridge/mcp is installed). The agent then has 14 tools: session, targets, snapshot, find, act, wait_for, screenshot, logs, network, ipc, state, app, and, where the app grants eval, dialogs and eval.

    For tests:

    # checkout.flow.yaml
    name: Place an order
    steps:
    - act:
    - { type: fill, locator: { role: textbox, name: Customer }, value: Ada }
    - { type: click, locator: { role: button, name: Save order } }
    - expect: { text: Order saved }
    - expect: { noConsoleErrors: true }
    npx eab run flows/ --junit report.xml --artifacts artifacts
    

    From code:

    import { connect } from '@electron-agent-bridge/client';

    const app = await connect();
    const { data } = await app.call('snapshot.take', {});
    await app.call('action.run', { actions: [{ type: 'click', locator: { role: 'button', name: 'Save' } }] });
    Modes Integrated and Launch mode, gates, packaged builds
    Flows YAML tests and eab run
    IPC what is recorded, correlation, values policy
    Logs and network sources, custom loggers, network metadata
    State registerState, the devtools shim, reads, dispatch
    Main control windows, menus, dialog stubs, eval
    Bundlers electron-vite, Forge, webpack
    Security threat model and capabilities; SECURITY.md for reports
    Architecture packages, data flow, design decisions (ADRs)
    API reference every exported function and type (TypeDoc; pnpm docs:api builds it locally)
    Package
    @electron-agent-bridge/electron in-app runtime (main process); /register, /renderer (registerState), /inject (Launch mode)
    @electron-agent-bridge/mcp eab-mcp (MCP server over stdio) and the eab CLI
    @electron-agent-bridge/client Node API: connect, launch, flows
    @electron-agent-bridge/attach Attach mode: drive a running app's pages over --remote-debugging-port
    @electron-agent-bridge/core, @electron-agent-bridge/engine, @electron-agent-bridge/page-agent protocol, engine and in-page agent (used by the others)
    pnpm install
    pnpm check # format, lint, typecheck, boundaries, unit tests with coverage
    EAB_E2E_ELECTRON=35,45 pnpm test:e2e
    EAB_E2E_BACKGROUND=1 EAB_E2E_ELECTRON=35,45 pnpm test:e2e # test windows stay off your screen
    pnpm hooks # optional: git hooks (conventional commits, formatting)

    See CONTRIBUTING.md. MIT licensed.