Codex Computer Use MCP

This package exposes the official signed macOS Computer Use capabilities as direct typed tools for Pi and MCP clients. The calling agent chooses every tool and argument itself.

The primary path has:

• no nested model call;
• no model-generated action plan;
• no subagent;
• no prompt sent to Codex;
• no separate model-token usage.

It does use OpenAI's signed codex app-server as the official host for the bundled Computer Use MCP client. The current official mcpServer/tool/call API requires a loaded thread identifier, so the bridge creates an empty, in-memory, zero-turn context (ephemeral: true, turns: [], path: null). It never calls turn/start and fails closed if any turn/* or item/* model activity appears.

Independent project. This is not an OpenAI product and is not endorsed by OpenAI. The app-server API is marked experimental and ChatGPT's reviewed component locations may change.

Direct tools

Pi registers namespaced tools to avoid collisions with Pi's built-ins. The MCP server exposes the upstream method names.

The MCP and Pi façades provide typed definitions for the ten Computer Use methods. Harmless changes to the signed helper's descriptions, annotations or schema metadata do not block calls. The official service remains authoritative when it executes a request.

Pi registers and activates all ten definitions together in every fresh session, while preserving active tools owned by Pi and other extensions. This prevents interaction methods from being absent or loaded through an incompatible provider binding.

Pi—not a nested planner—calls computer_use_get_app_state once per assistant turn before interacting with an app, then chooses and executes actions itself. The adapter retains one verified app-server runtime and signed Computer Use client for that inspection-action pair, so the action reuses the official active-app session established by get_app_state. It closes and verifies the retained process tree after the action, when a new inspection supersedes it, or on Pi session shutdown.

Authorization policy: durable no-permissions

no-permissions has one precise meaning here: the wrapper asks no permission questions and exposes all ten official actions. It is the only mode and the durable default. There is no safe/full selector, config file, environment override, slash command, CLI switch, per-call elevation, app allowlist, intent classifier, task schema, per-action confirmation, special-case app policy, or method gate.

The app-server runtime uses the official Full access combination: approvalPolicy: "never" and sandbox: "danger-full-access". In the pinned Codex host, that maps to a disabled permission profile and automatically accepts empty-schema MCP approval elicitations. Normal Computer Use app-access checks therefore proceed without a per-app prompt, just as they do in Codex Full access. The bridge does not edit the service's persistent per-bundle approval file. If app-server emits an elicitation instead of resolving it under Full access, the bridge still forwards it faithfully to the invoking client; unsupported clients return cancel, never a fabricated accept or decline.

No-permissions leaves the official and transport requirements unchanged:

• macOS Screen Recording, Accessibility, and TCC controls remain authoritative;
• the adapter still selects and verifies the official signed components required for the supported transport;
• unsupported calls surface the official service's own error instead of failing an independent schema-fidelity gate.

The current release also retains behavior from the earlier background-computer-use wrapper. This includes canonical app resolution, per-user/per-app coordination, focus completion telemetry, process cleanup, and metadata-only audit. These provide compatibility, lifecycle management, and observability. They do not provide extra authorization or a sandbox. Do not use them as a foundation for more wrapper safeguards.

Why the signed app-server is required

Calling the signed SkyComputerUseClient mcp binary directly from an ordinary Pi/Node parent successfully initializes and lists all ten schemas, but real calls are rejected with:

Computer Use server error -10000: Sender process is not authenticated

OpenAI's app-server exposes a documented mcpServer/tool/call endpoint. That endpoint calls a configured MCP tool directly; no model turn is required. Running it from the signed app-bundled binary preserves the official responsible-process/authentication chain without injection, re-signing, TCC changes, private socket emulation, or credential extraction.

See ARCHITECTURE.md for source links and the full restriction inventory.

Requirements

• macOS
• Node.js 22 or newer
• Pi 0.80.7 or newer
• official ChatGPT macOS app at /Applications/ChatGPT.app
• official Computer Use component installed by ChatGPT under ~/.codex/computer-use/

The bridge follows ChatGPT's current launcher contract for SkyComputerUseClient under that per-user component directory. It does not honor HOME, CODEX_HOME, or an arbitrary path override when resolving the production client. The former exact app-in-plugin layout remains a strict compatibility candidate only when the current component is absent. Every selected client must be at a canonical reviewed path, pass strict code-signature verification, and carry OpenAI Team ID 2DC432GLL2.

The direct bridge starts app-server with a new private CODEX_HOME containing no account credentials and only one configured MCP server: official Computer Use. It does not inherit the user's Codex MCP servers, plugins, history, memories, API keys, or auth file. It selects a non-websocket dummy model provider bound to unreachable loopback, disables plugin/remote-control features, and never starts a turn; this prevents app-server model prewarm or Responses API traffic.

Locked-screen limitation

Direct local calls require an unlocked macOS session. Window and accessibility actions can fail with official error -10005 after the Mac locks.

OpenAI's locked Computer Use requires an active, trusted ChatGPT turn started from a connected device. It does not authorize other apps or local processes to unlock the Mac. This package cannot support locked local use unless OpenAI provides a supported local authorization API.

Pi integration

Install from npm:

pi install npm:codex-computer-use-mcp

To evaluate a source checkout instead:

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

Command:

/computer-use-status

The native Pi adapter is the primary product path. It registers and activates all ten typed tools directly, and routes the required get_app_state and following action through one retained signed-client session. It exposes no mode-changing command or wrapper-generated approval UI. Official app-access approval elicitations are resolved by Codex Full access before they reach Pi. Any elicitation that app-server does emit is shown through Pi's UI, and only the user's choice is returned to the service.

MCP server

Running the binary without arguments starts a stdio MCP server exposing the same ten direct methods plus computer_use_status:

node dist/mcp-server.js

For Claude Code, install the package in a dedicated directory and register its binary:

install_dir="$HOME/.local/share/codex-computer-use-mcp"
mkdir -p "$install_dir"
npm install --prefix "$install_dir" --save-exact codex-computer-use-mcp
claude mcp add --scope user codex-computer-use -- \
  "$install_dir/node_modules/.bin/codex-computer-use-mcp"

For Pi's generic MCP gateway, keep directTools: false so this powerful surface remains intentional:

{
  "mcpServers": {
    "computer-use": {
      "command": "node",
      "args": ["/absolute/path/to/codex-computer-use-mcp/dist/mcp-server.js"],
      "lifecycle": "lazy",
      "requestTimeoutMs": 180000,
      "directTools": false
    }
  }
}

The generic MCP server exposes the same no-permissions behavior: official Codex Full access, no wrapper permission gate, and all ten methods. App-access approvals are resolved inside the official host. Any standard form or URL elicitation that app-server emits is forwarded as an MCP elicitation/create request. The upstream client response is returned unchanged; unsupported or headless clients cancel rather than fabricate a decision.

Execution and privacy

For the current released implementation, each call:

1. validates typed arguments;
2. applies the single durable no-permissions policy with no mode or prompt branch;
3. resolves a target to a canonical installed bundle ID;
4. acquires a fixed per-user/per-app kernel lock shared across all supported clients and state roots;
5. starts global focus telemetry;
6. verifies fixed OpenAI-signed broker/client binaries;
7. starts a credential-free isolated app-server process tree with model transport disabled;
8. starts an ephemeral thread and requires a usable thread ID;
9. issues exactly one mcpServer/tool/call without a separate schema-fidelity gate;
10. rejects any model-turn notification, including during teardown;
11. combines partial-preserving ancestry enumeration with private-working-directory ownership recovery, then freezes, terminates, and verifies the app-server plus separately grouped or reparented helpers; finally it removes temporary state, releases the lock, and writes a content-safe audit with separate broker/lease cleanup evidence.

Focus telemetry is legacy observational behavior from the earlier background-computer-use wrapper. It does not provide an official Codex access control or a preventive macOS sandbox. Matching native Computer Use, the wrapper permits calls when the target is already frontmost and does not convert a completed official call into an error when focus changes or telemetry is unavailable. backgroundPreserved records the observation without gating the result. Do not use this telemetry as a reason to add further defensive policy.

Tool results may contain visible target-app text or screenshots because that is the purpose of Computer Use. They return only to the invoking Pi/MCP client. Audits never retain arguments, typed values, screenshots, app-state payloads, result text, prompts, credentials, or tokens—only bounded metadata such as method, canonical/hashed app identity, byte counts, content types, outcome, focus, broker version, and zero-turn evidence.

State and migration

Audit state defaults to ~/.direct-computer-use; override with CODEX_COMPUTER_USE_HOME. Permission policy is not read from that agent-writable path: no-permissions is compiled as the only interface. Legacy config.json files are ignored.

See MIGRATION.md for version 0.1 migration, source acceptance, rollback, and conflict avoidance.

Development

npm ci
npm run check
npm run check:pi
npm test
npm run build
npm audit --omit=dev
npm pack --dry-run

package-lock.json gives source checkouts and CI reproducible dependency versions. Published consumers use standard npm dependency resolution.

See CHANGELOG.md, PROOF.md, SECURITY.md, and CONTRIBUTING.md. Agent contributors must also follow AGENTS.md. It records the maintainer's thin-adapter intent and review standard.

License

MIT