@minhspark/codex-mcp-bridge 1.11.2 → 1.12.0

package/CHANGELOG.md

@@ -2,10 +2,81 @@
 
 Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](https://semver.org/).
 
-## [Unreleased]
+## [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

package/README.md

@@ -24,12 +24,17 @@ Codex ───────────────┤ stdio
                      └────────────────────────────────────────────────────────────────────┘
 
 Codex TUI  ──codex --remote ws://127.0.0.1:8791──> same app-server, same live thread
+
+                     ┌──── codex-native-relay (launched by Codex Desktop, macOS) ──────────┐
+claude-bridge ───────┤ unix socket ~/.codex/native-relay.sock       native tools           ├──> the thread already open in Codex Desktop
+                     └────────────────────────────────────────────────────────────────────┘
 ```
 
 - The app-server is a **singleton per port**. The bridge probes `http://127.0.0.1:8791/readyz`; if nothing answers it spawns a detached `codex app-server --listen ws://127.0.0.1:8791`, which keeps running after the bridge exits.
 - Every client pointed at the same URL shares **one app-server**, so `thread/resume` with a `threadId` rejoins the running thread instead of opening a new session.
 - The bridge keeps exactly one WebSocket, calls `initialize` once, and routes notifications by `threadId`, so parallel threads never bleed into each other.
 - `delegate_to_codex` is the one-call Claude → Codex hand-off: it starts the thread at the supplied `cwd`, names it, sends the prompt, stops the bridge app-server after a terminal turn, and opens `codex://threads/<id>` in Codex Desktop when enabled.
+- The **native relay** (macOS, optional) is the third line: a thread the human is watching in Codex Desktop belongs to the app, and a second app-server cannot write to it. Instead of taking the thread away, `claude-bridge` hands the message to a companion the app itself launched, and the app delivers it. See [Codex Desktop native relay](#codex-desktop-native-relay-macos).
 
 ## Requirements
 
@@ -222,7 +227,25 @@ launchctl kickstart -k gui/$UID/com.codex-mcp-bridge.app-server
 
 `CLAUDE_BRIDGE_PEER_NAME` sets the name Claude shows for this bridge in its agent list.
 
-### 5. macOS only: keep the app-server alive with launchd
+### 5. macOS only: the Codex Desktop native relay
+
+Optional, and only worth installing if you keep the bound thread **open in Codex Desktop** while Claude messages back. See [Codex Desktop native relay](#codex-desktop-native-relay-macos) for what it does and why.
+
+```bash
+node scripts/install-native-relay.mjs
+```
+
+This registers the companion with Codex (`codex mcp add codex-native-relay -- <node> src/native-relay-companion.mjs`) and bootstraps the executor thread the native dispatch needs, writing its id to `~/.codex/native-relay.json`. The bootstrap starts a throwaway app-server, creates one thread, and stops the app-server again so nothing is left holding a lock.
+
+```bash
+codex mcp get codex-native-relay
+node scripts/install-native-relay.mjs --no-bootstrap   # register only; supply CODEX_RELAY_ID yourself
+node scripts/install-native-relay.mjs --remove         # unregister, and delete the socket and the thread id
+```
+
+Restart Codex Desktop so it launches the companion, then call its `native_relay_status` tool — or `claude_bridge_status`, whose `delivery:` line names the backend in force. Until both the companion and the executor thread are in place, `claude-bridge` keeps using the app-server path exactly as before.
+
+### 6. macOS only: keep the app-server alive with launchd
 
 > ⚠️ **Do not enable the LaunchAgent while using the Codex desktop app.** The app runs its **own** stdio app-server against the **same** `~/.codex` sqlite state. Two app-servers contend even while idle — measured here: the launchd one burned ~11% CPU doing nothing and **the Codex app UI stuttered**. Keep exactly one alive; `codex_bridge_status` detects and warns about this.
 >
@@ -240,20 +263,21 @@ tail -f ~/Library/Logs/codex-mcp-bridge/app-server.err.log            # logs
 node scripts/install-launch-agent.mjs --uninstall                     # remove
 ```
 
-### 6. Verify the install
+### 7. Verify the install
 
 ```bash
 npm run check          # boots the bridge, autostarts an app-server, lists threads
 npm run check:claude   # lists the live Claude Code sessions Codex can reach
 ```
 
-From inside Claude, call the `codex_bridge_status` tool; from inside Codex, call `claude_bridge_status`. Both print the resolved binary, the endpoint and whether anything is listening.
+From inside Claude, call the `codex_bridge_status` tool; from inside Codex, call `claude_bridge_status`. Both print the resolved binary, the endpoint and whether anything is listening. `claude_bridge_status` also prints a `delivery:` line naming the backend that would carry a relayed message, and the reason when it is not the native one.
 
-### 7. Uninstall everything
+### 8. Uninstall everything
 
 ```bash
 claude mcp remove codex-bridge --scope user
 node scripts/install-codex-mcp.mjs --remove
+node scripts/install-native-relay.mjs --remove
 node scripts/install-launch-agent.mjs --uninstall
 ```
 
@@ -334,6 +358,14 @@ There is no token in the frame — **the socket is mode `0600`, so owning the us
 
 The relay has two hard limits in `src/claude-bridge.mjs`: at most **one message every 5s** and **50 per bridge run**. Two agents left talking to each other unattended still come to a stop.
 
+## Tools — `codex-native-relay` (launched by Codex Desktop, macOS)
+
+| Tool | What it does | Hints |
+|---|---|---|
+| `native_relay_status` | Reports the local socket the companion listens on, the executor thread it dispatches through, and the dispatch method in force. | read-only |
+
+The companion carries no work of its own. Its job is the socket and the dispatch; everything a human asks for still goes through the two bridges above.
+
 ## macOS notes
 
 ### Watch a thread in the Codex desktop app
@@ -347,10 +379,58 @@ send_to_codex_thread { threadId: "01a0…", prompt: "…", openInApp: true }
 
 This is how a human watches Codex work in real time instead of reading the rollout at `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl` after the fact.
 
+### Codex Desktop native relay (macOS)
+
+`bind_codex_thread` relays every message Claude sends into a Codex thread. That works — until the thread is one **you are watching in Codex Desktop**, which is the case it was built for. Codex takes a per-thread writer lock when the app loads a thread and holds it for as long as the thread is open, so the app-server path, which has to `thread/resume` before it can send, is refused:
+
+```
+thread <id> already has an active writer
+```
+
+Closing the thread first is not a fix. It is the opposite of the point: Codex Desktop is meant to stay the permanent owner of the thread and the surface the human is looking at.
+
+The native relay removes the second writer rather than fighting it. A companion MCP process, **launched by Codex Desktop's own app-server**, already sits inside the app's context, so it can ask that app-server to deliver the message. Nothing attaches, nothing resumes, no second app-server starts, and the lock never changes hands:
+
+```
+Claude
+  → claude-bridge
+  → ~/.codex/native-relay.sock          (unix socket, mode 0600)
+  → codex-native-relay                  (launched by Codex Desktop's app-server)
+  → codex_app.send_message_to_thread    (over that same connection)
+  → the thread already open in Codex Desktop
+```
+
+**The executor thread.** `codex_app.send_message_to_thread` runs against an executor thread, and that thread is not the destination — it is validated, so a synthetic UUID is rejected with `NATIVE_DISPATCH_FAILED`. A dedicated relay thread keeps that requirement away from the thread you are watching. It is created once by `scripts/install-native-relay.mjs` and recorded in `~/.codex/native-relay.json`:
+
+```json
+{ "relayThreadId": "<uuid>" }
+```
+
+Resolution order is `CODEX_RELAY_ID` → that file → an error naming both. Never a guess: an invented executor fails inside Codex with a message that says nothing about the configuration that actually caused it. The recorded thread works as an executor even if it has never been opened in the app.
+
+**It is a backend, not a replacement.** `claude-bridge` picks between two delivery backends and reports which one it used; the tools, the peer protocol, the routing, the rate limits and `CodexAppServerClient` are untouched. The native path is used only when all of these hold — otherwise the app-server path runs exactly as it did before:
+
+| Condition | Otherwise |
+|---|---|
+| macOS | the app-server path (`CODEX_BRIDGE_NATIVE_RELAY=1` forces the attempt anyway) |
+| `CODEX_BRIDGE_NATIVE_RELAY` is not `0` | switched off by hand |
+| `~/.codex/native-relay.sock` exists and is a socket | the companion is not installed, or Codex Desktop is not running |
+
+A companion that cannot be reached 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 and then fail on the very writer lock this backend exists to avoid.
+
+> ⚠️ `codex_app.send_message_to_thread` and the native tools pipe are **Codex Desktop internals with no public documentation**, on the same footing as the Claude peer protocol above. That is why the relay is macOS-only, feature-detected, optional and fallback-safe. If Codex changes it, the two places to fix are `NATIVE_DISPATCH_METHOD` and `nativeDispatchParams()` in `src/native-relay.mjs`; `CODEX_NATIVE_RELAY_METHOD` overrides the method name without a release. The request the companion sends is:
+>
+> ```json
+> {"jsonrpc":"2.0","id":1,"method":"codex_app.send_message_to_thread",
+>  "params":{"executorThreadId":"<relay thread>","threadId":"<destination>","message":"..."}}
+> ```
+
+**Security.** The socket is mode `0600` inside `~/.codex`, and that file mode is the entire boundary — the same one the Claude peer protocol relies on. Anything able to open it can put text into a Codex thread, so it is created private and swept on exit. The companion accepts exactly one shape, `{ targetThreadId, message }`, caps a frame at 128 KiB, and refuses a destination that is its own executor thread — otherwise a mistaken bind would deliver into the invisible relay thread and report success.
+
 ### Caveats
 
-- The Codex desktop app runs its own app-server over stdio (`ChatGPT.app/Contents/Resources/codex … app-server`, **no** `--listen`), so nothing external can attach to it. `~/.codex/ipc/ipc.sock` is the Electron app's internal IPC, not an app-server. Threads opened there can still be driven through the bridge, but by resuming from the rollout `.jsonl` rather than attaching live.
-- **A thread currently open in the desktop app cannot be written to** — Codex holds a per-thread writer lock (`~/.codex/thread-writer-locks/`) and returns `thread <id> already has an active writer`. That error is the guard working, not data loss. Check `status` with `list_codex_threads` first and only send when it is `idle` or `notLoaded` and not open in the app.
+- The Codex desktop app runs its own app-server over stdio (`ChatGPT.app/Contents/Resources/codex … app-server`, **no** `--listen`), so nothing external can attach to it. `~/.codex/ipc/ipc.sock` is the Electron app's internal IPC, not an app-server. Threads opened there can still be driven through the bridge, but by resuming from the rollout `.jsonl` rather than attaching live. The [native relay](#codex-desktop-native-relay-macos) is not an exception to this: the companion never attaches to that app-server, it is *launched by* it as one of the app's own MCP servers.
+- **A thread currently open in the desktop app cannot be written to** through a second app-server — Codex holds a per-thread writer lock (`~/.codex/thread-writer-locks/`) and returns `thread <id> already has an active writer`. That error is the guard working, not data loss. Check `status` with `list_codex_threads` first and only send when it is `idle` or `notLoaded` and not open in the app. For the Claude → Codex relay specifically, the [native relay](#codex-desktop-native-relay-macos) removes the second writer instead of waiting for the lock.
 - **Bridge-created threads are named before they are opened.** The bridge calls the app-server's `thread/name/set` with the requested title, or derives `[project] first line of prompt`, then opens the exact `codex://threads/<id>` link. This gives Codex Desktop a visible session title and preserves the precise `cwd` in the thread metadata.
 - A repo living on the NTFS partition of a dual-boot machine (`/Volumes/<label>/...`) is **read-only** under macOS. Keep a separate checkout on an APFS volume to run and edit it.
 - `codex app-server daemon start` uses the `unix://` transport with a control socket at `~/.codex/app-server-control/app-server-control.sock`. The bridge does **not** use that path (different framing, no public API) — it always talks over `ws://`.
@@ -374,7 +454,9 @@ python3 -c "import json;[print(v['properties']['method'].get('const') or v['prop
 
 **The bridge disappears from Claude after sending into a busy thread.** Fixed in 1.6.0. A rejected `turn/start` — which is exactly what a thread locked by the desktop app produces — also rejected an internal promise nothing was awaiting. Node treats that as an unhandled rejection and, by default, exits the process, so the MCP server died while the tool handler was still formatting a tidy error message for a client that no longer had a server. Pinned by a test that runs the failure in a real child process and asserts it exits 0.
 
-**The Codex app says a thread is "open in another application".** That is the per-thread writer lock, and the other application is usually this bridge: the shared app-server takes the lock when it loads a thread and keeps it until it exits, so the desktop app cannot write to the same thread. `delegate_to_codex` releases the bridge server before opening the final desktop link when `releaseAfterTurn` is enabled. For an existing thread, pass `releaseAfterTurn: true` or call `stop_codex_app_server` once the hand-off is done — the bridge starts a new app-server the next time it needs one. A thread held by a *different* Codex window is the app's own lock; close it there.
+**The Codex app says a thread is "open in another application".** That is the per-thread writer lock, and the other application is usually this bridge: the shared app-server takes the lock when it loads a thread and keeps it until it exits, so the desktop app cannot write to the same thread. `delegate_to_codex` releases the bridge server before opening the final desktop link when `releaseAfterTurn` is enabled. For an existing thread, pass `releaseAfterTurn: true` or call `stop_codex_app_server` once the hand-off is done — the bridge starts a new app-server the next time it needs one. A thread held by a *different* Codex window is the app's own lock; close it there. If what you want is for Codex Desktop to **keep** the thread while Claude messages into it, that is what the [native relay](#codex-desktop-native-relay-macos) is for — it never asks for the lock.
+
+**`claude_bridge_status` says the delivery backend is `app-server` on a Mac with the relay installed.** The `delivery:` line carries the reason, and there are only three. *"no companion socket at …"* — Codex Desktop has not launched the companion: restart the app after `install-native-relay.mjs`, and check `codex mcp get codex-native-relay`. *"disabled by CODEX_BRIDGE_NATIVE_RELAY=0"* — it was switched off in the MCP server's `env`. *"macOS-only"* — the bridge is not running where the Codex Desktop app is; the app-server path is the correct answer there. A relay that is reachable but has no executor thread fails at send time instead, with `RELAY_THREAD_UNCONFIGURED` naming both `CODEX_RELAY_ID` and the file to bootstrap.
 
 **A thread opens against the wrong directory.** The same project sits at a different absolute path on each machine: on the shared drive's letter under Windows, under its mount point when that drive is visible from macOS (**read-only** there), and in a native checkout otherwise. Since 1.4.0 the bridge picks the candidate that both **exists and is writable** on the current machine and prints a `note: cwd remapped …` line whenever it rewrites one. If nothing usable exists it fails immediately instead of opening a thread somewhere wrong. Handing Codex a read-only cwd is a reliable way to hit the freeze above: it runs a few reads, then asks for write permission and stalls.
 
@@ -411,6 +493,12 @@ The bridge reads these from the environment its MCP client hands it — there is
 | `CODEX_BRIDGE_EFFORT` | from `~/.codex/config.toml` | Default reasoning effort: `minimal` · `low` · `medium` · `high` · `xhigh` · `ultra`. |
 | `CODEX_BRIDGE_OPEN_IN_APP` | `1` on Windows, `0` elsewhere | Open delegated or sent threads through the `codex://threads/<id>` desktop link. |
 | `CODEX_BRIDGE_RELEASE_AFTER_TURN` | `1` on Windows, `0` elsewhere | Stop the shared bridge app-server after a terminal turn so Codex Desktop can write the handed-off thread. |
+| `CODEX_BRIDGE_NATIVE_RELAY` | `auto` | Delivery backend for relayed Claude messages. `auto` uses the Codex Desktop native relay on macOS when the companion socket exists; `0` never does; `1` attempts it on any platform. |
+| `CODEX_RELAY_ID` | from `~/.codex/native-relay.json` | Executor thread for `codex_app.send_message_to_thread`. Not the destination — see [Codex Desktop native relay](#codex-desktop-native-relay-macos). |
+| `CODEX_HOME` | `~/.codex` | Where the relay socket and `native-relay.json` live. |
+| `CODEX_NATIVE_RELAY_SOCKET` | `$CODEX_HOME/native-relay.sock` | Override the companion's socket path on both halves of the relay. |
+| `CODEX_NATIVE_RELAY_METHOD` | `codex_app.send_message_to_thread` | The undocumented Codex Desktop method the companion dispatches through; override it if Codex renames it. |
+| `CODEX_NATIVE_RELAY_NAME` | `codex-native-relay` | The MCP server name `scripts/install-native-relay.mjs` registers with Codex. |
 | `CLAUDE_BRIDGE_PEER_NAME` | `codex-<pid>` | The name Claude shows for this bridge in its agent list. |
 | `CLAUDE_BRIDGE_CWD` | the process cwd | The working directory the peer advertises. |
 | `CLAUDE_DESKTOP_CONFIG` | auto-detected | Override the config path used by `install-claude-desktop.mjs`. |
@@ -448,15 +536,16 @@ Runs the whole suite with `node --test`. It needs no Codex install, no login and
 
 | File | Covers |
 |---|---|
-| `test/tool-contract.test.mjs` | both servers boot over stdio and every tool declares a title, a description, per-parameter descriptions and complete annotation hints |
+| `test/tool-contract.test.mjs` | all three servers boot over stdio and every tool declares a title, a description, per-parameter descriptions and complete annotation hints |
 | `test/server-requests.test.mjs` | all 10 app-server requests get a reply in the shape their schema declares — the regression test for "the turn pauses itself" |
 | `test/reconnect.test.mjs` | reconnect after a dropped socket, no leaked pending requests or listeners, an interrupted turn ending promptly, a refused first handshake being retried |
 | `test/turn.test.mjs` | the turn state machine: buffered notifications, terminal statuses, timeout, disconnect, retryable vs fatal errors, and that a failed `turn/start` cannot kill the process |
 | `test/peer-protocol.test.mjs` | frame round-trips, the session registry, transcript scanning, and a live peer endpoint over a real unix socket |
 | `test/platform.test.mjs` | binary resolution, the PATH handed to child processes, per-OS config paths and cwd remapping |
+| `test/native-relay.test.mjs` | the Codex Desktop relay: executor thread resolution, feature detection, socket round trips over a real unix socket, reclaiming a socket a killed companion left behind, backend selection and when it may fall back, and the companion answering a real MCP client that plays Codex Desktop |
 | `test/repo-hygiene.test.mjs` | no environment file or build output is ever tracked, versions do not drift, documentation stays in English |
 
-GitHub Actions runs the same command on every push and pull request, across Node 22 and 24 on Linux, macOS and Windows (`.github/workflows/ci.yml`). The Codex → Claude direction needs unix sockets, so those tests skip on Windows; the rest of the suite runs there like anywhere else.
+GitHub Actions runs the same command on every push and pull request, across Node 22 and 24 on Linux, macOS and Windows (`.github/workflows/ci.yml`). The Codex → Claude direction and the native relay both need unix sockets, so those tests skip on Windows; the rest of the suite runs there like anywhere else.
 
 Two checks need a real Codex and are not part of `npm test`:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhspark/codex-mcp-bridge",
-  "version": "1.11.2",
+  "version": "1.12.0",
   "description": "Two-way MCP bridge between Claude and Codex: prompts into a live Codex thread, messages into a running Claude Code session.",
   "keywords": [
     "mcp",
@@ -25,7 +25,9 @@
     "codex-mcp-bridge": "src/index.mjs",
     "claude-mcp-bridge": "src/claude-bridge.mjs",
     "codex-mcp-bridge-install": "scripts/install-claude-desktop.mjs",
-    "claude-mcp-bridge-install": "scripts/install-codex-mcp.mjs"
+    "claude-mcp-bridge-install": "scripts/install-codex-mcp.mjs",
+    "codex-native-relay": "src/native-relay-companion.mjs",
+    "codex-native-relay-install": "scripts/install-native-relay.mjs"
   },
   "files": [
     "src",
@@ -48,9 +50,11 @@
     "install:desktop": "node scripts/install-claude-desktop.mjs",
     "install:codex": "node scripts/install-codex-mcp.mjs",
     "uninstall:codex": "node scripts/install-codex-mcp.mjs --remove",
+    "install:relay": "node scripts/install-native-relay.mjs",
+    "uninstall:relay": "node scripts/install-native-relay.mjs --remove",
     "install:agent": "node scripts/install-launch-agent.mjs",
     "uninstall:agent": "node scripts/install-launch-agent.mjs --uninstall",
-    "version": "node scripts/sync-version.mjs && git add src/index.mjs src/claude-bridge.mjs"
+    "version": "node scripts/sync-version.mjs && git add src/index.mjs src/claude-bridge.mjs src/native-relay-companion.mjs"
   },
   "engines": {
     "node": ">=22"

package/scripts/install-native-relay.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { CodexAppServerClient } from "../src/app-server-client.mjs";
+import { bootstrapRelayThread, readRelayConfig, relayConfigPath, relaySocketPath } from "../src/native-relay.mjs";
+import { IS_MACOS, PLATFORM_LABEL, homeDir, resolveCodexBin, spawnEnv } from "../src/platform.mjs";
+
+/**
+ * Installs the Codex Desktop native relay: registers the companion as an MCP
+ * server so Codex Desktop launches it, and bootstraps the executor thread the
+ * native dispatch needs.
+ *
+ * The bootstrap is the one step that has to take a writer lock, and it takes it
+ * on a thread that belongs to nobody: a dedicated relay thread, created through
+ * an ordinary app-server which is then stopped so the lock is released. After
+ * this runs, no part of the relay ever attaches a thread again.
+ */
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const entry = path.join(root, "src", "native-relay-companion.mjs");
+const serverName = process.env.CODEX_NATIVE_RELAY_NAME ?? "codex-native-relay";
+const remove = process.argv.includes("--remove");
+const skipBootstrap = process.argv.includes("--no-bootstrap");
+
+const codexBin = resolveCodexBin(process.env.CODEX_EXE);
+const run = (args) => execFileSync(codexBin, args, { env: spawnEnv(), stdio: "pipe" }).toString().trim();
+
+if (!fs.existsSync(entry)) throw new Error(`companion entry point missing: ${entry}`);
+if (!path.isAbsolute(codexBin) || !fs.existsSync(codexBin)) {
+  throw new Error(`codex binary not found (resolved to "${codexBin}"). Set CODEX_EXE to its absolute path.`);
+}
+
+if (remove) {
+  try {
+    console.log(run(["mcp", "remove", serverName]) || `removed ${serverName}`);
+  } catch (err) {
+    console.log(`${serverName} was not registered (${err.message.trim().split("\n").at(-1)})`);
+  }
+  for (const leftover of [relaySocketPath(), relayConfigPath()]) {
+    if (fs.existsSync(leftover)) {
+      fs.rmSync(leftover, { force: true });
+      console.log(`removed ${leftover}`);
+    }
+  }
+  process.exit(0);
+}
+
+/**
+ * Not a hard failure: the companion is harmless on any platform - it simply
+ * never gets a native tools connection to dispatch through - and refusing to
+ * register it would make the install order depend on which machine runs it.
+ */
+if (!IS_MACOS) {
+  console.log(`note: the native relay only delivers on macOS; this is ${PLATFORM_LABEL}.`);
+  console.log("claude-bridge will keep using the app-server path here.");
+}
+
+try {
+  run(["mcp", "remove", serverName]);
+} catch {
+  // not registered yet
+}
+run(["mcp", "add", serverName, "--", process.execPath, entry]);
+
+console.log(`platform: ${PLATFORM_LABEL}`);
+console.log(`registered MCP server "${serverName}" with Codex:`);
+console.log(run(["mcp", "get", serverName]));
+
+const existing = readRelayConfig()?.relayThreadId;
+if (existing) {
+  console.log(`\nrelay thread already bootstrapped: ${existing} (${relayConfigPath()})`);
+} else if (skipBootstrap) {
+  console.log(`\nskipped the relay thread bootstrap; set CODEX_RELAY_ID or rerun without --no-bootstrap.`);
+} else {
+  const client = new CodexAppServerClient({
+    clientInfo: { name: "native-relay-install", title: "Native Relay Install", version: "1.11.3" },
+    log: (msg) => console.log(`  ${msg}`),
+  });
+  console.log("\nbootstrapping the relay executor thread...");
+  try {
+    const { threadId, configPath } = await bootstrapRelayThread(client, { cwd: homeDir() });
+    console.log(`relay thread: ${threadId}`);
+    console.log(`written to:   ${configPath}`);
+  } finally {
+    /**
+     * The bootstrap thread must not stay locked by this app-server: leaving it
+     * held would reintroduce, for the relay's own thread, exactly the writer
+     * conflict the relay exists to remove.
+     */
+    const stopped = await client.stopServer();
+    console.log(stopped.stopped ? "released the bootstrap app-server" : `app-server not stopped: ${stopped.reason}`);
+  }
+}
+
+console.log(`\nrelay socket: ${relaySocketPath()}`);
+console.log("Restart Codex Desktop so it launches the companion, then check with native_relay_status.");
+console.log("remove: node scripts/install-native-relay.mjs --remove");

package/scripts/sync-version.mjs

@@ -15,7 +15,11 @@ import { fileURLToPath } from "node:url";
  * claude-bridge sat at 1.3.0 while the package shipped 1.10.0.
  */
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
-const entries = [path.join("src", "index.mjs"), path.join("src", "claude-bridge.mjs")];
+const entries = [
+  path.join("src", "index.mjs"),
+  path.join("src", "claude-bridge.mjs"),
+  path.join("src", "native-relay-companion.mjs"),
+];
 const { version } = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
 
 for (const entry of entries) {

package/src/claude-bridge.mjs

@@ -6,9 +6,9 @@ import { z } from "zod";
 import { CodexAppServerClient } from "./app-server-client.mjs";
 import { PLATFORM_LABEL } from "./platform.mjs";
 import { PeerEndpoint, findClaudeSession, listClaudeSessions, readTranscript } from "./peer-protocol.mjs";
-import { runTurn } from "./turn.mjs";
+import { createThreadDelivery } from "./thread-delivery.mjs";
 
-const VERSION = "1.11.2";
+const VERSION = "1.12.0";
 const FORWARD_MIN_INTERVAL_MS = 5000;
 const FORWARD_MAX_PER_SESSION = 50;
 
@@ -27,6 +27,14 @@ const codex = new CodexAppServerClient({
   log,
 });
 
+/**
+ * Delivery is a backend choice, not a call: a thread the human is watching in
+ * Codex Desktop is written through the desktop's own app-server, and every
+ * other thread through the shared one. `claude-bridge` never picks between
+ * them - see `thread-delivery.mjs`.
+ */
+const delivery = createThreadDelivery({ codex, log });
+
 const forwarding = {
   threadId: process.env.CODEX_THREAD_ID ?? null,
   lastAt: 0,
@@ -64,18 +72,11 @@ async function forwardToCodexThread(record) {
   forwarding.lastAt = now;
   forwarding.count += 1;
   try {
-    await codex.ensureThreadAttached(forwarding.threadId);
-    await runTurn(codex, {
-      threadId: forwarding.threadId,
-      input: [
-        {
-          type: "text",
-          text: `[message from Claude session ${record.fromSocket ?? "?"}]\n\n${record.text}`,
-        },
-      ],
-      timeoutMs: 240000,
-    });
-    log(`forwarded a Claude message into thread ${forwarding.threadId}`);
+    const { backend } = await delivery.deliver(
+      forwarding.threadId,
+      `[message from Claude session ${record.fromSocket ?? "?"}]\n\n${record.text}`,
+    );
+    log(`forwarded a Claude message into thread ${forwarding.threadId} via ${backend}`);
   } catch (err) {
     log(`forward failed: ${err.message}`);
   }
@@ -245,7 +246,8 @@ server.registerTool(
     title: "Relay Claude messages into a Codex thread",
     description:
       "Bind a Codex thread so every message Claude pushes to this bridge is relayed into that thread, where it " +
-      "shows up in the Codex desktop app. Pass an empty threadId to stop relaying.",
+      "shows up in the Codex desktop app. On macOS a thread already open in Codex Desktop is written through " +
+      "the desktop's own app-server, so it keeps its writer lock and stays open. Pass an empty threadId to stop.",
     inputSchema: {
       threadId: z.string().describe("Codex thread id, or an empty string to unbind"),
     },
@@ -264,7 +266,7 @@ server.registerTool(
     peer.rename(name);
     return textResult(
       trimmed
-        ? `Relaying Claude messages into Codex thread ${trimmed} (max ${FORWARD_MAX_PER_SESSION} per bridge run, at most one every ${FORWARD_MIN_INTERVAL_MS / 1000}s).\nClaude now sees this bridge as "${name}".`
+        ? `Relaying Claude messages into Codex thread ${trimmed} (max ${FORWARD_MAX_PER_SESSION} per bridge run, at most one every ${FORWARD_MIN_INTERVAL_MS / 1000}s).\ndelivery: ${delivery.describe()}\nClaude now sees this bridge as "${name}".`
         : `Relay disabled. Messages stay in the inbox. Claude sees this bridge as "${name}".`,
     );
   },
@@ -296,6 +298,7 @@ server.registerTool(
         `peer socket:   ${peer.socketPath}`,
         `live sessions: ${sessions.length}`,
         `relay thread:  ${forwarding.threadId ?? "(none - use bind_codex_thread)"}`,
+        `delivery:      ${delivery.describe()}`,
         `inbox:         ${peer.inbox.length} pending message(s)`,
       ];
       return textResult(lines.join("\n"));

package/src/index.mjs

@@ -21,7 +21,7 @@ import {
 import { runTurn } from "./turn.mjs";
 import { BridgeSecurityPolicy } from "./security-policy.mjs";
 
-const VERSION = "1.11.2";
+const VERSION = "1.12.0";
 const log = (msg) => process.stderr.write(`[codex-mcp-bridge] ${msg}\n`);
 
 /**

package/src/native-relay-companion.mjs

@@ -0,0 +1,337 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import net from "node:net";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+import {
+  MAX_FRAME_BYTES,
+  NATIVE_DISPATCH_METHOD,
+  RELAY_PROTOCOL_VERSION,
+  nativeDispatchParams,
+  relaySocketPath,
+  resolveRelayThreadId,
+} from "./native-relay.mjs";
+import { PLATFORM_LABEL } from "./platform.mjs";
+
+/**
+ * The companion half of the Codex Desktop native relay.
+ *
+ * Codex Desktop launches this as one of its own MCP servers, so the connection
+ * it answers on belongs to the app's real app-server - the one already holding
+ * the writer lock of every thread the human has open. Asking that app-server to
+ * deliver a message is therefore not a second writer, and the thread stays open
+ * and owned by Codex Desktop throughout.
+ *
+ * Everything else is deliberately small: a private socket, one accepted shape
+ * (`{ targetThreadId, message }`), one dispatch, one acknowledgement.
+ */
+
+const VERSION = "1.12.0";
+const log = (msg) => process.stderr.write(`[native-relay] ${msg}\n`);
+
+function errorResponse(code, message) {
+  return { ok: false, v: RELAY_PROTOCOL_VERSION, error: { code, message } };
+}
+
+/**
+ * A JSON-RPC error arrives with a numeric code, and passing that straight back
+ * would put `-32601` in a field whose other values read `RELAY_TIMEOUT`. Only a
+ * string code from this project's own errors is carried through.
+ */
+function errorCode(err) {
+  return typeof err?.code === "string" ? err.code : "NATIVE_DISPATCH_FAILED";
+}
+
+/**
+ * The whole request handler, kept free of sockets and of the MCP connection so
+ * the rules it enforces can be tested against a stub dispatcher rather than
+ * against a running Codex Desktop.
+ */
+export async function handleRelayRequest(
+  payload,
+  { dispatch, resolveExecutor = resolveRelayThreadId, env = process.env } = {},
+) {
+  const targetThreadId = typeof payload?.targetThreadId === "string" ? payload.targetThreadId.trim() : "";
+  const message = typeof payload?.message === "string" ? payload.message : "";
+
+  if (!targetThreadId) return errorResponse("RELAY_BAD_REQUEST", "targetThreadId must be a non-empty string");
+  if (!message.trim()) return errorResponse("RELAY_BAD_REQUEST", "message must be a non-empty string");
+
+  let executorThreadId;
+  try {
+    executorThreadId = resolveExecutor(env).threadId;
+  } catch (err) {
+    return errorResponse(errorCode(err), err.message);
+  }
+
+  /**
+   * Codex validates the executor thread, so a destination that is also the
+   * executor would be dispatched rather than refused - and the message would
+   * land in the relay thread instead of the thread the human is watching.
+   * Nothing downstream can tell those two apart afterwards.
+   */
+  if (executorThreadId === targetThreadId) {
+    return errorResponse(
+      "RELAY_BAD_REQUEST",
+      `${targetThreadId} is the relay's own executor thread, not a destination. Bind the thread you are watching in Codex Desktop.`,
+    );
+  }
+
+  try {
+    const result = await dispatch({ executorThreadId, targetThreadId, message });
+    return { ok: true, v: RELAY_PROTOCOL_VERSION, targetThreadId, executorThreadId, result: result ?? null };
+  } catch (err) {
+    return errorResponse(errorCode(err), err?.message ?? String(err));
+  }
+}
+
+/**
+ * Listens on a private unix socket and answers one NDJSON line per request.
+ *
+ * The socket is mode 0600 inside the Codex home directory, which is the same
+ * boundary the Claude peer protocol already relies on: owning the user account
+ * is what grants access, and nothing weaker does. Named separately here because
+ * this socket can put text into a Codex thread, so the file mode is the
+ * security control rather than a detail of the transport.
+ */
+export class RelaySocketServer {
+  constructor({
+    socketPath,
+    dispatch,
+    resolveExecutor = resolveRelayThreadId,
+    restrictSocket = (target) => fs.chmodSync(target, 0o600),
+    log: logFn = () => {},
+  } = {}) {
+    this.socketPath = socketPath;
+    this.dispatch = dispatch;
+    this.resolveExecutor = resolveExecutor;
+    this.restrictSocket = restrictSocket;
+    this.log = logFn;
+    this.server = null;
+    this.started = false;
+  }
+
+  async start() {
+    if (this.started) return this.socketPath;
+    fs.mkdirSync(path.dirname(this.socketPath), { recursive: true });
+
+    this.server = net.createServer((socket) => this.#handleConnection(socket));
+    await this.#listen({ replaceStale: true });
+
+    /**
+     * The file mode is the whole security boundary, so a socket whose mode
+     * could not be set is not a degraded relay - it is an open one. Refuse it
+     * and let the caller fall back to the app-server path, rather than serving
+     * thread writes on an address anyone can open.
+     */
+    try {
+      this.restrictSocket(this.socketPath);
+    } catch (err) {
+      try {
+        this.server.close();
+      } catch {}
+      throw new Error(`refusing to serve on ${this.socketPath}: its mode could not be restricted (${err.message})`);
+    }
+    this.started = true;
+
+    for (const signal of ["SIGINT", "SIGTERM"]) {
+      process.on(signal, () => {
+        this.stop();
+        process.exit(0);
+      });
+    }
+    process.on("exit", () => this.stop());
+
+    this.log(`relay socket listening on ${this.socketPath}`);
+    return this.socketPath;
+  }
+
+  /**
+   * A companion killed with SIGKILL leaves its socket file behind, and the next
+   * one then fails to bind a path nothing is listening on. Removing it blindly
+   * would be worse: Codex Desktop can launch more than one companion, and the
+   * second would silently steal the address from the first. So an in-use path
+   * is probed - a refused connection means the owner is gone and the file is
+   * swept, an accepted one means a live companion already has the socket and
+   * this process leaves it alone.
+   */
+  async #listen({ replaceStale }) {
+    try {
+      await new Promise((resolve, reject) => {
+        this.server.once("error", reject);
+        this.server.listen(this.socketPath, () => {
+          this.server.off("error", reject);
+          resolve();
+        });
+      });
+    } catch (err) {
+      if (err.code !== "EADDRINUSE" || !replaceStale) throw err;
+      if (await this.#socketIsLive()) {
+        throw new Error(`another native relay companion already owns ${this.socketPath}`);
+      }
+      this.log(`removing the stale relay socket left at ${this.socketPath}`);
+      fs.rmSync(this.socketPath, { force: true });
+      await this.#listen({ replaceStale: false });
+    }
+  }
+
+  #socketIsLive() {
+    return new Promise((resolve) => {
+      const probe = net.connect({ path: this.socketPath });
+      const timer = globalThis.setTimeout(() => done(false), 1000);
+      const done = (answer) => {
+        globalThis.clearTimeout(timer);
+        probe.destroy();
+        resolve(answer);
+      };
+      probe.on("connect", () => done(true));
+      probe.on("error", () => done(false));
+    });
+  }
+
+  #handleConnection(socket) {
+    let buffer = "";
+    socket.on("error", (err) => this.log(`relay socket error: ${err.message}`));
+    socket.on("data", (chunk) => {
+      buffer += chunk.toString("utf8");
+      if (Buffer.byteLength(buffer, "utf8") > MAX_FRAME_BYTES) {
+        this.#reply(socket, errorResponse("RELAY_MESSAGE_TOO_LARGE", `a relay frame may not exceed ${MAX_FRAME_BYTES} bytes`));
+        socket.destroy();
+        return;
+      }
+      let index;
+      while ((index = buffer.indexOf("\n")) >= 0) {
+        const line = buffer.slice(0, index).trim();
+        buffer = buffer.slice(index + 1);
+        if (!line) continue;
+        void this.#handleLine(socket, line);
+      }
+    });
+  }
+
+  async #handleLine(socket, line) {
+    let payload;
+    try {
+      payload = JSON.parse(line);
+    } catch (err) {
+      this.#reply(socket, errorResponse("RELAY_BAD_REQUEST", `malformed JSON: ${err.message}`));
+      return;
+    }
+    const response = await handleRelayRequest(payload, {
+      dispatch: this.dispatch,
+      resolveExecutor: this.resolveExecutor,
+    });
+    if (!response.ok) this.log(`relay refused ${payload?.targetThreadId ?? "?"}: ${response.error.message}`);
+    else this.log(`relayed a message into thread ${response.targetThreadId}`);
+    this.#reply(socket, response);
+  }
+
+  #reply(socket, response) {
+    if (socket.destroyed) return;
+    socket.write(`${JSON.stringify(response)}\n`);
+  }
+
+  stop() {
+    try {
+      this.server?.close();
+    } catch {}
+    try {
+      if (this.started) fs.rmSync(this.socketPath, { force: true });
+    } catch {}
+    this.started = false;
+  }
+}
+
+/**
+ * `import.meta.main` is Node 24 and up, and this project supports Node 22, so
+ * the entry point is detected by comparing the resolved argv path instead.
+ */
+const invokedDirectly =
+  Boolean(process.argv[1]) && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url));
+
+if (invokedDirectly) {
+  const mcp = new McpServer(
+    { name: "codex-native-relay", version: VERSION },
+    {
+      instructions:
+        "Companion process for the Codex Desktop native relay. It carries no work of its own: it accepts " +
+        "messages from claude-bridge on a private local socket and asks the Codex Desktop app-server that " +
+        "launched it to deliver them into an already-open thread, so that thread keeps its writer lock.",
+    },
+  );
+
+  /**
+   * The dispatch goes back over the very connection Codex Desktop opened to
+   * launch this process, which is what keeps the app the single writer. Sent as
+   * a plain JSON-RPC request rather than through a typed helper because the
+   * method is an internal of the app, not part of the MCP specification.
+   */
+  const dispatch = ({ executorThreadId, targetThreadId, message }) =>
+    mcp.server.request(
+      {
+        method: process.env.CODEX_NATIVE_RELAY_METHOD ?? NATIVE_DISPATCH_METHOD,
+        params: nativeDispatchParams({ executorThreadId, targetThreadId, message }),
+      },
+      z.any(),
+    );
+
+  const relay = new RelaySocketServer({ socketPath: relaySocketPath(), dispatch, log });
+
+  mcp.registerTool(
+    "native_relay_status",
+    {
+      title: "Check the Codex Desktop native relay",
+      description:
+        "Report the local socket this companion listens on, the executor thread it dispatches through, and " +
+        "whether the relay is ready to deliver messages into threads Codex Desktop has open.",
+      inputSchema: {},
+      annotations: {
+        readOnlyHint: true,
+        openWorldHint: false,
+      },
+    },
+    async () => {
+      let executor = "(unconfigured)";
+      try {
+        const resolved = resolveRelayThreadId();
+        executor = `${resolved.threadId}  (from ${resolved.source})`;
+      } catch (err) {
+        executor = err.message;
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: [
+              `platform:       ${PLATFORM_LABEL} (${process.platform}/${process.arch})`,
+              `companion:      codex-native-relay ${VERSION}`,
+              `relay socket:   ${relay.started ? relay.socketPath : `${relay.socketPath} (not listening)`}`,
+              `executor:       ${executor}`,
+              `dispatch:       ${process.env.CODEX_NATIVE_RELAY_METHOD ?? NATIVE_DISPATCH_METHOD}`,
+            ].join("\n"),
+          },
+        ],
+      };
+    },
+  );
+
+  /**
+   * Never let the socket take the MCP server down. Codex Desktop waits on the
+   * `initialize` handshake, so a process that dies before answering reads as a
+   * hang rather than an error - the same failure mode `claude-bridge` already
+   * guards its peer endpoint against.
+   */
+  try {
+    await relay.start();
+  } catch (err) {
+    log(`relay socket unavailable (${err.message}) - claude-bridge will fall back to the app-server path`);
+  }
+
+  await mcp.connect(new StdioServerTransport());
+  log(`ready on ${PLATFORM_LABEL} (${relay.started ? relay.socketPath : "socket down"})`);
+}

package/src/native-relay.mjs

@@ -0,0 +1,319 @@
+import fs from "node:fs";
+import net from "node:net";
+import path from "node:path";
+
+import { IS_MACOS, PLATFORM_LABEL, homeDir } from "./platform.mjs";
+
+/**
+ * The Codex Desktop app owns the per-thread writer lock of every thread it has
+ * open, and it keeps it for as long as the thread is open. Anything that wants
+ * to write into such a thread by attaching a second app-server loses: the
+ * app-server answers `thread <id> already has an active writer`. Closing the
+ * thread first is not an answer either, because the whole point of binding a
+ * thread is that the human keeps watching it in Codex Desktop.
+ *
+ * The way through is to stop bringing a second writer. A companion MCP process
+ * launched by Codex Desktop's own app-server already sits inside the app's
+ * context, so it can ask that app-server to deliver the message on the app's
+ * behalf. No resume, no attach, no second app-server, no lock to fight over.
+ *
+ * This module is the client half - the part `claude-bridge` talks to. The
+ * companion half lives in `native-relay-companion.mjs`.
+ */
+
+/**
+ * Measured, not documented. `codex_app.send_message_to_thread` is an internal
+ * of the Codex Desktop native tools pipe, on the same footing as the Claude
+ * peer protocol in `peer-protocol.mjs`: it works today and carries no public
+ * contract. When Codex changes it, this constant and `nativeDispatchParams`
+ * below are the two places to fix, and `CODEX_NATIVE_RELAY_METHOD` overrides
+ * the name without a release.
+ */
+export const NATIVE_DISPATCH_METHOD = "codex_app.send_message_to_thread";
+
+export const RELAY_PROTOCOL_VERSION = 1;
+
+/**
+ * A relay frame carries one chat message, so a megabyte-scale line is either a
+ * bug or something trying to make the companion buffer without limit. The cap
+ * is applied on both halves: the client refuses to send an oversized message,
+ * and the companion refuses to accumulate one.
+ */
+export const MAX_FRAME_BYTES = 128 * 1024;
+
+const DEFAULT_TIMEOUT_MS = 30000;
+const RELAY_SOCKET_NAME = "native-relay.sock";
+const RELAY_CONFIG_NAME = "native-relay.json";
+
+export class NativeRelayError extends Error {
+  /**
+   * `reachedCompanion` is what decides whether falling back to the app-server
+   * path is worth doing. A companion that never answered says nothing about
+   * the target thread, so the older path deserves its turn; a companion that
+   * answered with a refusal has already asked Codex, and asking again through
+   * a second app-server only adds a writer-lock failure on top.
+   */
+  constructor(message, code, { reachedCompanion = false } = {}) {
+    super(message);
+    this.name = "NativeRelayError";
+    this.code = code;
+    this.reachedCompanion = reachedCompanion;
+  }
+}
+
+export function codexHome(env = process.env) {
+  return env.CODEX_HOME ?? path.join(homeDir(), ".codex");
+}
+
+export function relaySocketPath(env = process.env) {
+  return env.CODEX_NATIVE_RELAY_SOCKET ?? path.join(codexHome(env), RELAY_SOCKET_NAME);
+}
+
+export function relayConfigPath(env = process.env) {
+  return path.join(codexHome(env), RELAY_CONFIG_NAME);
+}
+
+function isSocketFile(target) {
+  try {
+    return fs.statSync(target).isSocket();
+  } catch {
+    return false;
+  }
+}
+
+export function readRelayConfig(env = process.env) {
+  const file = relayConfigPath(env);
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * `codex_app.send_message_to_thread` runs against an executor thread, which has
+ * to be a real Codex thread and is not the destination: a synthetic UUID is
+ * rejected with `NATIVE_DISPATCH_FAILED`, so the id cannot be invented at call
+ * time. A thread dedicated to the relay keeps that requirement off the
+ * destination thread, which stays open in Codex Desktop and untouched.
+ *
+ * The order is deliberate: an explicit `CODEX_RELAY_ID` wins so a single run
+ * can be pointed elsewhere without editing state, then the id bootstrapped
+ * once into `~/.codex/native-relay.json`, and then an error. Never a guess -
+ * an invented executor fails inside Codex with a message that says nothing
+ * about the missing configuration that actually caused it.
+ */
+export function resolveRelayThreadId(env = process.env) {
+  const explicit = env.CODEX_RELAY_ID?.trim();
+  if (explicit) return { threadId: explicit, source: "CODEX_RELAY_ID" };
+
+  const persisted = readRelayConfig(env)?.relayThreadId;
+  if (typeof persisted === "string" && persisted.trim()) {
+    return { threadId: persisted.trim(), source: relayConfigPath(env) };
+  }
+
+  throw new NativeRelayError(
+    `No Codex relay thread is configured. Set CODEX_RELAY_ID, or bootstrap one into ${relayConfigPath(env)} ` +
+      "with: node scripts/install-native-relay.mjs",
+    "RELAY_THREAD_UNCONFIGURED",
+  );
+}
+
+/**
+ * Builds the parameters of the native dispatch. Kept apart from the transport
+ * so the one shape this project cannot verify against a published schema sits
+ * in a single named function with a single test, rather than inline in the
+ * middle of a request.
+ */
+export function nativeDispatchParams({ executorThreadId, targetThreadId, message }) {
+  return { executorThreadId, threadId: targetThreadId, message };
+}
+
+/**
+ * Whether the native path is usable right now, and when it is not, why. The
+ * reason is carried rather than dropped because "the relay did nothing" is the
+ * one answer nobody can act on: a missing companion socket, an unsupported
+ * platform and an operator switching the backend off all look identical from
+ * the outside, and they need three different responses.
+ */
+export function nativeRelayStatus(env = process.env) {
+  const mode = (env.CODEX_BRIDGE_NATIVE_RELAY ?? "auto").toLowerCase();
+  const socketPath = relaySocketPath(env);
+
+  if (mode === "0" || mode === "off") {
+    return { enabled: false, mode, socketPath, reason: "disabled by CODEX_BRIDGE_NATIVE_RELAY=0" };
+  }
+  const forced = mode === "1" || mode === "on";
+  if (!IS_MACOS && !forced) {
+    return {
+      enabled: false,
+      mode,
+      socketPath,
+      reason: `the Codex Desktop native relay is macOS-only (this is ${PLATFORM_LABEL})`,
+    };
+  }
+  if (!isSocketFile(socketPath)) {
+    return {
+      enabled: false,
+      mode,
+      socketPath,
+      reason: `no companion socket at ${socketPath} - is the native relay installed and Codex Desktop running?`,
+    };
+  }
+  return { enabled: true, mode, socketPath, reason: null };
+}
+
+/**
+ * Speaks one request per connection to the companion: a single NDJSON line out,
+ * a single NDJSON line back. Connections are not pooled - a relayed message is
+ * a rare event bounded by the bridge's own ping-pong guard, and a short-lived
+ * socket cannot go stale while Codex Desktop restarts underneath it.
+ */
+export class NativeDesktopRelay {
+  constructor({ env = process.env, socketPath = null, timeoutMs = DEFAULT_TIMEOUT_MS, log = () => {} } = {}) {
+    this.env = env;
+    this.explicitSocketPath = socketPath;
+    this.timeoutMs = timeoutMs;
+    this.log = log;
+  }
+
+  get socketPath() {
+    return this.explicitSocketPath ?? relaySocketPath(this.env);
+  }
+
+  status() {
+    if (!this.explicitSocketPath) return nativeRelayStatus(this.env);
+    const status = nativeRelayStatus({ ...this.env, CODEX_NATIVE_RELAY_SOCKET: this.explicitSocketPath });
+    return { ...status, socketPath: this.explicitSocketPath };
+  }
+
+  get available() {
+    return this.status().enabled;
+  }
+
+  async sendMessage(targetThreadId, message, { timeoutMs = this.timeoutMs } = {}) {
+    const request = { v: RELAY_PROTOCOL_VERSION, targetThreadId, message };
+    const line = `${JSON.stringify(request)}\n`;
+    if (Buffer.byteLength(line, "utf8") > MAX_FRAME_BYTES) {
+      throw new NativeRelayError(
+        `Relay message is larger than ${MAX_FRAME_BYTES} bytes; shorten it before relaying.`,
+        "RELAY_MESSAGE_TOO_LARGE",
+      );
+    }
+
+    const response = await this.#roundTrip(line, timeoutMs);
+    if (response?.ok) return response;
+    throw new NativeRelayError(
+      response?.error?.message ?? "the Codex Desktop relay refused the message",
+      response?.error?.code ?? "NATIVE_DISPATCH_FAILED",
+      { reachedCompanion: true },
+    );
+  }
+
+  #roundTrip(line, timeoutMs) {
+    const socketPath = this.socketPath;
+    return new Promise((resolve, reject) => {
+      let buffer = "";
+      let settled = false;
+      const socket = net.connect({ path: socketPath });
+
+      const finish = (fn, value) => {
+        if (settled) return;
+        settled = true;
+        globalThis.clearTimeout(timer);
+        socket.destroy();
+        fn(value);
+      };
+
+      const timer = globalThis.setTimeout(
+        () =>
+          finish(
+            reject,
+            new NativeRelayError(
+              `The Codex Desktop relay did not answer within ${timeoutMs}ms`,
+              "RELAY_TIMEOUT",
+              { reachedCompanion: true },
+            ),
+          ),
+        timeoutMs,
+      );
+
+      socket.on("connect", () => socket.write(line));
+      socket.on("data", (chunk) => {
+        buffer += chunk.toString("utf8");
+        if (Buffer.byteLength(buffer, "utf8") > MAX_FRAME_BYTES) {
+          finish(
+            reject,
+            new NativeRelayError("The Codex Desktop relay answered with an oversized frame", "RELAY_BAD_RESPONSE", {
+              reachedCompanion: true,
+            }),
+          );
+          return;
+        }
+        const index = buffer.indexOf("\n");
+        if (index < 0) return;
+        try {
+          finish(resolve, JSON.parse(buffer.slice(0, index)));
+        } catch (err) {
+          finish(
+            reject,
+            new NativeRelayError(
+              `The Codex Desktop relay answered with malformed JSON: ${err.message}`,
+              "RELAY_BAD_RESPONSE",
+              { reachedCompanion: true },
+            ),
+          );
+        }
+      });
+      socket.on("error", (err) =>
+        finish(
+          reject,
+          new NativeRelayError(`Cannot reach the Codex Desktop relay at ${socketPath}: ${err.message}`, "RELAY_UNREACHABLE"),
+        ),
+      );
+      socket.on("close", () =>
+        finish(
+          reject,
+          new NativeRelayError(
+            `The Codex Desktop relay at ${socketPath} closed before answering`,
+            "RELAY_UNREACHABLE",
+          ),
+        ),
+      );
+    });
+  }
+}
+
+/**
+ * Creates the dedicated executor thread once and remembers it, using the
+ * ordinary app-server path - which is allowed to take a writer lock here
+ * precisely because this thread belongs to nobody else. The caller stops the
+ * app-server afterwards, so the lock is released and Codex Desktop is left
+ * with the state to itself.
+ */
+export async function bootstrapRelayThread(client, { cwd = homeDir(), env = process.env, name = "Native Relay" } = {}) {
+  const res = await client.call("thread/start", {
+    cwd,
+    approvalPolicy: "never",
+    sandbox: "read-only",
+  });
+  const threadId = res?.thread?.id;
+  if (!threadId) throw new NativeRelayError("Codex app-server created no relay thread id", "RELAY_BOOTSTRAP_FAILED");
+
+  try {
+    await client.call("thread/name/set", { threadId, name });
+  } catch {
+    // A thread without a title still works as an executor context.
+  }
+
+  writeRelayConfig({ relayThreadId: threadId, createdAt: new Date().toISOString() }, env);
+  return { threadId, configPath: relayConfigPath(env) };
+}
+
+export function writeRelayConfig(config, env = process.env) {
+  const file = relayConfigPath(env);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+  return file;
+}

package/src/peer-protocol.mjs

@@ -5,9 +5,24 @@ import net from "node:net";
 import os from "node:os";
 import path from "node:path";
 
-import { homeDir } from "./platform.mjs";
+import { homeDir, IS_WINDOWS } from "./platform.mjs";
 
 const SOCKET_DIR = "/tmp/cc-socks";
+
+/**
+ * Windows has no /tmp, and path.join rewrites the unix default to "\tmp\cc-socks"
+ * on the system drive, where listen() fails with EACCES. The endpoint then never
+ * comes up, so Claude has no address to answer on and the bridge is silently
+ * one-way: messages reach Claude, replies never come back.
+ *
+ * Claude Code advertises a named pipe on Windows for exactly this reason, so the
+ * peer uses the same transport there. net.connect({ path }) and server.listen()
+ * accept a pipe name unchanged, so only creation differs - a pipe has no
+ * directory to create, no mode to chmod and no file to unlink beforehand.
+ */
+function peerSocketPath(pid) {
+  return IS_WINDOWS ? `\\\\.\\pipe\\LOCAL\\cc-peer-${pid}` : path.join(SOCKET_DIR, `${pid}.sock`);
+}
 const PEER_PROTOCOL_VERSION = 1;
 const CLAUDE_VERSION_HINT = "2.1.229";
 const PS_BIN = "/bin/ps";
@@ -171,7 +186,7 @@ export class PeerEndpoint {
     this.cwd = cwd;
     this.log = log;
     this.pid = process.pid;
-    this.socketPath = path.join(SOCKET_DIR, `${this.pid}.sock`);
+    this.socketPath = peerSocketPath(this.pid);
     this.registryPath = path.join(sessionsDir(), `${this.pid}.json`);
     this.keyPath = null;
     this.server = null;
@@ -219,16 +234,16 @@ export class PeerEndpoint {
     const keyHash = crypto.createHash("sha256").update(`${peerToken}${procStart}`).digest("hex");
     this.keyPath = path.join(sessionsDir(), `${this.pid}.${keyHash}.key`);
 
-    fs.mkdirSync(SOCKET_DIR, { recursive: true });
+    if (!IS_WINDOWS) fs.mkdirSync(SOCKET_DIR, { recursive: true });
     fs.mkdirSync(sessionsDir(), { recursive: true });
-    if (fs.existsSync(this.socketPath)) fs.rmSync(this.socketPath, { force: true });
+    if (!IS_WINDOWS && fs.existsSync(this.socketPath)) fs.rmSync(this.socketPath, { force: true });
 
     await new Promise((resolve, reject) => {
       this.server = net.createServer((socket) => this.#handleConnection(socket));
       this.server.on("error", reject);
       this.server.listen(this.socketPath, resolve);
     });
-    fs.chmodSync(this.socketPath, 0o600);
+    if (!IS_WINDOWS) fs.chmodSync(this.socketPath, 0o600);
 
     this.registry = {
       pid: this.pid,

package/src/thread-delivery.mjs

@@ -0,0 +1,71 @@
+import { NativeDesktopRelay } from "./native-relay.mjs";
+import { runTurn } from "./turn.mjs";
+
+/**
+ * Which backend puts a message into a Codex thread.
+ *
+ * There are two, and they are not interchangeable. The app-server path resumes
+ * the thread through a second app-server, which takes the per-thread writer
+ * lock - correct for a thread nobody else has open, and guaranteed to fail with
+ * `thread <id> already has an active writer` for a thread Codex Desktop is
+ * showing. The native path asks Codex Desktop's own app-server to deliver the
+ * message, so the app stays the single writer and the thread stays open.
+ *
+ * Naming the choice here rather than branching inside the relay keeps
+ * `claude-bridge` unaware of either mechanism: it asks for delivery and is told
+ * which backend did it.
+ */
+export const NATIVE_BACKEND = "codex-desktop-native";
+export const APP_SERVER_BACKEND = "app-server";
+
+export function createThreadDelivery({
+  codex,
+  relay = new NativeDesktopRelay(),
+  log = () => {},
+  timeoutMs = 240000,
+} = {}) {
+  let reportedUnavailable = null;
+
+  /**
+   * Falling back is right when the companion never answered - an absent relay
+   * says nothing about the target thread, and the older path is exactly as good
+   * as it was before this backend existed. It is wrong once the companion has
+   * answered: Codex has already refused, and retrying through a second
+   * app-server only spawns a process that contends for the ~/.codex state and
+   * then fails on the writer lock the native path exists to avoid.
+   */
+  async function deliver(threadId, text) {
+    const status = relay.status();
+    if (status.enabled) {
+      try {
+        const ack = await relay.sendMessage(threadId, text);
+        reportedUnavailable = null;
+        return { backend: NATIVE_BACKEND, threadId, ack };
+      } catch (err) {
+        if (err.reachedCompanion) throw err;
+        log(`native relay unreachable (${err.message}); falling back to the app-server path`);
+      }
+    } else if (status.reason !== reportedUnavailable) {
+      reportedUnavailable = status.reason;
+      log(`native relay not in use: ${status.reason}`);
+    }
+
+    if (!codex) throw new Error("No Codex app-server client is configured to deliver this message");
+    await codex.ensureThreadAttached(threadId);
+    const turn = await runTurn(codex, {
+      threadId,
+      input: [{ type: "text", text }],
+      timeoutMs,
+    });
+    return { backend: APP_SERVER_BACKEND, threadId, turn };
+  }
+
+  function describe() {
+    const status = relay.status();
+    return status.enabled
+      ? `${NATIVE_BACKEND} via ${status.socketPath}`
+      : `${APP_SERVER_BACKEND} (${status.reason})`;
+  }
+
+  return { deliver, describe };
+}