Codex Computer Use MCP

Give Pi and MCP clients OpenAI's official signed macOS Computer Use runtime, cua_repl: the same JavaScript tool that ChatGPT's own threads use to operate Mac apps and browsers. The calling agent writes each script. This package runs no nested model and generates no action plan.

OpenAI does not produce or endorse this independent project. It relies on an experimental app-server API and installed ChatGPT components that may change.

Requirements

• macOS with an unlocked user session
• Node.js 22 or newer
• the official ChatGPT macOS app with its unified Computer Use plugin (tested with ChatGPT for Work 26.1029.61003), by default at /Applications/ChatGPT.app
• ChatGPT opened at least once since its last update, so it has written its Computer Use runtime settings. ChatGPT writes them only when OpenAI has turned on its unified Computer Use runtime for the account; without them, the adapter falls back to the older typed tools (see Accounts without the unified runtime)
• the Computer Use component installed by ChatGPT, by default under ~/.codex/computer-use/
• Pi 0.99.0 or newer when using the Pi integration

macOS Screen Recording, Accessibility and TCC controls still apply.

Pi

Install from npm:

pi install npm:codex-computer-use-mcp

After pi update, run /reload to load the new version.

The extension registers two ordinary Pi tools:

• cua_repl is the official js tool. It runs JavaScript in a persistent official runtime with a cua object for apps and browser tabs.
• cua_repl_reset is the official js_reset tool. It discards the runtime's JavaScript bindings.

Their descriptions and parameters are the ones ChatGPT's installed runtime gives its own model, read from ChatGPT when the extension loads. They explain the API, so an agent can start with:

let app = await cua.getApp("TextEdit");

The result includes the app's accessibility tree and the API documentation. Later calls reuse the binding:

await app.click(7);
await app.typeText("hello");
await app.getAXState();

Bindings such as app last across calls and agent turns until cua_repl_reset, a transport failure or the end of the Pi session. When the agent settles, the extension sends the official turn_ended notification, as ChatGPT does when its turn stops, so the service can clear that turn's software cursor.

The runtime also drives browsers ChatGPT can reach, such as Chrome through ChatGPT's Chrome extension. cua.listTabs() lists your tabs, and cua.createBrowserTab("chrome", url, { sessionName }) opens one for the agent, which can read it, act in it and close it. Inside ChatGPT each turn needs ChatGPT's browser access grant. This adapter starts the runtime without ChatGPT's grant host, so browser use needs no grant.

A failed call returns the official error text as an error result, followed by a recovery step when the adapter recognises the cause (see Failures). Pi limits returned text to 50KB or 2,000 lines. When text exceeds that limit, the complete text is written to a mode-0600 file in a private directory under /tmp. Images are returned directly and are never spilled to disk.

Use /computer-use-status to inspect the installed components and transport status.

Upgrading from 0.6

Version 0.7.0 replaces the ten computer_use_<method> codemode tools with cua_repl wherever ChatGPT has its unified runtime. Scripts that called tools.computer_use_get_app_state({ app }) and similar tools now call the cua API inside cua_repl: cua.getApp(app), app.getAXState(), app.click(index or [x, y]), app.typeText(text), app.pressKey(key) and so on. The official tool description lists every method.

Accounts without the unified runtime (deprecated)

OpenAI turns on ChatGPT's unified Computer Use runtime per account. Where it is off, ChatGPT itself still uses the ten older typed tools, and so does this adapter: when Pi loads the extension or the MCP server starts, and ChatGPT has not written its cua_repl settings, the adapter registers the 0.6 tools instead (computer_use_<method> codemode tools in Pi, <method> tools over MCP). Status reports "route": "legacy" and why. Browser control needs the unified runtime.

This fallback is deprecated and is likely to be removed once the unified runtime reaches every account. If OpenAI turns it on later, /reload in Pi or restart the MCP server to switch to cua_repl.

To run a source checkout:

npm ci
npm run build
pi -ne -e /absolute/path/to/codex-computer-use-mcp/integrations/pi/index.ts

MCP

Running the package binary starts a stdio MCP server with the official js and js_reset tools and computer_use_status:

npx codex-computer-use-mcp

Example Pi MCP configuration:

{
  "mcpServers": {
    "computer-use": {
      "command": "npx",
      "args": ["codex-computer-use-mcp"],
      "lifecycle": "lazy",
      "requestTimeoutMs": 180000,
      "directTools": false
    }
  }
}

MCP has no turn boundary, so the server sends turn_ended after a minute without calls. The runtime and its bindings stay until the client disconnects.

Behaviour

Each session starts ChatGPT's signed Codex app-server with an isolated, credential-free home and asks it to run ChatGPT's own cua_repl server: OpenAI's signed node_repl with the settings ChatGPT wrote to ~/.codex/plugins/cache/openai-bundled/unified-computer-use/<ChatGPT version>/.mcp.json. The adapter passes that server entry through unchanged, with three exceptions: a private working directory; the account's real HOME, which the runtime needs to find the shared Computer Use service; and starting node_repl directly rather than through ChatGPT's shell wrapper, so the runtime does not ask ChatGPT for a browser access grant. The app-server stays isolated. The Computer Use service accepts the runtime only when a signed OpenAI parent starts it, so the app-server cannot be skipped.

This is the beginning of the README. Read the rest at the original. Read the full README ↗