What Is the `window.cth` Bridge in Munder Difflin? Architecture and API Reference

The window.cth bridge is a typed preload API that securely connects the Electron renderer process to privileged main process capabilities while maintaining strict sandbox isolation.

The window.cth bridge serves as the central communication conduit in the chaitanyagiri/munder-difflin Electron application. It exposes a strictly controlled JavaScript API to the UI, allowing the renderer to execute filesystem operations, manage terminal processes, and interact with the multi-agent Hive without direct access to system resources. This typed preload bridge ensures that sandboxed renderer code can only invoke explicitly permitted functionality.

What Is the window.cth Bridge?

The window.cth bridge is implemented in src/preload/index.ts using Electron’s contextBridge.exposeInMainWorld method. This creates an isolated API surface that the renderer process can access globally via window.cth, while preventing direct exposure of Node.js or native system APIs to the UI layer.

According to the Munder Difflin architecture, the application operates on two distinct planes:

• Terminal plane – The main process manages PTYs (pseudo-terminals) that run agent CLIs and stream I/O.
• Hive/event plane – The main process maintains the on-disk multi-agent system (mailboxes, task routing, and agent registries).

The window.cth bridge functions as the single typed conduit between these planes and the renderer, enabling real-time agent messaging and file manipulation while preserving security boundaries.

Core API Categories

The bridge exposes categorized functions that map to specific capabilities in the main process:

PTY Management

These functions control terminal processes that run agent CLIs:

• spawnPty – Creates a new PTY instance with specified working directory and arguments.
• writePty – Sends input data to a running PTY session.
• listPtys – Returns metadata about active terminal sessions.
• resizePty – Adjusts terminal dimensions.
• killPty – Terminates a specific PTY process.

Implementation resides in src/main/pty.ts, invoked through IPC channels exposed via the bridge.

Filesystem and Git Operations

Because the renderer lacks direct filesystem access, these methods proxy file operations through the main process:

• readFileText and writeFileText – Read and write text files safely.
• statAbs – Retrieve file metadata.
• gitIsRepo, gitDiff, and related functions – Execute Git operations without exposing the Git CLI directly to the UI.

Hive Multi-Agent System

The Hive represents the on-disk storage layer for agent communication and task management:

• hiveTasks – Retrieves the current task board state.
• hiveAddTask and hivePatchTask – Create or modify tasks in the agent workflow.
• hiveInbox and hiveSend – Manage inter-agent messaging through mailboxes.
• hiveRegistry – Access agent registration information.

These calls target the core logic in src/main/hive.ts.

System Integration

Additional utilities provide controlled access to system resources:

• readClipboard and copyToClipboard – Clipboard access without exposing native APIs.
• openExternal – Opens URLs in the system default browser.
• getConfig and updateConfig – Manage harness configuration stored in <harnessHome>.
• telemetrySnapshot and onTelemetryEvent – Access usage metrics and monitoring data.

Security Model and Sandboxing

The renderer process in Munder Difflin operates under strict sandbox restrictions with no direct access to:

• The filesystem
• Network sockets
• Native system APIs
• Shell environments

Every privileged operation must traverse the window.cth bridge. The typed interface guarantees that only the intended API surface is available to the UI, significantly reducing the attack surface. This architecture ensures that even if the renderer process is compromised, malicious code cannot escape the sandboxed environment without exploiting the explicitly defined bridge methods.

Implementation Examples

The following patterns demonstrate how the renderer interacts with main process capabilities through the bridge:

// Spawn a new agent PTY (e.g., Claude Code)
await window.cth.spawnPty({
  id: 'agent-123',
  cwd: '/home/user/projects/my-app',
  argv: ['claude', '--model=claude-3.5']
});

// Send input to the terminal session
await window.cth.writePty('agent-123', 'print("hello world")\n');

// Query active sessions
const ptys = await window.cth.listPtys();
// Returns: [{ id: 'agent-123', ... }]

Filesystem and Hive operations follow the same async pattern:

// Read a workspace file safely through the main process
const src = await window.cth.readFileText('/home/user/projects/my-app/main.ts');

// Retrieve current Hive tasks
const tasks = await window.cth.hiveTasks();

// Create a new task entry
await window.cth.hiveAddTask({
  id: 'task-42',
  title: 'Refactor utils',
  status: 'todo',
  assignee: 'agent-123',
  createdAt: new Date().toISOString()
});

Key Source Files

Understanding the bridge requires examining these specific implementation files:

• src/preload/index.ts – Defines and exposes the window.cth API via contextBridge.exposeInMainWorld.
• src/main/pty.ts – Implements PTY lifecycle management and I/O streaming.
• src/main/hive.ts – Core multi-agent storage layer handling mailboxes, tasks, and routing.
• docs/architecture-two-planes-one-renderer.md – Documents the architectural separation between terminal and hive planes.

Summary

• The window.cth bridge is a typed preload API exposed via contextBridge.exposeInMainWorld in src/preload/index.ts.
• It enables secure IPC between the sandboxed renderer and privileged main process capabilities.
• The API covers PTY management, filesystem/Git operations, Hive multi-agent workflows, and system integration.
• All privileged actions traverse this single conduit, maintaining strict sandbox isolation for the UI layer.
• Source implementations reside primarily in src/main/pty.ts and src/main/hive.ts.

Frequently Asked Questions

How does window.cth maintain security between processes?

The bridge uses Electron’s contextBridge module to create a context-isolated API surface. The renderer can only invoke specific exposed functions, not access Node.js modules or native APIs directly. This ensures that even compromised renderer code cannot perform unauthorized filesystem or shell operations.

What is the difference between the Terminal and Hive planes?

The Terminal plane handles PTY creation and CLI agent I/O through src/main/pty.ts, while the Hive plane manages persistent on-disk storage for agent tasks and messages through src/main/hive.ts. Both planes communicate with the UI exclusively through the window.cth bridge.

Can I extend the window.cth API with custom functions?

Yes, though it requires modifying src/preload/index.ts to expose new methods and implementing corresponding handlers in the main process (typically in src/main/ modules). Any additions should maintain the typed interface pattern to preserve type safety between renderer and main process code.

Why does the bridge use async patterns for all operations?

All window.cth methods return Promises because they communicate across the Electron IPC boundary, which is inherently asynchronous. This design prevents the renderer from blocking while the main process performs potentially slow filesystem, Git, or network operations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}