IPC Handlers & API

Relevant source files

The following files were used as context for generating this wiki page:

• src/electron/util.ts
• src/electron/main.ts
• types.d.ts
• src/ui/hooks/useIPC.ts
• src/electron/libs/config-store.ts
• src/electron/test.ts

The Inter-Process Communication (IPC) system in Agent Cowork serves as the vital bridge between the Electron Main process and the React-based Renderer process. It facilitates secure data exchange, system resource monitoring, and the execution of AI-driven tasks by wrapping the Claude Agent SDK. The system is designed with type safety at its core, utilizing a mapping of event payloads to ensure consistency across the process boundary.

The architecture relies on ipcMain for handling requests from the UI and webContents.send for pushing asynchronous updates, such as real-time system statistics or AI stream events, back to the frontend.

Architecture & Security

The IPC layer implements a type-safe wrapper around Electron's native IPC modules. This ensures that every event key corresponds to a specific data structure, reducing runtime errors. Furthermore, a validation mechanism is in place to prevent malicious frames from executing IPC handlers.

Type-Safe Communication

The project uses a custom ipcMainHandle function which enforces that the handler key exists within the EventPayloadMapping type and returns the correct payload type.

The diagram shows the flow of an IPC request from the UI to the Main process, including the security validation step.
Sources: src/electron/util.ts:13-20, src/electron/util.ts:28-32

Security Validation

Before executing any handler, the system validates the senderFrame. In production, it ensures the frame URL matches the local UI path; in development, it allows connections from the Vite dev server port (5173).
Sources: src/electron/util.ts:4, src/electron/util.ts:28-32

API Reference

The communication is categorized into synchronous handles (requests/responses) and asynchronous events (pushed from Main to UI).

IPC Handlers (Main Process)

These endpoints are registered in the Main process and invoked by the UI via window.electron.

Event Key	Description	Return Type
getStaticData	Retrieves hardware info (CPU model, total RAM).	StaticData
generate-session-title	Generates a title using Claude based on user prompt.	string
get-recent-cwds	Returns a list of recently used working directories.	string[]
select-directory	Opens a native OS dialog to pick a folder.	string | null
get-api-config	Loads the current API configuration (Key, URL, Model).	ApiConfig | null
save-api-config	Persists new API credentials to local storage.	{ success: boolean; error?: string }

Sources: src/electron/main.ts:81-135, types.d.ts:18-30

Asynchronous Events (Main to UI)

The Main process pushes data to the UI using the following channels:

Channel	Description	Payload
statistics	Real-time CPU, RAM, and Storage usage.	Statistics
server-event	AI agent events (stream deltas, tool calls).	any (SDK Events)

Sources: src/electron/test.ts:23, types.d.ts:33-34

System Resource Monitoring

The IPC system includes a polling mechanism that periodically gathers system performance data and broadcasts it to the UI.

This sequence illustrates the recurring telemetry updates sent from the Main process to the UI.
Sources: src/electron/test.ts:9-25

AI Configuration Management

The api-config.json file is managed through IPC handlers. Configuration includes sensitive data like API keys and service endpoints required for the Claude Agent SDK to function.

Data Structures

The configuration is stored in the user data path and follows a strict schema:

type ApiConfig = {
  apiKey: string;
  baseURL: string;
  model: string;
  apiType?: "anthropic";
};

Sources: src/electron/libs/config-store.ts:6-12

Configuration Flow

1. Load: On startup, the UI calls check-api-config via IPC to determine if a setup is required.
2. Save: The SettingsModal in the UI collects user input and invokes save-api-config.
3. Persist: The Main process validates the input and writes it to disk using writeFileSync.
   Sources: src/electron/main.ts:117-135, src/electron/libs/config-store.ts:40-66

UI Integration (useIPC Hook)

On the frontend, the useIPC hook provides a reactive interface to the Electron API. It manages subscriptions to server events and provides a sendEvent callback for client-initiated actions.

export function useIPC(onEvent: (event: ServerEvent) => void) {
  useEffect(() => {
    const unsubscribe = window.electron.onServerEvent((event: ServerEvent) => {
      onEvent(event);
    });
    return () => unsubscribe();
  }, [onEvent]);

  const sendEvent = useCallback((event: ClientEvent) => {
    window.electron.sendClientEvent(event);
  }, []);
}

Sources: src/ui/hooks/useIPC.ts:4-31

Conclusion

The IPC Handlers and API module forms the backbone of Agent Cowork's desktop experience. By centralizing system access, AI SDK management, and configuration persistence in the Main process while exposing a clean, type-safe API to the React frontend, the system ensures a responsive and secure collaboration environment between the user and the AI agent.