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

> Understand the window.cth bridge in Munder Difflin. Discover its architecture and API reference to securely connect renderer and main processes while maintaining sandbox isolation.

- Repository: [Chaitanya Giri/munder-difflin](https://github.com/chaitanyagiri/munder-difflin)
- Tags: architecture
- Published: 2026-08-27

---

**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](https://github.com/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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:

```typescript
// 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:

```typescript
// 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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/preload/index.ts)** – Defines and exposes the `window.cth` API via `contextBridge.exposeInMainWorld`.
- **[`src/main/pty.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/pty.ts)** – Implements PTY lifecycle management and I/O streaming.
- **[`src/main/hive.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/hive.ts)** – Core multi-agent storage layer handling mailboxes, tasks, and routing.
- **[`docs/architecture-two-planes-one-renderer.md`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/pty.ts) and [`src/main/hive.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/pty.ts), while the **Hive plane** manages persistent on-disk storage for agent tasks and messages through [`src/main/hive.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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.