Repository avatar
AI Tools
v1.1.0
active

electron-agent-bridge

io.github.Chavagov123/electron-agent-bridge

See and drive any Electron app: pages, IPC, logs, network, state and main process.

Documentation

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.

Quick start

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' } }] });

Documentation

ModesIntegrated and Launch mode, gates, packaged builds
FlowsYAML tests and eab run
IPCwhat is recorded, correlation, values policy
Logs and networksources, custom loggers, network metadata
StateregisterState, the devtools shim, reads, dispatch
Main controlwindows, menus, dialog stubs, eval
Bundlerselectron-vite, Forge, webpack
Securitythreat model and capabilities; SECURITY.md for reports
Architecturepackages, data flow, design decisions (ADRs)
API referenceevery exported function and type (TypeDoc; pnpm docs:api builds it locally)

Packages

Package
@electron-agent-bridge/electronin-app runtime (main process); /register, /renderer (registerState), /inject (Launch mode)
@electron-agent-bridge/mcpeab-mcp (MCP server over stdio) and the eab CLI
@electron-agent-bridge/clientNode API: connect, launch, flows
@electron-agent-bridge/attachAttach mode: drive a running app's pages over --remote-debugging-port
@electron-agent-bridge/core, @electron-agent-bridge/engine, @electron-agent-bridge/page-agentprotocol, engine and in-page agent (used by the others)

Development

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.

NPM
@electron-agent-bridge/mcp
Install Command
npm install @electron-agent-bridge/mcp
Runtime: npx