IPC Communication Bridge
Relevant source files
The following files were used as context for generating this wiki page:
The IPC (Inter-Process Communication) Communication Bridge serves as the vital link between the Electron Main process and the React-based Renderer process. It enables secure, type-safe communication for handling AI session management, system resource monitoring, and configuration persistence. By leveraging Electron's ipcMain and ipcRenderer (exposed via context bridge), the bridge allows the UI to trigger backend operations like running the Claude Agent SDK while receiving real-time stream updates.
Sources: src/electron/main.ts:98-150, src/ui/hooks/useIPC.ts:4-31
Architecture and Security
The bridge is designed with security and type safety as primary considerations. It utilizes a EventPayloadMapping type to ensure that data passed between processes matches expected schemas. Security is enforced through frame validation, ensuring that only trusted origins (local UI files or the development server) can execute sensitive IPC handlers.
Secure Execution Flow
The following diagram illustrates how an IPC request is validated and handled:
The validateEventFrame function checks the URL of the sender frame against the known UI path or the development port (5173).
Sources: src/electron/util.ts:13-31, src/electron/main.ts:114-118
Core Communication Mechanisms
The system employs two primary communication patterns: One-Way/Request-Response (Main-Handle) and Asynchronous Streams (WebContents-Send).
1. Type-Safe Handlers
Handlers in the Main process are registered using ipcMainHandle, which wraps Electron's ipcMain.handle to provide type checking based on the EventPayloadMapping definition.
| Handler Key | Purpose | Returns |
|---|---|---|
getStaticData | Retrieves system hardware info (CPU, RAM, Storage). | StaticData |
generate-session-title | Uses AI to generate a title from user input. | string |
select-directory | Opens a native dialog to choose a workspace. | string | null |
save-api-config | Persists Anthropic API settings to disk. | { success: boolean } |
Sources: types.d.ts:18-29, src/electron/main.ts:114-150
2. Event Subscription
The UI subscribes to server-sent events (like logs or AI status updates) via a subscription model. The useIPC hook manages the lifecycle of these listeners.
UI Integration: useIPC Hook
The useIPC hook is the primary interface for React components to interact with the bridge. It maintains connection state and provides a sendEvent function for transmitting ClientEvent payloads to the backend.
Implementation Details
- Connection State: Tracks if the event listeners are active.
- Lifecycle Management: Automatically unsubscribes from events when components unmount to prevent memory leaks.
- Event Dispatching: Wraps
window.electron.sendClientEventto send messages likesession.startorpermission.response.
Sources: src/ui/hooks/useIPC.ts:4-31, src/ui/App.tsx:210-213
Data Flow for AI Sessions
One of the most complex flows involves starting an AI session, which requires multiple IPC interactions to coordinate the UI, the Main process, and the Claude Agent SDK.
When a user initiates a task, the usePromptActions hook orchestrates these calls before sending the final session.start event.
Sources: src/ui/components/PromptInput.tsx:28-48, src/ui/App.tsx:55-85
System Resource Monitoring
The bridge also handles real-time telemetry. The Main process polls system resources (CPU, RAM, Disk) every 500ms and pushes this data to the Renderer process using ipcWebContentsSend.
- Polling Interval: 500ms
- Data Points: CPU usage percentage, RAM usage percentage, and storage usage.
- Implementation:
pollResources(mainWindow)in the Main process transmits data which is consumed by components subscribed to thestatisticsevent.
Sources: src/electron/test.ts:10-25, types.d.ts:18-19
Summary
The IPC Communication Bridge is a robust infrastructure that ensures the decoupling of the heavy-lifting AI and system logic in the Main process from the interactive React UI. By utilizing type-safe wrappers and strict frame validation, it provides a reliable and secure environment for the Agent Cowork application to function as a desktop AI partner.