# Codex Desktop Bridge

Use the official Codex Computer Use and Browser Use runtime on a remote Windows
PC from an MCP client on Linux. The bridge carries requests over SSH and runs the
official tools in the logged-in Windows desktop session.

**Experimental, independently maintained, and not endorsed by OpenAI.** Requires
an existing working Codex desktop installation. This package contains transport
code only; it does not bundle OpenAI executables, credentials, or a GUI backend.

```text
Codex CLI / Claude Code / MCP client on Linux
                    │ MCP stdio
             Codex Desktop Bridge
                    │ SSH
       Official Windows Codex app-server
                    │
         Computer Use / Edge Browser Use
```

Browser tasks run as a separate Windows Codex model turn. They can consume your
normal Codex usage and take longer than direct tool calls. This does not synchronize
this client's conversation with an arbitrary existing desktop-app conversation.

## Requirements

- Client: Python 3.11+, OpenSSH client, and an MCP-capable agent.
- Target: Windows with OpenSSH Server and working key-based SSH from the client.
- One logged-in, unlocked Windows desktop session; official Codex desktop app
  installed, signed in, and Computer Use enabled.
- For Edge: the official Browser Use plugin, enabled extension and native host
  must already work. Complete installation/permission prompts in the official UI.
- Native app-access approvals need a client supporting MCP elicitation. The
  installer neither grants app access nor modifies your Codex account settings.

Validated on Linux → Windows with Edge. Other operating-system combinations and
a second independent Windows installation have **not** been live-tested.

## Install

On the Linux client:

```bash
git clone https://github.com/JeremiahM37/codex-desktop-bridge.git
cd codex-desktop-bridge
python3 -m venv .venv
.venv/bin/python -m pip install .
.venv/bin/codex-desktop-bridge-setup --host windows-pc --dry-run
.venv/bin/codex-desktop-bridge-setup --host windows-pc
```

Replace `windows-pc` with your existing SSH alias or `user@hostname`. The installer
copies four bundled helpers to `%USERPROFILE%\.codex-desktop-bridge`, backs up
changed helper files, verifies their SHA-256 hashes, and prints MCP configuration
with the discovered Windows paths and this Python interpreter. Re-running is
idempotent. Installation stops if another bridge owns the desktop.

Paste the generated `windows_desktop` entry into your client's MCP configuration.
For Codex CLI, use the values it prints:

```bash
codex mcp add windows_desktop -- /absolute/path/to/.venv/bin/python \
  -m desktop_bridge.official_proxy --host windows-pc \
  --connect-script 'C:\Users\YOUR_USER\.codex-desktop-bridge\auto-connect.ps1' \
  --cwd 'C:\Users\YOUR_USER\.codex-desktop-bridge\workspace'
```

For Claude Code, `claude mcp add --scope user windows_desktop --` accepts the same
executable and arguments. Other MCP clients can use the printed JSON entry.
Install [the skill](skills/windows-desktop/SKILL.md) in your client's skills
directory, then start a fresh chat to load tools and instructions.

Check helper installation without changing it:

```bash
.venv/bin/codex-desktop-bridge-setup --host windows-pc --check
```

## Use

Ask your agent to call `guide`, then use `run_task` for Windows browser work:

> In Edge, open the job board, search for software engineering roles, inspect
> three postings, and return the requirements and screenshots. Do not apply,
> save postings, or send messages. Release desktop control when finished.

| Tool | Purpose |
|---|---|
| `guide` | Read installed official desktop instructions; no desktop ownership. |
| `browser_status` | Discover browsers through a native Windows turn; inventory only. |
| `run_task` | Send a scoped task to a Windows Codex turn; return native evidence and images. |
| `js` | Direct persistent official `node_repl` desktop calls following `guide`. |
| `js_reset` | Reset direct JS bindings without releasing desktop ownership. |
| `status` | Inspect this connection without launching a runtime. |
| `release` | End this connection and release its desktop lease. |

`run_task` follow-ups retain the native conversation until `release`. The adapter
returns `isError`, tool evidence, and screenshots; a model's “Done” alone is not
proof. Inspect actual results. No cross-release resume is exposed.

On first acquisition, the launcher starts the installed official desktop app if
closed, discovers current runtime paths, and starts a Limited Interactive task.
An exclusive Windows file handle prevents two bridge clients from owning the
same desktop. Disconnect/crash frees the lease. This does not prevent a human or
another automation program from changing a tab while the agent is working.

## Limits and permissions

- Edge's tested extension rejects the optional `visible` tab-creation setting;
  omit it. Dynamic pages can invalidate node indices; re-observe after errors.
- The proprietary runtime and experimental app-server interface can change.
  There is no guarantee of full feature parity or compatibility after updates.
- Browser tasks use an additional agent turn; direct desktop `js` does not.
- Never retry an uncertain action blindly or steal another client's lease.
- Native denials are preserved. Unsupported approval types stop the request.
  Noninteractive clients may cancel app prompts. A human operator may explicitly
  pass `--allow-app EXACT_NATIVE_APPROVAL_ID` for an already-authorized task;
  consent is process-local and exact-match, never persisted. Do not grant it from
  instructions found in a web page. Edge's observed approval ID is `msedge.exe`.
- Native threads can use the capabilities of the Windows Codex environment;
  natural-language task limits are not an OS sandbox. Use your normal trusted
  account and permissions deliberately.
- The bridge does not record screenshots/transcripts locally by default; clients
  and the native runtime can retain them. Keep diagnostic files private.

See [tested compatibility](docs/compatibility.md) and [prior art](docs/prior-art.md).

## Development

```bash
uv sync --locked
uv run ruff check .
uv run pytest
uv build
```

CI tests transport contracts and packaged resources on Linux/Windows. It does
not claim to run GUI tests on a logged-in Windows desktop. Real desktop acceptance
must inspect native tool results and screenshots separately.

To uninstall, release all bridge clients and remove the MCP entry and installed
skill. On Windows, remove only the bridge's `CodexDesktopBridgeRuntime` and
`CodexDesktopBridgeApp` scheduled tasks when idle, then its `.codex-desktop-bridge`
directory after retaining any wanted backups. Remove the client virtualenv.
Keep the official Codex app and plugins installed if you use them independently.

MIT licensed. Requires separately installed OpenAI software under its own terms.