Claude Codex Computer Use

An experimental, unofficial bridge that lets
Claude Code control local macOS applications
through an existing OpenAI Computer Use installation.

The package contains no OpenAI binaries. It starts the Computer Use client
already installed on the user's Mac and translates the small MCP compatibility
gap between Claude Code and that client.

Requirements

• macOS. The installed OpenAI runtime currently declares macOS 14.4 or later.
• Claude Code with plugin support. Version 2.1.223 is verified.
• ChatGPT or Codex with OpenAI Computer Use installed and working.
• Accessibility and Screen Recording permissions granted to the OpenAI
  Computer Use runtime.

The bridge looks for the Computer Use client at:

$CODEX_HOME/computer-use/Codex Computer Use.app/Contents/SharedSupport/
SkyComputerUseClient.app/Contents/MacOS/SkyComputerUseClient

When CODEX_HOME is unset, it defaults to ~/.codex.

Install as a Claude Code plugin

In a Claude Code session:

/plugin marketplace add songkeys/claude-codex-computer-use
/plugin install claude-codex-computer-use@songkeys

Or from the shell:

claude plugin marketplace add songkeys/claude-codex-computer-use
claude plugin install claude-codex-computer-use@songkeys

New sessions load the Computer Use Skill and MCP server automatically.

Inspect the installation with:

/plugin
/mcp

Install the MCP bridge from npm

The plugin installation is recommended because it includes both the MCP bridge
and the Computer Use Skill. The npm package can also be used as a standalone
stdio MCP server:

claude mcp add computer-use -- npx -y claude-codex-computer-use@latest

Or as a direct .mcp.json entry:

{
  "mcpServers": {
    "computer-use": {
      "command": "npx",
      "args": ["-y", "claude-codex-computer-use@latest"]
    }
  }
}

This MCP-only installation does not load the bundled Skill. Prefer the plugin
unless the MCP client supplies its own Computer Use instructions.

Usage

Ask Claude to use Computer Use explicitly, or describe a desktop task:

Use Computer Use to inspect Calculator and enter 42.

Open System Settings with Computer Use and tell me what page is visible.

The bundled Skill instructs Claude to use an observable state/action/state
loop:

1. Read the target app with get_app_state.
2. Use accessibility elements when available and screenshot coordinates only
   as a fallback.
3. Perform the action.
4. Fetch a fresh app state before deciding the next action.

How it works

The OpenAI Computer Use service authenticates the client process ancestry.
Launching its MCP client directly from Claude Code is rejected as an
unauthenticated sender. The bridge therefore uses the signed Codex executable
bundled with ChatGPT or Codex as a process launcher:

Claude Code
  -> claude-codex-computer-use bridge
  -> signed Codex launcher
  -> OpenAI Computer Use MCP client
  -> OpenAI Computer Use service

Codex is not used as an agent and no OpenAI model request is made by the
bridge. It runs codex sandbox with Codex's disabled/unrestricted permission
profile so the signed client can access its normal caches, macOS services, and
Unix sockets.

The Computer Use client requires its MCP client to advertise the elicitation
capability and answers app-access approvals through it. The bridge guarantees
that capability is present on initialize and automatically accepts the
app-access elicitation, so sessions work unattended. All other JSON-RPC
messages, including screenshot image blocks, pass through unchanged.

The Computer Use service treats a connected client as an active hold on the
controlled applications and releases them when the client exits. Codex ends
its client at the end of a conversation, but Claude Code keeps plugin MCP
servers alive for the whole session. The bridge therefore terminates the
client after 60 seconds without traffic and relaunches it on demand,
transparently replaying the recorded initialize handshake, so apps are not
held between tasks.

The service also scopes a user-initiated stop (the overlay's Esc cancel) to
the client's current "turn", which never ends for a long-lived client. When a
tool result reports that the app session was stopped by the user, the bridge
recycles the client so the next request starts a fresh session instead of
hitting the same stop again.

Configuration

Environment variables:

The signed launcher is discovered in this order:

1. COMPUTER_USE_CODEX_LAUNCHER_PATH
2. The entrypoint declared in
   /Applications/ChatGPT.app/Contents/Resources/codex-cli/codex-package.json
3. /Applications/ChatGPT.app/Contents/Resources/codex
4. The same two locations inside /Applications/Codex.app

Newer ChatGPT releases bundle Codex as a package under Resources/codex-cli
and name its launcher in that manifest. Older releases place the launcher
directly at Resources/codex.

Security and data flow

Installing this package gives Claude access to the local Computer Use tools,
which can read screenshots, click, type, scroll, drag, and interact with
applications.

The bridge intentionally:

• automatically accepts the Computer Use MCP app-access elicitation;
• launches the signed client with an unrestricted Codex permission profile;
• passes accessibility text and screenshots back to Claude as MCP tool
  results;
• releases the client after an idle timeout so applications are not held
  between tasks, and relaunches it on demand.

Claude Code may send those tool results to the configured model provider as
part of the conversation. Do not install the plugin unless that behavior is
acceptable for the applications and data on the Mac.

Compatibility

The initial release was verified with:

OpenAI Computer Use is an internal desktop integration rather than a stable
third-party SDK. ChatGPT, Codex, or Computer Use updates may change binary
paths, process-authentication rules, or protocol behavior.

Development

The bridge has no runtime npm dependencies.

pnpm install
pnpm test
pnpm smoke

pnpm test uses a fake Computer Use server and is safe to run anywhere.
pnpm smoke connects to the real local service, calls list_apps, and
verifies that get_app_state returns both text and a JPEG screenshot.

Troubleshooting

Sender process is not authenticated

The Computer Use client was started directly instead of through the signed
Codex launcher. Ensure ChatGPT or Codex is installed in /Applications, or set
COMPUTER_USE_CODEX_LAUNCHER_PATH.

OpenAI's signed Codex launcher was not found

ChatGPT or Codex is not installed in /Applications, or an update moved its
bundled Codex again. Set COMPUTER_USE_CODEX_LAUNCHER_PATH to the Codex
executable inside the app, for example
/Applications/ChatGPT.app/Contents/Resources/codex-cli/bin/codex.

Computer Use client is missing

Enable or reinstall OpenAI Computer Use first, then verify that its client
exists below $CODEX_HOME/computer-use.

Client and server version mismatch

Quit and relaunch ChatGPT so its Computer Use client and runtime update
together, then retry the smoke test.

This application session has been explicitly stopped by the user

Someone pressed Esc on the Computer Use overlay, which cancels the app
session for the current turn. The bridge recycles the client automatically,
so simply ask Claude to continue when you are ready.

ChatGPT still lists the app under Computer Use

ChatGPT's Computer Use menu can keep showing an app (with a "Stop Using …"
action) after the bridge has released the client. The service keeps its app
session record so that a follow-up turn can resume without a new approval,
and only Codex's own turn-tracking closes it. External clients have no
supported way to send that signal. The record is bookkeeping: the controlling
client process is gone and new bridge sessions are unaffected. Clear it with
the "Stop Using …" action in ChatGPT, or by quitting ChatGPT.

SkyComputerUseClient computer-history processes linger

These are ChatGPT's own history/recording helpers, spawned by its
codex app-server daemon whenever Computer Use is used and kept around
afterwards. They are idle, they do not hold control of any application, and
they are not managed by this bridge. The client the bridge manages runs with
a plain mcp argument and exits on idle release. The helpers exit when
ChatGPT quits.

errAETimeout: the AppleEvent timed out

The Computer Use service could not reach the target application in time. The
call can block for a few minutes. Retry once; if it persists, quit and
relaunch the target application, and as a last resort quit and relaunch
ChatGPT so its Computer Use service restarts.

Plugin changes do not appear

Restart Claude Code or run /plugin marketplace update songkeys and
reinstall. Claude Code runs a cached copy of the installed plugin, so editing
a checkout does not affect an existing installation until the plugin is
updated.

License and trademarks

The bridge code is available under the MIT License.

This project is independent and is not affiliated with, endorsed by, or
sponsored by OpenAI or Anthropic. OpenAI, ChatGPT, Codex, Anthropic, Claude,
and related names may be trademarks of their respective owners. Users must
supply and be licensed to use their own OpenAI and Anthropic software and
accounts.

Prior art

This project mirrors
kimi-computer-use, the same
bridge for Kimi Code CLI.