# Native Socket Protocol Version 6 in pi-computer-use: macOS and Windows Transport Layers

> Discover how macOS and Windows transport layers in pi-computer-use leverage native socket protocol version 6 for efficient JSON message exchange. Learn more about this powerful connection.

- Repository: [injaneity/pi-computer-use](https://github.com/injaneity/pi-computer-use)
- Tags: internals
- Published: 2026-07-16

---

**Both macOS and Windows transport layers in pi-computer-use use protocol version 6 over local sockets—Unix-domain sockets on macOS and TCP sockets on Windows—to exchange JSON messages with native helper applications.**

The `pi-computer-use` repository implements platform-specific transport layers that enable JavaScript applications to communicate with native operating system helpers via local sockets. Both the macOS and Windows implementations rely on a strict **protocol version constant** to ensure compatibility between the runtime client and the background helper daemon before executing system-level commands.

## Protocol Version Constants by Platform

### macOS HELPER_PROTOCOL_VERSION

In [`src/platform/macos/helper.ts`](https://github.com/injaneity/pi-computer-use/blob/main/src/platform/macos/helper.ts) at line 12, the constant `HELPER_PROTOCOL_VERSION` is explicitly set to `6`. This integer represents the expected protocol revision that the macOS bridge application must advertise during the initial handshake. The client creates a Unix-domain socket at `HELPER_SOCKET_PATH` (typically `~/Library/Caches/pi-computer-use/bridge.sock`) and initiates JSON message exchange only after validating this version.

### Windows WINDOWS_HELPER_PROTOCOL_VERSION

Similarly, [`src/platform/windows/helper.ts`](https://github.com/injaneity/pi-computer-use/blob/main/src/platform/windows/helper.ts) at line 10 defines `WINDOWS_HELPER_PROTOCOL_VERSION = 6`. The Windows transport layer establishes a local TCP socket connection to the helper process running on localhost, using the same version validation mechanism before accepting commands.

## Socket Architecture and Message Flow

### Unix-Domain Sockets on macOS

The macOS transport layer utilizes Unix-domain sockets for inter-process communication. When the `macosHelper` class initializes, it spawns the bridge application and monitors the socket path for availability. All subsequent messages—including the critical `"diagnostics"` request—travel through this local socket as JSON payloads.

### TCP Sockets on Windows

Windows employs TCP sockets bound to localhost rather than Unix-domain sockets. The `windowsBackend` establishes this connection during startup, forwarding API calls such as `listApps()` through the TCP stream. Despite the different transport mechanism, the message format remains identical to the macOS implementation.

### Version Negotiation and Validation

Both platforms implement a validation routine that queries the helper's `"diagnostics"` endpoint immediately after connection. If the reported protocol version differs from the expected constant—`6` for either platform—the client assumes a version mismatch and triggers corrective action, such as restarting the helper daemon (macOS) or throwing a compatibility error (Windows).

## Implementing Protocol Checks in Your Code

### macOS Socket Communication

To ensure compatibility with the native macOS helper before issuing commands, invoke the `ensureProtocol()` method provided by the platform helper class:

```typescript
import { macosHelper } from "./platform/macos/helper.ts";

// Verify the helper daemon is running and speaks protocol version 6
await macosHelper.ensureProtocol();

// Request diagnostics to confirm version match
const diagnostics = await macosHelper.command("diagnostics", {});
console.log("macOS helper protocol version:", diagnostics.protocolVersion);

```

### Windows Socket Communication

The Windows backend automatically performs version validation during initialization through the `ensureReady()` method:

```typescript
import { windowsBackend } from "./platform/windows/backend.ts";

// Automatic protocol version check occurs here
await windowsBackend.ensureReady(/* ctx */{}, { lastPermissionCheckAt: 0 });

// Proceed with native commands after validation
const apps = await windowsBackend.listApps();
console.log(apps);

```

## Key Source Files and Implementation Details

The transport layer implementation spans four critical files:

- **[`src/platform/macos/helper.ts`](https://github.com/injaneity/pi-computer-use/blob/main/src/platform/macos/helper.ts)**: Defines `HELPER_PROTOCOL_VERSION = 6` (line 12), manages the Unix-domain socket lifecycle, and handles JSON serialization for the macOS bridge application.
- **[`src/platform/macos/backend.ts`](https://github.com/injaneity/pi-computer-use/blob/main/src/platform/macos/backend.ts)**: Provides the high-level `macosHelper` API that wraps socket operations and exposes methods like `listApps()` and `focusWindow()`.
- **[`src/platform/windows/helper.ts`](https://github.com/injaneity/pi-computer-use/blob/main/src/platform/windows/helper.ts)**: Declares `WINDOWS_HELPER_PROTOCOL_VERSION = 6` (line 10) and implements TCP socket management for the Windows helper process.
- **[`src/platform/windows/backend.ts`](https://github.com/injaneity/pi-computer-use/blob/main/src/platform/windows/backend.ts)**: Implements `windowsBackend` with automatic protocol validation and command forwarding to the Windows native layer.

## Summary

- Both macOS and Windows transport layers in `pi-computer-use` utilize **protocol version 6** for native socket communication.
- **macOS** uses **Unix-domain sockets** at `~/Library/Caches/pi-computer-use/bridge.sock` with the constant `HELPER_PROTOCOL_VERSION` defined in [`src/platform/macos/helper.ts`](https://github.com/injaneity/pi-computer-use/blob/main/src/platform/macos/helper.ts).
- **Windows** uses **TCP sockets** on localhost with the constant `WINDOWS_HELPER_PROTOCOL_VERSION` defined in [`src/platform/windows/helper.ts`](https://github.com/injaneity/pi-computer-use/blob/main/src/platform/windows/helper.ts).
- Version mismatches trigger automatic helper restarts or error throws to prevent incompatible command execution.
- All messages follow a **JSON-over-socket** format validated through the `"diagnostics"` endpoint.

## Frequently Asked Questions

### What happens if the protocol version mismatches between client and helper?

If the client receives a protocol version other than `6` in the diagnostics response, it interprets this as a compatibility error. On macOS, the system automatically terminates and restarts the helper daemon to force a version sync. On Windows, the backend throws an explicit error indicating the version mismatch, halting further command execution until the helper is updated.

### Why does macOS use Unix-domain sockets while Windows uses TCP?

Unix-domain sockets provide lower latency and better security for local inter-process communication on POSIX-compliant systems like macOS, bypassing network stack overhead. Windows implementations traditionally rely on TCP sockets for localhost communication due to differences in named pipe handling and cross-platform consistency requirements in the Node.js/JavaScript runtime environment.

### How do I check the current protocol version of a running helper?

Query the `"diagnostics"` command through the platform-specific helper interface. On macOS, use `await macosHelper.command("diagnostics", {})` and inspect the `protocolVersion` field in the response. The Windows backend performs this check automatically during `ensureReady()`, but you can also access version metadata through the underlying socket connection if manual verification is required.

### Where is the protocol version defined in the source code?

The macOS protocol version `6` is declared at line 12 of [`src/platform/macos/helper.ts`](https://github.com/injaneity/pi-computer-use/blob/main/src/platform/macos/helper.ts) as `HELPER_PROTOCOL_VERSION`. The Windows equivalent is declared at line 10 of [`src/platform/windows/helper.ts`](https://github.com/injaneity/pi-computer-use/blob/main/src/platform/windows/helper.ts) as `WINDOWS_HELPER_PROTOCOL_VERSION`. Both constants must remain synchronized with the native helper application builds to maintain compatibility.