Skip to content

buidangminh23/codex-mcp-bridge

v2.3.2MIT

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 with UPDATE_SETUP_INCOMPLETE after 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's engines requirement.
  • codex-bridge-update no longer refuses with UPDATE_DOWNGRADE_REFUSED when an older copy comes first on PATH and 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_CHANGED because 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_DATA from 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 with BRIDGE_ACCOUNT_CHANGED while its status still said listening. 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_CHANGED now names the provider and the reason when an account could not be read, instead of only saying it changed.
  • codex-bridge-update no 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_DATA value, 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-projects got CLAUDE_SESSION_NOT_READY even with crossSessionInbound set to accept. 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 as refused with CLAUDE_QUEUE_SCOPE_REVOKED. Hardened deployments still do not use queued delivery.
  • codex-bridge-update now updates every other installation it finds on PATH or 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.json under 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 older codex-bridge-update still reinstalls itself: for this first update run npm exec --yes --ignore-scripts --package=@minhspark/codex-mcp-bridge@latest -- codex-bridge-update.

[2.2.0] - 2026-11-06

Added

  • send_to_claude_session can now queue a message for a Claude Desktop session that is not running. With target: "auto", the exact expectedTaskId and a recipient crossSessionInbound of accept, it returns status: "queued" and sent: false instead of CLAUDE_SESSION_NOT_READY. The codex-bridge process 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_delivery accepts the returned queueId and reports queued, dispatching, sent_unconfirmed, reply_received, refused, expired or unknown.

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-mode was 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, refuse or no explicit setting keeps getting CLAUDE_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_unconfirmed means the frame was written to the session's socket. Claude's handling is confirmed only by reply_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-bridge cannot 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 listening while loaded conversations still own the relay sockets. desktop-relay-host.json now says standby in that case and is rewritten when the host takes the sockets over, so ownedSockets stays 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.clientToolList in status results says whether the tool list a client received at connection is still current: current, stale, refreshed or unknown, 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, and automatic reload: current alone 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 with The replacement tool catalog requires an explicit client reconnect. A client that did not declare tools.listChanged still 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-bridge still 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_creation and abandon_claude_creation.
  • The requestId, autoSubmit and trustProject inputs of send_to_claude_session, the CLAUDE_BRIDGE_AUTO_TRUST_PROJECTS setting, and the 64-character creation ID lookup in read_claude_delivery.

Changed

  • Claude delivery now happens only through the direct relay to a running session with send_to_claude_session.
  • send_to_claude_session with target: "new" is refused with CLAUDE_SESSION_CREATION_REMOVED and sent: false, in any case and with surrounding spaces. It opens nothing and is never treated as a session name, even when a session is named new.
  • With no running session in expectedCwd, send_to_claude_session returns CLAUDE_SESSION_NOT_READY with sent: false and asks the user to open the session in Claude Desktop. This now covers target: "auto" without expectedTaskId and an exact identity, both of which returned CLAUDE_SESSION_NOT_FOUND before.
  • 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.mjs no longer treats a handoff that arrived through Computer Use as already authorized.
  • Tool descriptions, inspect_bridge_project and the documentation now say that the user opens Claude sessions.
  • Codex-side creation with start_codex_thread and delegate_to_codex is unchanged.

Migration

  • Codex can no longer open a new Claude conversation by itself. Open the session in Claude Desktop, then send with target: "auto" and expectedCwd, adding expectedTaskId when several tasks match.
  • Remove CLAUDE_BRIDGE_AUTO_TRUST_PROJECTS from your configuration. It no longer does anything.
  • If you enabled message automation, run node scripts/configure-message-automation.mjs --apply --approve-message-automation again. An installed collaboration rule keeps the old text until you do, and --check reports it as out of date.
  • A saved requestId from 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 named new, 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_status kept reporting RELAY_UNREACHABLE with ECONNREFUSED, 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 --remove still stops with Unsafe relay socket file on 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_project no longer reports needs_setup or recommends installing a project policy when the bridge process already authorizes the directory by another supported mode. communicationAuthorization now reports the effective mode and result for the calling process (project-policy, allowed-roots, all-directories, pinned-roots, no-root-restriction), and a new projectPolicy field reports the policy file separately. Installing a policy appears as projectPolicy.optionalMigration for an authorized directory unless policy mode is actually in force. A configured policy stays authoritative and still fails closed. Under thread policy owned, existingTasks and the detail state that existing tasks stay unreachable until they are allowlisted or the policy changes. bridge-projects inspect now reports not_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_checked and 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}) reports authorizationMode, existingTasks and, 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 change ready, because sending to an existing task does not need a saved project. In pinned-roots mode every native operation needs one, so an unusable result makes ready false with NATIVE_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=roots and no policy: inspection said needs_setup while codex_bridge_status said authorized=true for 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 project refusal 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 Codex mcp command 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 one codex mcp get instead of listing every server first, the verification reads all three registrations from a single codex 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 missing for claude-bridge, codex-native-relay and antigravity-bridge when Codex CLI was merely too slow to answer. A slow inventory now says so, and the three registrations are reported as not checked. Codex mcp commands 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 through codex-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@latest on Windows, or npx -y @minhspark/codex-mcp-bridge@latest on 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 update subcommand 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 --user to pin installation to the per-user npm prefix before inspecting or replacing packages. The recommended Windows command now avoids EPERM when Node resolves its global prefix to Program 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-update no longer stops with UPDATE_SETUP_INCOMPLETE / WORKER_MCP_COLLISION on machines with more than one Node.js installation. The Antigravity worker-relay entry is still recognised as the bridge's own when it launches this package's background-relay-mcp.mjs through another existing node / 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_status and agent_bridge_status now return their full status (version, caller, Desktop sidecar availability, CLI and outbound routes) as structured content. Previously the supervisor attached only its autoReload block 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 autoReload only 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-update orchestration 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 PATH during 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-relay command. 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_CAPACITY with not_sent instead 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-relay command 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: true remains 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_READY with sent: 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-bridge instead 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; set CODEX_BRIDGE_RELAY_KEEPER=1 to 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-desktop connector and user-level Claude Code codex-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-setup and codex-mcp-bridge setup support read-only --check, --dry-run, JSON reports and --no-download. Local dependency installation does not change application configuration; global setup can be skipped with CODEX_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_unavailable and 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_id names 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_unavailable with nextAction: inspect_existing_task and the original receipt, instead of failed. Desktop's own failed or interrupted status is still reported when it belongs to the exact observed turn. wait_codex_reply with responsePreferences returns the same next action plus guidance telling 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 to read_claude_inbox and 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 to read_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-install configures 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-bridge MCP 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-review permissions and both directions between Codex and Antigravity Desktop. The App replied ANTIGRAVITY_DESKTOP_NATIVE_OK; its outbound MCP delivered ANTIGRAVITY_TO_CODEX_DESKTOP_OK to 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_codex lists, 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 load remote_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 0600 before 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_reply with a short timeoutSec no longer fails with The response deadline elapsed while another operation held this thread when 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 with nextAction: 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_threads on a gate that the test releases, instead of a fixed 2.5 s sleep against a 1 s budget. That timing failed on a stalled windows-latest runner.
  • The relay fixture in test/bridge-integration.test.mjs provisions 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-bridge run from Claude Code's Bash tool no longer warns that the installed version could not be verified. Claude Code shell snapshots keep the npm() function from scripts/npm-footer.sh but drop functions whose names start with _, so the separate _codex_bridge_installed_version helper vanished and every install printed Warning: npm completed, but the installed @minhspark/codex-mcp-bridge version could not be verified. even though it succeeded. The version reader now lives inside npm() 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 snapshot loads only typeset -f npm in 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=0 turns off the background check; CODEX_BRIDGE_RELAY_WAKE=0 still 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-connector runs whoami.exe and icacls.exe from %SystemRoot%\System32 instead of looking them up on PATH. Started from Git Bash, it ran GNU whoami, could not read the Windows user SID and refused to protect its files.
  • npm test runs the suite without the caller's CLAUDE*, CODEX_*, ANTHROPIC_* and MCP_* 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-relay only 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 restart codex_bridge_status, list_codex_threads, send_to_codex_thread and delegate_to_codex failed with connect ENOENT .../native-relay.sock-accounts-v2 until 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 through codex://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=0 turns this off. On Windows the bridge recognises Codex Desktop by the packaged OpenAI.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, so open_codex_thread and the open option 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 PowerShell Start-Process, which returns 0 on success and fails when no codex:// 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), and read_codex_thread with a turnId failed. 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 .jsonl when 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), because COPYFILE_FICLONE never clones there.
  • inspect_bridge_project reports a missing CODEX_BRIDGE_PROJECT_POLICY as policy_not_configured with 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_reply and read_codex_thread keep 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, and install-claude-desktop updates that entry instead of adding a second one. Neither claims or removes entries that run another program.
  • The relay companion and claude-bridge drain 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 --remove also removes the account and Desktop task sockets and names the retired executor task.
  • Adding a missing name to an existing env_vars array 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 with open -g codex://threads/<id> started a new codex-native-relay supervisor within about 10 seconds, after which delegate_to_codex created 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 unavailable before 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 passes CODEX_APP_TOOLS_PIPE_PATH on the app-server command line. Windows discovery only looked at codex-browser-use-* pipes, which answer No handler registered for method: tools/call, so the relay companion never opened codex-native-relay-accounts-v2 and every Claude-to-Codex send failed with RELAY_UNAVAILABLE (connect ENOENT). Discovery now also accepts codex-app-tools-* pipes. The existing checks still apply: the pipe must be local, owned by the exact ChatGPT.exe ancestor of the companion's app-server, and answer a read-only list_projects call. 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, resolveNativeToolsPipePath from v1.22.12 returned null and the fixed code returned the live codex-app-tools-* pipe, owned by the Desktop process that started the app-server. list_projects through that pipe returned the saved projects; the five codex-browser-use-* pipes returned No 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-install and codex-native-relay-install used to refuse an existing codex-native-relay entry that had env_vars, the very setting the README told users to add, and codex mcp add drops env_vars and every comment in config.toml. When the environment does not change, the installers now edit only command and args of the existing table in place, read the entry back through codex mcp get --json, and restore the previous file if anything differs. Seen on 2026-10-20: both Codex-side entries still pointed at src/claude-bridge.mjs and src/native-relay-companion.mjs, so claude-bridge stayed 1.22.8 STALE after v1.22.10 until Codex Desktop restarted.
  • On Windows and macOS, codex-native-relay-install adds CODEX_APP_TOOLS_PIPE_PATH to the relay's env_vars itself, 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 add when that loses nothing; if the relay's env_vars cannot then be added, the installer says so instead of failing. Datetimes written with a space instead of T no 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_UNCONFIRMED for 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 with RELAY_RELOADING (no message sent), and reads peer messages into the inbox that the next worker restores. A relay client answered with RELAY_RELOADING during 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 codex and a live-shaped config.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 with write EPIPE and 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-line args array with comments, a rerun and a fresh install. Only command, args and the added env_vars changed.

  • 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.toml through 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 remaining js/path-injection reports on the config and relay socket paths come from operator configuration (CODEX_HOME, CODEX_NATIVE_RELAY_SOCKET or 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 exact command and args to set by hand.

[1.22.11] - 2026-10-20

Fixed

  • Stop claude-bridge and 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.mjs already 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. Each npm test run 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-bridge unregisters 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-bridge and 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 test runs on macOS left no process from a mcp-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 failed while 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, because incomplete final record can 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^60 and 2^60 + 1) is rejected and left untouched, and a transcript reply is observed while its Number mtimeMs and size stay frozen. Both fail on v1.22.8.
  • Two independent sweeps of src/, scripts/ and bin/, 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-injection flows 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, size and nanosecond mtime/ctime as bigint. Number stats round inodes above 2^53, which NTFS file IDs and some macOS volumes (such as /tmp on the sealed system volume) exceed, so a replaced file or directory could pass as unchanged; this made rejects replacement of a pinned receipt directory fail 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^60 and 2^60 + 1) compare as different for both ino and dev; 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 12 js/path-injection flows on the edited stat lines; each source is operator process.env configuration, 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 opt paths instead of a versioned Cellar keg when the Claude Desktop, Codex and native relay installers and bridge-projects register-manager write a client configuration, for both the bridge and Homebrew's Node.js. A keg path broke every registration as soon as brew upgrade removed 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 opt alias. 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 opt alias, 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 opt mapping, a custom HOMEBREW_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-bridge and opt/node (the relay keeps Codex Desktop's Node). A bridge launched from the recorded Claude Desktop entry kept its supervisor through brew upgrade and brew cleanup and reloaded the new keg; fresh launches from the recorded paths answered initialize.
  • 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-install still refuses to rewrite an entry that has env_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_codex and start_codex_thread now 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: accepted instead of unconfirmed.

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-level delegate_to_codex tests 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_reply and 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 test passes 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_thread snapshots when the wait_threads renderer 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 turnId for 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.1 and 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_project and prepare_bridge_project, with shared project grants, registered worktree support and explicit revocation.
  • Add bridge-projects for project policy management and codex-bridge-code-install for 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.0 and 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_POLICY JSON 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-access installer 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.toml whose allowed_sandbox_modes omits read-only before auto-starting an external app-server. The bridge and npm run check now 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 analytics branch with the Repository analytics workflow's own token. Its hourly commits were pushed with ANALYTICS_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 from github-actions[bot]. ANALYTICS_TOKEN only 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_thread omits cwd or 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 no node_modules of its own, and preparing the immutable runtime failed with ENOENT (scandir …node_modules) since 1.15.0; only global installs, which keep a nested node_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 an npm install that 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_desktop as 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_desktop tasks 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_TIMEOUT before 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 as INSPECTOR_START_TIMEOUT. The helper also writes its JSON itself, so the timed read no longer loads PowerShell's JSON serializer.
  • Lock ip-address at 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 requestId UUID on delegate_to_codex and start_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 fresh requestId creates 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 without requestId keep the previous deduplication. Legacy app-server mode rejects requestId before 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 managed permission profile, a workspace-write sandbox, and a granular approval 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 with CODEX_SENDER_CONTEXT_UNVERIFIED. A managed profile whose file system is restricted now attests prompting with a user or auto_review reviewer and any approval policy, matching Claude, which counts dontAsk and auto as prompting; it can never attest bypass, which still requires Full access with approval_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 stable granular(<allowed categories>) label, and claude_bridge_status shows the sender's permission profile and approval reviewer, which a queued send now also pins. A class mismatch against a Claude task in bypassPermissions names 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 returns video/mp4 and image/gif with 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 through read_claude_creation. The official Desktop link requires user confirmation and Send; opening a composer is reported as awaiting_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 use send_to_claude_session with target: "new" and inspect its request ID through read_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 procStart instead of procStartFt. 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_uuid is unrelated to the peer message ID. Version 1.13.8 incorrectly rejected that valid legacy format. Use the matching peer origin.msg_id as 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_uuid on Claude Code 2.1.260 and later and by origin.msg_id on 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_command attachment whose source_uuid is 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 reported reply_timeout and kept the message pending. Both shapes now resolve to the turn's closing text. A reply taken from an absorbed turn is marked replyAbsorbed: true in 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 with CLAUDE_RECIPIENT_INBOUND_POLICY when it is refuse or hold; an explicit accept sends without a class check. Otherwise read the recipient task's permission mode from Claude Desktop metadata, report it with its Claude parity class in list_claude_sessions, and refuse with CLAUDE_RECIPIENT_CLASS_MISMATCH when 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 carry senderApprovalPolicy, recipientPermissionMode, recipientPermissionClass, and recipientInboundPolicy, and a held receipt names both classes.

Changed

  • Document Claude's symmetric inbound parity: a prompting-class Desktop recipient holds a bypass sender just as a bypassing recipient holds a prompting one, so a held receipt 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 setting crossSessionInbound to accept there. The bridge never adjusts the attested class. Describe node_repl_auto_review_required as the per-model catalog attribute observed live alongside a user reviewer, note that auto_review_enabled: true with 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_required is a Codex model-catalog requirement (gpt-6-astra cannot run without auto review) and auto_review_enabled names an automated Guardian reviewer; neither adds a human prompt, so a verified full-access approval_policy: never sender is bypass whichever review flags the host sets. Since 1.13.5 such senders were downgraded to prompting, and a bypassing Claude Desktop recipient held every message behind a peer_inbound_approval dialog 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-bridge MCP 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 as dynamic_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_NODE overrides 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 expectedCwd when sending to Claude. A held receipt still requires the recipient's approval; inspect its msgId with read_claude_delivery instead 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 --version and -v on every packaged command without starting servers, opening sockets, or mutating client configuration.
  • Preserve PowerShell's $? and conditional &&/|| behavior as well as $LASTEXITCODE by 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-install backs 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 loadedOnly queries 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_codex creates a task in the exact saved local project and opens it while running. send_to_codex_thread continues through Desktop without a second writer. start_codex_thread accepts an initial prompt and requires it in Desktop mode.
  • Enable with codex-native-relay-install --desktop-tasks or CODEX_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:claude command 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 held receipt; 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.env override 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/call with distinct executor and destination thread IDs, fresh call/turn IDs, and a UInt32LE length prefix. A response must explicitly report success: 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_thread and 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's thread/resume was refused with thread <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-relay is 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-bridge reaches it over a private mode-0600 unix socket at ~/.codex/native-relay.sock and sends exactly { targetThreadId, message }.

    codex_app.send_message_to_thread runs 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.mjs creates it once, records it in ~/.codex/native-relay.json, and stops the app-server it borrowed so no lock is left held. Resolution is CODEX_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, CodexAppServerClient and 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 with CODEX_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 ~/.codex state before failing on the very writer lock the native path exists to avoid.

  • claude_bridge_status and bind_codex_thread report the backend in force, and carry the reason when it is not the native one - a missing companion socket, an explicit 0, and an unsupported platform are three different problems that otherwise look identical from the outside.

  • native_relay_status on the companion reports its socket, its executor thread and the dispatch method. npm run install:relay / npm run uninstall:relay register and remove it.

Security

  • The relay socket is created mode 0600 inside 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_thread and the Codex Desktop native tools pipe are internals with no public documentation, on the same footing as the Claude peer protocol in src/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 are NATIVE_DISPATCH_METHOD and nativeDispatchParams() in src/native-relay.mjs, and CODEX_NATIVE_RELAY_METHOD overrides 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-socks has no Windows equivalent, and path.join rewrote it to \tmp\cc-socks on the system drive, where listen() fails with EACCES. 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-uri is bumped to 3.1.7 and qs to 6.16.0. fast-uri 3.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.0 and v1.11.1 published all three to npm, while the Releases page still showed v1.10.0 as 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.mjs prints one version's changelog section, and a test asserts the version in package.json has 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_codex now gives Claude a single contract for handing work to Codex: it creates the thread at the requested project directory, names it through thread/name/set, returns the exact threadId and cwd, releases the bridge writer lock after a terminal turn, and opens the Windows or macOS codex:// deep link when configured. Windows app-server shutdown uses netstat and taskkill instead of the Unix-only lsof path, 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 with CODEX_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.mjs now forwards CODEX_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-install deleted settings it does not write. It assigned a whole new entry over the old one, so CODEX_BRIDGE_ALLOWED_THREADS, a hand-added CODEX_BRIDGE_THREAD_POLICY and any key from a later version were dropped, and CODEX_BRIDGE_ALLOWED_ROOTS was 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, args and CODEX_BIN are still resolved fresh — pointing the entry at the code installed now is the reason to re-run at all. --reset discards inherited values for the rare case of wanting the defaults back.

Added

  • The installer now writes CODEX_BRIDGE_THREAD_POLICY explicitly, and when it is left at owned it says what that means: a thread opened in the Codex app or the VS Code extension will answer NOT 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_POLICY selects what authorizes a thread: owned (unchanged default) or roots.

    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_THREADS beforehand, 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 answered not authorized. On a machine with ten live threads, nine of them were unreachable and the tenth only because the bridge had just created it.

    roots grants on the workspace instead of the ID: a thread already working inside a directory named in CODEX_BRIDGE_ALLOWED_ROOTS is reachable. That is the same containment every tool already enforces on the cwd it is handed, applied to the cwd the 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.
  • openInApp no longer raises a thread on screen before that thread is known to be in scope - a refusal that leaked which threads exist.
  • codex_bridge_status printed the approval policy under a thread policy label. Two different settings: one was misreported, the other invisible. It now names both.
  • The NOT AUTHORIZED line in list_codex_threads pointed only at CODEX_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_status advertised claude-bridge 1.3.0 inside 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.mjs named src/index.mjs and 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, the version lifecycle stages both, and the test discovers every src/*.mjs declaring const VERSION rather 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-latest has 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 with npm install -g git+https://github.com/buidangminh23/codex-mcp-bridge.git for 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-install and claude-mcp-bridge-install, so a copy installed as a package can do the wiring without node scripts/... paths into node_modules. Both installer scripts gained the shebang this requires.
  • publish workflow, tag-triggered, with provenance and a guard that fails when the tag and package.json version disagree.
  • .gitattributes pinning eol=lf, so a Windows clone and a macOS clone stop producing different bytes for the same file.
  • windows-latest in 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 provenance flag came back out of publishConfig - 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 version now rewrites the VERSION constant in src/index.mjs and stages it, via a version lifecycle 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@v7 and actions/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 @minhspark because npm only accepts a scope matching the publishing account or an organisation it belongs to, and the account here is minhspark - the GitHub handle and the npm handle are not the same.
  • CODEX_BRIDGE_ALLOWED_ROOTS no 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 inside node_modules. The old default produced an entry that started fine and then refused every thread.

Fixed

  • The peer bridge ignored HOME on Windows. src/peer-protocol.mjs resolved ~/.claude through os.homedir(), which reads HOME on macOS and Linux but USERPROFILE on Windows. A Windows user whose HOME points 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 same homeDir() helper as the rest of the code, so all three platforms agree.
  • files now limits the tarball to what a consumer runs. Before this, npm pack shipped 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 HOME when Windows correctly follows APPDATA, and the symlink containment test needs a privilege Windows withholds from an unelevated process. The first now points APPDATA into 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=nonsense and no variant at all return byte-identical 1017-byte SVGs still reading C · Emerging, and the edge cache advertises netlify-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.md removed; its contributor guidance now lives in CONTRIBUTING.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, the npm test gate, 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.mjs fails 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_thread and openInApp warn 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_server now says it released the writer locks too, not only the ~/.codex state.
  • 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.md documented 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.mjs fails 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_ROOTS is 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_ROOTS is 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-request plus workspace-write by default).
  • Automatic approval is disabled by default. CODEX_BRIDGE_APPROVAL=approve now requires the explicit CODEX_BRIDGE_AUTO_APPROVE_ACK=1 acknowledgement.
  • App-server endpoints are loopback-only. The bridge rejects non-loopback CODEX_APP_SERVER_URL values 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: EROFS on 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_MOUNT and CODEX_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_ROOTS and CODEX_BRIDGE_REMAP still 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-bridge makes ~/code the 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_MOUNT and CODEX_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, so d, D and D: 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 $HOME no longer probes the same directory twice.
  • CODEX_BRIDGE_REMAP, CODEX_BRIDGE_SHARE_MOUNT and CODEX_BRIDGE_SHARE_DRIVE are 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=0 opt-out.

[1.6.0] - 2026-08-19

Fixed

  • A failed turn/start killed the whole MCP server. runTurn rejected its internal completion promise from the catch block, but on that path nothing is awaiting it — await done sits after the turn/start call 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_thread declared approvalPolicy and sandbox with no descriptions, leaving a caller to guess that anything other than approvalPolicy: "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_inbox empties the inbox as it reads it, so it is not read-only despite the name, and claude_bridge_status registers 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 ~/.claude or ~/.codex runs against a throwaway HOME. 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 test on every push and pull request, across Node 22 and 24 on Linux and macOS.
  • test/repo-hygiene.test.mjs fails the build if an environment file or build output is ever committed, if the version in src/index.mjs drifts from package.json, or if documentation stops being English.

Changed

  • The repository is English-only. README.en.md merged back into README.md; the changelog translated.
  • README.md documents 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.mjs and scripts/check-reconnect.mjs became test/server-requests.test.mjs and test/reconnect.test.mjs; scripts/fake-app-server.mjs moved to test/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. runTurn waits for a turn/completed notification, 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 through subscribeDisconnect() and the turn ends immediately with status disconnected plus a hint to re-read the thread. Measured: 20,004 ms → 302 ms.
  • The old socket's onclose wiped the new one. The handler set this.ws = null unconditionally, so a late close event 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 when this.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. #handleServerRequest now answers all 10 ServerRequest methods (taken from codex app-server generate-json-schema, identical in codex-cli 0.147 and 0.148). Three used to fall through to default: 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/fileChange need {decision}, permissions needs {permissions, scope}, elicitation needs {action}, tool/call needs {success, contentItems}. attestation/generate and account/chatgptAuthTokens/refresh are 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:\X on Windows, /Volumes/<label>/X when that drive is mounted on macOS (read-only), and a separate checkout under $HOME on 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 with CODEX_BRIDGE_REMAP=0.

  • The wrong codex build spawned the app-server. On macOS the bridge probed ~/.local/bin/codex first 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_MODEL and CODEX_BRIDGE_EFFORT — default model and effort for threads and turns the bridge creates, because Codex Desktop ignores model/model_reasoning_effort in ~/.codex/config.toml and runs its own configuration.
  • effort accepts ultra (verified: state_5.sqlite and the rollout both record ultra rather than silently dropping it).
  • codex_bridge_status prints the default model and effort in effect.
  • install-claude-desktop.mjs writes both variables into the MCP server's env when 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 ~/.codex alone; the bridge starts a new one when it next needs it.

Fixed

  • codex_bridge_status detects the desktop app's own app-server and warns when a LaunchAgent runs alongside it — two app-servers sharing the ~/.codex sqlite state make the Codex app UI stutter (measured at ~11% CPU while idle).
  • isDesktopAppServerRunning() was missing its execFileSync import and silently always returned false.

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.toml through codex 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/ps is 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 every thread/start).
  • Claude transcripts are found by scanning ~/.claude/projects/ instead of rebuilding the directory slug (/mnt/dev_disk becomes -mnt-dev-disk, which does not preserve _).

[1.1.0] - 2026-08-17

Added

  • macOS and Linux support: src/platform.mjs resolves codex per platform and rebuilds PATH for child processes.
  • scripts/install-launch-agent.mjs — a LaunchAgent that keeps the app-server alive on macOS.
  • open_codex_thread and the openInApp parameter — open a thread in the Codex desktop app through codex://threads/<id>.
  • codex_bridge_status — report the resolved environment.
  • README.en.md and the MIT license.

Fixed

  • install-claude-desktop.mjs picks 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 node shebang 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.