Codex Bridge

Codex Desktop, reachable through Adom Bridge. A compiled Rust binary owned by adom/codex.

Codex Bridge lets an Adom assistant manage a Codex Desktop installation on a selected Windows host, talk to its native tools, and use its bundled backend for accounts, plugins, skills, and conversations. Your assistant can run elsewhere: the tested desktop lives on arav-rog, not on AdomLapper.

The real Windows application after first-run setup. The tested Store package is named ChatGPT and includes this Codex workspace. This is not the Hydrogen dock dashboard or a mockup.

The seven screenshots in this guide are real, unretouched window captures from the arav-rog test on 2026-09-08. The Home image was refreshed for this guide; onboarding and conversation images preserve the earlier verified run. We did not repeat UAC, install plugins, create schedules, or import other apps just to stage pictures. The gallery illustrates observed UI, not every API operation below. See capture provenance and checksums for dates and the distinction between the original setup run and bridge 0.1.1's later toast guidance.

Back to adom/codex · Technical setup · Command catalog · Setup skill

At a glance

Workflow	What the bridge does	Verification boundary
Install and launch	Finds the official Windows package, installs with WinGet, opens the native app	Install, uninstall, reinstall and visible first-run completion tested
Sign in	Imports a user-authorized native auth cache without overwriting credentials; offers native login as fallback	Cache import and signed-in account/app verified; not universal VS Code SSO
Desktop conversations	Discovers native schemas and calls the running app over a PID-verified pipe	Desktop-created test conversation and persisted reply verified
Plugins	Searches catalogs, inspects details, installs, reads back and removes plugins	LaTeX install/read-back/remove/read-back tested; third-party OAuth not tested
Projects and worktrees	Exposes the desktop's live project, fork and handoff tools	Schemas discovered; worktree mutations not exercised in the baseline
Scheduled tasks	Exposes the desktop's automation tools	Schemas discovered; no recurring task created for this guide
Panels and organization	Exposes file/review/terminal panels and thread/sidebar tools	Availability follows the running app's catalog; not every action tested
Progress and approvals	Tracks bridge jobs, backend events and pending native requests	Native approvals remain user decisions; bridge responses do not grant consent
Remove safely	Removes desktop or bridge separately while retaining Codex home	Running-app refusal and retained account/history after reinstall tested

1. Three installations, not one

Component	Runs where	Installed by
adom/codex integration	Your Adom workspace	adom-wiki pkg install adom/codex
codex-bridge.exe and bridge.json	AB on the selected Windows desktop	A separately built bridge ZIP and AB's runtime lifecycle
OpenAI Codex Desktop	The same Windows desktop	Official Microsoft Store package, managed through codex_desktop_install

The Rust bridge does not need Node or Python on the target. It uses Windows PowerShell/WinGet for package operations and the desktop's activated native codex.exe for its separate app-server connection. Other Adom components can have their own runtime requirements.

Build the bridge

From a current source checkout of adom/codex:

bash bridge/build.sh

Linux cross-building requires Rust's x86_64-pc-windows-gnu target, MinGW-w64, zip, and sha256sum. The script runs tests and builds a Windows x64 release. It produces bridge/dist/codex-bridge-windows-x64.zip and SHA256SUMS. The ZIP root contains bridge.json and codex-bridge.exe.

Distribution status: the tested runtime is development-pinned on arav-rog. There is no published public runtime release/update manifest yet. Do not assume the wiki package installer deploys this ZIP, and do not invent a download URL. The technical guide describes the AB SDK development-cache deployment and safe update sequence. Preserve existing development pins and do not replace a bridge owned by another task.

Select the desktop explicitly

First discover the reachable AB targets and choose the relay that reaches your host. The examples below use the dedicated test machine. Replace it deliberately for another installation; your container hostname is not target discovery.

ab --target arav-rog --ai-thread codex-bridge-guide codex_status '{}'
ab --target arav-rog --ai-thread codex-bridge-guide codex_readiness '{}'
ab --target arav-rog --ai-thread codex-bridge-guide codex_describe '{}'

adom-bridge can be used instead of ab. Use the same caller identity for an operation and its job polls. codex_status reports package/version, windows, auth-cache presence, backend ownership and connection mode. A present auth cache is not proof of a valid account; a running process is not proof of completed setup.

2. Install, sign in, and finish Windows setup

Current testing uses crr (ConfRoomROG). arav-rog is in use by Caleb; the arav-rog screenshots and results in this guide are historical.

ab --target ConfRoomROG --ai-thread codex-bridge-guide codex_desktop_install '{}'
ab --target ConfRoomROG --ai-thread codex-bridge-guide codex_progress '{"jobId":"<returned-job-id>"}'
ab --target ConfRoomROG --ai-thread codex-bridge-guide codex_desktop_open '{}'

The tested official Store ID is 9PLM9XGG6VKS, package OpenAI.Codex. Its displayed Store/app name was ChatGPT in this test. If the installer asks for agreements, obtain the user's actual acceptance of both the Store source and package agreements for this target before retrying with {"acceptAgreements":true}. Bridge 0.1.2 supplies both agreement flags and returns installer.args plus the installer output. Existing installations are detected and retained.

Reuse an existing Codex sign-in

Historical setup capture: the native app recognized the account and asked to confirm the existing role. Sign-in worked, but OS setup was not complete yet.

Being signed in to the VS Code extension is helpful only when there is a transferable native Codex auth cache. This is not password scraping or a promise that every extension login can be silently reused across machines.

1. With the user's authorization, transfer their native $CODEX_HOME/auth.json (usually ~/.codex/auth.json) to private staging on the selected host using AB.
2. Keep the bridge backend disconnected. Import with codex_auth_import and the absolute host staging path. Existing destination credentials are never overwritten.
3. Delete the staging copy promptly. Do not print tokens or put credentials in chat, command arguments, source files, screenshots, or wiki uploads.
4. Connect and verify codex_account_read, then verify the visible signed-in app. An already-running desktop may need a normal quit/relaunch; preserve active work.

The importer sets an owner-only Windows ACL. If no transferable cache exists, start the native chatgpt or chatgptDeviceCode login via codex_login_start after connecting. Let the user complete authentication. Refresh/revocation and connected-service authentication can still require the user's involvement.

Give advance notice before UAC

Historical capture of the app's pre-UAC page. The pictured dialog is the app's own instructional illustration, not a capture of Windows' secure desktop. This is the point where the AI must send the advance AB toast before continuing.

Before Finish setup, or another action expected to request elevation, send the _beforeUac payload returned by codex_describe, status, readiness, install or open as an AB notify_user call on the same target and caller.

{
  "title": "Codex setup needs your approval",
  "body": "A Windows administrator (UAC) prompt is coming for Codex setup. Please approve the native Windows prompt for OpenAI's Codex/ChatGPT app to continue. This notification cannot approve it.",
  "level": "warning",
  "durationLong": true,
  "focus": { "app": "ChatGPT" }
}

Prefer the currently discovered app HWND for focus when one is available. Send the toast before elevation, while the normal desktop is visible, and also tell the user in chat because Windows may suppress notification banners. Wait for the native Windows decision and then inspect the resulting app.

This is conditional AI guidance, not an unconditional automatic toast on every status check. A toast acknowledgment does not approve UAC. Do not send a false upcoming-UAC warning on an already-configured host or bypass the secure desktop. The baseline user approved the real setup prompt; this guide does not re-trigger it.

3. Talk to the actual desktop

The baseline created "Adom Rust bridge test" through the desktop's native tools. Its DESKTOP_BRIDGE_OK reply was read back and survived uninstall/reinstall.

There are two different connections. Choose the one that matches the result you want.

Adom assistant -> named AB target -> codex-bridge.exe
                                    |
                                    +-- Desktop-native pipe -> running Codex Desktop
                                    |   native threads, projects, panels, automations
                                    |
                                    +-- app-server --stdio -> separate bundled backend
                                        accounts, plugins, skills, MCP, backend turns

The native route verifies the named pipe's server PID against the installed package's visible desktop process. It uses length-prefixed JSON-RPC, implemented in Rust. It is experimental app internals, not a documented stable public API. Rediscover schemas after desktop updates or restarts.

ab --target arav-rog --ai-thread codex-bridge-guide codex_desktop_tools '{}'

If multiple verified endpoints exist, the bridge lists them and requires desktopPipe. Do not guess or persist a pipe name across restarts. PID verification does not guarantee every endpoint serves the same tool methods; a stale or non-serving endpoint can still report a native handler error.

The app exposes tools such as list_threads, read_thread, create_thread, send_message_to_thread, and wait_threads. Discover their current schemas. An invocation has this shape:

{
  "tool": "read_thread",
  "threadId": "<native-caller-thread-id>",
  "desktopPipe": "<verified-endpoint-if-required>",
  "arguments": {
    "threadId": "<native-thread-to-read>",
    "turnLimit": 1,
    "includeOutputs": false
  }
}

Pass that object to codex_desktop_tool_call and poll its job. The outer threadId is native caller context, not the human-readable AB --ai-thread name. Use real IDs from discovery or an authorized seed; never fabricate them. Tool calls may have additional native instructions and approval requirements.

For a requested conversation, create it, retain the returned thread/host IDs, wait for completion or attention, and read the result back. To show it, use the native navigation tool and verify an actual window capture. An acknowledgment such as navigated:true is not sufficient: during guide preparation an endpoint acknowledged navigation while the captured page stayed on Home.

4. Find and manage plugins

The Home screenshot's Plugins entry is the native app's catalog entry point. The bridge also exposes catalog management directly, without needing to click through that page. Catalog contents and availability can vary by account and app version; seeing an entry does not mean it is installed.

Plugin operations use the separate bridge-owned native app-server. Connect once, poll the returned job, and verify its result before issuing backend commands:

ab --target arav-rog --ai-thread codex-bridge-guide codex_connect '{"mode":"standalone"}'
ab --target arav-rog --ai-thread codex-bridge-guide codex_progress '{"jobId":"<connect-job-id>"}'
ab --target arav-rog --ai-thread codex-bridge-guide codex_plugin_list '{"query":"latex","limit":10}'

Read details using the exact marketplace returned by discovery:

{"pluginName":"latex","marketplacePath":"<discovered-local-marketplace-path>"}

Send this to codex_plugin_read. For a remote marketplace use remoteMarketplaceName instead of marketplacePath. Inspect availability, installation policy, terms, interstitials, and connected apps before installation.

After authorization, use the same identifiers with codex_plugin_install, poll the job, then read the plugin again. Verify result.plugin.summary.installed, rather than treating queue acceptance as an installation. appsNeedingAuth means the user still needs to authenticate to a connected service. Do not silently approve OAuth or claim it is ready early.

For removal, discover the exact installed pluginId and pass it to codex_plugin_uninstall. Poll and read back the absent state. The baseline used latex@openai-bundled, verified installation/enabled state, and removed that temporary test plugin. No paid service or third-party OAuth workflow was exercised.

5. Projects, worktrees, and review

Project selection belongs to the remote desktop's environment. The Home view shows Choose project and an empty Projects sidebar on this test installation. A container path on your assistant's machine is not automatically a directory on arav-rog.

Discover list_projects before selecting a project. Native thread creation can target a saved project or projectless work. Worktree and handoff tools can affect real checkouts, branches and active tasks, so follow the live schemas and user intent. Do not invent a project ID, branch name, or destination host.

The baseline discovered fork_thread and handoff_thread but did not exercise checkout changes. Treat this as exposed capability, not a tested cross-machine handoff promise. A handoff may interrupt its source task; inspect ownership and current activity first.

The app also has a Pull requests entry. Its presence is not evidence that the bridge created, reviewed, or merged a GitHub pull request.

open_in_codex can expose native file, terminal, browser and review panels when available in the app's catalog. Opening a panel is a UI action; it does not itself inspect the content, run a command, or prove a code review was completed.

Native imports are a separate decision

Historical setup capture: the desktop offered to import work from another app. We skipped it. The visible default switches do not mean import or sync was authorized or executed.

The bridge's auth-cache import is not this cross-app project/history import. Keep credentials reuse, project selection, and importing another app's data separate. Do not accept defaults that broaden data access as an incidental setup step.

6. Scheduled work and desktop-only surfaces

Historical onboarding suggestions, not completed tasks. We selected Skip rather than running a spreadsheet task, sending a message, or scheduling a calendar event. A calendar suggestion here is not proof of a Codex automation run.

The discovered automation_update tool supports viewing, creating, updating and deleting automations. Its native instructions distinguish ongoing thread follow-ups from standalone scheduled project work. Inspect existing automations, preserve unrelated fields and notification preferences, and ask before creating recurring activity that the user has not requested. The bridge does not add an independent cron scheduler or guarantee wake-from-sleep execution.

Historical post-setup Home view. Start Voice is the native app's optional offer; no voice session was started. The bridge does not enable the microphone merely because voice tools appear in the discovered catalog.

The native catalog also exposes thread organization, archive/restore, usage inspection, and other app-specific actions. Availability and policy follow the installed app. Voice-only tools are for an active voice session, not ordinary text automation. Sharing, consuming usage-reset credits, and changing recurring jobs need the user's intent; catalog discovery is not permission to invoke everything.

7. Models, skills, MCP, and the separate backend

The screenshots show the native composer with its model/effort selector and Ask for approval control. Model availability is account/build dependent; these captures are not a permanent model list or a subscription entitlement.

Once codex_connect completes, use codex_models, codex_skills_list, codex_mcp_status, and codex_config_read to inspect the bundled backend's effective environment. codex_account_read verifies sign-in. These commands are inspection APIs; a config read is not a general-purpose settings editor.

On Windows, codex_connect launches the activated desktop-bundled codex.exe app-server --stdio as a separate bridge-owned process sharing Codex home. It does not attach to desktop-owned active sessions. mode:desktop fails explicitly on Windows rather than silently substituting a backend.

Backend conversations use codex_thread_start, codex_turn_start, codex_thread_read, codex_thread_turns, and codex_thread_items. Steering, interrupting, forking, archiving and releasing subscriptions are also available. Only operate on authorized work. Never resume an active desktop-owned thread in this separate backend. The backend test reply was CODEX_BRIDGE_OK; the actual desktop test reply was separately verified as DESKTOP_BRIDGE_OK.

8. Follow progress and preserve approvals

Long-running bridge calls return a jobId. Poll codex_progress until stillRunning:false, then inspect result.success and any nested native result.success or error. Top-level success can mean only that the poll worked.

ab --target arav-rog --ai-thread codex-bridge-guide codex_progress '{"jobId":"<job-id>"}'
ab --target arav-rog --ai-thread codex-bridge-guide codex_events '{"sinceSeq":0}'
ab --target arav-rog --ai-thread codex-bridge-guide codex_requests '{}'

Omit jobId to list the current caller's jobs. Job history is bounded and retained for one hour in the bridge process; it does not survive a bridge restart. After a timeout, inspect the existing job and native state before retrying a mutation. Event streams use sequence cursors; compare oldestSeq to detect gaps.

Pending native approval/user-input requests are returned by codex_requests. Use codex_request_reply with the native response shape only after the appropriate user decision. No automatic execution approval, OAuth approval or UAC bypass is part of this bridge. Disconnect refuses active turns and pending requests rather than abandoning them silently.

9. Uninstall without deleting your work

Desktop removal and bridge removal are separate operations:

Request	Operation	What remains
Remove Codex Desktop	codex_desktop_uninstall {"confirm":true} after disconnecting and normally quitting the app	Codex home, credentials, plugins, saved threads and projects
Remove the AB bridge	AB bridge_uninstall {"name":"codex"} invokes its lifecycle hook	OpenAI desktop installation and user data
Delete account data or projects	Not part of either uninstall	Requires a separate explicit decision

Quit the desktop normally, including tray/background package processes, and preserve any active work first. The bridge refuses desktop removal while package processes or its own backend are running. Do not kill unrelated Codex processes to force an uninstall. The live baseline verified refusal while running, then uninstall/reinstall on the idle test installation with account/history retained.

Troubleshooting

Symptom	Next check
Wrong machine or missing bridge	Rediscover AB targets, select the correct relay, inspect bridge_list; do not default to the local laptop
Multiple desktop pipes	Select a verified endpoint from fresh discovery; inspect native errors; rediscover after restart
Navigation says success but nothing changes	Capture the current window and inspect its actual state; acknowledgment alone is insufficient
connected:false while desktop is open	This describes the separate backend connection, not whether the desktop exists
Auth cache exists but app needs login	Verify account validity; finish native login/setup; do not overwrite an existing cache
Store agreements or Windows setup blocks	Get the user's real decision; send the advance UAC toast before the elevation step
Plugin installed but unavailable	Read details and appsNeedingAuth; connected-service authentication may remain
A job or event disappeared	Check process restart, retention, caller identity and cursor gaps before repeating work
Removal is refused	Inspect active turns, pending requests, tray processes and task ownership; quit normally

Verified baseline and source map

Baseline: 2026-09-08, arav-rog, AB 2.1.72, bridge 0.1.1, OpenAI.Codex 26.901.6511.0, bundled native CLI 0.153.4. Fourteen tests passed, including unit/mock and HTTP integration coverage; Windows-target Clippy and the Windows x64 release build passed. The screenshot tour illustrates native UI; the workflow table above distinguishes it from end-to-end mutation tests. No Codex Desktop installation was made on AdomLapper.

File	Responsibility
src/main.rs	Loopback HTTP, routing, jobs, caller attribution, setup/UAC hints
src/desktop.rs	Windows package lifecycle, process detection, protected auth import
src/app_tools.rs	PID-verified native desktop pipe and structured RPC
src/rpc.rs	Separate app-server connection, events, requests and ownership
src/process.rs	Bounded process output and timeouts
bridge.json, verbs.json	AB executable lifecycle and the 40-command catalog
tests/http.rs, build.sh	HTTP contract verification and Windows release packaging

The HTTP listener binds loopback and rejects browser Origin requests. AB caller identity provides attribution and ownership, not isolation from other processes running as the same OS user. Screenshots contain no credential cache contents.

Windows x64 is the tested platform. Other OS installers, a dedicated bridge dock UI, full worktree/automation testing, third-party OAuth and a public runtime update channel remain outside this verified baseline. The existing CAD videos on the main adom/codex page were recorded in Hydrogen, not this desktop app.