# How the Codex Plugin Handles Cross-Platform Differences (Windows vs Unix)

> Discover how the openai/codex-plugin-cc handles cross-platform differences, checking process platform to adapt shells, utilities, and path separators for Windows and Unix.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: internals
- Published: 2026-07-13

---

**The openai/codex-plugin-cc repository abstracts OS-specific behavior by checking `process.platform` at runtime, automatically selecting appropriate shells, termination utilities, and path separators for Windows and Unix-like systems.**

The openai/codex-plugin-cc project must operate reliably across diverse operating systems. To handle cross-platform differences without burdening callers with OS-specific logic, the plugin centralizes platform detection in utility modules that adjust behavior dynamically based on the host environment.

## Shell Invocation and Command Execution

On Windows (`win32`), the plugin uses the user-defined `SHELL` environment variable when available, otherwise falling back to `cmd.exe` by passing `true` to the `shell` option in `spawnSync`. This ensures commands execute within a proper command interpreter even when calling batch files or shell built-ins.

On Unix-like systems (Linux and macOS), the plugin runs commands directly without intermediate shell overhead by setting `shell: false`. This reduces process spawning overhead and avoids shell injection vulnerabilities.

The `runCommand` function in `plugins/codex/scripts/lib/process.mjs` implements this logic at lines 12-13, checking `process.platform` to determine the appropriate shell configuration.

```javascript
// Example: Running a command with automatic shell handling
import { runCommand } from "./plugins/codex/scripts/lib/process.mjs";

const result = runCommand("npm", ["install"], {
  cwd: "/some/project",
});
// On Windows the command runs under a shell; on Unix it runs directly.

```

## Process Termination Strategies

### Windows Taskkill Implementation

When terminating process trees on Windows, the plugin invokes the native `taskkill /PID <pid> /T /F` command to forcefully terminate the target process and all its child processes. If `taskkill` is unavailable, it gracefully falls back to `process.kill`.

### Unix POSIX Signal Handling

On Unix systems, the plugin uses Node.js's standard `process.kill(pid)` method to send POSIX signals directly to the target process, avoiding external utility dependencies.

The `terminateProcessTree` function in `plugins/codex/scripts/lib/process.mjs` (lines 66-88) contains this platform-specific branching logic.

```javascript
// Example: Terminating a process tree
import { terminateProcessTree } from "./plugins/codex/scripts/lib/process.mjs";

const status = terminateProcessTree(12345);
// Windows → uses `taskkill`; Unix → uses `process.kill`.

```

## Path Separator Handling

The plugin accounts for classpath separator differences between platforms. Windows uses semicolons (`;`) while Unix systems use colons (`:`). The test utilities in `tests/helpers.mjs` (lines 21-22) demonstrate this detection:

```javascript
// tests/helpers.mjs
const sep = process.platform === "win32" ? ";" : ":";

```

## Broker Endpoint and App Server Configuration

The `createBrokerEndpoint` function in `plugins/codex/scripts/lib/broker-endpoint.mjs` accepts an optional `platform` parameter defaulting to `process.platform`, allowing the factory to construct OS-appropriate paths and service names.

In `plugins/codex/scripts/lib/app-server.mjs` (line 194), the plugin sets `shell: process.platform === "win32" ? (process.env.SHELL || true) : false` when spawning the application server, ensuring proper interpreter selection on Windows while maintaining direct execution on Unix.

```javascript
// Example: Creating a broker endpoint that respects the host OS
import { createBrokerEndpoint } from "./plugins/codex/scripts/lib/broker-endpoint.mjs";

const endpoint = createBrokerEndpoint("/tmp/session"); // platform auto-detected

```

## Summary

- The plugin detects the operating system via `process.platform` checks at runtime to handle cross-platform differences seamlessly.
- **Windows** commands execute through `cmd.exe` or user-defined shells, while **Unix** commands run directly via `shell: false`.
- Process termination uses `taskkill` on Windows and `process.kill` on Unix.
- Path separators adapt automatically (`;` vs `:`) for classpath-style strings.
- All platform-specific logic is confined to utility modules (`process.mjs`, `broker-endpoint.mjs`, `app-server.mjs`).

## Frequently Asked Questions

### How does the Codex plugin detect which operating system is running?

The plugin checks `process.platform` at runtime, which returns `"win32"` for Windows or `"darwin"`/`"linux"` for Unix-like systems. This value determines which shell options, termination utilities, and path separators to use according to the implementation in `plugins/codex/scripts/lib/process.mjs`.

### Why does the plugin use different shell settings for Windows versus Unix?

Windows requires shell execution (`shell: true`) to properly interpret batch files and command syntax through `cmd.exe`, while Unix systems benefit from direct execution (`shell: false`) to reduce overhead and prevent shell injection vulnerabilities when spawning child processes.

### What happens if taskkill is not available on Windows?

The `terminateProcessTree` function in `process.mjs` includes error handling that falls back to Node.js's `process.kill` method if the `taskkill` command fails or is unavailable, ensuring the process can still be terminated even without the Windows utility.

### Does the plugin handle path separators automatically?

Yes, the plugin and its test utilities detect the platform and use semicolons (`;`) as classpath separators on Windows and colons (`:`) on Unix systems, preventing manual path construction errors when building environment variables or command arguments.