buidangminh23/codex-mcp-bridge
Connect ChatGPT to your own Codex Desktop projects and conversations.
Changelog
Follows Keep a Changelog and SemVer.
[2.3.2] - 2026-11-06
Fixed
- An update no longer stops the background relay on a machine with more than one Node installation. Setup moved the relay to whichever Node ran the updater, so it had to re-register the relay's scheduled task. When that task belongs to Administrators, a normal terminal gets
Access denied, and the update failed withUPDATE_SETUP_INCOMPLETEafter npm had already replaced the package the relay was running from. The relay stayed down until someone repaired it. Setup now keeps the Node the relay already uses, as long as that Node still exists, runs, and meets the package'senginesrequirement. codex-bridge-updateno longer refuses withUPDATE_DOWNGRADE_REFUSEDwhen an older copy comes first onPATHand a newer bridge is installed. That older copy hands the update to the newer one, or installs the latest published version first if there is a newer one. Refusal still applies when no handover is possible.- A failed handover now reports the reason from the updater that took over, instead of only
EXIT_1.
Verification and limits
- Tests cover keeping the relay's Node, moving away from one that is too old, broken or removed, the handover from an older copy with and without npm access, and the reported reason. Reverting each change turns its tests red.
- A copy older than this version still refuses as before, so an older copy that cannot be overwritten has to be updated once from an administrator terminal, or bypassed with
npm exec --yes --ignore-scripts --package=@minhspark/codex-mcp-bridge@latest -- codex-bridge-update --user. - A relay task that belongs to Administrators still cannot be changed from a normal terminal. This only matters if the relay's Node or package folder has to change, and the update then still fails with
TASK_SCHEDULER_UNAVAILABLE.
[2.3.1] - 2026-11-06
Fixed
- A relay call no longer fails with
BRIDGE_ACCOUNT_CHANGEDbecause Claude Desktop touched an unrelated file in its data directory. The account reader compared the directory's modification time, so any file created or removed there during a read counted as an account change. It now compares the directory's identity, and the account file's own version and contents still have to match. If a read still catches the account file mid-change, it reads again up to three more times over about 75 ms before reporting the account as unavailable.
Verification and limits
- With a process creating and removing a file in the data directory every 5 ms, 125 of 1,500 reads failed on 2.3.0 and 0 of 3,000 failed on this version. Tests cover unrelated directory changes, a replaced directory, an account changing once during a read, and a file that stays unreadable.
- An account that is really signed out or changed is still reported, and a second data directory with account state appearing during a read is still reported as
ambiguous, with no account selected.
[2.3.0] - 2026-11-06
Fixed
- The background relay no longer inherits
CLAUDE_DESKTOP_USER_DATAfrom its long-running service. A service started before Claude Desktop moved its data kept the old path for days, could not read the Claude account, and failed every Claude to Codex call withBRIDGE_ACCOUNT_CHANGEDwhile its status still saidlistening. The daemon now finds the data directory itself. An explicit value is saved for it only when it selects a different directory that holds account state, and an explicit value stays authoritative everywhere else. BRIDGE_ACCOUNT_CHANGEDnow names the provider and the reason when an account could not be read, instead of only saying it changed.codex-bridge-updateno longer reinstalls its own version when a newer one is published. It installs the latest version and hands the update over to it. If npm cannot be reached it continues with its own version and says so.- Setup replaces a
CLAUDE_DESKTOP_USER_DATAvalue, from the shell or saved in a Claude or Codex entry, that points at a directory without account state. A value that still holds account state is kept.
Added
- Queued delivery to a dormant Claude session now works with a project policy. It was switched off for the whole mode, so a machine using
bridge-projectsgotCLAUDE_SESSION_NOT_READYeven withcrossSessionInboundset toaccept. The policy must authorize the sender and the recipient directory, and both are checked again when the message is queued, immediately before it is written, and when its receipt is read. A grant revoked while a message waits ends it asrefusedwithCLAUDE_QUEUE_SCOPE_REVOKED. Hardened deployments still do not use queued delivery. codex-bridge-updatenow updates every other installation it finds onPATHor in a client's saved entry, waits up to a minute for running workers and the relay daemon to load the new version, and sends a read-only request through the relay to Codex Desktop. The result reports all three. An installation it cannot write is named, with the error, and does not fail the update.- Setup records the installed bridge in
bridge-current-install.jsonunder the Codex home. A supervisor started from another installation moves its worker to that one when it is at least as new, so a client that still points at a leftover copy, or a copy in a folder that needs administrator rights, gets the new version without a restart. Hardened deployments and checkouts do not follow it.
Verification and limits
- Tests cover each of these paths, including a supervisor moving between installations and a project policy revoked while a message waits. The fixes were run on the Windows machine where the failure occurred.
- A conversation already open in Codex Desktop can keep its old tool list, because Codex does not refresh it for that conversation. The tools it already has use the new version; a new tool needs a new conversation.
- A supervisor process keeps its own code until its app restarts; only its worker moves. The Antigravity sidecar runs directly from its installation and also needs an Antigravity restart.
- Installations older than this version do not read
bridge-current-install.json, so the first update to it relies on updating those copies directly. An oldercodex-bridge-updatestill reinstalls itself: for this first update runnpm exec --yes --ignore-scripts --package=@minhspark/codex-mcp-bridge@latest -- codex-bridge-update.
[2.2.0] - 2026-11-06
Added
send_to_claude_sessioncan now queue a message for a Claude Desktop session that is not running. Withtarget: "auto", the exactexpectedTaskIdand a recipientcrossSessionInboundofaccept, it returnsstatus: "queued"andsent: falseinstead ofCLAUDE_SESSION_NOT_READY. Thecodex-bridgeprocess inside that session delivers the message when the user next opens it. Nothing opens or wakes the session, and the composer and the Claude Desktop interface are not used.read_claude_deliveryaccepts the returnedqueueIdand reportsqueued,dispatching,sent_unconfirmed,reply_received,refused,expiredorunknown.
Changed
- The rule against using another process to make a blocked send succeed now has one exception, approved by the owner: this queued delivery. It claims no sender class, because the sending turn has ended, and it requires the recipient's explicit
accept, which is checked again immediately before the write.
Verification and limits
- Tests cover the store, dedupe, limits, expiry, file permissions, malformed and symlinked entries, ordering, at-most-once handling, policy and directory changes at delivery, and the queued result through the real tool. On macOS a frame without
from-modewas written into a live Claude Desktop session, which showed it as a message from another session. - Delivery can start a turn as soon as the session opens, without anyone reading the message first. A recipient that uses
hold,refuseor no explicit setting keeps gettingCLAUDE_SESSION_NOT_READY. Hardened deployments and project-policy mode do not use queued delivery. - A queued message waits for the user to open the session. It cannot get an immediate answer, and the bridge still cannot wake a session. It expires after 7 days. The Antigravity outbound path is unchanged and still reports
CLAUDE_SESSION_NOT_READY. sent_unconfirmedmeans the frame was written to the session's socket. Claude's handling is confirmed only byreply_received, or by reading the session. A control receipt that Claude sends back while the frame is being delivered is not recorded.- A session whose
codex-bridgecannot run or verify itself never drains, and its entries expire after 7 days. - macOS relay behaviour is unchanged: Codex Desktop still refuses any process it did not launch, and the bridge does not work around that. The macOS setup guide now says to keep Codex Desktop running with a task open.
- Upgrade with
npm install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge --foreground-scripts. A session's bridge picks up the new version when idle or when the session next opens.
[2.1.1] - 2026-11-05
Fixed
- The Windows relay host no longer reports
listeningwhile loaded conversations still own the relay sockets.desktop-relay-host.jsonnow saysstandbyin that case and is rewritten when the host takes the sockets over, soownedSocketsstays accurate. Relay behavior itself is unchanged: the host already waited behind those conversations and took over when they left, which is now covered by a test and was measured at 326 ms against a running Codex Desktop.
[2.1.0] - 2026-11-05
Added
- On Windows, the always-on background relay service now hosts the native Codex relay whenever Codex Desktop is running. Claude no longer needs a Codex conversation opened first, new or old, for the relay to answer. The service finds the running Desktop by itself, checks that the endpoint belongs to it, and closes the relay when Desktop exits. A relay already owned by a Codex-launched companion is left alone. An update reloads the host with the service, without opening anything.
autoReload.clientToolListin status results says whether the tool list a client received at connection is still current:current,stale,refreshedorunknown, with the added, removed and changed tool names. Status text adds a warning when it differs. Automatic reload replaces the running code, but a conversation opened before an update can still show its old list, andautomatic reload: currentalone did not reveal that.
Fixed
- A crashed native relay worker now recovers when the update it restarts into changes the tool list, and the client is told through
notifications/tools/list_changed. It previously stopped at the recovery limit withThe replacement tool catalog requires an explicit client reconnect. A client that did not declaretools.listChangedstill has to reconnect.
Limitations
- macOS is unchanged: a Codex conversation still has to be loaded before the relay answers. Codex Desktop on macOS refuses any process it did not launch (
dynamic_app_tools_peer_rejected reason=untrusted-process-ancestry, measured on the app-signed Node as well), and the bridge does not work around that check. - On Windows, the relay cannot run while Codex Desktop is fully closed. The host needs the background relay service and a configured Desktop relay. It stays off for a hardened profile, which keeps its Codex-launched companion.
- This covers delivery into Codex only. A dormant Claude Code session still returns
CLAUDE_SESSION_NOT_READY, because the bridge has no way to wake it silently. - An open conversation keeps its old tool list until a new one is started. The bridge reports this; it cannot refresh that list.
- Code of a running supervisor and of
vscode-bridgestill changes only when their client reconnects.
[2.0.0] - 2026-11-05
Removed
- The bridge no longer creates Claude sessions. It never opens or prefills the Claude Desktop composer and never presses Send. The composer helpers, the native folder selection and the trust dialog handling are gone.
- The tools
start_claude_session,read_claude_creationandabandon_claude_creation. - The
requestId,autoSubmitandtrustProjectinputs ofsend_to_claude_session, theCLAUDE_BRIDGE_AUTO_TRUST_PROJECTSsetting, and the 64-character creation ID lookup inread_claude_delivery.
Changed
- Claude delivery now happens only through the direct relay to a running session with
send_to_claude_session. send_to_claude_sessionwithtarget: "new"is refused withCLAUDE_SESSION_CREATION_REMOVEDandsent: false, in any case and with surrounding spaces. It opens nothing and is never treated as a session name, even when a session is namednew.- With no running session in
expectedCwd,send_to_claude_sessionreturnsCLAUDE_SESSION_NOT_READYwithsent: falseand asks the user to open the session in Claude Desktop. This now coverstarget: "auto"withoutexpectedTaskIdand an exact identity, both of which returnedCLAUDE_SESSION_NOT_FOUNDbefore. - An exact identity that no longer matches while another session runs in that project still returns
CLAUDE_SESSION_NOT_FOUND, and nothing is redirected to that other session. - The collaboration rule written by
configure-message-automation.mjsno longer treats a handoff that arrived through Computer Use as already authorized. - Tool descriptions,
inspect_bridge_projectand the documentation now say that the user opens Claude sessions. - Codex-side creation with
start_codex_threadanddelegate_to_codexis unchanged.
Migration
- Codex can no longer open a new Claude conversation by itself. Open the session in Claude Desktop, then send with
target: "auto"andexpectedCwd, addingexpectedTaskIdwhen several tasks match. - Remove
CLAUDE_BRIDGE_AUTO_TRUST_PROJECTSfrom your configuration. It no longer does anything. - If you enabled message automation, run
node scripts/configure-message-automation.mjs --apply --approve-message-automationagain. An installed collaboration rule keeps the old text until you do, and--checkreports it as out of date. - A saved
requestIdfrom an earlier creation can no longer be inspected. Look for the conversation in Claude Desktop instead of sending it again. - A running 1.x bridge can hand its state to this version. Pending creation requests in that state are dropped and do not resume or reopen anything.
- Upgrade with
npm install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge --foreground-scripts.
Verification and limits
- Tests check that the removed tools and inputs are not registered, that
target: "new"is refused in both routing modes without reaching a session namednew, and that a worker restored from a state holding pending or invalid creation data starts normally and resumes nothing. - The reload test uses real worker processes with a crafted 1.x state. A live 1.x to 2.0.0 reload with Claude Desktop and Codex Desktop was not run.
- After a worker crash, the supervisor treats the smaller tool list as needing an explicit client reconnect, as it does for any catalog change in
claude-bridge. - Clients that have not refreshed their tool list get a tool-not-found error when they call a removed tool.
[1.27.2] - 2026-11-05
Fixed
- The native relay and the Antigravity sidecar now recover when an owner is killed between publishing its socket and removing the private name used to create it. That left the socket with a second hard link, which the safety check refused to remove, so every later start failed and
codex_bridge_statuskept reportingRELAY_UNREACHABLEwithECONNREFUSED, even after restarting Codex Desktop. Once a socket has refused a connection, a replacement removes only hard links of that same socket named like a private socket and owned by the same user. A socket with any other hard link is still refused, and a live owner that is confirmed by the probe is left alone. The removal is now bound to the socket that was probed, so an owner that replaces it during the probe keeps its socket. The native relay then retries, and the Antigravity sidecar start fails without touching that owner.
Verification and limits
- Reproduced on macOS: Codex Desktop killed a relay companion that exceeded its 30-second startup limit under heavy load, and the relay stayed down until the extra link was removed by hand. Regression tests kill a real process inside that window, and also cover a live owner and a foreign hard link.
- Private socket names left unlinked by earlier crashes stay in
~/.codex. They are harmless and are not removed, because a live companion may be using a name of that form. - A running supervised companion loads the new version once idle and then recovers on its own; a companion without a supervisor needs its host to reconnect. This reload was checked with a test harness, not on a machine stuck in this state with live Codex Desktop.
- In the native relay, a liveness probe that fails or times out under heavy load still counts as a dead owner. That existing limit is unchanged and now also covers an owner still inside the brief link step. The Antigravity sidecar treats a timeout as a live owner.
codex-native-relay-install --removestill stops withUnsafe relay socket fileon a socket in this state. Starting a companion recovers it, or the leftover private name can be removed by hand.- Upgrade with
npm install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge --foreground-scripts.
[1.27.1] - 2026-11-05
Fixed
inspect_bridge_projectno longer reportsneeds_setupor recommends installing a project policy when the bridge process already authorizes the directory by another supported mode.communicationAuthorizationnow reports the effectivemodeand result for the calling process (project-policy,allowed-roots,all-directories,pinned-roots,no-root-restriction), and a newprojectPolicyfield reports the policy file separately. Installing a policy appears asprojectPolicy.optionalMigrationfor an authorized directory unless policy mode is actually in force. A configured policy stays authoritative and still fails closed. Under thread policyowned,existingTasksand the detail state that existing tasks stay unreachable until they are allowlisted or the policy changes.bridge-projects inspectnow reportsnot_evaluated, because it reads only the policy file. Hardened deployments can now be inspected through MCP without being prepared or migrated, and inspection of a directory outside their pinned roots returns only the refusal.- Inspection now marks the same-project and new-task checks as
not_checkedand explains that a grant or allowed root does not replace them. A directory outside the allowed roots asks for an owner decision instead of a policy. codex_bridge_status({cwd})reportsauthorizationMode,existingTasksand, for a verified sender in the same project,readiness.target.savedProject(matched,absent,rejected,ambiguous,unresolved,not_checked) for creating a new Codex Desktop task. It checks the same resolved directory a delegation uses, so a mapped path can now report its resolved target. Outside hardened deployments this does not changeready, because sending to an existing task does not need a saved project. Inpinned-rootsmode every native operation needs one, so an unusable result makesreadyfalse withNATIVE_SCOPE_UNVERIFIED. A refusal for a directory outside the allowed roots no longer points at the project policy.- A failed saved-project match now separates an absent project from one rejected for its kind, host or missing ID, and counts saved projects that could not be compared, with code
DESKTOP_PROJECT_UNMATCHED. The message does not name other saved projects.
Verification and limits
- Reproduced on v1.27.0 with
CODEX_BRIDGE_THREAD_POLICY=rootsand no policy: inspection saidneeds_setupwhilecodex_bridge_statussaidauthorized=truefor the same directory. - Delivery enforcement is unchanged: authorization, same-project, receipt and project-match decisions make the same choices as before. Only diagnostics, one error code and the message text change. Without a policy, the Codex-to-Claude bridge has no directory allowlist and now says so.
- The cause of the reported
No saved local Codex Desktop projectrefusal is still unknown. The new status and message should narrow it down on the next occurrence; this release does not change which projects match. - Upgrade with
npm install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge --foreground-scripts, then reconnect the MCP clients so they load the new version.
[1.27.0] - 2026-11-05
Added
- A versioned local Antigravity human-dashboard channel with exact conversation/workspace validation, fixed human sender identity, durable idempotent request receipts and explicit preflight/uncertain delivery outcomes. It requires the app-launched sidecar and never treats native acceptance as a completed reply.
Verification and limits
- Unit tests cover preflight, idempotent receipts and refusal paths on Windows, macOS and Linux with Node 22 and 24. Delivery through a live Antigravity sidecar was not exercised before this release.
- Upgrade with
npm install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge --foreground-scripts, then restart Antigravity so its sidecar loads the new channel.
[1.26.10] - 2026-11-03
Fixed
- Recover Claude replies whose native ancestry passes through a verified Monitor notification. Preserve outstanding background work and reject unrelated or malformed notifications. Pending-delivery diagnostics now retain the original message ID and direct callers to its receipt without suggesting a duplicate send.
- Observe Antigravity Desktop replies through a bounded, read-only native transcript adapter. New deliveries retain a pre-send boundary and prompt hash; completion requires the exact original message, execution, public final response and idle conversation. Unsupported schemas, interleaved messages and ambiguous matches remain unconfirmed. Reply reads retain sender, account and project isolation.
- Migrate pending Claude transcript observations during future worker updates only after a unique native message proves acceptance. Held and unobserved deliveries keep their locks and defer reload, preserving their original reply channel.
- Resolve Codex CLI candidates from the worker's actual environment, skip incomplete version directories and retry read-only inspection once if an unpinned executable disappears during an app update. Explicit executable selections, authentication failures and real jobs are never retried or silently redirected.
- Report background relay readiness separately from unverified Desktop connections after updating. A ready background worker does not establish a live native Desktop relay.
- Reject malformed transcript session identifiers before composing filesystem paths, and validate executable candidates before inspecting their file type. Configured external executable locations remain supported.
Verification and limits
- Regression coverage includes Monitor ancestry, pending receipt ownership, reload safety, exact native reply correlation, account changes and CLI replacement races. Historical native transcripts confirmed both reply-observation failures without resending their prompts.
- An already-running older worker can still defer its own upgrade while a receipt is pending. Preserve that receipt and any verified historical result before reconnecting its MCP client; a missing receipt after reconnecting is not evidence of non-delivery. Legacy Antigravity receipts without the original account binding cannot disclose recovered reply text.
- A Desktop relay exiting on another machine still requires that machine's MCP host log and shutdown reason. This release does not infer an idle-chat cause or replace Desktop delivery with a CLI worker.
Upgrade
npx.cmd -y @minhspark/codex-mcp-bridge@latest
For noninteractive Windows updates, use codex-bridge-update --user. Reconnect affected existing MCP clients after active work finishes, then check their status tools. The global installation path remains available with npm install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge --foreground-scripts.
[1.26.9] - 2026-11-03
Fixed
- Shorten the "Applying managed settings" step of
npx @minhspark/codex-mcp-bridge@latest. Each Codexmcpcommand takes several seconds to start on a machine with many MCP servers and plugins, and one update ran about sixteen of them. The Codex installers now read their own entry with onecodex mcp getinstead of listing every server first, the verification reads all three registrations from a singlecodex mcp list, and the updater no longer runs a second, separate verification process after setup has already verified the saved settings. - Show which component the updater is configuring while managed settings are applied, instead of a single line that looked frozen for a minute or more.
- Stop reporting
MCP registration is missingforclaude-bridge,codex-native-relayandantigravity-bridgewhen Codex CLI was merely too slow to answer. A slow inventory now says so, and the three registrations are reported as not checked. Codexmcpcommands used by setup may take up to 120 seconds instead of 30, so a busy computer no longer fails an otherwise complete update.
Verification
- Regression coverage checks that verification makes exactly one Codex inventory call, that only Codex's own "No MCP server named" error counts as an absent entry, that a timed-out inventory is reported as unchecked, and that the updater runs setup once and relays only its progress lines.
Upgrade
npx.cmd -y @minhspark/codex-mcp-bridge@latest
This command runs the 1.26.9 updater itself, so the shorter sequence applies to this update.
[1.26.8] - 2026-11-03
Fixed
- Discover Claude Desktop's migrated Windows MSIX data under
%LOCALAPPDATA%\Claude-Data\claude_*. Ignore old roots containing only migration markers, including an alias to a discovered retired root, without deleting data or guessing between active profiles. Explicit data-root overrides remain authoritative. - Retarget verified older bridge source registrations during managed setup, including renamed checkouts, while preserving custom environment values, project restrictions and disabled settings. Changed configuration files receive unique backups, including repeated Desktop migrations on the same day. Custom launchers, extra arguments, unrelated packages and unavailable old source remain protected and receive specific recovery guidance.
- Restore a missing Antigravity sidecar definition when only its ordinary enable/disable registration remains. Preserve a deliberately disabled sidecar and refuse custom orphan settings.
- Include the failed setup components and safe recovery guidance in updater errors instead of reporting only
EXIT_1. Detailed local setup failures remain available throughcodex-bridge-setup --check --json; raw child output and private configuration are excluded from the updater summary.
Verification
- Regression coverage includes migrated MSIX roots, retired aliases, multiple profiles, verified legacy entrypoints, exact configuration backups, concurrent configuration changes, disabled sidecars and bounded error summaries. Native delivery on the reporter's Windows 11 / Claude Desktop 4.4212 environment has not been exercised.
Upgrade
npx.cmd -y @minhspark/codex-mcp-bridge@latest
After active work finishes, reconnect the affected MCP clients or restart their host apps so existing direct processes load the updated registrations.
[1.26.7] - 2026-11-03
Fixed
- Isolate setup test filesystem targets beneath their temporary fixture directory and independently verify configuration discovery. This removes the data flow reported by 12 CodeQL path-injection alerts in the setup tests.
- Isolate the postinstall failure test from installed Claude executables so authentication probes cannot create unrelated configuration files in its temporary home.
Verification
- Setup tests and the complete Node 22/24 CI matrix pass on Windows, macOS and Linux. CodeQL reports no findings on the fix pull request. This release changes test isolation and version metadata only; application runtime behavior is unchanged.
[1.26.6] - 2026-11-02
Added
- One short command for a complete terminal install or update:
npx.cmd -y @minhspark/codex-mcp-bridge@lateston Windows, ornpx -y @minhspark/codex-mcp-bridge@lateston macOS/Linux. A bare npm-exec launch with interactive input and output runs the full updater; Windows selects the per-user npm prefix automatically. Package installation, managed setup and live relay verification remain part of the same command. - An explicit
codex-mcp-bridge updatesubcommand for installed-package automation. Existing piped MCP launches, direct MCP invocation, setup, telemetry and version commands retain their routing.
Documentation
- Reduce the README from 817 to 133 lines, keeping installation, prerequisites, verification, everyday use and documentation links.
[1.26.5] - 2026-11-02
Fixed
- Add
codex-bridge-update --userto pin installation to the per-user npm prefix before inspecting or replacing packages. The recommended Windows command now avoidsEPERMwhen Node resolves its global prefix toProgram Files, including machines with several Node installations. Existing owned relay runtimes, project grants and disabled-service choices are preserved when moving between prefixes. - Install the global package with npm lifecycle scripts disabled, then apply managed setup directly using Node and verify settings and live relay readiness. This removes the lifecycle shell and npm script-approval dependency, and preserves the installed package if setup needs repair.
- Report installation permission failures, numeric child exit codes, signals and timeouts explicitly while keeping raw child output and credentials out of diagnostics.
Upgrade
Windows PowerShell, without administrator rights:
npx.cmd --yes --ignore-scripts --package=@minhspark/codex-mcp-bridge@latest -- codex-bridge-update --user
This single command updates the package, applies all managed client settings and verifies the independent background relay. On macOS/Linux, keep using the installation command in the README; optional --user selects ~/.local.
[1.26.4] - 2026-11-01
Fixed
codex-bridge-updateno longer stops withUPDATE_SETUP_INCOMPLETE/WORKER_MCP_COLLISIONon machines with more than one Node.js installation. The Antigravityworker-relayentry is still recognised as the bridge's own when it launches this package'sbackground-relay-mcp.mjsthrough another existingnode/node.exe, matching how every other bridge MCP entry is checked. Entries that use a different script, a non-Node launcher, a missing executable, a URL, headers or embedded environment are still refused and left unchanged.
Upgrade
npm exec --yes --ignore-scripts --package=@minhspark/codex-mcp-bridge@latest -- codex-bridge-update
[1.26.3] - 2026-11-01
Fixed
antigravity_bridge_statusandagent_bridge_statusnow return their full status (version, caller, Desktop sidecar availability, CLI and outbound routes) as structured content. Previously the supervisor attached only itsautoReloadblock as structured content, so clients that render structured content showed the reload state and hid whether the Antigravity sidecar was reachable.- The supervisor no longer creates structured content for a status result that has none; it adds
autoReloadonly to an existing structured object and always appends the reload summary to the text content.
Upgrade
npm exec --yes --ignore-scripts --package=@minhspark/codex-mcp-bridge@latest -- codex-bridge-update
Reconnect the antigravity-bridge MCP server in each open client after updating; the running supervisor keeps its old code until it restarts.
[1.26.2] - 2026-11-01
Upgrade
Install or update the global package and all managed client and background-service settings with one command, including upgrades from 1.26.0 or 1.26.1:
npm exec --yes --ignore-scripts --package=@minhspark/codex-mcp-bridge@latest -- codex-bridge-update
Use npm.cmd in Windows PowerShell. npm downloads the latest updater without running setup in its cache; the updater installs that exact resolved version globally with managed setup enabled and verifies the global installation. No second installation command is required.
Added
- Automatic
codex-bridge-updateorchestration for package replacement, all managed client settings and background-service configuration. Before replacing a Windows installation held by an owned legacy relay, it moves only that service to newer code using private relay storage as its working directory, waits for work to drain and verifies replacement readiness. The temporary runtime points to the downloaded updater package. It reports a pending migration instead of killing processes or interrupting jobs. - Preserve disabled services, provider authentication, custom project grants and permission denials throughout the update. Setup does not open apps or chats, and a deliberately disabled service is not reported as ready.
Fixed
- New background service and daemon launches use private relay storage as their working directory instead of the npm installation directory, preventing those processes from locking the package on Windows. The updater migrates owned legacy instances before package replacement. Worker jobs continue using their explicitly authorized project directories.
[1.26.1] - 2026-11-01
Upgrade
Update the package and reapply all managed client and background-service settings with the same command:
npm install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge --foreground-scripts
Use npm.cmd in Windows PowerShell. Setup does not open apps or chats.
Fixed
- Read-only background-service checks validate the installed runtime environment. A normal terminal no longer reports a healthy service as unconfigured merely because npm added temporary entries to
PATHduring installation. Package, startup ownership and running-runtime identity checks remain in place.
[1.26.0] - 2026-11-01
Upgrade
The same single command updates the package, reapplies managed client settings and configures the independent background service:
npm install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge --foreground-scripts
Use npm.cmd in Windows PowerShell. Setup applies the managed client registrations, background startup and scoped worker communication settings, including Antigravity's four relay tool grants. CLI authentication and explicit project grants remain separate from installing configuration; no Desktop credentials are copied and no existing denials are removed. Setup supplies a missing Codex CLI; Claude Code and agy must be installed separately when those workers are needed.
Added
- An independent per-user relay and separate Codex, Claude and Antigravity CLI workers, supporting all six worker-to-worker directions. Background jobs and cross-worker messages can continue without a responsive Desktop host. Native conversations retain their existing native routing and are never silently replaced by worker sessions.
- Durable job receipts, authenticated local transport, same-project delegation, bounded queues and delegation depth, and persistent diagnostic reports. Interrupted sends stay unknown; only proven queued work resumes after daemon restart.
- Background worker status, discovery, send and receipt tools plus the
worker-relaycommand. Service readiness, CLI authentication and model execution evidence are reported separately. - Managed background startup and recovery on Windows, macOS and Linux, with hidden Windows launches and idle adoption of updated service code. Setup preserves disabled services and reports pending activation honestly.
Fixed
- Antigravity MCP registrations use managed supervisors so future package updates can replace idle workers without reconnecting the host. Live CLI sessions and unconfirmed deliveries defer reload; crashed operations are never replayed.
- Worker CLI launches isolate their session identity from native Desktop chats. Claude worker launches suppress optional user/plugin startup hooks without changing authentication or permission policy.
- Antigravity worker discovery accepts the CLI's native MCP dispatcher when initialization does not enumerate individual server tools. Dispatcher availability is reported separately from verified relay-tool discovery; missing relay tools and permission failures still produce typed diagnostics.
Validation and limits
- Live Windows checks completed all six directions between Codex, Claude and Antigravity workers with Antigravity CLI 1.4.12. A saturated delegation returned
WORKER_DELEGATION_CAPACITYwithnot_sentinstead of queuing behind waiting workers. - Closed or frozen Desktop apps do not host these workers. A frozen UI cannot accept new user input or display results until it responds; a terminal's
worker-relaycommand or another responsive MCP client can submit authorized background work and read receipts. - Execution still requires a running operating system and per-user service, installed and authenticated provider CLIs, an authorized project, network/provider availability, quota and effective tool permissions. Saved configuration is not a guarantee of readiness or a live verification result on another machine.
[1.25.3] - 2026-11-01
Upgrade
One command updates the package and reapplies managed settings for all clients:
npm install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge --foreground-scripts
On Windows PowerShell use npm.cmd in place of npm. Setup reports saved configuration separately from live host readiness and never opens apps or chats to load a relay.
Fixed
- Normal Codex task creation and delivery no longer navigate or activate the Desktop window by default, including on Windows. Explicit
openInApp: trueremains available. Comprehensive install/update migrates historical automatic navigation settings to the silent default. - The native relay refuses navigation to its internal executor, which has no user conversation history and must not be opened as a task.
- Claude endpoint rediscovery from Codex and Antigravity no longer opens apps or saved chats to load a relay. A dormant native task reports
CLAUDE_SESSION_NOT_READYwithsent: false; an endpoint that becomes available is revalidated against the current account, process, directory and native permission policy. - Antigravity inbound MCP instructions now describe the existing outbound
agent-bridgeinstead of incorrectly claiming that Antigravity cannot send to Codex or Claude. Status reports distinguish supported Desktop routes from unverified outbound readiness and retain the CLI and automatic-reply-forwarding limits. - An unreachable Antigravity sidecar now reports a connectivity problem without assuming the App is closed, and points callers to the sidecar diagnostics when the App is already running.
- Relay and tool failures include a readable diagnostic block and structured report with the exact error/cause codes, operation, phase, bridge/Node/platform versions, UTC time, report ID and safe request identifiers. Credential and private-path redaction applies to the report block. Uncertain sends remain uncertain and are never automatically replayed.
- Antigravity IPC and durable delivery records preserve original failure codes and reports; failed or unknown receipt reads are surfaced as errors instead of successful-looking results. Supervisor crashes distinguish in-flight unknown delivery from a new request refused before dispatch.
- The same one-command npm install/update applies managed settings for all clients, shows setup progress, and fails if configuration is incomplete. It enables supported native background preferences without changing accounts or permissions and distinguishes saved configuration from unverified running-client activation.
Limitations
- Background delivery still requires the native host process and its loaded bridge. Closing a window can retain these processes; fully quitting a native host cannot provide an always-ready endpoint. An unloaded Codex MCP or dormant Claude Code process has no supported silent cold-start path in this bridge. Recovery never opens old, new, empty or failed chats, uses Computer Use, or launches a substitute CLI/app-server.
[1.25.2] - 2026-10-31
Fixed
- Relay recovery no longer opens a task or activates a Desktop window, including request-triggered recovery. The old keeper flag cannot restore navigation. Windows background task navigation now fails explicitly instead of silently stealing focus.
- The Desktop-owned supervisor restarts crashed native relay workers with bounded exponential backoff and validates their protocol and tool catalog before activation. In-flight operations fail without replay; client disconnect still shuts down the supervisor and its workers.
- Stale inherited native pipe hints can recover through verified Desktop ancestry. Explicitly configured endpoints stay pinned, and uncertain native sends are never replayed.
- Recovery waits and subsequent retries share the original request deadline. Native relay status checks a read-only operation through the serving shared relay instead of treating socket availability as proof of working dispatch.
Limitations
- Reconnect the relay MCP once after upgrading to load the new supervisor. Worker hot reload alone cannot replace its running parent. Automatic recovery requires that Desktop-owned supervisor to remain alive; it cannot cold-start MCP in an idle application with no loaded session.
[1.25.1] - 2026-10-31
Fixed
- On Windows, Codex Desktop no longer jumps to the front and switches to another task on its own. The background relay keeper opened
codex://threads/<id>whenever the native relay was missing, and Windows always activates the app for that link, so the window was pulled forward about once a minute while the relay stayed down. The keeper is now off by default on Windows; setCODEX_BRIDGE_RELAY_KEEPER=1to turn it back on. macOS is unchanged because it opens the link in the background.
Verification and limitations
- Focused regressions cover the Windows default, the explicit opt-in and the wake opt-out taking precedence.
- A request that needs the relay while it is missing still opens a Codex task on Windows, which brings the app to the front once for that request.
[1.25.0] - 2026-10-30
Added
- Global npm installation now configures Claude Desktop, Claude Code, Codex and Antigravity in one command. On npm versions that require lifecycle-script authorization, use
npm install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge. - Setup creates the distinct shared Claude Desktop
codex-bridge-desktopconnector and user-level Claude Codecodex-bridge, registers the native Codex relay and its executor, and installs Antigravity's inbound, outbound and sidecar entries. An absent Codex CLI is installed from the official package into a separate per-user tools directory. codex-bridge-setupandcodex-mcp-bridge setupsupport read-only--check,--dry-run, JSON reports and--no-download. Local dependency installation does not change application configuration; global setup can be skipped withCODEX_BRIDGE_SKIP_SETUP=1.- README troubleshooting now includes detailed recovery procedures and a versioned catalog of historical installation, routing, identity and reply-observation fixes.
Fixed
- Initial Claude Code registration no longer requires hand-written JSON or an existing supervised entry. Setup preserves custom settings and scope, retargets recognized bridge paths, separates a shadowing shared connector, and reports conflicting entries instead of replacing them. Antigravity setup respects a custom Claude configuration directory and an explicitly disabled sidecar.
- Setup detects Microsoft Store Claude data directories and explicit data-root overrides, refusing ambiguous installations. Antigravity registrations from recognized older package paths are also retargeted during setup.
- Migrating a shared native entry into Claude Code retains its restrictions and implicit owned-thread policy. Missing saved Codex executable paths are refreshed, valid custom binaries remain selected, and incompatible shared native routing is reported instead of falsely verified.
- Simultaneous Claude sender-ancestry checks now share one pending Windows inspector. Completed results and failures are discarded; subsequent operations still verify current OS identity, task and account.
- A delivered Codex request with no matching reply marker no longer waits indefinitely when a new native turn remains finished and idle. After a bounded grace period and a fresh state check, the receipt reports
observation_unavailableand directs the caller to inspect the existing task without resending or attributing unrelated output. - Tool instructions for already-open Claude sessions now require native session discovery and peer delivery. The misleading instruction to inspect a title in the app was removed, and external Computer Use typing/clicking is explicitly excluded as a delivery fallback.
Verification and limitations
- Windows packed-package installation and configuration readback cover all registered clients. Focused regressions cover initial installation, existing settings, collisions, disabled components, lifecycle opt-outs, native CLI resolution, concurrent sender inspection, reply observation and MCP routing instructions.
- Configuration verification does not prove that running applications have reloaded their MCP servers. Applications still need to be installed and signed in; native Desktop handoffs require the same saved project and retain host permissions. Shared Claude Desktop chat uses the legacy local app-server route.
- Setup prewarms runtime snapshots, but the reported 30-second connection timeout was not reproduced and is not claimed resolved. Missing reply correlation still requires inspection of the original task. Updated tool instructions guide model behavior and cannot guarantee every model follows them.
[1.24.1] - 2026-10-29
Fixed
- Native Codex turns whose
root_turn_idnames a different causal root are no longer rejected as contradictory. Membership comes from explicit turn IDs, contradictory explicit IDs are still rejected, and a turn is never selected only because its causal root matches the requested turn (#169, #171 by @deinspanjer). - An accepted Desktop send whose response cannot be verified now reports
status: observation_unavailablewithnextAction: inspect_existing_taskand the original receipt, instead offailed. Desktop's ownfailedorinterruptedstatus is still reported when it belongs to the exact observed turn.wait_codex_replywithresponsePreferencesreturns the same next action plusguidancetelling the caller not to resend the prompt. - When a Claude reply observation is interrupted by a new input boundary after an asynchronous or timed-out
send_to_claude_session, the bridge now publishes a correlated bridge-status notification toread_claude_inboxand to the originating Codex task. It is labelled as a bridge notification rather than a Claude reply, keeps the original account and project scope, reports outcome unknown, task not cancelled and retry unsafe, and survives reload without duplication. Asynchronous send guidance now points toread_claude_delivery(#170, #172 by @deinspanjer).
Upgrade
npm install -g @minhspark/codex-mcp-bridge@latest, then restart Claude Desktop and Codex Desktop (or reconnect their MCP servers) so running bridges load 1.24.1.
[1.24.0] - 2026-10-28
Added
- Optional Antigravity MCP bridge for verified Codex and Claude Desktop callers. Select an exact existing Antigravity App conversation or explicitly create a bridge-owned CLI streaming session in the same project directory.
- Native App sidecar transport with current-user socket access, native workspace/project checks, busy-recipient protection, and durable request receipts. CLI streaming validates native conversation identity and preserves permission review; results and uncertain outcomes are recorded without automatic resends.
antigravity-mcp-bridge-installconfigures Codex, Claude, and the App sidecar independently or together, previews changes with--dry-run, preserves unrelated configuration, and removes only its own registrations.- Antigravity Desktop's
agent-bridgeMCP can discover, read, and send to existing Codex Desktop tasks and live Claude Desktop Code sessions in the same project. Native per-call sender metadata, process ancestry, project configuration, and permission checks preserve Antigravity authorship and recipient policy. - Sidecars track their native parent process identity and exit when that parent stops, preventing a restarted App from retaining an orphan's stale connection. Desktop callers without workspace metadata resolve their directory through exact native conversation and project evidence.
Compatibility
- Node.js 22.13 or newer is required for read-only native conversation discovery. The App adapter filters mirrored CLI records rather than trusting the database directory alone.
- App receipts report native acceptance; App response forwarding and creation are not implemented. CLI support uses bridge-owned headless sessions, not attachment to existing interactive terminals. Antigravity outbound is Desktop-only; nested callers and Linux host verification are unsupported. Claude socket writes remain unconfirmed until a native receipt or reply is observed.
Verification
- Automated coverage includes real MCP transports, caller identity, project scope, current-user pipe access, duplicate requests, native metadata, recipient permission checks, durable receipt states, stream protocol failures, installer preservation, and file replacement during reads.
- Live Windows verification covered CLI streaming under native
request-reviewpermissions and both directions between Codex and Antigravity Desktop. The App repliedANTIGRAVITY_DESKTOP_NATIVE_OK; its outbound MCP deliveredANTIGRAVITY_TO_CODEX_DESKTOP_OKto the exact originating Codex task. Claude outbound routing has automated coverage; a live Claude receiver was unavailable during verification.
[1.23.0] - 2026-10-26
Added
remote_codexlists, reads and messages existing Codex Desktop tasks on an explicitly configured SSH host. Calling-turn verification, exact project and repository checks, current account binding and signed durable receipts prevent wrong-project delivery and duplicate sends after uncertain transport outcomes. The two computers may use different Codex accounts; signing in again is discovered on the next call.
Tests
- Remote handoff regressions cover different accounts, mid-request identity changes, target and repository mismatches, missing sender metadata, SSH argument isolation, size and deadline limits, concurrent retries and receipt recovery after restart. Task membership is verified through native listings because native task reads can omit the project ID.
Upgrade
- Update both computers with
npm install -g @minhspark/codex-mcp-bridge@latest. If an existing Codex task keeps its old tool catalog, reconnect its MCP server or start a fresh task to loadremote_codex.
[1.22.21] - 2026-10-26
Fixed
- Recognize native Claude background-task completion notifications stored as inline attachments. A completed command could otherwise remain outstanding, hiding the final reply and blocking later messages with
PEER_REPLY_PENDING. Both notification formats retain native-origin, exact task/tool-call identity and transcript ancestry checks; observing the original reply never resends its action. - Resolve Claude reply ancestry when a final response is persisted before its parent attachment. Process unambiguous records with ancestors first, reject cycles, and preserve input boundaries and pending ownership until the required parent arrives.
Verification
- Three focused regressions fail against 1.22.20 and pass with this fix: inline completion, child-before-parent ancestry, and pending ownership recovery without repeating the original action.
- Independent parser checks cover 1,320 record-order and invalid-notification combinations. Endpoint tests verify that missing parents keep ownership pending and that a distinct follow-up is allowed only after the original reply resolves.
Limitations
- Missing or ambiguous transcript ancestry still cannot establish a reply. Inspect the existing task instead of resending its original action. An already blocked older runtime may need a client restart after upgrading to load this fix.
[1.22.20] - 2026-10-24
Fixed
- A Claude Desktop target no longer stays blocked for good when another sender's peer message lands in a reply chain that is waiting on a background task. Reply observation used to drop that message and everything after it, so the delivery never resolved, every later send to that session failed with
PEER_REPLY_PENDING, and reload stayed refused until Codex Desktop restarted. A peer message for a different message id now ends observation the same way human input does: the delivery is reported as interrupted, the task outcome stays unknown, and it is not marked safe to retry. - Peer interruption requires a nonblank string message id distinct from the tracked request. Missing, blank, non-string and matching ids cannot release pending ownership. Existing transcript ancestry, ambiguity and open-branch checks remain in force.
Tests
- Transcript regressions cover a background wait interrupted by another peer, malformed peer ids, unrelated ancestry, incomplete or duplicate records, and unresolved sibling branches.
- Endpoint regressions verify late interruption after a timeout, pending-send and reload recovery, retained interruption receipts across reload, and a separately requested follow-up without resending the original action.
Limitations
- Interruption ends reply observation only. Background work may still be running; inspect the existing task before issuing a follow-up. The original action is never marked safe to retry.
[1.22.19] - 2026-10-22
Fixed
- Relay cleanup validates the canonical parent, expected file type, ownership, link count and identity before removing a configuration file or Unix socket. A regular file selected through a socket path is preserved, and symlinks and hardlinks are rejected.
- Unix relay sockets are created with mode
0600before accepting connections. Startup verifies the socket identity and permissions without changing permissions through an environment-derived path, and restores the process umask after binding. - Supervisor timer intervals use explicit lower and upper bounds, including Node's timer overflow limit, so CodeQL can verify the resource limits.
Tests
- Regression tests cover ordinary files, hardlinks, symlinks, custom Unix sockets, private socket creation, umask restoration, replaced socket identities and timer boundaries.
[1.22.18] - 2026-10-22
Fixed
wait_codex_replywith a shorttimeoutSecno longer fails withThe response deadline elapsed while another operation held this threadwhen no other operation held the thread. The tool's deadline starts before the caller's identity check, and that check spawns PowerShell on Windows. When it used up the whole budget, the observation never started and the bridge reported a held thread instead of a timeout. It now returns the normal timeout result withnextAction: wait_codex_reply. The held-thread message is now used only when another operation actually holds the thread; otherwise the error says the deadline elapsed before the operation started.
Tests
- The account-change wait test no longer depends on timing. Its relay fixture parks
wait_threadson a gate that the test releases, instead of a fixed 2.5 s sleep against a 1 s budget. That timing failed on a stalledwindows-latestrunner. - The relay fixture in
test/bridge-integration.test.mjsprovisions its creation receipts once per file, so Windows tests no longer spend four PowerShell cold starts inside their own timing. - The Desktop task integration assertions now print the tool result when they fail.
Verification
- New unit tests cover a deadline that elapses before an unheld operation starts, and one that elapses while another operation holds the thread. The first fails on 1.22.17.
- Simulating a 1.2 s caller check reproduced the CI failure text exactly on 1.22.17. The rewritten test passes with 1.2 s and 3 s simulated delays.
- Full suite on macOS: 1558 pass, 0 fail, 23 skipped.
[1.22.17] - 2026-10-22
Fixed
npm install -g @minhspark/codex-mcp-bridgerun from Claude Code's Bash tool no longer warns that the installed version could not be verified. Claude Code shell snapshots keep thenpm()function fromscripts/npm-footer.shbut drop functions whose names start with_, so the separate_codex_bridge_installed_versionhelper vanished and every install printedWarning: npm completed, but the installed @minhspark/codex-mcp-bridge version could not be verified.even though it succeeded. The version reader now lives insidenpm()and the script defines no other function.- The 1.22.14 changelog entry no longer reads "The wake It needs".
Verification
- New test
reports an upgrade when only the npm function survives a shell snapshotloads onlytypeset -f npmin bash and zsh, the way a snapshot does. CI passed on Ubuntu, macOS and Windows with Node 22 and 24 (#151).
[1.22.16] - 2026-10-22
Fixed
- Start the Codex Desktop native relay on its own after Codex Desktop opens, instead of only when a send fails. In 1.22.14 the relay woke only inside a failing Desktop request, so
codex_bridge_status(which has no calling task) could never wake it, and a wake that took longer than its 20-second window left the request failed with the relay-down guidance. Each bridge process now checks the relay socket every 30 seconds. When the relay is missing and Codex Desktop is running, it opens a recent Codex Desktop task in the background and waits up to 60 seconds for the relay. Codex Desktop is checked at most once a minute while it is closed. - Coordinate wakes across bridge processes. Every Claude Code session runs its own bridge, so several of them could open tasks at the same moment. Wakes now share a state file (
~/.codex/bridge-relay-wake.json) and a lock beside it. Only one process opens a task at a time; an on-demand request that finds the lock held waits for the relay instead of opening another task. Failed background wakes, including those that find no Codex Desktop task to open, back off from one minute up to 30 minutes and reset after a success. A stale lock is reclaimed. - Fall back to the most recent Codex Desktop task of any project when neither the destination task nor a task of the sender's project is available, so a status call or a session in a new project can still wake the relay. The internal Native Relay executor task is still never opened.
CODEX_BRIDGE_RELAY_KEEPER=0turns off the background check;CODEX_BRIDGE_RELAY_WAKE=0still turns off every wake.- A request that arrives while a background wake is in progress waits only until its own deadline instead of the background wake's 60 seconds.
codex-sites-connectorrunswhoami.exeandicacls.exefrom%SystemRoot%\System32instead of looking them up onPATH. Started from Git Bash, it ran GNUwhoami, could not read the Windows user SID and refused to protect its files.npm testruns the suite without the caller'sCLAUDE*,CODEX_*,ANTHROPIC_*andMCP_*variables. Inside a Claude Code session they pointed tests at the live Claude Desktop data, messaging socket and bridge configuration, so tests that pass in CI failed locally.
Limitations
- Opening a task through
codex://threads/<id>makes Codex Desktop show that task. The keeper opens only while the relay is missing and picks the most recent task, which is usually the one already on screen. - The keeper runs only while a Claude client keeps a bridge process alive. With no Claude session open, the relay still starts when a task is opened in Codex Desktop.
[1.22.15] - 2026-10-22
Fixed
- Confirm Claude peer replies after native compaction includes transient, nonpersisted message IDs. The receipt reader now validates the ordered projection onto persisted records instead of requiring both metadata lists to be identical. Account, project, process identity, ancestry, interruption and pending background-work checks remain unchanged; transient IDs never establish reply ancestry.
[1.22.14] - 2026-10-21
Fixed
- Start the Codex Desktop native relay when it is missing instead of failing every Claude-to-Codex call. Codex Desktop runs
codex-native-relayonly while a task has its MCP servers loaded: at launch it starts them for about a second to build its tool catalog and then cancels them, so after a Desktop restartcodex_bridge_status,list_codex_threads,send_to_codex_threadanddelegate_to_codexfailed withconnect ENOENT .../native-relay.sock-accounts-v2until a task was opened. When a Desktop request cannot reach the relay before anything was written and Codex Desktop is running on macOS or Windows, the bridge now opens the destination task, or the most recent Codex Desktop task of the sender's project, in the background throughcodex://threads/<id>, waits up to 20 seconds for the relay socket and retries once. A failed wake backs off for one minute.CODEX_BRIDGE_RELAY_WAKE=0turns this off. On Windows the bridge recognises Codex Desktop by the packagedOpenAI.Codex_*\app\ChatGPT.exe, and the project fallback also accepts a task of the same git repository, so a Claude Code session in a linked worktree can wake the relay through the main checkout's task. - Open Codex Desktop tasks on Windows without reporting a false failure.
explorer.exe codex://threads/<id>opens the task but always exits with code 1, soopen_codex_threadand theopenoption of the send tools reported an error after a successful open, and the relay wake gave up although Codex had loaded the task. Links now go through PowerShellStart-Process, which returns 0 on success and fails when nocodex://handler is registered. The URL is passed base64-encoded, never interpolated into the command. - Report the relay-down cause accurately. The guidance now says that the relay runs only while a task has its MCP servers loaded, points to a regular project task rather than the internal Native Relay executor task (which reports a missing rollout when opened, by design), and appears only when the relay was actually unreachable. The Desktop failure text no longer doubles its final period.
- Read compressed Codex rollouts. Codex compresses rollouts that have been idle for about a week to
rollout-*.jsonl.zst(244 of 269 files on the test Mac). The bridge matched only.jsonl, so a send to such a task delivered the message but returned an empty reply (No trusted pre-send rollout watermark is available), andread_codex_threadwith aturnIdfailed. Discovery now accepts both forms, decompresses with Node's zstd support (22.15+ or 23.8+; older runtimes get a clear error) under a separate 256 MiB limit, follows Codex rewriting the file as plain.jsonlwhen the task resumes, retries reads that race that rewrite, and caches unchanged compressed scans. The VS Code task bridge also lists compressed tasks. - Prune the runtime snapshot cache. Nothing removed snapshots from
~/.codex/bridge-runtimes(76 directories, 1.8 GB measured). Supervisors now lease their worker runtimes and prune one minute after start and after each activation: runtimes that are leased, referenced by a running process, among the three most recently used, or used in the last 24 hours are kept, at most eight are removed per hourly pass, and orphaned digest files, stale leases and abandoned temporaries are cleaned up. On macOS snapshots are APFS clones (/bin/cp -c), becauseCOPYFILE_FICLONEnever clones there. inspect_bridge_projectreports a missingCODEX_BRIDGE_PROJECT_POLICYaspolicy_not_configuredwith next steps instead of failing. Errors from read-only tools no longer carry the "No Desktop mutation was dispatched ... do not resend" boilerplate,wait_codex_replyandread_codex_threadkeep their no-resend guidance only while the turn can still change, and error sentences are punctuated.- The Claude Code registration check detects an unsupervised shared Claude Desktop bridge entry, including one renamed to
codex-bridge-desktop, andinstall-claude-desktopupdates that entry instead of adding a second one. Neither claims or removes entries that run another program. - The relay companion and
claude-bridgedrain accepted work on SIGTERM, SIGINT and SIGHUP like they do when the MCP client closes; a second signal exits at once. A relay listener whose startup is refused or cancelled no longer leaves a dead public socket.install-native-relay --removealso removes the account and Desktop task sockets and names the retired executor task. - Adding a missing name to an existing
env_varsarray keeps its comments and layout.
Verification
- 1,489 tests before, 1,564 after, 0 failures (23 platform skips). New tests cover the relay wake (destination and project fallback, executor exclusion, back-off, coalescing, retry only before a write), compressed discovery, reads, rematerialization races and the descriptor-leak path, snapshot pruning and liveness re-checks, the read-only tool surface, and registration detection. Each behaviour test was confirmed to fail on the previous code.
- Measured on Codex Desktop 26.1016.6573.0 on Windows 11: after the relay processes were stopped, opening a regular task that was not loaded brought all three
\\.\pipe\LOCAL\codex-native-relay*pipes back and the wake returned in 4.8 seconds. Reopening the task whose MCP session was still loaded did not restart the relay within 20 seconds, which the wake reported and backed off from. - Measured on Codex Desktop 26.1013 (Codex Framework 155.0.8059.80) on macOS: a relay process outside the app-server's process tree is refused with
dynamic_app_tools_peer_rejected reason=untrusted-process-ancestry, so the relay cannot be kept alive outside a task's MCP session. Opening a regular task withopen -g codex://threads/<id>started a newcodex-native-relaysupervisor within about 10 seconds, after whichdelegate_to_codexcreated a task and returned Codex's reply (RELAY-OK 22:17) through the relay. - A read-only probe on a real compressed task returned an available watermark (57.9 MB decompressed in 185 ms) and an authoritative turn read, both
unavailablebefore the fix. - Three adversarial reviews ran over the changes; every confirmed finding is fixed with a test.
Limitations
- On macOS the wake opens the task without activating Codex Desktop. On Windows the
codex://handler brings the Codex Desktop window forward. - The wake helps only when the opened task does not already have its MCP servers loaded. If the relay process died while its task stayed loaded, reopening that task does not restart it; open another task or reconnect the task's MCP servers.
- The wake needs either the destination task or an earlier Codex Desktop task in the sender's project; otherwise the bridge reports the relay-down guidance.
- Codex can unload a task's MCP servers when the task is idle; the next request wakes the relay again.
[1.22.13] - 2026-10-20
Fixed
- Find the Codex Desktop native tools pipe on Desktop 26.1013. That build serves the native app tools on
\\.\pipe\codex-app-tools-<id>and no longer passesCODEX_APP_TOOLS_PIPE_PATHon the app-server command line. Windows discovery only looked atcodex-browser-use-*pipes, which answerNo handler registered for method: tools/call, so the relay companion never openedcodex-native-relay-accounts-v2and every Claude-to-Codex send failed withRELAY_UNAVAILABLE(connect ENOENT). Discovery now also acceptscodex-app-tools-*pipes. The existing checks still apply: the pipe must be local, owned by the exactChatGPT.exeancestor of the companion's app-server, and answer a read-onlylist_projectscall.codex-app-tools-*sorts first, so it is tried before the browser pipes.
Verification
- One new test covers a Desktop 26.1013 snapshot with both pipe kinds and checks that only the app-tools pipe is probed. It fails on v1.22.12. A pipe with another
codex-prefix, and an app-tools pipe owned by another process, are still rejected. - On a Windows machine running Codex Desktop 26.1013.4894.0,
resolveNativeToolsPipePathfrom v1.22.12 returnednulland the fixed code returned the livecodex-app-tools-*pipe, owned by the Desktop process that started the app-server.list_projectsthrough that pipe returned the saved projects; the fivecodex-browser-use-*pipes returnedNo handler registered for method: tools/call.
Limitations
- A running companion keeps its old discovery code until it reloads. After updating, restart Codex Desktop, or let automatic reload pick up the new source, then check
native_relay_status.
[1.22.12] - 2026-10-20
Fixed
- Move directly registered Codex entries to the supervisor.
claude-mcp-bridge-installandcodex-native-relay-installused to refuse an existingcodex-native-relayentry that hadenv_vars, the very setting the README told users to add, andcodex mcp adddropsenv_varsand every comment inconfig.toml. When the environment does not change, the installers now edit onlycommandandargsof the existing table in place, read the entry back throughcodex mcp get --json, and restore the previous file if anything differs. Seen on 2026-10-20: both Codex-side entries still pointed atsrc/claude-bridge.mjsandsrc/native-relay-companion.mjs, soclaude-bridgestayed1.22.8 STALEafter v1.22.10 until Codex Desktop restarted. - On Windows and macOS,
codex-native-relay-installaddsCODEX_APP_TOOLS_PIPE_PATHto the relay'senv_varsitself, by name only, instead of asking for a hand edit. - An entry written as an inline table or with dotted keys, which the in-place edit does not handle, still goes through
codex mcp addwhen that loses nothing; if the relay'senv_varscannot then be added, the installer says so instead of failing. Datetimes written with a space instead ofTno longer stop the scan. - Keep relay requests and peer messages that reach the listener while a reload quiesces. A client whose connection was still in the kernel's accept queue when the listener closed was reset: the relay client reported
RELAY_DELIVERY_UNCONFIRMEDfor a request the companion never read, and a Claude peer message was lost after a successful write. Quiesce now removes the socket path first, waits a few event-loop turns for queued connections, answers relay clients withRELAY_RELOADING(no message sent), and reads peer messages into the inbox that the next worker restores. A relay client answered withRELAY_RELOADINGduring reload also no longer keeps the old listener from closing. The relay now binds a private name and hard-links it to the public path, because closing a Unix socket server unlinks the path it was bound to; a companion that binds the public path while a reload drains keeps its socket.
Verification
-
18 new tests. The installer tests run both installers against a fake
codexand a live-shapedconfig.toml; 7 tests fail on v1.22.10. The race tests block the event loop while a client connects and writes, then quiesce; the relay and peer cases fail on v1.22.10 withwrite EPIPEand an empty inbox. A successor companion's socket survives the old listener closing; that test fails when the relay binds the public path directly. -
Both installers were also run against the real Codex CLI 0.163.0 with a temporary
CODEX_HOME, covering a CRLF file, a multi-lineargsarray with comments, a rerun and a fresh install. Onlycommand,argsand the addedenv_varschanged. -
An independent review of reload safety covered the relay, the peer endpoint and the supervisor. Two of five claims survived two refutation attempts each; both are fixed above. A second review of this change found three more defects that survived refutation: inline-table entries refused, space-separated datetimes refused, and the close-time unlink of a successor's socket. All three are fixed, each with a test.
-
CodeQL reported a file-system race in the first version of the config write: it checked the file, then wrote it by path. The installer now reads
config.tomlthrough one file descriptor, keeps its device, inode, mode and contents, and checks all four again through a new descriptor just before the atomic rename. The remainingjs/path-injectionreports on the config and relay socket paths come from operator configuration (CODEX_HOME,CODEX_NATIVE_RELAY_SOCKETor the home directory) and were dismissed as false positives, as in earlier releases.
Limitations
- Windows named pipes cannot be removed from the namespace before the listener closes, so a client that connects in the last moment before close can still be reset there. It is reported as unconfirmed, never as delivered.
- Moving an entry to the supervisor needs one Codex Desktop restart. The installer does not touch an entry whose environment must also change while it has custom
env_vars,cwd, tool filters or timeouts; it prints the exactcommandandargsto set by hand.
[1.22.11] - 2026-10-20
Fixed
- Stop
claude-bridgeand native relay companion workers from outliving their MCP client. The supervisor ends a worker's stdin and IPC channel and waits before killing it, but MCP clients such as the SDK stdio transport kill the supervisor about 4 seconds after closing it.index.mjsalready exited on stdin end; the other two workers did not, so they kept running with parent PID 1 and kept their relay and peer sockets. Eachnpm testrun left two such processes, and the same could happen in Codex Desktop or Claude Desktop whenever an MCP client closed. - Both workers now exit on their own when stdin ends or the supervisor channel disconnects. They first stop taking new work and wait up to 35 seconds for work already accepted: the companion refuses new relay connections with
RELAY_STOPPING(sent: false) and finishes accepted connections, active requests and pending Desktop dispatches;claude-bridgeunregisters its peer endpoint and finishes open peer connections, in-flight sends and queued reply forwards. A late activation from the supervisor cannot reopen the relay during this drain, and losing the supervisor's output pipes no longer crashes the worker mid-drain. The supervisor waits for that drain before forcing a stop when its client closes; retiring a quiesced worker after a reload keeps its 6-second limit.
Verification
- Every MCP supervisor test now records the supervisor and worker PIDs it sees and fails if any outlives its client, killing leftovers so a failure cannot accumulate processes. On v1.22.10, 4 tests fail: the real
claude-bridgeand companion upgrade tests leave their workers behind, and a new test that kills the supervisor finds both workers still running. - New tests cover the drain: an accepted relay delivery finishes before exit, a late connection is refused with
RELAY_STOPPING, a late activation is rejected, a worker whose parent is killed during a drain still exits 0 after its work finishes (it crashes on v1.22.10's output handling), and the peer endpoint stops accepting while keeping open connections. - Two full
npm testruns on macOS left no process from amcp-supervisor-test-directory; the run on v1.22.10 left two.
Limitations
- On Windows the supervisor's workers belong to its job object and end with it, so they never outlived their client there, and a drain cannot continue after the client kills the supervisor. The supervisor-kill test passes on Windows for that reason rather than through the drain.
[1.22.10] - 2026-10-20
Fixed
- Re-read the whole rollout set when Codex appends between per-segment reads. The pre-send watermark, dispatch, turn and creation readers and Codex sender verification now repeat find, read and set check together, up to three times, instead of failing with
A rollout segment changed while reading. Only read races qualify: identity, history, account, workspace and dispatch mismatches still fail at once. - Keep observing an accepted Desktop send or creation while Codex is still writing its rollout. When a read keeps reporting that the rollout changed while reading, the wait polls again until its deadline and then returns the pending receipt with that reason, instead of reporting the delivery as failed. Seen live on 2026-10-20: an accepted send reported
failedwhile the reply was later recovered from the same receipt. A rollout whose last record stays incomplete, for example after Codex stopped mid-write, is still reported at once with its turn status and reason.
Verification
- 8 new regression tests reproduce the append during the set check for the watermark, the turn and dispatch reply readers, sender verification and both wait paths; all fail on v1.22.8. Two more pin that a permanently incomplete rollout is reported without waiting, and a unit test pins which messages are retried.
- Two rounds of independent review shaped the wait behavior. A deferred released turn stays the observed turn even if a newer turn starts. The deferral reason is cleared after a clean read, and a timeout reports it as an unavailable observation. Only the set level retries, so an actively written rollout is scanned at most three times per observation. Deferral is limited to
changed while reading, becauseincomplete final recordcan be permanent. Each of these has a regression test that fails without its fix.
Limitations
- The original race was seen once in a live Desktop send and cannot be triggered on demand; the regression tests reproduce it deterministically by appending to the rollout during the set check. A Codex Desktop or MCP restart still ends in-memory peer receipts, as before.
[1.22.9] - 2026-10-20
Fixed
- Read the Claude Desktop configuration with exact bigint stats in
codex-mcp-bridge-install, so a configuration file replaced during the installer's read is detected even when the two inodes differ only beyond Number precision. v1.22.8 converted the runtime stores but missed this installer. - Notice a new reply in a Claude Code transcript when the file changes within the same millisecond and keeps its size. The reply poll now compares the file's device, inode, nanosecond modification and change times, and size instead of only the millisecond modification time and size.
Verification
- 2 new regression tests: a Desktop configuration whose inode changes only below Number precision (
2^60and2^60 + 1) is rejected and left untouched, and a transcript reply is observed while its NumbermtimeMsand size stay frozen. Both fail on v1.22.8. - Two independent sweeps of
src/,scripts/andbin/, one by stat API and one by stored or compared stat data, found no other Number-based identity or change detection. - CI passed on macOS, Ubuntu and Windows with Node 22 and 24. CodeQL re-reported 3
js/path-injectionflows on the edited stat lines; each source is operator environment configuration, matching earlier dismissals, and they were dismissed as false positives.
Limitations
- The 64-bit NTFS case runs for real only on Windows CI; local tests simulate it with mocked stats.
[1.22.8] - 2026-10-20
Fixed
- Compare file identities with exact 64-bit values everywhere. Reply and native creation receipts, the creation signing key, Codex rollout watermarks and segment checks, Codex account evidence, Claude Desktop task metadata and account state, project repository metadata, and the Sites connector's private files read
dev,ino,sizeand nanosecondmtime/ctimeas bigint. Number stats round inodes above 2^53, which NTFS file IDs and some macOS volumes (such as/tmpon the sealed system volume) exceed, so a replaced file or directory could pass as unchanged; this maderejects replacement of a pinned receipt directoryfail intermittently on Windows CI.
Security
- A rollout watermark now stores its file identity as exact decimal strings. A reply receipt written by an earlier version still matches only when its numeric identity is an exactly representable integer equal to the current file; a rounded identity no longer matches, and the observation reports the rollout as changed instead.
Verification
- 7 new regression tests. Two identities that differ only below Number precision (
2^60and2^60 + 1) compare as different for bothinoanddev; the reply and native creation receipt stores reject a pinned directory whose inode changes only below 2^53, and both store tests fail on v1.22.7. The rollout watermark keeps exact string identities through JSON and honors only exactly representable legacy numbers. - A review of the change found a test that now passed without reaching its byte comparison: its mock returned Number stats to code that requests bigint. It was fixed and checked by removing the comparison, which makes the test fail.
- CI passed on macOS, Ubuntu and Windows with Node 22 and 24, including
test (windows-latest, 22)where the flake appeared. CodeQL re-reported 12js/path-injectionflows on the edited stat lines; each source is operatorprocess.envconfiguration, matching the earlier dismissals, and they were dismissed as false positives.
Limitations
- The 64-bit NTFS case runs for real only on Windows CI; local tests simulate it with mocked bigint stats. A reply observation whose earlier receipt stored a rounded rollout identity reports the rollout as changed; inspect that task instead of resending.
[1.22.7] - 2026-10-20
Added
- Install with Homebrew:
brew install buidangminh23/tap/codex-mcp-bridge. The formula in buidangminh23/homebrew-tap follows each npm release.
Fixed
- Record Homebrew's stable
optpaths instead of a versioned Cellar keg when the Claude Desktop, Codex and native relay installers andbridge-projects register-managerwrite a client configuration, for both the bridge and Homebrew's Node.js. A keg path broke every registration as soon asbrew upgraderemoved the old keg. Paths outside a Homebrew keg are written exactly as before. - Start the supervisor when its path reaches the installation through a symbolic link, such as Homebrew's
optalias. The direct-execution check compared the unresolved command-line path with the resolved module path, so the process exited at once without serving MCP. - Follow a Homebrew upgrade in a running supervisor: it watches the
optalias, reloads the new keg like any other installed update, and forks workers with the stable Node.js path, instead of reporting "Installation is not ready" after the old keg is removed.
Verification
- 9 new regression tests: Cellar to
optmapping, a customHOMEBREW_PREFIX, the main-module check through a symlink and a respelled path, a running supervisor following a bridge keg switch, and one following a Node.js keg replacement. The supervisor tests fail on v1.22.6 and pass here. - End to end on macOS with a local tap: two packed versions installed with brew, the three installers run against an isolated home, and every recorded path was
opt/codex-mcp-bridgeandopt/node(the relay keeps Codex Desktop's Node). A bridge launched from the recorded Claude Desktop entry kept its supervisor throughbrew upgradeandbrew cleanupand reloaded the new keg; fresh launches from the recorded paths answeredinitialize. - An independent adversarial review confirmed two defects in the first draft, a main-module regression for respelled paths and a worker Node path resolved too late, and both were fixed before merge.
Limitations
- Registrations written from a Homebrew keg by an earlier version still name that keg; run the installers once after upgrading.
codex-native-relay-installstill refuses to rewrite an entry that hasenv_vars, so edit that entry's path by hand.
[1.22.6] - 2026-10-20
Fixed
- Keep a confirmed Desktop creation identifiable when post-creation verification fails.
delegate_to_codexandstart_codex_threadnow return the task's threadId, its deliveryId and "Task was accepted; do not resend" instead of a bare allowed-roots error that read as if nothing had been created. The confirmed threadId is kept even when a later account, receipt or scope check fails after the bridge waited for the task's workspace. - Treat a filesystem root that Codex Desktop briefly reports as a newly created task's workspace, observed as
/right after creation following an account switch, as "workspace not yet assigned" when it is not the expected project. Creation keeps observing until its deadline and then returns a pending receipt that keeps the accepted threadId; reply observation keeps polling. The tolerance lasts at most 120 seconds from creation, or from the first such report during reply observation, and the bridge acts on nothing at that path and grants no task access from it during that time. - Report a pending creation whose task Desktop already confirmed as
deliveryStatus: acceptedinstead ofunconfirmed.
Security
- A root report that outlasts the grace period, any other workspace outside the allowed roots, a different project, an account change or a sender mismatch still fails closed. Sends and plain thread inspection keep the normal allowed-roots refusal for a root workspace; nothing is sent.
Verification
- 10 regression tests reproduce the defect on v1.22.5 and pass with the fix: creation confirmation with a brief
/report, a pending result at the deadline, grace expiry, an outside-root workspace, a later account change, reply observation in both the wait and snapshot paths, and two MCP-leveldelegate_to_codextests through the relay companion. - The full CI matrix passed on Windows, macOS and Linux with Node 22 and 24. A local run outside the sandbox passed 1406 tests with 0 failures.
- An independent adversarial review found no security regression; its four confirmed correctness findings were fixed before merge.
Upgrade notes
- Reconnect the MCP server after updating and confirm the loaded version from the actual runtime before relying on the fix.
- A creation that is pending because Desktop has not reported its workspace continues with
wait_codex_replyand the returned deliveryId. Do not resend the prompt or create the task again. - Not yet exercised against a live Desktop account switch. A placeholder workspace other than a filesystem root still fails closed as before.
[1.22.5] - 2026-10-19
Fixed
- Persist confirmed Desktop send acceptance in the original owner-bound receipt so a later wait or MCP restart does not revert it to unconfirmed.
- Resolve exact peer dispatches from their original rollout watermark, including messages injected into an active Codex turn and completed replies followed by newer turns. Preserve sender, account, project and response-integrity checks, mark same-turn finals and retain exact empty memory-citation formatting.
- Include the advertised peer name in Claude's supported message envelope so the native recipient can identify the sender instead of showing an unnamed session. Codex Desktop's fixed sender badge remains controlled by the host; author headers identify the actual collaborator without impersonating user input.
- Follow verified native Claude compaction continuations when correlating an outstanding peer reply, while retaining interruption and identity checks.
- Return an unavailable reply at the observation deadline without losing accepted delivery state; continue rejecting identity and permission failures even when they occur after that deadline.
Verification
- The receipt fixes passed the full CI matrix on Windows, macOS and Linux with Node 22 and 24, including restart, compaction and deadline-boundary regressions.
- Live Desktop peer exchanges confirmed both directions, durable acceptance and recovery of a historical final response. Project authorization remained unchanged.
Upgrade notes
- A worker with an unresolved peer receipt can defer automatic reload. Verify the loaded version from the actual MCP after reconnecting; retain the original receipt and inspect the existing conversation before any follow-up.
- Native sender labels remain host-controlled. Claude can display the advertised peer name; Codex retains its native cross-chat label alongside the actual author header. This release does not add Cowork or Dispatch connectivity.
[1.22.4] - 2026-10-19
Fixed
- Discover moved Claude project directories for authorized new Desktop conversations using the workspace resolver and shared project policy. Report candidates separately from live sessions and resumable tasks; preserve original task IDs, account checks, directory bindings, revocations and exact new-session verification.
- Reject ambiguous workspace replacements during Claude project discovery and recheck the saved project before opening, trusting and submitting, including restored requests. Preserve original-path revocations across ancestor junction changes.
- Retain creation scope bindings when an error occurs after opening the native composer, so the original request remains inspectable without reopening or resending.
Verification
- CI passed on Windows, macOS and Linux with Node 22 and 24, including project revocation, source replacement, restored-request and receipt-binding regressions.
- A live Windows Desktop peer message received its correlated Claude reply, and the reverse Claude message arrived in the originating Codex chat with the same nonce. Account, process, task, project and permission checks remained enabled.
Upgrade notes
- Existing supervisors load updated source when safe. Relocation discovery requires the shared project policy and does not make a dormant or moved task a verified live recipient.
- Peer sender attribution requires a verified live Claude Code task. Native composer creation remains a separate operation; it does not substitute for a peer message or its native sender label. This release does not establish Cowork or Dispatch connectivity.
[1.22.3] - 2026-10-15
Fixed
- Retry the complete Claude Desktop identity snapshot up to three times when task metadata changes during inspection. An unrelated active chat updating its metadata no longer causes an immediate sender rejection; persistent changes, conflicting identities, archived tasks, and invalid metadata still fail closed.
- Include bounded metadata diagnostic codes in sender-verification failures instead of discarding the underlying failure category behind a generic account message. Diagnostics exclude task contents and untrusted error text.
Verification
- Regression tests reproduce a one-time unrelated metadata update, persistent updates, archive changes, duplicate identities, and diagnostic sanitization.
- A live Windows check from the originally affected Claude Code session completed two reads, one diagnostic send to its existing Codex task, and reply observation through the returned delivery receipt. The exact diagnostic reply was verified in the destination task.
Upgrade notes
- Existing supervisors load the updated source when safe. Shared Desktop MCP entries still cannot identify a Code task's process ancestry; use the per-Code bridge registration. The repair does not resend earlier work or weaken account, process, or project checks.
[1.22.2] - 2026-10-13
Fixed
- Preserve exact filesystem identities when checking Desktop creation locks and receipts. Large file IDs can collide when represented as JavaScript Numbers; BigInt stat values prevent a replaced lock with a copied token from being mistaken for the owned file.
- Clarify the shared sending-tool guidance: agent-authored handoffs must identify their actual Codex or Claude author in the first line and use English throughout, including the header purpose, instructions, constraints, and reply format.
- Require sufficient measured context, file boundaries, validation steps, and completion criteria for a receiving agent to act without guessing.
Verification
- A deterministic regression uses two distinct file IDs above the safe integer limit. It fails against the previous implementation and passes with exact BigInt comparisons; the real filesystem replacement test remains enabled.
- Full Node test suite on macOS: 1,276 passed, 23 skipped, zero failures. A clean archived checkout passed 1,268 tests with 23 skipped and zero failures; Git-dependent tests are not registered outside a Git checkout.
Upgrade notes
- The handoff changes update prompt guidance, not automatic translation or payload validation. Verbatim user text and exact identifiers retain their original content.
- The native host may still display its own generic attribution label. A sender header inside the prompt does not rename that label or alter permission checks. Cowork/Dispatch support is unchanged.
- Reconnect the MCP client to load the updated tool descriptions; installing the package does not hot-reload an existing process.
[1.22.1] - 2026-10-13
Fixed
- Align the README badges in two centered rows. Render the three custom analytics badges at an intrinsic height of 20 pixels to match the standard flat badges even when GitHub overrides HTML height attributes. Scale both SVG dimensions together to preserve the artwork proportions.
Verification
- Regression coverage checks the intrinsic height and aspect ratio of all three generated analytics badges. The existing analytics tests retain coverage for source dates, stale values, missing data, and aggregate privacy.
npm testpasses from a clean archived checkout: 1,267 passed, 23 platform skips, and no failures. The Repository analytics workflow publishes the updated SVGs from the existing source data.
Upgrade notes
- This release updates README presentation and the bundled analytics publisher. MCP behavior is unchanged; it does not add or validate a Desktop handoff feature. GitHub may cache badge images until its image proxy refreshes them.
[1.22.0] - 2026-10-12
Added
- Optional response preferences for Desktop reads and reply observation, with tool payload filtering and bounded, replayable cursor pages. Snapshots remain bound to the caller, accounts, workspace, selected task, and delivery receipt (#125).
Fixed
- Accept completed Desktop replies whose memory citation is represented separately in the completion event, but appended to the authoritative response item. Require an exact reconstruction from validated citation metadata and preserve reply IDs, hashes, lifecycle checks, and conflict rejection (#123).
- Preserve bounded default history reads while allowing explicit tool output selection. Return structured oversize errors across native transport and serialized MCP responses.
Upgrade notes
- Update both bridge and native relay companion. Calls without response preferences retain existing response formats and the 2,000-character default item budget. Preferred history reads use a 16,000-character item budget; exact-turn reads retain authoritative assistant text.
- Cursor pages default to 64 KiB and support 8–96 KiB budgets. Native responses above 8 MiB and authoritative replies above 1 MiB remain explicit limits.
[1.21.6] - 2026-10-12
Fixed
- Continue observing a delivered Desktop task through bounded
read_threadsnapshots when thewait_threadsrenderer stops returning results after relay recovery. Preserve the original deadline, access checks, and authoritative reply validation without resending the prompt (#122, #123). - Keep native requests capped at 128 KiB while accepting responses up to 8 MiB on both relay hops. Reject larger responses explicitly, trim internal metadata reads, omit tool output from default transcript reads, and bound the serialized MCP read result (#123).
- Identify failed rollout validation checks and record byte offsets in bounded diagnostics without exposing reply contents. Validation requirements remain unchanged; unsupported rollout sequences still fail closed pending concrete evidence (#123).
Upgrade notes
- Update both the bridge and native relay companion. Default Desktop transcript reads omit tool outputs and cap each included item at 2,000 characters; use an exact
turnIdfor authoritative assistant response inspection. - Native frames above 8 MiB, rollout files above 16 MiB, and authoritative replies above 1 MiB remain explicit limits.
[1.21.5] - 2026-10-11
Fixed
- README npm download badges no longer show "rate limited by upstream service". The total and monthly badges are now rendered from the archived daily npm totals and served from the analytics branch, refreshed hourly, instead of shields.io.
Upgrade notes
- MCP behavior is unchanged.
[1.21.4] - 2026-10-11
Added
- Add the Glama ownership manifest to the repository and published package so the directory can identify the maintainer.
- Document Glama metadata synchronization, hosted usage limitations, and Docker infrastructure failures.
Upgrade notes
- MCP behavior is unchanged. Glama must synchronize the repository to detect the manifest; its Docker service must be available before a new hosted release can be built.
[1.21.3] - 2026-10-10
Changed
- Replace the large README download chart with compact monthly npm downloads and dependent repository badges. The badges link to npmcharts and GitHub dependents.
- Stop publishing the unused download chart to the analytics branch; the dashboard and archived daily download history remain available.
Upgrade notes
- MCP behavior is unchanged. The next repository analytics refresh removes the old chart asset from the analytics branch.
[1.21.2] - 2026-10-10
Added
- Show an npm download trend in the repository README, with links to the interactive npmcharts view and GitHub dependents.
- Publish a source-dated trend SVG from the existing hourly analytics history. Distinguish unavailable data from a reported zero and label stale sources at generation time.
Fixed
- Preserve a telemetry lock replaced by another writer on Windows even when rapid file creation gives both locks the same reported file identity and birth time.
Upgrade notes
- MCP behavior is unchanged. The repository analytics workflow publishes the new SVG after this release reaches
main.
[1.21.1] - 2026-10-07
Fixed
- Read project policies, onboarding settings, manager descriptors and automation configuration through bounded, verified file descriptors. Reject files replaced, linked, enlarged or modified during reads, and preserve verified bytes in backups.
- Pin reply receipt directory identity and recheck receipt and signing-key metadata before and after descriptor reads. Reject nonregular rollout descriptors and open without blocking on POSIX pipes.
- Encode Windows ACL target paths as data so Unicode quotation marks in directory names cannot alter the PowerShell command.
- Reject linked and oversized installer configuration, restore configuration through exclusive temporary files, and validate whole-home project aliases before acquiring onboarding locks.
- Update the MCP SDK to 1.32.1 for GHSA-6qxp-vccf-f47h.
Upgrade notes
- Update to
@minhspark/codex-mcp-bridge@1.21.1and reconnect existing MCP connections to load the fixes in running processes. - The 91 open findings reported for 1.21.0 have been resolved: nine closed after code changes and 82 were reviewed as false positives with individual evidence. Additional findings from the new scans were reviewed against their data-flow sources and file validation controls. The final main-branch scan reported zero open CodeQL alerts without disabling queries or excluding paths.
[1.21.0] - 2026-10-06
Added
- Resume an accepted Codex Desktop delivery after a timeout with
wait_codex_reply, using its original delivery ID without resending the prompt. - Inspect and prepare the selected workspace through
inspect_bridge_projectandprepare_bridge_project, with shared project grants, registered worktree support and explicit revocation. - Add
bridge-projectsfor project policy management andcodex-bridge-code-installfor explicit, previewable Claude Code MCP registration. Include Desktop handoff and new-machine onboarding guides.
Fixed
- Authenticate native creation receipt contents with a private persisted signing key; reject altered and unsigned receipts before restoring ownership.
- Restore owned task authority from verified native creation receipts after lost acknowledgements or bridge restarts. Keep ordinary inspection and editable local receipts subject to ownership checks.
- Bind project grants to repository identity and retain repository and registered worktree revocations when Git metadata or directories disappear or are replaced. Reject malformed Git metadata instead of treating it as a plain folder.
- Recheck live project, account and runtime authority after awaited sender validation before opening, trusting or submitting a Claude Desktop creation.
- Preserve reply continuation for confirmed Desktop creation and for existing-thread sends whose native acknowledgement times out. Return an owner/account-bound delivery ID without resending; keep uncertain delivery distinct from acceptance, and correlate creation replies to the exact native creation dispatch. Retain the upstream project and permission checks.
- Bind standalone Git directory pointers to their checkout so a different project cannot impersonate an authorized recipient. Reject private metadata, task receipts and connector credentials that grow, disappear or change while being read.
- Read release fingerprints through bounded file descriptors, preserve locks replaced by another writer, and refuse automatic expiry of an occupied telemetry lock. Write installer output atomically and stop if the Desktop configuration changes before replacement.
- Refuse app-server health redirects and revalidate loopback endpoints before use. Clamp supervisor timer intervals to the supported range and restrict CI token permissions while pinning the Deno setup action.
- Create Windows private files and directories with a protected access list owned by the current user; reject unsafe existing artifacts instead of retaining inherited or foreign explicit access entries.
Upgrade notes
- Update the installed npm package to
@minhspark/codex-mcp-bridge@1.21.0and reconnect the existing Desktop MCP connections. Publication does not reload already running MCP processes or prove a live Desktop handoff. - Shared project policy is opt-in. Configure both bridge MCP entries with the same absolute
CODEX_BRIDGE_PROJECT_POLICYJSON path when using shared grants; project grants do not change session permissions. - At release preparation, 91 new CodeQL alerts from PR #100 remain open. Static triage did not establish an exploitable security boundary for 86 alerts; five file-reading race alerts still require validation. This release does not claim a clean CodeQL alert inventory.
[1.20.1] - 2026-10-03
Fixed
- Start the Sites connector through symbolic installation paths, including the Windows NVM directory junction. Resolve the entry point before comparing it with the module path, so the installed command polls its paired Site instead of silently exiting.
[1.20.0] - 2026-10-03
Added
- Codex MCP Bridge plugin package and a public Sites MCP server. Each account pairs its own computer; users can access only their paired connector and its allowed local projects. Public ChatGPT directory publication remains subject to developer verification and review.
- Outbound HTTPS Desktop connector with account binding, private credentials, persistent operation receipts, and live pairing checks before sending work. Duplicate operation IDs cannot send the same prompt again; interrupted sends remain uncertain until inspected.
- Hosted Worker source, D1 migrations, pairing UI, plugin compatibility manifest, workflow skill, and Windows/macOS setup instructions.
[1.19.7] - 2026-10-02
Fixed
- Recover dormant Claude Desktop Code tasks by reopening their exact saved task ID before sending. Keep account, sender, project and recipient checks active throughout recovery; never substitute a CLI or another task.
- On Windows, submit authorized new Desktop conversations after verifying the exact prompt and explicitly selecting the full native project path. A deep-link folder hint can otherwise create a scratch "No folder" session. Authorized workspace trust handles only the exact native project dialog. Preserve uncertain submission receipts without duplicate Send and track native helper changes during runtime reload.
- Recover the Windows Claude URI launcher when an application update leaves the registered executable missing.
[1.19.6] - 2026-10-02
Fixed
- Make newly created Linux and macOS managed Codex policies readable by the account running Codex. Repair an existing valid policy that was created with restrictive file permissions, so Full access + Never works after administrator setup and remains repairable on later bridge starts.
[1.19.5] - 2026-10-02
Added
- Add an explicit
--full-accessinstaller option that sets Codex Full access + Never globally, repairs the managed policy on Windows, macOS, and Linux with OS administrator authentication when needed, and restores the chosen settings on later bridge connections.
[1.19.4] - 2026-10-02
Fixed
- Detect a managed Codex
requirements.tomlwhoseallowed_sandbox_modesomitsread-onlybefore auto-starting an external app-server. The bridge andnpm run checknow report the policy error directly instead of waiting for a generic connection failure; they do not edit the administrator-managed file.
[1.19.3] - 2026-09-30
Changed
- Write the
analyticsbranch with theRepository analyticsworkflow's own token. Its hourly commits were pushed withANALYTICS_TOKEN, a personal token, so they were attributed to the repository owner and GitHub showed the owner an "analytics had recent pushes" banner with a "Compare & pull request" button after every run. The commits now come fromgithub-actions[bot].ANALYTICS_TOKENonly reads GitHub traffic and no longer needs write access (fine-grained: Administration read).
Fixed
- Refuse Claude-to-Codex Desktop delivery into another project even when
send_to_codex_threadomitscwdor supplies the recipient's directory. The bridge now compares the independently verified Claude caller with the destination before creation, rename, navigation and prompt delivery, and checks both directory/repository identities and the current native destination again at the socket write. Broad allowed roots and thread overrides cannot authorize a different project. Subfolders and registered worktrees of the same repository remain usable; drive/home repositories do not absorb unrelated projects. Blocked preflight calls report that no Desktop mutation was dispatched.
[1.19.2] - 2026-09-29
Fixed
- Start both bridges from project-local npm installations. When npm hoists the bridge's dependencies into the project's
node_modules, the package has nonode_modulesof its own, and preparing the immutable runtime failed withENOENT(scandir …node_modules) since 1.15.0; only global installs, which keep a nestednode_modules, started. The runtime now copies the dependency tree Node resolves from the package (hoisted, nested, scoped, aliased, linked and peer dependencies) and nothing else from the project, so it stays isolated from later installation changes. Its revision also covers the project's npm lock, so annpm installthat changes those dependencies reloads the bridge. - Stop the Codex bridge cleanly when its MCP client disconnects. The bridge ends the Windows PowerShell caller checks it started and waits for them to close, and the supervisor gives its worker up to 6 seconds to exit before stopping it. Before, the supervisor stopped the worker after 1 second without waiting, which left those checks running with the bridge's working directory in use. On Windows, deleting that directory right after a test closed its bridge then failed with
EPERM; the tests no longer retry that deletion.
[1.19.1] - 2026-09-29
Fixed
- Recognize
codex_work_desktopas a local Desktop sender while retaining exact host task/turn, workspace, and lifecycle checks (#84). Its permission profile is classified like that of any other Codex Desktop task, including the managed sandboxes supported since 1.19.0 (#83). Claude's inbound policy and permission parity checks are unchanged. - Read completed native replies from
codex_work_desktoptasks and correlate both raw and XML-escaped Desktop dispatch envelopes to the exact sent prompt (#84). Task, workspace, turn, executor, and pre-send watermark checks remain required for automatic reply observation. - Preserve confirmed native send acceptance when the overall response deadline expires (#84). The timeout does not release the underlying operation's thread lock, retry a prompt, or turn an unconfirmed send into a successful delivery.
- Avoid a Windows Node 24.13.0 native crash when preparing supervisor and MCP contract test fixtures from a Unicode checkout path by awaiting asynchronous directory copies (#84).
- Stop refusing Claude → Codex callers on Windows because Windows PowerShell started slowly (#42). The caller check reads the process ancestry in a fresh Windows PowerShell that first compiles its Toolhelp helper, and the five-second fail-closed deadline covered that startup as well as the read. On a cold or contended machine the startup alone has taken 5 to 15 seconds: CI refused callers with
INSPECTION_TIMEOUTbefore the script had begun (5,036 ms) and while the helper was still compiling (5,017 ms), although the read itself takes about 60 ms. The helper now reports when it is ready, and the five-second deadline starts there. Getting ready has its own 25-second ceiling, so a whole read still ends within the 30 seconds the bridge gives its other PowerShell identity reads. Either expiry still refuses the caller, and a slow start is reported asINSPECTOR_START_TIMEOUT. The helper also writes its JSON itself, so the timed read no longer loads PowerShell's JSON serializer. - Lock
ip-addressat 10.7.2 for development installs (#87). 10.5.0 misclassified IPv6 link-local and NAT64 local-use addresses. The bridge's stdio servers never load the rate-limiting code that uses it, and the published package ships no lockfile, so installs from npm resolve their own versions.
[1.19.0] - 2026-09-29
Added
- Give each independent Codex Desktop task its own creation identity with an optional
requestIdUUID ondelegate_to_codexandstart_codex_thread(#82). Creation receipts were keyed by directory and title, or by the exact prompt when no title was given, so a second independent task with the same title returned the earlier task and its brief was never sent. A freshrequestIdcreates a separate task even with the same directory, title and prompt, and retrying with the same ID recovers the original receipt after a bridge restart without resending the prompt. Calls withoutrequestIdkeep the previous deduplication. Legacy app-server mode rejectsrequestIdbefore creating anything, because it cannot deduplicate creations durably.
Changed
- Guide agents to open a new Codex conversation for each independent task when the user asks for one or has given standing instructions to, and to continue unfinished work, fixes and results in the task's original thread (#82). The server instructions, tool descriptions and README previously told agents to prefer an existing task and to create one only on an explicit request.
Fixed
- Verify Codex → Claude Desktop senders that run inside a Codex-managed sandbox (#83). Codex Desktop 26.924 starts ordinary tasks with a
managedpermission profile, aworkspace-writesandbox, and agranularapproval policy, and its permission selector may offer only Ask for approval and Approve for me; the bridge accepted only the disabled full-access profile, so every send from such a task stopped withCODEX_SENDER_CONTEXT_UNVERIFIED. A managed profile whose file system is restricted now attestspromptingwith auserorauto_reviewreviewer and any approval policy, matching Claude, which countsdontAskandautoas prompting; it can never attestbypass, which still requires Full access withapproval_policy: never. The bridge still fails closed when the managed file system is unrestricted, grants write access to the file-system root, a literal root path, a glob, or an unrecognised special path, or has any unrecognised shape. A granular policy is reported as a stablegranular(<allowed categories>)label, andclaude_bridge_statusshows the sender's permission profile and approval reviewer, which a queued send now also pins. A class mismatch against a Claude task inbypassPermissionsnames the Full access requirement. - Retry removing an integration test's temporary home on Windows while the bridge and the PowerShell probes it started are still exiting (#86). They keep that directory as their working directory after the SDK's close() sends SIGKILL, so the removal failed a Windows CI run with
EPERM.
[1.18.2] - 2026-09-26
Fixed
- Restore native relay compatibility with Codex Desktop 26.924 by including the required caller source in native tool requests, allowing pipe discovery and Desktop operations to recover automatically.
[1.18.1] - 2026-09-25
Fixed
- Report npm installation completion with an unchanged version instead of claiming the package is already up to date after a same-version reinstall.
- Discover Claude Desktop sessions when accumulated task configuration exceeds 32 MiB. Retain only bounded identity fields and SHA-256 fingerprints while preserving account isolation, duplicate detection, and concurrent-change checks.
- Report Desktop task verification failures separately from missing peer endpoints in session discovery and bridge status.
[1.18.0] - 2026-09-23
Changed
- Guide agents to write every cross-agent prompt in English with a fixed section order: Goal, Context, Task, Scope, Constraints, Done when, Reply format. The Codex, Claude and VS Code bridges share one definition in their server instructions, sending-tool descriptions and prompt fields, and text supplied by the user is still sent unchanged.
[1.17.0] - 2026-09-21
Added
- Bridge existing Claude Code and Codex conversations inside VS Code on Windows, with same-project session checks and delivery receipts.
- Mirror published releases to GitHub Packages alongside npm.
Fixed
- Keep discovering the Codex Desktop native tools pipe when it is absent during companion startup. Retry with capped backoff until Desktop is ready or the companion closes, without sending user messages or requiring another task to restart the relay.
- Repair current bridge client configurations while refusing to overwrite changes from active client writers.
- Distinguish unreadable process identity from a confirmed identity change during session validation.
- Preserve hosted demo media and keep analytics Pages deployment working when analytics sources are incomplete.
Changed
- Document release notification subscriptions and improve receipt test reliability under load.
[1.16.1] - 2026-09-15
Changed
- Serve the README demo from the Pages branch and show it as a GIF that opens the recording. GitHub serves release assets with
Content-Disposition: attachment, so clicking the demo downloaded a file instead of playing it, and its embedded player could not replace it: GitHub wraps every video in chrome carrying the file name that a README cannot style away, and strips an<img>fallback placed inside the<video>tag, which left npm showing a bare link. Pages returnsvideo/mp4andimage/gifwith no attachment header, so npm renders the GIF and the video plays with seeking.
Fixed
- Bound every short-lived process the test suite spawns, so a wedged child fails its test instead of running to the CI job wall. Thirteen spawn sites had no time limit at all. The children that are meant to outlive their call - the MCP stdio servers, the relay socket server, and the lock holder that waits on stdin - are deliberately left unbounded, since killing those on a timer would end a healthy process mid-test.
- Raise the mock peer delivery guard in the tool contract tests from five to thirty seconds. Every scenario that legitimately receives nothing returns before that guard, so it only ever waits on a delivery that is expected to arrive; five seconds was not enough on a contended Windows runner and failed two runs.
- Read this process's own ancestry once per test process in the Desktop caller fixture, in a hook rather than inside whichever test runs first, and retry a failed cold read instead of reusing its rejection. The snapshot cannot change while the test process runs, so the eleven repeat reads only paid PowerShell's startup cost again; the first one reached the old ceiling and failed a Windows run, and the one test carrying its own timeout would have had to absorb that cold start inside its cap. The production five-second inspection deadline is unchanged and still asserted.
[1.16.0] - 2026-09-14
Added
- Prepare a separate native Claude Desktop Code conversation in an existing project with
start_claude_session, then verify its new task identity and exact initial prompt throughread_claude_creation. The official Desktop link requires user confirmation and Send; opening a composer is reported asawaiting_user, never as completed creation. - Retain bounded creation receipts across automatic reload, prevent duplicate or competing composer launches, reject old tasks resumed as new processes, and allow explicit cancellation through
abandon_claude_creation. Existing clients can usesend_to_claude_sessionwithtarget: "new"and inspect its request ID throughread_claude_delivery. - Detect a submitted new conversation that remains in No folder as
awaiting_project_confirmation, preserve its native identity, and verify completion after the user moves it to the requested project. Recognize Claude Desktop's initial No folder banner without accepting a different or later user prompt.
[1.15.2] - 2026-09-14
Fixed
- Restore Codex-to-Claude Desktop messaging on Windows with Claude Code 2.1.270, which advertises its process FILETIME as
procStartinstead ofprocStartFt. Normalize both fields in session records and authentication keys, retain live process verification, and reject malformed or conflicting identities. - Advertise both Windows identity fields on bridge peer records and authentication keys so current Claude sessions and older peers can validate the same endpoint without restarting Desktop.
[1.15.1] - 2026-09-14
Fixed
- Allow bounded cold startup time for the Windows snapshot identity test on slower CI hosts while preserving the production five-second inspection deadline and the real MCP caller check.
- Discover the native tools pipe on current Windows Codex Desktop builds that load app tools through a plugin instead of an inline app-server override. Validate the Desktop process ancestry and pipe owner before connecting, so the relay can start without a pinned pipe address.
- Keep native relay reloads usable when another companion takes over a shared listener during the handoff, while still rejecting a missing endpoint.
- Migrate legacy Desktop installations explicitly with
install-claude-desktop.mjs --desktop-tasks, disable external app-server autostart, and leave automatic routing unpinned so a later relay installation can take effect. - Reload effective shared routing changes on the existing MCP connection when safely idle. Allow legacy-to-Desktop upgrades while preserving confirmed receipts without replay; reject automatic downgrades to the external app-server. Clarify that open Desktop tasks are valid native destinations.
- Reuse validated dependency hashes for unchanged files when preparing cached runtimes, avoiding repeated content reads that can delay MCP initialization during Windows startup. Changed source dependencies and modified cached copies still require verification; missing or invalid hash metadata falls back to reading file contents.
- Log runtime preparation start and elapsed time before the MCP worker launches, so startup delays can be distinguished from worker initialization failures.
[1.15.0] - 2026-09-07
Added
- Keep Claude and Codex MCP stdio connections open through a stable supervisor, with immutable worker snapshots and automatic activation of compatible installed-source changes when safely idle. Packaged bridge commands and all three MCP installers use the supervisor.
- Expose automatic reload state and pending-update blockers in status diagnostics. Failed candidates retain the working generation; active calls, pending deliveries, late replies, and native relay work defer replacement without replaying prompts.
Fixed
- Preserve existing Claude MCP entry properties and native companion environment settings during installer upgrades. Codex registrations refuse to overwrite custom access, timeout, or transport settings and print the exact launcher fields to change in place. Accept or preserve an explicit Claude data directory without binding an account.
Upgrade notes
- Re-run the relevant installers and reconnect each MCP server once in its existing task to load the supervisor. A previously running direct-entry process cannot adopt this mechanism from a disk update alone. Subsequent compatible worker updates do not require an application restart.
- Automatic reload observes installed files; npm/Git updates remain the responsibility of the existing update mechanism. Client environment changes and incompatible supervisor changes still require MCP reconnect. Pending or uncertain deliveries can defer an update until safely resolved; never resend them merely to unblock a reload.
[1.14.0] - 2026-09-07
Added
- Rediscover Claude Desktop and Codex account identity for each Desktop call, including repeated account switches and Windows Store Claude installations. Add
target: "auto"for the unique current-account Claude Code task in an exact project directory, with native task identity retained across CLI restarts. - Bind pending replies and Codex creation receipts to their original account fingerprints. Verify the calling Claude Code task through process ancestry, reject lingering old-account callers, and hide delayed results after an account change without repeating an uncertain delivery.
Fixed
- Clear automatically discovered native relay endpoints after disconnect, error, or close so the next request can discover a replacement while preserving explicit socket overrides and uncertain-delivery semantics.
- Recheck account identity after asynchronous transport connection and before native dispatch. Account-bound requests use protocol v2 and a separate companion endpoint so an older shared companion cannot accept them without enforcement.
- Isolate Windows MCP contract fixtures from the machine's live native relay pipe. Skip file-symlink tests only when Windows denies creating the test link.
- Read Windows caller ancestry through a bounded native process snapshot instead of WMI service queries. Clean up integration fixtures even when initialization fails, and fail creation gates promptly when preflight rejects a request.
Upgrade notes
- Reconnect both Desktop MCP clients once after upgrading. Codex can defer its reload until the next active turn. Verify the loaded version and current runtime from that task; subsequent account changes are inspected on each call.
- Account detection uses Claude's local sign-in snapshot and Codex file-backed ChatGPT identity. Unsupported or transitional identity states stop dispatch until the next call can verify them. Legacy creation receipts without account fingerprints remain protected from implicit reuse.
[1.13.9] - 2026-09-07
Fixed
- Restore reply correlation for queued messages from Claude Code 2.1.229 and 2.1.237, where
source_uuidis unrelated to the peer message ID. Version 1.13.8 incorrectly rejected that valid legacy format. Use the matching peerorigin.msg_idas the authoritative identifier while retaining duplicate-root, non-peer, command-boundary, and malformed-record guards. Regression coverage reproduces both legacy builds and rejects correlation through the unrelated source UUID.
[1.13.8] - 2026-09-07
Fixed
- Reject contradictory message IDs, non-peer origins, duplicate matching roots, and reply branches that cross another queued command. Preserve both measured Desktop transcript formats while preventing another command's answer from completing the wrong pending request.
- Ignore malformed transcript records and text blocks without crashing the reply watcher. Empty or malformed user input no longer counts as a tool-result continuation.
Changed
- Document that an absorbed message is identified by
source_uuidon Claude Code 2.1.260 and later and byorigin.msg_idon earlier builds, which 1.13.7 already matches.
[1.13.7] - 2026-09-07
Fixed
- Correlate a Desktop reply to a message that arrived while the recipient was mid-turn. Claude Code absorbs such a message into the running turn and records it as a
queued_commandattachment whosesource_uuidis the message id, under a fresh uuid; only the idle shape (a user entry whose uuid is the message id) was recognised, so the reply appeared in the app while the bridge reportedreply_timeoutand kept the message pending. Both shapes now resolve to the turn's closing text. A reply taken from an absorbed turn is markedreplyAbsorbed: truein receipts, the tool result says so, and the text forwarded to Codex carries the same note, because that closing text may not address the message. - Detect a Claude Desktop task record rewritten during inspection by comparing its bytes, not only its stat fields. A same-size rewrite inside one filesystem timestamp tick (about 16 ms on Windows) left size, times and inode unchanged, so the replace-detection test failed intermittently on Windows CI and the guard could miss such a replacement.
Added
- Read the recipient session's effective
crossSessionInbound(managed, user, project, and local settings with Claude's tightening precedence) and refuse a send at preflight withCLAUDE_RECIPIENT_INBOUND_POLICYwhen it isrefuseorhold; an explicitacceptsends without a class check. Otherwise read the recipient task's permission mode from Claude Desktop metadata, report it with its Claude parity class inlist_claude_sessions, and refuse withCLAUDE_RECIPIENT_CLASS_MISMATCHwhen that class differs from the verified sender class, naming both classes and the user-only remedies on either side, since Claude Desktop cannot show the approval dialog such a hold would need. Both checks repeat before writing; an unknown mode leaves the decision to Claude. Only a plain alphabetic mode value is exposed. Receipts carrysenderApprovalPolicy,recipientPermissionMode,recipientPermissionClass, andrecipientInboundPolicy, and a held receipt names both classes.
Changed
- Document Claude's symmetric inbound parity: a prompting-class Desktop recipient holds a
bypasssender just as a bypassing recipient holds apromptingone, so aheldreceipt means the two tasks run in different permission classes and only the user can align them, by running the recipient in the matching class or settingcrossSessionInboundtoacceptthere. The bridge never adjusts the attested class. Describenode_repl_auto_review_requiredas the per-model catalog attribute observed live alongside a user reviewer, note thatauto_review_enabled: truewith a user reviewer is unobserved, and pin the held-receipt wording in the tool contract test.
Upgrade notes
- Reconnect the MCP connections in both Desktop clients after upgrading; a bridge process started before this version reports stale source and refuses new sends once the files change.
[1.13.6] - 2026-09-06
Fixed
- Classify a Desktop sender by its human approval policy alone.
node_repl_auto_review_requiredis a Codex model-catalog requirement (gpt-6-astracannot run without auto review) andauto_review_enablednames an automated Guardian reviewer; neither adds a human prompt, so a verified full-accessapproval_policy: neversender isbypasswhichever review flags the host sets. Since 1.13.5 such senders were downgraded toprompting, and a bypassing Claude Desktop recipient held every message behind apeer_inbound_approvaldialog that Claude Desktop does not declare it can render, so nothing sent from that model could ever be delivered. Review flags remain required booleans and are still reported in status and receipts. - Report the verified sender's approval policy in
claude_bridge_status, and state in held receipts that Claude Desktop exposes no peer approval dialog.
Upgrade notes
- Reconnect the
claude-bridgeMCP in the Codex Desktop task after upgrading. A bridge process started before this version keeps the old classification until it is restarted; its status reports stale source and refuses new sends once the files change.
[1.13.5] - 2026-09-06
Fixed
- Verify each Desktop sender from Codex-provided MCP task/turn identity and its active rollout permission settings, instead of relying on a shared environment declaration. Explicitly enabled host review uses the prompting sender class; missing, invalid, stale, or unsupported contexts stop before message bytes are sent. Diagnostic sandbox labels never grant permissions, and review never grants bypass permissions.
- Match Claude sessions to exact native Desktop task IDs and titles, require the intended task ID and cwd, and revalidate process and task identity at dispatch. Discovery can filter by exact project and never falls back to a different project.
- Preserve the original sender task and permission class per request, including concurrent and early replies. Revalidate sender evidence after connecting and before writing. Held receipts explicitly leave the approval UI unverified instead of implying a button exists.
- Queue burst replies instead of dropping them under the forwarding rate limit. Preserve the original destination and expose forwarding outcomes, uncertainty, and session-limit blocks through receipts and inbox reads without automatic retries or fallback routing.
- Keep unread inbox pages and require the exact correlated Desktop transcript reply before completing a request. Unrelated socket notifications no longer cancel the original response watcher.
- Expose each host review flag and preserve its value in delivery receipts. Already accepted replies can finish after a source update while the configured delivery route remains unchanged.
[1.13.4] - 2026-09-06
Fixed
- Latch queued Desktop delivery deadlines when they expire, so a timed-out prompt cannot dispatch later or release the lock owned by an active send.
- Require and revalidate the exact intended workspace for Claude Desktop sends, expose pending recipient receipts through
read_claude_delivery, and block no-wait retries of held or uncertain messages. Preserve pending ownership after an uncertain socket write. - Detect source and Desktop-policy changes in loaded bridge processes and refuse new sends until reconnect. Diagnostics identify their separate MCP process instead of implying the Desktop connection was refreshed.
- Preserve the Codex MCP registration environment on upgrade, pin Desktop routing explicitly, disable its external autostart, and refuse to reset custom access or transport settings. Prefer existing Desktop tasks in MCP instructions.
- Enforce Desktop task mode for Claude destinations as well as Codex delivery. Exclude non-Desktop sessions from discovery, refuse CLI or unknown entrypoints before connecting, and require a unique exact target. Status reports eligible and excluded sessions; receipts identify the actual entrypoint, workspace, and session. Legacy CLI mode remains available when Desktop task mode is disabled.
- Register the native relay companion under a runtime Codex Desktop trusts instead of whichever Node happens to run the installer. The app authenticates the code-signing identity of any process connecting to its native tools pipe and closes the connection before reading a byte when that identity is not its own, so a companion started by a user-installed Node still created its socket and still reported itself installed while every delivery failed as
NATIVE_DELIVERY_UNCONFIRMED— the refusal is only visible in the app's own log asdynamic_app_tools_peer_rejected. On macOS the installer now resolves the runtime the app ships, honours the variables the app declares for its own bundled plugin, and prints the runtime and its source;CODEX_NATIVE_RELAY_NODEoverrides it. Windows and Linux keep the runtime running the installer, since neither was measured to enforce the check.
Upgrade notes
- Reconnect the MCP connections in both Desktop clients after upgrading. Reinstall an existing native relay companion with the updated installer to apply runtime selection. Updating package files alone does not replace running processes or add the stale-runtime guard to an older process.
- In Desktop task mode, provide the independently verified absolute
expectedCwdwhen sending to Claude. A held receipt still requires the recipient's approval; inspect itsmsgIdwithread_claude_deliveryinstead of resending. Receipt history is in memory and is not restored after a bridge restart.
[1.13.3] - 2026-09-05
Fixed
- Verify the current saved project's identity, canonical directory, and task membership before reusing a Desktop creation receipt. Project drift is rejected; omitted recent/pinned metadata reports unverified assignment while preserving the task ID without resending or creating a duplicate.
- Support
--versionand-von every packaged command without starting servers, opening sockets, or mutating client configuration. - Preserve PowerShell's
$?and conditional&&/||behavior as well as$LASTEXITCODEby invoking its footer through a script alias.
Added
- Opt-in Bash, Zsh, and PowerShell installation footers for
npm install -g @minhspark/codex-mcp-bridge@latest: first installation, changed version, unchanged version, failure, dry run, and unverifiable metadata are distinguished after npm's final output while preserving its exit code. codex-npm-footer-installbacks up and updates shell profiles idempotently, refuses unmanaged npm wrappers, supports removal, and explains how to reload an already-open terminal. Package installation does not change profiles automatically.
Verification
- Regression coverage includes same-workspace project moves, deleted/repointed/replaced projects, incomplete Desktop snapshots, deadlines and authorization, shell argument boundaries, dry-run configuration, failure exit codes, metadata validation, and profile preservation.
[1.13.2] - 2026-09-05
Fixed
- Prevent duplicate Desktop tasks across concurrent MCP processes and restarts with durable creation receipts. The same workspace and explicit title reuse the verified existing task even after completion or an edited brief; continuations remain explicit sends to its ID.
- Bound the entire Desktop tool call to 40 seconds, including creation, opening, observation, and queued sends. Expired queued prompts are never sent later, and an accepted task keeps running with its ID available to the caller.
- Preserve confirmed task IDs when the first turn fails or needs attention; block uncertain creation retries without automatically expiring receipts or abandoned locks. Reusing a receipt cannot expand thread authorization.
- Keep project selection restricted to exact existing local projects. Explain that Desktop's recent-task snapshot can omit visible agent-created tasks, so absence is not evidence that a retry should create another one.
Verification
- Windows suite: 322 passed, 0 failed, 8 platform-specific skips. Includes real concurrent MCP processes, restart reuse, lost acknowledgements, persisted receipt validation, strict owned-policy checks, and call deadlines.
- Archived two completed duplicate tasks and retained the latest task in its existing project. A direct native read verified its exact workspace before recording the existing creation receipt.
[1.13.1] - 2026-09-05
Fixed
- Make Desktop task mode independent of the external app-server for status, thread discovery, diagnostics, and fallback delivery. A missing native relay reports an actionable failure without starting another process or taking a task's writer lock.
- Verify native connectivity through Desktop projects and list its authorized local recent/pinned Codex tasks. Explain the snapshot coverage and reject unsupported
loadedOnlyqueries instead of returning external-server state. - Persist external autostart off when installing Claude Desktop in Desktop task mode, while preserving explicit legacy mode and existing permission settings. Reconnect the native companion after upgrading to enable the new allowlisted thread-list operation.
Verification
- Windows suite: 300 passed, 0 failed, 8 platform-specific skips. Added absent-relay, zero-external-connection, native-list authorization, and overlapping-send regressions.
- Live Windows checks returned bridge 1.13.1, eight native local projects, recent Desktop tasks, and an existing task's history while port 8791 remained stopped.
[1.13.0] - 2026-09-05
Added
- Opt-in Desktop task delivery:
delegate_to_codexcreates a task in the exact saved local project and opens it while running.send_to_codex_threadcontinues through Desktop without a second writer.start_codex_threadaccepts an initial prompt and requires it in Desktop mode. - Enable with
codex-native-relay-install --desktop-tasksorCODEX_BRIDGE_DESKTOP_TASKS=1. Desktop mode uses Desktop permissions and preserves bridge workspace/thread authorization. Missing, ambiguous, remote, or parent-only project matches fail before creation; the requested checkout is preserved. - Strictly allowlisted native operations and a separate Desktop task socket allow upgrades alongside an older legacy relay owner. Read/open operations use Desktop too; timed-out native tasks point to Desktop's Stop control.
Fixed
- Distinguish task acceptance, model failure, attention requests, and observation timeout. Follow-up polling ignores the previous completed turn; unconfirmed creation or sending is never automatically retried through another backend.
- Mark prompt-bearing task creation as potentially destructive in MCP annotations, and preserve the shared Desktop opt-in when bootstrapping a relay executor.
Verification
- Added project matching, authorization, protocol validation, socket transport, uncertain acknowledgement, attention, timeout, and full MCP creation/opening tests.
- A real Windows Desktop task appeared under PCC4SH and completed with
cwd=C:\PCC4SH,HEAD=74ed553. A subsequent native message reached that same task and reported an account usage-limit failure; a second successful model response was not claimed.
[1.12.5] - 2026-09-05
Fixed
- Preserve the configured environment when the Claude diagnostic starts its MCP child, including sender permission mode and native-relay settings. The MCP SDK's default environment whitelist otherwise drops these settings and can make the diagnostic exercise a different receiver policy than the installed bridge.
Verification
- The live Codex MCP bridge returned a real Claude Desktop answer through the UUID-correlated transcript path with the expected workspace. The native Codex relay also delivered its marker into the existing Desktop task. No receiver permission settings or Desktop tool restrictions were changed.
- The live
check:claudecommand reported bridge 1.12.5, received the correlated Desktop response, and exited with code 0.
[1.12.4] - 2026-09-05
Fixed
- Authenticate Windows peer connections with the destination peer key, publish keys under the canonical socket hash, use Claude-compatible reply pipe names, and encode reply addresses. Incoming unauthenticated Windows frames are refused.
- Keep receiver policy receipts separate from replies and correlate them to the original message and destination. Socket writes no longer report confirmed delivery; timeout and held/refused outcomes fail the roundtrip diagnostic without automatic retries.
- Read ordinary Claude Desktop responses from the local transcript using the injected UUID and assistant ancestry, preserving Desktop's disabled native reply tool. Late correlated responses remain available while the bridge runs.
- Declare sender permission mode only when explicitly configured, and preserve receiver approval decisions. Status reports unknown sender mode instead of inventing one.
Tests
- Added authenticated transport, missing/bad auth, canonical key and address, receiver status, MCP outcome, and transcript-correlation regressions. Live Windows testing confirmed authentication and returned an actual
heldreceipt; the Desktop assistant roundtrip remains subject to recipient approval.
[1.12.3] - 2026-09-05
Fixed
- Discover the native tools pipe from the launching Desktop app-server's
mcp_servers.codex_app.envoverride when Desktop does not pass it to custom MCP servers. Explicit pipe settings keep precedence; discovery rejects unrelated processes, ambiguous settings, and remote Windows pipes without scanning other sessions or persisting a restart-specific address. - Cancel pending pipe discovery when the client closes, and share discovery between concurrent connection requests so a closed client cannot send a delayed message.
- Report a reachable shared companion in native relay status when another MCP instance owns the listening endpoint.
Tests
- Added Windows/POSIX command-line parsing, parent discovery, environment precedence, real mock-pipe delivery, cancellation, concurrent connection, and shared-companion regressions.
[1.12.2] - 2026-09-05
Fixed
- Use the native protocol measured by Seb in #23. The companion uses the native pipe inherited from Codex Desktop, separately from MCP stdio. Dispatch is
tools/callwith distinct executor and destination thread IDs, fresh call/turn IDs, and a UInt32LE length prefix. A response must explicitly reportsuccess: true. The companion recovers when a configured native pipe appears after startup. - Do not kill other delegations when one finishes. Automatic handoff unsubscribes only the completed thread. It confirms unload before opening Desktop, reports pending idle unload honestly, and fails safely on servers without
thread/unsubscribe. Explicit shared-server shutdown remains a separate destructive tool. - Keep RPC and turn state consistent across failures. Failed sends settle their pending promise, concurrent calls wait for initialization, and disconnects clean up listeners and requests. Same-thread transactions are serialized while other threads remain independent; timed-out or disconnected turns require state reconciliation before another turn starts.
- Prevent duplicate or misattributed messages. A native request with an unconfirmed outcome is never retried through another backend, and invalid messages cannot bypass validation through fallback. Claude requests are queued per destination; unresolved earlier replies block new waited sends instead of assigning a late reply to the wrong request. Fire-and-forget and late responses remain accessible through the inbox.
- Preserve Unicode across fragmented pipe traffic. Both relay protocols and Claude peer messages retain complete UTF-8 characters when stream chunks split a character.
- Validate the workspace actually used. Relative input becomes absolute, regular files are refused as directories, and a created thread must report the requested workspace within allowed roots. A path map cannot disguise an unexpected server-created cwd.
- List loaded threads correctly. The bridge reads the IDs returned by
thread/loaded/list, applies workspace/title filters, and follows pagination to find matching threads. - Keep diagnostics and installer settings truthful. The Desktop installer honors both enabling and revoking
CODEX_BRIDGE_AUTO_APPROVE_ACK. Check commands fail on MCP tool errors, and the live continuity smoke test requires two completed turns to preserve a unique codeword.
Tests
- Added regressions for connection and turn lifecycle, authorization, concurrent handoffs, late replies, fragmented/malformed native frames, missing/late native pipes, fallback boundaries, configuration preservation, and diagnostic exit status. Native wire tests run a real MCP child against isolated mock pipes without sending messages to user sessions.
[1.12.1] - 2026-09-05
Fixed
- Windows no longer loses the Codex Desktop native relay to a Unix-only transport. The Claude peer endpoint and the Codex Desktop companion now use local named pipes on Windows, while macOS and Linux keep their Unix sockets. The same platform-aware endpoint detection is used by status checks and cleanup, so a live Windows companion is not mistaken for a missing session or deleted as a stale file.
- Live Claude sessions no longer disappear intermittently while their registry file is being rewritten. Session metadata is read twice and retried until stable, and peer delivery retries the short startup window before the named pipe is listening. A session that is alive but still bringing up its Windows pipe remains visible and deliverable.
- A disconnected hand-off now releases the bridge app-server when release-after-turn is enabled. This prevents a dropped turn from leaving a writer lock behind and blocking Codex Desktop on the next open.
- Windows resolves the versioned Codex Desktop binary before older install locations. The bridge and installers therefore use the current desktop executable instead of silently attaching to an obsolete copy.
[1.12.0] - 2026-09-04
Added
-
A thread open in Codex Desktop can now receive Claude's messages without being taken away from the app. Binding a thread with
bind_codex_threadand then watching it in Codex Desktop was the workflow the relay was built for, and it was the one case that could not work: Codex takes a per-thread writer lock when the app loads a thread and holds it while the thread is open, so the relay'sthread/resumewas refused withthread <id> already has an active writer. The only way through was to close the thread before every message - which gives up the reason the thread was bound in the first place.The fix is to stop bringing a second writer.
codex-native-relayis a companion MCP process that Codex Desktop launches itself, so it already sits inside the app's context and can ask the app's own app-server to deliver the message. Nothing attaches, nothing resumes, no second app-server starts, and the desktop app stays the single writer of the thread throughout.claude-bridgereaches it over a private mode-0600unix socket at~/.codex/native-relay.sockand sends exactly{ targetThreadId, message }.codex_app.send_message_to_threadruns against an executor thread, distinct from the destination and validated by Codex - a synthetic UUID is rejected. A dedicated relay thread carries that role so the watched thread never has to:scripts/install-native-relay.mjscreates it once, records it in~/.codex/native-relay.json, and stops the app-server it borrowed so no lock is left held. Resolution isCODEX_RELAY_ID, then that file, then an explicit error naming both - never an invented id, which Codex would reject with a message that says nothing about the missing configuration behind it. -
Delivery is now a backend choice rather than a call, in
src/thread-delivery.mjs. Nothing else moves: the Claude peer protocol,list_claude_sessions,send_to_claude_session,bind_codex_thread, the routing, the ping-pong limits,codex-mcp-bridge,CodexAppServerClientand the thread authorization policies are unchanged, and the app-server path stays the default for every thread Codex Desktop does not own. The native path is macOS-only, feature-detected on the companion socket, and switched off entirely withCODEX_BRIDGE_NATIVE_RELAY=0.An unreachable companion falls back to the app-server path, because an absent relay says nothing about the target thread. A companion that answered with a refusal does not: Codex has already been asked, and a second app-server would only contend for the
~/.codexstate before failing on the very writer lock the native path exists to avoid. -
claude_bridge_statusandbind_codex_threadreport the backend in force, and carry the reason when it is not the native one - a missing companion socket, an explicit0, and an unsupported platform are three different problems that otherwise look identical from the outside. -
native_relay_statuson the companion reports its socket, its executor thread and the dispatch method.npm run install:relay/npm run uninstall:relayregister and remove it.
Security
- The relay socket is created mode
0600inside the Codex home and swept on exit; that file mode is the whole boundary, exactly as it already is for the Claude peer protocol. The companion accepts one payload shape, caps a frame at 128 KiB on both halves, and refuses a destination that is its own executor thread - otherwise a mistaken bind would deliver into the invisible relay thread and report success. A socket already held by a live companion is never stolen: an in-use path is probed before any leftover from a killed process is swept.
Notes
codex_app.send_message_to_threadand the Codex Desktop native tools pipe are internals with no public documentation, on the same footing as the Claude peer protocol insrc/peer-protocol.mjs. That is why this path is optional, feature-detected and fallback-safe rather than the default. If Codex changes it, the two places to fix areNATIVE_DISPATCH_METHODandnativeDispatchParams()insrc/native-relay.mjs, andCODEX_NATIVE_RELAY_METHODoverrides the method name without a release.
[1.11.3] - 2026-09-03
Fixed
-
The peer endpoint never started on Windows, so the bridge was one-way there.
/tmp/cc-sockshas no Windows equivalent, andpath.joinrewrote it to\tmp\cc-sockson the system drive, wherelisten()fails withEACCES. Codex could push a message into a live Claude session, but Claude had no address to answer on - and the only sign was one line on stderr saying replies could not be received, which nothing surfaces once the server is running under an MCP client. The peer now listens on a named pipe on Windows, the same transport Claude Code itself advertises in~/.claude/sessions/<pid>.json, and skips the directory, mode and unlink steps that a pipe does not have. -
fast-uriis bumped to 3.1.7 andqsto 6.16.0.fast-uri3.0.0-3.1.5 is vulnerable to host confusion and server-side request forgery through repeated hostname percent-decoding (CVE-2026-75899, high); it reaches the tree transitively through@modelcontextprotocol/sdk->ajv. -
A tag is not a release, and nothing was creating the release. Pushing
v1.10.1,v1.11.0andv1.11.1published all three to npm, while the Releases page still showedv1.10.0as Latest - the one release that had been created by hand. Anyone reading the repository saw a project that had not shipped in days, and the three versions people were actually installing had no notes anywhere except this file.The publish workflow now creates the release from the changelog entry, in a separate job that is the only one granted
contents: write- the job that talks to npm keeps the read-only default. Generated commit lists say what changed; the entry says why it mattered, so the entry is what ships. Re-running a tag is safe: an existing release is left alone. -
scripts/release-notes.mjsprints one version's changelog section, and a test asserts the version inpackage.jsonhas an entry substantial enough to be a release note - so forgetting to write it fails before the tag is pushed rather than at the end of a release.
Added
delegate_to_codexnow gives Claude a single contract for handing work to Codex: it creates the thread at the requested project directory, names it throughthread/name/set, returns the exactthreadIdandcwd, releases the bridge writer lock after a terminal turn, and opens the Windows or macOScodex://deep link when configured. Windows app-server shutdown usesnetstatandtaskkillinstead of the Unix-onlylsofpath, which removes the lock that previously left Codex Desktop showing "open in another app".
[1.11.2] - 2026-08-28
Fixed
- Thread workspaces are normalized through the cross-machine path resolver before authorization, attaching, reading, interrupting, or opening. A stale drive letter, mount point, or UNC path can therefore be mapped to the writable checkout on the current machine instead of sending Codex into the wrong directory.
CODEX_BRIDGE_ALLOWED_ROOTS=*now explicitly means every usable workspace, and the installer uses that cross-machine default together withCODEX_BRIDGE_THREAD_POLICY=roots, so a thread opened by a human is not rejected because its id or the install directory belongs to another machine. A workspace still has to resolve to an existing writable directory before a turn acts on it.scripts/check.mjsnow forwardsCODEX_BRIDGE_THREAD_POLICY, so validation checks the same authorization mode as the MCP server.
[1.11.1] - 2026-08-23
Fixed
-
Re-running
codex-mcp-bridge-installdeleted settings it does not write. It assigned a whole new entry over the old one, soCODEX_BRIDGE_ALLOWED_THREADS, a hand-addedCODEX_BRIDGE_THREAD_POLICYand any key from a later version were dropped, andCODEX_BRIDGE_ALLOWED_ROOTSwas reset to the install directory. Upgrading is exactly when people re-run it, so the command you reach for to keep the bridge current was the command that silently broke it. Measured on a config carrying four custom values: all four gone, roots narrowed from two projects to the install directory, other MCP servers untouched.Existing values are now the fallback rather than the casualty. Precedence, highest first: a variable passed to this run, what the config already says, then the default.
command,argsandCODEX_BINare still resolved fresh — pointing the entry at the code installed now is the reason to re-run at all.--resetdiscards inherited values for the rare case of wanting the defaults back.
Added
- The installer now writes
CODEX_BRIDGE_THREAD_POLICYexplicitly, and when it is left atownedit says what that means: a thread opened in the Codex app or the VS Code extension will answerNOT AUTHORIZED, because its id is assigned as it opens and cannot be allowlisted in advance. Shipping 1.11.0 without this left the fix reachable only by reading the environment table — and the symptom points nowhere near the setting responsible.
[1.11.0] - 2026-08-23
Added
-
CODEX_BRIDGE_THREAD_POLICYselects what authorizes a thread:owned(unchanged default) orroots.Under the only behaviour that existed before, a thread opened in the Codex app or the VS Code extension was not merely restricted - it was unreachable. Codex assigns the thread ID at the moment it opens, so the ID cannot have been listed in
CODEX_BRIDGE_ALLOWED_THREADSbeforehand, and the bridge-owned set lives in memory and empties on every MCP server restart. The listing showed those threads, because listing is gated on the workspace, and then every send into one answerednot authorized. On a machine with ten live threads, nine of them were unreachable and the tenth only because the bridge had just created it.rootsgrants on the workspace instead of the ID: a thread already working inside a directory named inCODEX_BRIDGE_ALLOWED_ROOTSis reachable. That is the same containment every tool already enforces on thecwdit is handed, applied to thecwdthe thread reports. It is opt-in so an existing install cannot widen silently on upgrade, and an unknown workspace fails closed exactly like one outside the roots.
Fixed
- Authorization now happens before
thread/resume. Attaching takes the per-thread writer lock away from whoever else has the thread open, so deciding afterwards would have locked a thread on its way to being refused. openInAppno longer raises a thread on screen before that thread is known to be in scope - a refusal that leaked which threads exist.codex_bridge_statusprinted the approval policy under athread policylabel. Two different settings: one was misreported, the other invisible. It now names both.- The
NOT AUTHORIZEDline inlist_codex_threadspointed only atCODEX_BRIDGE_ALLOWED_THREADS, which is the option that cannot work for a thread a human just opened. It now names the policy as well.
[1.10.1] - 2026-08-20
Fixed
claude_bridge_statusadvertisedclaude-bridge 1.3.0inside a 1.10.0 package. Seven releases of drift, and the only thing it could tell a bug reporter was a wrong answer about which build was running. The stale constant was the symptom:scripts/sync-version.mjsnamedsrc/index.mjsand the repo-hygiene test checked that same single file, so nothing in the release path ever looked at the second entry point. The sync script now walks both, theversionlifecycle stages both, and the test discovers everysrc/*.mjsdeclaringconst VERSIONrather than naming one - a third bridge added later is covered without editing any of this again. Confirmed red on the previous tree:src/claude-bridge.mjs declares 1.3.0, package.json says 1.10.0.- README said Windows was supported but not covered by CI, while
windows-latesthas been in the matrix since 1.10.0. A README that undersells its own coverage reads as a warning, and it is the first thing anyone evaluating the bridge sees. What stays true is narrower and is now what it says: the Codex to Claude tests skip on Windows because they need unix sockets, and the rest of the suite runs there.
[1.10.0] - 2026-08-20
Added
- The package can be installed instead of cloned:
npm install -g @minhspark/codex-mcp-bridge, or straight from the repository withnpm install -g git+https://github.com/buidangminh23/codex-mcp-bridge.gitfor anyone who would rather not involve a registry. Measured end to end on a clean directory before this was documented: 94 packages, both server bins resolve, and the server prints its ready line. - Two installer bins,
codex-mcp-bridge-installandclaude-mcp-bridge-install, so a copy installed as a package can do the wiring withoutnode scripts/...paths intonode_modules. Both installer scripts gained the shebang this requires. publishworkflow, tag-triggered, with provenance and a guard that fails when the tag andpackage.jsonversion disagree..gitattributespinningeol=lf, so a Windows clone and a macOS clone stop producing different bytes for the same file.windows-latestin the CI matrix.- The publish workflow authenticates with npm through OIDC trusted publishing, so the repository stores no access token at all. npm attaches provenance automatically in that mode, so the
provenanceflag came back out ofpublishConfig- it would also have broken the one publish that cannot use OIDC, which is the first one. Note the version pin: trusted publishing needs npm 11.5.1 or newer and Node 22 still bundles npm 10.9.x, so the publish job runs Node 24 and fails early with a clear message if npm is older. npm versionnow rewrites theVERSIONconstant insrc/index.mjsand stages it, via aversionlifecycle script. The repo-hygiene test has always required the two to match; keeping them in step by hand was an avoidable way to fail a release.- Workflows pin
actions/checkout@v7andactions/setup-node@v7. The v4 pair targets Node.js 20, which GitHub deprecated and now force-runs on Node 24 with a warning on every job. The platform layer has Windows-specific branches and this is where the bridge is most used, so leaving it untested was the wrong gap to carry.
Changed
- Package renamed to
@minhspark/codex-mcp-bridge. The unscoped name on npm belongs to an unrelated project by another author, so a scoped name is the only one this package can honestly publish under. The scope is@minhsparkbecause npm only accepts a scope matching the publishing account or an organisation it belongs to, and the account here isminhspark- the GitHub handle and the npm handle are not the same. CODEX_BRIDGE_ALLOWED_ROOTSno longer defaults to the install directory when the package is installed as a dependency — it defaults to the directory the installer was run from, and the installer warns when the roots it wrote point insidenode_modules. The old default produced an entry that started fine and then refused every thread.
Fixed
- The peer bridge ignored
HOMEon Windows.src/peer-protocol.mjsresolved~/.claudethroughos.homedir(), which readsHOMEon macOS and Linux butUSERPROFILEon Windows. A Windows user whoseHOMEpoints somewhere else - the default for Git Bash and MSYS shells - had the bridge look for Claude Code sessions and transcripts in a directory that holds neither, and get an empty list with no error. It now resolves the home directory through the samehomeDir()helper as the rest of the code, so all three platforms agree. filesnow limits the tarball to what a consumer runs. Before this,npm packshipped 37 files including.github/, the whole test suite, and a stray tooling directory carrying a second, older copy of the source. It now ships 17 files, 45.6 kB packed.- Two tests could never pass on Windows and had gone unnoticed because CI never ran there: the Claude Desktop config assertion assumed the path follows
HOMEwhen Windows correctly followsAPPDATA, and the symlink containment test needs a privilege Windows withholds from an unelevated process. The first now pointsAPPDATAinto its sandbox; the second skips with a stated reason instead of reporting a containment failure that never happened.
[1.9.6] - 2026-08-19
Changed
- The M8ven badge now requests
?variant=verified, which their listing page documents as the way to show the verified mark without the letter grade. It has no effect today: with cache-busting query strings,?variant=verified,?variant=nonsenseand no variant at all return byte-identical 1017-byte SVGs still readingC · Emerging, and the edge cache advertisesnetlify-vary: query=__nextDataReq|_rsc, so the parameter never reaches the application. The URL is written the documented way regardless, so it starts behaving correctly the moment they fix it rather than needing another commit here. The listing itself is claimed and verified, which the badge does show.
[1.9.5] - 2026-08-19
Added
- M8ven Trust Index badge in the README, linking to the third-party audit of this server. Two of that audit's findings were real and are fixed in 1.6.0 (missing annotation hints, no test suite); a third - "11 of 14 tool handlers declare input schemas" - is a scanner artefact: all 14 declare
inputSchema, and the three counted as missing are empty because those tools take no parameters. The publisher has been told.
[1.9.4] - 2026-08-19
Changed
CLAUDE.mdremoved; its contributor guidance now lives inCONTRIBUTING.md. A file named for one vendor's agent reads as part of one person's toolchain rather than as this project's conventions, which is the wrong shape for a public repository. Nothing was dropped: how to tell which checkout you are in, thenpm testgate, the annotation contract every tool must satisfy, the rule that nothing here may depend on one person's setup, and how to get the app-server schema instead of guessing at it - all of it moved, under the name a contributor already knows to look for.
[1.9.3] - 2026-08-19
Added
test/repo-hygiene.test.mjsfails the build on an instruction that only works inside one person's setup: a link to a private repository, or a reference to a personal rule, memory or skills file kept outside this project. A public repository cannot lean on a private one - an instruction pointing somewhere the reader cannot open is a dead end wearing the clothes of a rule. Verified by adding such a reference and watching the suite go red at that line.
[1.9.2] - 2026-08-19
Added
open_codex_threadandopenInAppwarn when the bridge is still holding the thread's writer lock. The app-server takes that lock when it loads a thread and keeps it until it exits, so opening the same thread in the Codex app produces a message with no cause attached to it - the app only says the thread is open somewhere else, and the bridge is the somewhere else. The warning names the thread and the way out (stop_codex_app_server) at the moment of opening, which is the moment the reader can still act on it.stop_codex_app_servernow says it released the writer locks too, not only the~/.codexstate.CodexAppServerClient.holdsThread()and coverage for it: attaching takes the claim, creating a thread takes it too, and a dropped connection drops it - because the lock died with the app-server and continuing to claim it would be a lie.
[1.9.1] - 2026-08-19
Changed
- Nothing tracked here names a real home directory, volume or checkout any more.
CLAUDE.mddocumented one contributor's machines by absolute path and the changelog quoted the same drive letter and mount point. To anyone else cloning the repository that reads as an instruction rather than as one person's setup. The same guidance is now stated as the situation it actually is - a tree reachable at more than one path, read-only on the macOS side of a shared NTFS drive - together with the two commands that tell you which copy you are in.
Added
test/repo-hygiene.test.mjsfails the build on a path naming a real home directory, and on a real volume name in prose. Fixtures may still use invented volume labels, because a test has to hand the code under test a concrete string. Verified by injecting a real path and watching the suite go red.
[1.9.0] - 2026-08-19
Security
- Thread operations are deny-by-default. Existing threads require an exact ID in
CODEX_BRIDGE_ALLOWED_THREADS; newly created threads are authorized only for the lifetime of that bridge process. Reading, sending, interrupting and opening all enforce that capability check. - Listing is gated on the workspace root instead, because gating it on the same allowlist left no path to a thread id at all: an id cannot be allowlisted before it is known, and the bridge is the only thing that can report it, so the only usable thread was one the bridge had created itself. Naming a root in
CODEX_BRIDGE_ALLOWED_ROOTSis the operator declaring that project in scope, which is what makes the id safe to disclose - acting on it still needs the allowlist, and every listed row says so when it is missing. A cwd this machine cannot resolve stays out of the listing: containment is decided on the real path, and a directory that is not there cannot be shown to be inside the root. - Working directories are confined.
CODEX_BRIDGE_ALLOWED_ROOTSis required for thread creation and every authorized thread's cwd is checked against it, including symlink canonicalization and traversal attempts. Callers can no longer supply arbitrary approval or sandbox settings; new threads use the bridge's safe policy (on-requestplusworkspace-writeby default). - Automatic approval is disabled by default.
CODEX_BRIDGE_APPROVAL=approvenow requires the explicitCODEX_BRIDGE_AUTO_APPROVE_ACK=1acknowledgement. - App-server endpoints are loopback-only. The bridge rejects non-loopback
CODEX_APP_SERVER_URLvalues because its WebSocket transport does not implement remote authentication.
Added
- Security-policy regression coverage for thread capabilities, workspace containment, endpoint validation, approval defaults, and the split between listing a thread and acting on one.
[1.8.0] - 2026-08-19
Changed
- No drive letter or volume label is blessed any more. 1.7.0 still shipped one machine's mount point and drive letter as defaults, which is a storage layout wearing a configuration hat. A path now counts as coming from another machine by its shape — a drive letter (
D:\project) or an attached volume (/Volumes/<label>/,/mnt/<label>/,/media/<user>/<label>/) — so every dual-boot and external-disk setup is handled without configuring anything. - The path as given is tried first. Rewriting a directory this machine can already write to would be guessing over an explicit instruction. Rewriting now only happens for a path this machine cannot use, which is exactly the case it exists for: macOS mounts NTFS read-only (measured:
EROFSon the mount this was built for), so the drive a Windows brief quotes is visible and useless at the same time. This is what makes recognising every volume safe rather than reckless.
Removed
CODEX_BRIDGE_SHARE_MOUNTandCODEX_BRIDGE_SHARE_DRIVE, added in 1.7.0 earlier the same day. Generic detection makes them dead knobs, and a dead knob in the documentation costs more than it saves.CODEX_BRIDGE_WORKSPACE_ROOTSandCODEX_BRIDGE_REMAPstill cover overriding and opting out.
Verified
- Every path that resolved under the hardcoded version resolves to the same directory: the mounted-drive and drive-letter forms of a repo both reach the checkout beside the bridge, another project reaches its
$HOME-level checkout, and a nonexistent project still fails with the list of what was tried.
[1.7.0] - 2026-08-19
Changed
- The cwd remapping no longer hardcodes one developer's directory layout.
remapCandidates()used to probe a literal$HOME/<a developer's own folder>/<project>, which is a fact about one machine sitting in the source of a public repository. The second candidate is now derived from where the bridge itself is checked out: a bridge at~/code/codex-mcp-bridgemakes~/codethe place to look for a sibling project. That is a measurement rather than a guess, and it needs no configuration to be right. Verified unchanged on the machine the hardcoded value came from — every path that resolved before resolves to the same directory now.
Added
CODEX_BRIDGE_SHARE_MOUNTandCODEX_BRIDGE_SHARE_DRIVE— the two halves of the dual-boot pair the remapping bridges, previously fixed at one machine's mount point and drive letter. Those remain the defaults; a drive letter is normalised, sod,DandD:all mean the same thing.CODEX_BRIDGE_WORKSPACE_ROOTS— take over the search entirely with an explicit, ordered,path.delimiter-separated list. It replaces the derived roots rather than adding to them, so the order is exactly what was written.- Candidate lists are deduplicated, so a bridge checked out directly in
$HOMEno longer probes the same directory twice. CODEX_BRIDGE_REMAP,CODEX_BRIDGE_SHARE_MOUNTandCODEX_BRIDGE_SHARE_DRIVEare read per call instead of at import, so a client that changes the environment does not have to restart the bridge to be believed — and so the behaviour is testable in-process.- Five tests covering the derived root, the explicit override and its ordering, a reconfigured mount and drive letter, and the
CODEX_BRIDGE_REMAP=0opt-out.
[1.6.0] - 2026-08-19
Fixed
- A failed
turn/startkilled the whole MCP server.runTurnrejected its internal completion promise from the catch block, but on that path nothing is awaiting it —await donesits after theturn/startcall that just threw. Node treats an unhandled rejection as fatal by default, so the process exited while the tool handler was still formatting a tidy error message for a client that no longer had a server to talk to. Sending into a thread the Codex desktop app holds open (thread <id> already has an active writer) is the everyday way to trigger it. The promise is now resolve-only. Measured: the same failure used to exit the process with code 1; it now returns an error and the server stays up. start_codex_threaddeclaredapprovalPolicyandsandboxwith no descriptions, leaving a caller to guess that anything other thanapprovalPolicy: "never"stalls an unattended turn on the first approval prompt.
Added
- Annotation hints on all 14 tools (
readOnlyHint,destructiveHint,idempotentHint,openWorldHint). Clients decide whether a call needs a human in the loop from these, and a tool without them reads as an unknown quantity — the wrong default for tools that reach another agent with shell access. Two are worth naming:read_claude_inboxempties the inbox as it reads it, so it is not read-only despite the name, andclaude_bridge_statusregisters the peer endpoint on first call, so it writes too. - A real test suite:
npm test, 96 tests across 7 files, no Codex install or quota needed. Connection behaviour runs against the fake app-server; anything touching~/.claudeor~/.codexruns against a throwawayHOME. Covers the tool contract, all 10 server requests, connection recovery, the turn state machine, the peer protocol over a real unix socket, platform resolution, and repository hygiene. - GitHub Actions runs
npm teston every push and pull request, across Node 22 and 24 on Linux and macOS. test/repo-hygiene.test.mjsfails the build if an environment file or build output is ever committed, if the version insrc/index.mjsdrifts frompackage.json, or if documentation stops being English.
Changed
- The repository is English-only.
README.en.mdmerged back intoREADME.md; the changelog translated. README.mddocuments every install path end to end, including Claude Code (claude mcp add), which was previously undocumented, plus prerequisites, verification and uninstall commands for each platform.scripts/check-approvals.mjsandscripts/check-reconnect.mjsbecametest/server-requests.test.mjsandtest/reconnect.test.mjs;scripts/fake-app-server.mjsmoved totest/helpers/. The fake app-server now binds an ephemeral port, so test files running in parallel cannot collide.
[1.5.0] - 2026-08-18
Fixed
- A turn that lost its connection sat idle until its timeout expired — four minutes by default.
runTurnwaits for aturn/completednotification, which can only arrive over a live socket; a dead socket wakes nobody. This is the everyday case after a machine wakes up: the old app-server died with the previous login session while the bridge kept waiting. The client now signals the break throughsubscribeDisconnect()and the turn ends immediately with statusdisconnectedplus a hint to re-read the thread. Measured: 20,004 ms → 302 ms. - The old socket's
onclosewiped the new one. The handler setthis.ws = nullunconditionally, so a latecloseevent from the previous socket destroyed the healthy connection a reconnect had just established and rejected all of its pending requests. It now only cleans up whenthis.ws === ws. - No retry at boot. A freshly started machine produces transient failures: the app-server is still opening its sqlite state, or an old one is shutting down but still answering
/readyz.connect()now retries once (750 ms apart) instead of failing the tool call and making the user repeat it. A handshake that breaks mid-way counts as an error rather than hanging for the full 15s timeout.
Added
npm run check:reconnect— 9 assertions against a fake app-server: reconnecting after a drop, no leaked pending requests or listeners, an interrupted turn exiting promptly, and a refused first handshake being retried. Run against 1.4.0 the first two fail.scripts/fake-app-server.mjs— a shared fake app-server for the connection tests (hand-rolled WebSocket, no extra dependency).
[1.4.0] - 2026-08-18
Fixed
-
A turn stopped mid-run as if Codex had paused itself. The app-server waits for the client's reply to each server request before continuing, so an unanswered method does not surface as an error — the turn simply stops.
#handleServerRequestnow answers all 10ServerRequestmethods (taken fromcodex app-server generate-json-schema, identical in codex-cli 0.147 and 0.148). Three used to fall through todefault:and get-32601:item/permissions/requestApproval— Codex asking to widen permissions (writes outside the workspace, network). By far the most common.mcpServer/elicitation/request— an MCP server asking for input.item/tool/call— a dynamic tool call back to the client.
Each method needs the response shape its own schema declares; they are not interchangeable:
commandExecution/fileChangeneed{decision},permissionsneeds{permissions, scope},elicitationneeds{action},tool/callneeds{success, contentItems}.attestation/generateandaccount/chatgptAuthTokens/refreshare refused deliberately — the bridge cannot mint real tokens and does not touch auth. -
Threads opened against the wrong directory. The same project sits at
D:\Xon Windows,/Volumes/<label>/Xwhen that drive is mounted on macOS (read-only), and a separate checkout under$HOMEon macOS.resolveWorkspacePath()picks the candidate that both exists and is writable on the current machine. If nothing usable exists it fails immediately instead of opening a thread somewhere wrong; if the only match is read-only it says so. Disable withCODEX_BRIDGE_REMAP=0. -
The wrong codex build spawned the app-server. On macOS the bridge probed
~/.local/bin/codexfirst and started a 0.147 app-server while Codex Desktop ran 0.148 — two builds writing the same~/.codex/state_5.sqlite. When the desktop app is installed, its own binary now wins.
Added
npm run check:approvals— stands up a fake app-server (hand-rolled WebSocket, no extra dependency), fires all 10 server requests and asserts each reply matches its schema. Run against the unpatched code, exactly the three methods above fail.
[1.3.0] - 2026-08-17
Added
CODEX_BRIDGE_MODELandCODEX_BRIDGE_EFFORT— default model and effort for threads and turns the bridge creates, because Codex Desktop ignoresmodel/model_reasoning_effortin~/.codex/config.tomland runs its own configuration.effortacceptsultra(verified:state_5.sqliteand the rollout both recordultrarather than silently dropping it).codex_bridge_statusprints the default model and effort in effect.install-claude-desktop.mjswrites both variables into the MCP server'senvwhen they are passed.
[1.2.1] - 2026-08-17
Added
stop_codex_app_server— stop the shared app-server after a hand-off so Codex Desktop owns~/.codexalone; the bridge starts a new one when it next needs it.
Fixed
codex_bridge_statusdetects the desktop app's own app-server and warns when a LaunchAgent runs alongside it — two app-servers sharing the~/.codexsqlite state make the Codex app UI stutter (measured at ~11% CPU while idle).isDesktopAppServerRunning()was missing itsexecFileSyncimport and silently always returnedfalse.
Documentation
- Spelled out: do not enable the LaunchAgent while using Codex Desktop; a thread open in the app holds a writer lock; threads created by the bridge have no entry in
session_index.jsonl, so the app shows no title for them.
[1.2.0] - 2026-08-17
Added
claude-bridge— an MCP server that runs inside Codex and talks to a live Claude Code session:list_claude_sessions,send_to_claude_session,read_claude_inbox,read_claude_transcript,bind_codex_thread,claude_bridge_status.src/peer-protocol.mjs— a client for the Claude Code peer protocol (NDJSON over/tmp/cc-socks/<pid>.sock) that registers a peer session so Claude can see it and reply to it.scripts/install-codex-mcp.mjs— register and remove the bridge in~/.codex/config.tomlthroughcodex mcp.scripts/check-claude-bridge.mjs— exercise the Codex → Claude direction, sending for real and waiting for the answer.
Fixed
- The MCP server died when spawned with an empty PATH:
/bin/psis now called by absolute path and a failed peer registration no longer takes the server down (the old symptom was Codex hanging for 60s on everythread/start). - Claude transcripts are found by scanning
~/.claude/projects/instead of rebuilding the directory slug (/mnt/dev_diskbecomes-mnt-dev-disk, which does not preserve_).
[1.1.0] - 2026-08-17
Added
- macOS and Linux support:
src/platform.mjsresolvescodexper platform and rebuilds PATH for child processes. scripts/install-launch-agent.mjs— a LaunchAgent that keeps the app-server alive on macOS.open_codex_threadand theopenInAppparameter — open a thread in the Codex desktop app throughcodex://threads/<id>.codex_bridge_status— report the resolved environment.README.en.mdand the MIT license.
Fixed
install-claude-desktop.mjspicks the right config path for macOS/Windows/Linux and creates the file when it is missing.- Spawning the app-server on macOS/Linux no longer dies at the
#!/usr/bin/env nodeshebang when PATH is trimmed.
[1.0.0] - 2026-08-15
Added
- An MCP server that sends prompts into a live Codex thread through a shared app-server:
send_to_codex_thread,list_codex_threads,start_codex_thread,read_codex_thread,interrupt_codex_turn. - Autostart of the app-server when none is running, and automatic answers to approval requests according to
CODEX_BRIDGE_APPROVAL. scripts/install-claude-desktop.mjs,scripts/check.mjs,scripts/smoke.mjs.