Codex
Public Made by Adomby adom
Codex in Adom Hydrogen: ecosystem setup, dock dashboard and live engineering demos.
9fee13e
1mo ago
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.
- 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. - Keep the bridge backend disconnected. Import with
codex_auth_importand the absolute host staging path. Existing destination credentials are never overwritten. - Delete the staging copy promptly. Do not print tokens or put credentials in chat, command arguments, source files, screenshots, or wiki uploads.
- 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.
# 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](https://wiki.adom.inc/adom/codex/files/bridge/screenshots/README.md)
for dates and the distinction between the original setup run and bridge 0.1.1's
later toast guidance.
[Back to adom/codex](https://wiki.adom.inc/adom/codex) ·
[Technical setup](https://wiki.adom.inc/adom/codex/files/docs/DESKTOP-BRIDGE.md) ·
[Command catalog](https://wiki.adom.inc/adom/codex/files/bridge/verbs.json) ·
[Setup skill](https://wiki.adom.inc/adom/codex/files/skills/codex-desktop-bridge/SKILL.md)
## 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:
```sh
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](https://wiki.adom.inc/adom/codex/files/docs/DESKTOP-BRIDGE.md)
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.
```sh
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.
```sh
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.
```json
{
"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.
```text
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.
```sh
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:
```json
{
"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:
```sh
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:
```json
{"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.
```sh
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.