claude-codex-computer-use

# Claude Codex Computer Use An experimental, unofficial bridge that lets [Claude Code](https://code.claude.com) 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: ```text $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: ```text /plugin marketplace add songkeys/claude-codex-computer-use /plugin install claude-codex-computer-use@songkeys ``` Or from the shell: ```sh 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: ```text /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: ```sh claude mcp add computer-use -- npx -y claude-codex-computer-use@latest ``` Or as a direct `.mcp.json` entry: ```json { "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: ```text Use Computer Use to inspect Calculator and enter 42. ``` ```text 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: ```text 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: | Variable | Purpose | | --- | --- | | `CODEX_HOME` | Override the Codex data directory. Defaults to `~/.codex`. | | `COMPUTER_USE_CLIENT_PATH` | Override the full path to `SkyComputerUseClient`. | | `COMPUTER_USE_CODEX_LAUNCHER_PATH` | Override the signed Codex executable path. | | `COMPUTER_USE_BRIDGE_IDLE_TIMEOUT_MS` | Idle time before the client is released. Defaults to `60000`; `0` keeps the client running for the whole session. | | `COMPUTER_USE_BRIDGE_DEBUG=1` | Write bridge diagnostics to stderr. | The signed launcher is discovered in this order: 1. `COMPUTER_USE_CODEX_LAUNCHER_PATH` 2. `/Applications/ChatGPT.app/Contents/Resources/codex` 3. `/Applications/Codex.app/Contents/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: | Component | Verified version | | --- | --- | | Claude Code | 2.1.223 | | ChatGPT bundled Codex | 0.148.0-alpha.15 | | OpenAI Computer Use runtime | 26.817.1000761 | | macOS / architecture | macOS 27.0 / arm64 | | MCP protocol | 2025-11-25 | 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. ```sh 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`. ### 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](./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](https://github.com/songkeys/kimi-computer-use), the same bridge for Kimi Code CLI.