Electron Pro Guru

A senior agent for cross-platform desktop application development with Electron, covering native OS integrations, security best practices, performance optimization, and packaging for Windows, macOS, and Linux.

When to Use This Agent

Choose Electron Pro when:

• Building cross-platform desktop apps with Electron 27+
• Implementing native OS integrations (menus, notifications, file dialogs)
• Securing Electron apps (IPC, context isolation, CSP)
• Optimizing Electron app performance and memory usage
• Packaging and distributing Electron apps with auto-update

Consider alternatives when:

• Building mobile apps (use React Native or Flutter agents)
• Building web-only applications (use a web development agent)
• Using Tauri instead of Electron (use a Rust/Tauri agent)

Quick Start

Copy
# .claude/agents/electron-pro-guru.yml
name: Electron Pro
model: claude-sonnet-4-20250514
tools:
  - Read
  - Write
  - Bash
  - Glob
  - Grep
prompt: |
  You are a senior Electron developer. Build secure, performant
  desktop apps with Electron 27+. Always use context isolation,
  preload scripts, and process sandboxing. Never expose Node.js
  APIs directly to renderer processes.

Example invocation:

Copy
claude --agent electron-pro-guru "Build a desktop file manager
  with native drag-and-drop, context menus, file watching, and
  thumbnail preview. Ensure proper security with context isolation
  and sandboxed renderers."

Core Concepts

Electron Process Architecture

Main Process (Node.js)
├── BrowserWindow management
├── Native OS APIs (menus, dialogs, notifications)
├── File system access
├── IPC message handling
└── App lifecycle management

Preload Script (Bridge)
├── contextBridge.exposeInMainWorld()
├── Safe API surface for renderer
└── Input validation and sanitization

Renderer Process (Chromium)
├── Web content (HTML, CSS, JS)
├── No direct Node.js access
├── Communicates via exposed API only
└── Sandboxed by default

Security Configuration

Copy
// Main process: Secure BrowserWindow creation
const win = new BrowserWindow({
  webPreferences: {
    contextIsolation: true,      // REQUIRED
    nodeIntegration: false,      // REQUIRED
    sandbox: true,               // RECOMMENDED
    preload: path.join(__dirname, 'preload.js'),
    webSecurity: true,           // Never disable
  }
});

// Preload script: Safe API exposure
const { contextBridge, ipcRenderer } = require('electron');

contextBridge.exposeInMainWorld('api', {
  readFile: (path) => ipcRenderer.invoke('read-file', path),
  saveFile: (path, data) => ipcRenderer.invoke('save-file', path, data),
  onFileChanged: (callback) =>
    ipcRenderer.on('file-changed', (_, data) => callback(data)),
});

IPC Communication Pattern

Pattern	Direction	Use Case
ipcRenderer.invoke	Renderer → Main (async)	Request-response operations
ipcRenderer.send	Renderer → Main (fire-forget)	One-way notifications
webContents.send	Main → Renderer	Push updates to UI
ipcMain.handle	Main handler for invoke	Async operations with return
ipcMain.on	Main handler for send	Event processing

Configuration

Parameter	Description	Default
electron_version	Target Electron version	28+
framework	UI framework	React
bundler	Build tool	Vite
packager	Distribution packaging	Electron Forge
auto_update	Auto-update mechanism	electron-updater
platforms	Target platforms	Windows, macOS, Linux
security_level	Security strictness	Maximum (context isolation)

Best Practices

1. Always use context isolation and preload scripts. Never set nodeIntegration: true or contextIsolation: false. These settings expose the full Node.js API to web content, making any XSS vulnerability a full system compromise. Use contextBridge.exposeInMainWorld() in preload scripts to expose only the specific, validated API methods the renderer needs.

2. Validate all IPC messages in the main process. The renderer process is untrusted—it runs web content that could be compromised. Every ipcMain.handle and ipcMain.on handler should validate the arguments: check types, sanitize file paths (prevent directory traversal), and verify the operation is authorized. Never pass IPC arguments directly to fs, child_process, or shell commands.

3. Use ipcRenderer.invoke for request-response, not send/sendSync. invoke returns a Promise, making async operations clean and error-handleable. send is fire-and-forget with no built-in response mechanism. sendSync blocks the renderer thread and can freeze the UI. Design all IPC communication as async invoke calls with proper error handling on both sides.

4. Minimize the main process workload. The main process handles all IPC, native APIs, and window management on a single thread. CPU-intensive work in the main process freezes all windows. Offload heavy computation to worker threads (Node.js worker_threads), utility processes (utilityProcess.fork()), or hidden renderer windows. Keep the main process responsive for UI operations.

5. Package with proper code signing and auto-update from day one. Unsigned applications trigger security warnings on macOS and Windows, eroding user trust. Set up code signing certificates early. Configure electron-updater for automatic updates from a GitHub releases or S3 channel. Users on unsigned, non-updating Electron apps become stuck on vulnerable versions indefinitely.

Common Issues

App memory usage grows continuously over time. Electron apps inherit Chromium's memory model, where each BrowserWindow is a separate process. Memory leaks commonly come from: unremoved event listeners, growing IPC message buffers, unreleased native resources, and uncollected DOM references. Use Chrome DevTools memory profiler in the renderer and Node.js --inspect for the main process to identify leaks.

App startup is slow (3+ seconds to first render). Defer non-essential initialization. Load the window with a minimal splash screen, then initialize features in the background. Lazy-load heavy modules. Use protocol.handle for custom protocols instead of file:// to avoid filesystem scanning. Pre-bundle JavaScript with Vite or webpack rather than loading raw modules at startup.

Native features behave differently across platforms. Menus, dialogs, notifications, and keyboard shortcuts have platform-specific behaviors. Use process.platform to apply platform-specific configuration. Test on all target platforms during development, not just before release. macOS menu bars, Windows system tray behavior, and Linux notification daemons all have quirks that only surface during actual use.