NexusRelay

[!WARNING] Experimental, Windows only. Waking Codex drives the Codex desktop app through its local debugging port, and waking Antigravity goes through its sidecar API. Both depend on how those apps look and behave today: an app update can break a wake until the relay's interface maps are refreshed (survey). Use at your own risk.

Why NexusRelay

Quick start

You need Windows 10 or 11 and two of Claude Code, the Codex desktop app and Antigravity (see Requirements).

[!TIP] Let your AI install it. Paste this into Claude Code, Codex or Antigravity:

text

Install NexusRelay by following https://raw.githubusercontent.com/pironjulien/NexusSystem/main/INSTALL-AI.md

Or install it from the NexusSystem app from the Microsoft Store (winget install --id 9NSH2P3QLWT1 --source msstore). New versions are no longer published to PyPI; earlier packages stay available.

$r = 'https://github.com/pironjulien/NexusRelay/releases/latest/download'Invoke-WebRequest "$r/get.ps1" -OutFile get.ps1Invoke-WebRequest "$r/SHA256SUMS.txt" -OutFile SHA256SUMS.txtSelect-String -Path SHA256SUMS.txt -Pattern 'get\.ps1'   # expected SHA-256(Get-FileHash get.ps1 -Algorithm SHA256).Hash            # must be the samegh attestation verify get.ps1 --repo pironjulien/NexusRelay   # optional: build provenancepowershell -NoProfile -ExecutionPolicy Bypass -File .\get.ps1

gh attestation verify NexusRelay-win-x64.zip --repo pironjulien/NexusRelay

Then:

1. Restart Claude Code and Codex (quit them completely). In the Codex app, once: Add a project, name "NexusRelay", folder %USERPROFILE%\.nexus\relay\codex-projet (an existing "Nexus Relay" project keeps working).
2. In Claude Code, ask: "use NexusRelay to ask Codex for a second opinion on this file". Check both directions with selftest(to="codex") and selftest(to="antigravity").

How it works

flowchart LR    C["Claude Code<br/>(host)"] -- "send / wait_reply" --> D["nexus-relay daemon<br/>127.0.0.1:16181"]    D -- "one immutable JSON<br/>per message" --> B[("~/.nexus/relay")]    D -- "debug port 9223:<br/>configured execution workspace" --> X["Codex app"]    D -- "sidecar + agentapi" --> A["Antigravity"]    X -- "read / reply" --> D    A -- "read / reply" --> D

1. Claude calls send(to, text, topic). The message is written to the local room, one file per message.
2. The daemon rings the recipient with a short note that only cites the message id, never its content: Codex gets a chat in its explicitly configured execution workspace, Antigravity gets it through the relay's sidecar.
3. The recipient calls read(id) and answers with reply(id, text). Claude waits with wait_reply(id).
4. Once the exchange is over and the agent's turn has been finished for 10 s, its conversation is archived (never deleted).

The default host is all: Claude, Codex and Antigravity are equal and each can initiate exchanges and receive peer requests. The installer selects all when at least two AI apps are present. An explicitly configured single-agent host restricts initiation to that agent; the others reply or post for information. status() reports the effective setting.

[!IMPORTANT] Waking Claude. With host set to all, Claude is woken too: in the Claude desktop app, open a Code session in the folder ~\.nexus\relay\NexusRelay and set it to Auto mode. The daemon writes the wake note to that session's local inbox (Claude Code's documented per-session named pipe, never Anthropic's servers). A session in Bypass permissions holds such messages, so keep the relay session in Auto, and pin it so that tidying up chats never archives it. Turn Remote Control on for it: the app otherwise stops an idle session's process after its turn, and with it the inbox (status() then shows relay_session.open: false). Never clear it: clearing stops its process, and with it the inbox the daemon wakes it through.

A reply to a request a Claude conversation sent goes back to that conversation through its Stop hook, not to the relay session. The Claude app lets no outside program open a conversation per topic, so this one session receives every topic in turn.

Tools

Every tool carries MCP annotations (readOnlyHint, destructiveHint, …). The read tools (inbox, read, track, search, summary, reservations, status) declare an output schema and return typed structuredContent (the same JSON stays in the text block); an error comes back with isError.

Requirements

• Windows 10 or 11 (x64 or ARM64), no administrator rights, nothing else to install (the release is self-contained).
• Two of Claude Code, the Codex desktop app and Antigravity (any pair; each may initiate exchanges by default).

Manual install from source

Settings

Read from ~\.nexus\nexus-relay\settings.json (this PC), then from settings.local.json at the root of the installed folder (shared by the PCs of a synced install), key by key; values may use environment variables (%LOCALAPPDATA%, %USERPROFILE%...), and a list keeps the first existing token_file. Variables already set in the daemon's environment win.

Updates

The daemon updates itself: POST /api/update on its local API (same bearer token as /mcp) answers 202 and the daemon runs its own get.ps1 (powershell -File, no window), which installs the latest release; the daemon then restarts on it. GET /api/update returns the state, also written to ~\.nexus\status\relay.json:

{"product": "relay", "version": "1.3.0", "latest": "1.3.0", "state": "idle", "checked_at": "2026-10-26T10:00:00Z", "message": null}

state is idle, updating, done or failed (the previous version stays in place and message says why). Only an install made by get.ps1 (%LOCALAPPDATA%\NexusRelay\app) updates itself; a git checkout answers 409. Running get.ps1 again also updates.

Safeguards

• Everything listens on 127.0.0.1 only; the daemon requires the bearer token.
• Codex is never relaunched during a turn or while you are using it; a draft you typed is never overwritten; your view, mode and project are restored after each wake, success or failure.
• Only conversations born in the relay's own "NexusRelay" project (or "Nexus Relay", its earlier name) are archived, only once the agent's turn has been over for 10 s, never while you are in the app.
• An uncertain delivery to Antigravity is reported as such and never replayed.
• Antigravity open without its debugging port (for instance after its own update) is restarted with it after 5 min, never while you are in it or while one of its agents works, at most once an hour.
• A peer's message is framed as an opinion to examine, never as an instruction from you; agents never ask you questions in relay conversations.
• Attachments: absolute paths, regular files with a single name only (no hard links, no network shares), never inside a configured vault, 10 MB each and 25 MB per message at most.

Privacy

[!NOTE] The relay's own transport is local, but what a connected AI reads through the relay (messages, attached files and images) is part of its conversation: Claude Code, Codex and Antigravity send it to their model provider under their own privacy policy, as they do with everything else you show them. Do not post or attach anything you would not give those apps directly.

• What is read: the messages agents post, the files they explicitly attach, the Codex and Antigravity windows (through their local debugging ports, to open a chat, check delivery and archive relay conversations), Codex's local session logs (to know when a relay chat's turn is over, and its quota) and Antigravity's settings page (quota).
• Where it goes: it talks only to 127.0.0.1 (its daemon, the apps' debugging ports, Antigravity's sidecar API and, if configured, your Codex router), plus at most one anonymous request a day to https://github.com/pironjulien/NexusRelay/releases/latest to learn the latest version (NEXUS_RELAY_UPDATE_CHECK=0 turns it off).
• What is stored: messages and attachments in ~\.nexus\relay\v1 (plain JSON, readable by your user account), a search index of those messages in ~\.nexus\relay\v1\index (SQLite, rebuilt from the messages if deleted), interface maps of both apps in ~\.nexus\relay\v1\cartes (element roles and visible labels, which can include conversation titles shown on screen), and one line per action in %LOCALAPPDATA%\NexusJournal\relay (never a message's text).
• How to remove everything: remove the scheduled task (powershell -NoProfile -File scripts\RelayTask.ps1 -Remove in the installed folder removes "NexusRelay" and the older "Nexus Relay") and stop the NexusRelay.exe processes, then delete ~\.nexus\relay, ~\.nexus\nexus-relay, %LOCALAPPDATA%\NexusRelay, ~\.nexus\daemons\specs\nexus-relay.json, %LOCALAPPDATA%\NexusJournal\relay, the nexus-relay plugin in ~\.gemini\config\plugins and its sidecars entry in ~\.gemini\config\config.json.

To report a vulnerability, see SECURITY.md.

Limits

• Windows only; tested with Codex desktop 26.1021 and Antigravity 2.26.
• Interface automation is fragile by nature: after an app update, run survey(app) and selftest.
• The host is never woken: it waits for answers with wait_reply. Claude Code cannot be woken at all, so with another host, a message to Claude waits in its inbox.

Development

Concurrent edits rely on compare-and-swap: Claude's Edit needs the exact old text, Codex's apply_patch and Antigravity's replace need matching context, so an edit based on a stale read is refused instead of overwriting a peer's change. On top of that, the edit hook takes an automatic lease: advisory (never a refusal), held only while the tool call runs and released when it returns (success or failure), whatever the Git state of the file, or at the end of the turn; 10-minute safety expiry if no completion event comes. While another agent's edit tool runs on the same file, Claude receives a note naming it. Only an explicit exclusive reserve() (long multi-file work) refuses another holder's edit or commit.

pwsh -NoProfile -File test.ps1   # dotnet test (xUnit v3) — offline, never touches the real apps

Builds and test files go to ~\.nexus\build\nexusrelay, never into the repository. Testing a copy (clone, worktree) never switches the installed relay to it: only install.ps1 does.

MIT. Not affiliated with Microsoft, Anthropic, OpenAI or Google.