# Codex Computer Use for macOS 13

An unofficial, source-built compatibility layer that restores the bundled
Codex Computer Use skill on macOS 13 Ventura without modifying system
libraries, lowering Mach-O deployment targets, or redistributing OpenAI code.

Tested on **macOS 13.7.8 arm64**, Xcode 15.2 / Swift 5.9.2, Codex CLI
`0.146.0`, and bundled Computer Use plugin versions `1.0.1000387` and
`1.0.1000451`.

> [!IMPORTANT]
> This project is not affiliated with or endorsed by OpenAI. It does not
> contain OpenAI's proprietary Computer Use wrapper, `@oai/sky`, skills,
> services, assets, or binaries. It interoperates with a legitimately installed
> local plugin and builds its native backend from MIT-licensed source.

## Why this is needed

Recent bundled Computer Use services declare macOS 14.4 as their minimum OS
and link APIs unavailable on Ventura. Changing `LSMinimumSystemVersion` or the
Mach-O load command is not sufficient because the binaries genuinely import
newer Foundation and Swift runtime symbols.

This project takes a different route:

1. Build an open Swift Accessibility/CoreGraphics backend targeting macOS 13.
2. Adapt its stdio MCP tools to the ten-method `sky` object expected by the
   existing Codex skill.
3. Install a small clean-room loader in the local plugin cache. On macOS 14.4+
   it delegates to the untouched saved OpenAI wrapper; on older systems it uses
   the open backend.

There is **no patching of OpenAI native binaries** and no TCC bypass.

```mermaid
flowchart LR
    Skill["Bundled Computer Use skill"] --> Loader["Open clean-room loader"]
    Loader -->|"macOS 14.4+"| Original["Saved local OpenAI wrapper"]
    Loader -->|"macOS 13 / early 14"| Adapter["Sky-to-MCP adapter"]
    Adapter --> Backend["MIT Swift macOS backend"]
    Backend --> AX["Accessibility + CoreGraphics"]
```

## What we added

- A Swift 5.9-safe capture result handoff for the open backend.
- The complete bundled Sky-facing tool surface, including `select_text`.
- Xdotool-style keypad names such as `KP_0`.
- Screenshot-pixel to global-coordinate conversion with bounds checks.
- App-path and bundle-ID resolution, app-scoped input, compact state diffs,
  permission prompting, bounded screenshot storage, and backend recovery.
- A hash-gated installer that refuses unfamiliar proprietary wrapper versions.
- A hash-gated local guidance patch that makes every `sky` call restart-safe.
- An optional LaunchAgent that reapplies the loader when an update creates a
  fresh versioned plugin cache.

The backend source and history live in
[`Torrekie/open-codex-computer-use`](https://github.com/Torrekie/open-codex-computer-use).

## Requirements

- Apple Silicon Mac running macOS 13 or newer.
- Xcode 15.2 or another Swift 5.9 toolchain capable of targeting macOS 13.
- A current Codex/ChatGPT installation that already includes the bundled
  Computer Use plugin and `node_repl` runtime.
- Node.js 20+. The installer can use ChatGPT/Codex's bundled Node runtime.
- Accessibility and Screen Recording permission for the locally built helper.

## Install

```bash
git clone https://github.com/Torrekie/codex-computer-use-ventura.git
cd codex-computer-use-ventura
./scripts/install.sh
```

The default build is ad-hoc signed. It works, but rebuilding can change its TCC
identity and require granting permissions again. If you have a stable local
code-signing identity, use it:

```bash
CODESIGN_IDENTITY='Apple Development: Your Name (TEAMID)' ./scripts/install.sh
```

The installer builds the pinned public backend commit, assembles a local app,
backs up recognized plugin wrappers and Computer Use guidance byte-for-byte,
installs the clean loader and restart guard, and enables the update watcher.
Set `INSTALL_WATCHER=0` to skip the watcher.

After installation, restart Codex or reset `node_repl`. The first app-state
request may open **Privacy & Security**; enable Accessibility and Screen
Recording for **Codex Computer Use for macOS 13**, then retry.

## Verify

`sky` is an in-memory `node_repl` binding. A CLI/app restart, `js_reset`, or
kernel recovery clears it. Begin every standalone Computer Use block with the
idempotent bootstrap guard. For the default installation, a minimal read-only
probe is:

```js
if (!globalThis.sky) {
  var { setupComputerUseRuntime } = await import(
    `${nodeRepl.homeDir}/.codex/computer-use-macos13/computer-use-loader.mjs`
  );
  await setupComputerUseRuntime({ globals: globalThis });
}
var apps = await sky.list_apps();
nodeRepl.write(JSON.stringify({ target: sky.target, count: apps.length }));
```

Then inspect Finder:

```js
if (!globalThis.sky) {
  var { setupComputerUseRuntime } = await import(
    `${nodeRepl.homeDir}/.codex/computer-use-macos13/computer-use-loader.mjs`
  );
  await setupComputerUseRuntime({ globals: globalThis });
}
var state = await sky.get_app_state({ app: "Finder", disableDiff: true });
nodeRepl.write(JSON.stringify({
  app: state.app,
  textLength: state.text.length,
  hasScreenshot: state.screenshot !== null,
}));
```

## Updates

The watcher runs the hash-gated patchers whenever the bundled plugin cache
changes and periodically reconciles the cache in case an update event arrived
before all files were ready. Known identical wrappers and guidance files are
updated automatically. Unknown future revisions are left untouched and
reported in:

```text
~/.codex/computer-use-macos13/reapply.log
```

Do not add an unknown hash without reviewing the new wrapper and skill API.

## Restore or uninstall

Restore the original local wrappers and disable the watcher while keeping the
backend:

```bash
./scripts/restore.sh
```

Restore and remove the installed compatibility files:

```bash
./scripts/uninstall.sh
```

Neither command modifies macOS TCC databases.

## Development

Run the Node adapter, loader, installer, and syntax checks:

```bash
npm run check
```

Build and test the Swift backend fork:

```bash
BACKEND_SOURCE=/path/to/open-codex-computer-use ./scripts/build-backend.sh
```

See [Architecture](docs/architecture.md), [Testing](docs/testing.md), and
[Troubleshooting](docs/troubleshooting.md) for implementation details.

## Security and licensing

Read [SECURITY.md](SECURITY.md) before enabling the backend on a sensitive
machine. The bridge is MIT-licensed. The native backend retains its upstream
MIT license and attribution; see [Third-Party Notices](THIRD_PARTY_NOTICES.md).

OpenAI and Codex are trademarks of their respective owner.