@prbe.ai/electron-sdk

A lightweight TypeScript SDK that adds an AI debug agent to your Electron app. When users hit a bug, the agent investigates autonomously — reading files, searching logs, exploring your codebase — and produces a structured report for your team.

Zero external runtime dependencies. Node.js built-ins only.

Install

npm install @prbe.ai/electron-sdk

Requires Node.js 18+ (for native fetch and WebSocket).

Quick Start

import { PRBEAgent, PRBEAgentConfigKey } from "@prbe.ai/electron-sdk";
import { app } from "electron";

const agent = new PRBEAgent({
  [PRBEAgentConfigKey.API_KEY]: "your-api-key",
  [PRBEAgentConfigKey.AUTO_APPROVED_DIRS]: [
    app.getPath("userData"),
    app.getAppPath(),
  ],
});

// Run an investigation
agent.investigate("App crashes when opening settings");

Configuration

All config keys are available via the PRBEAgentConfigKey enum:

| Key | Type | Default | Description | |-----|------|---------|-------------| | API_KEY | string | required | Your PRBE API key | | AUTO_APPROVED_DIRS | string[] | required | Directories the agent can access without asking the user | | APP_DATA_PATH | string | — | Path to the app's data directory (e.g. Electron userData). Sent to the agent so it explores this directory first. | | BACKGROUND_POLLING | boolean | true | Poll for context requests in the background | | POLLING_INTERVAL | number | 600000 | Polling interval in ms (10 min) | | CAPTURE_CONSOLE | boolean | true | Capture console.* calls into the log buffer | | MAX_LOG_ENTRIES | number | 10000 | Max entries in the in-memory log buffer | | INTERACTION_HANDLER | PRBEInteractionHandler | — | Handler for user interaction requests (ask questions, request permissions) | | ELECTRON_LOG | object | — | electron-log v5 instance for log capture | | IPC_MAIN | object | — | Electron ipcMain for renderer log forwarding | | RENDERER_LOG_CHANNEL | string | "prbe-renderer-log" | IPC channel name for renderer logs |

Listening to State

The agent exposes an observable state via EventEmitter:

import { PRBEStateEvent } from "@prbe.ai/electron-sdk";

agent.state.on(PRBEStateEvent.STATUS, () => {
  console.log("Status:", agent.state.currentStatus);
  console.log("Events:", agent.state.events);
});

agent.state.on(PRBEStateEvent.ERROR, (payload) => {
  console.error("Investigation error:", payload.message);
});

Custom Tools

Register tools that the AI agent can call during investigations:

agent.registerTool(
  "get_database_stats",
  "Returns row counts for all tables in the local database",
  [
    { name: "table_filter", type: ToolParamType.STRING, description: "Optional table name filter", required: false },
  ],
  async (args) => {
    const filter = args.table_filter as string | undefined;
    const stats = await getDbStats(filter);
    return JSON.stringify(stats);
  },
);

Built-in Tools

The SDK ships with 11 built-in tools that the agent uses automatically:

Filesystem — list_directory, read_file, search_content, find_files, flag_file

Logs — read_app_logs, search_app_logs, clear_app_logs, flag_app_logs

Interactive — ask_user, bash_execute (requires INTERACTION_HANDLER)

All filesystem access is sandboxed to your configured AUTO_APPROVED_DIRS. The agent can request access to paths outside these directories via the interaction handler, and the user can approve or deny each request individually.

Interactive tools are marked with interactive: true in their declaration, which tells the middleware to use a longer timeout (10 minutes) since they require user input.

Renderer-Safe Types

For renderer/browser code that needs PRBE types without Node.js imports:

import type { PRBESerializedState } from "@prbe.ai/electron-sdk/types";

Serialization

Serialize agent state for IPC transport to your renderer process:

import { serializePRBEState, DEFAULT_PRBE_STATE } from "@prbe.ai/electron-sdk";

// Send to renderer
const serialized = serializePRBEState(agent.state);
mainWindow.webContents.send("prbe-state", serialized);

Links

• Website

License

MIT