NexusWindows for Codex

Windows computer use for Codex, in the background. An MCP server (nexus-windows-codex, one npx command) that lets OpenAI Codex see and operate Windows desktop applications while the user keeps their mouse, keyboard and foreground window. Codex's own Computer Use came to macOS first; on Windows, OpenAI's documentation says to keep the target app visible on the active desktop while it runs (Codex docs). NexusWindows for Codex has its own local .NET helper for everything: window inventory, UI Automation tree, PrintWindow capture of covered windows, Win32 messages and UI Automation patterns without focus, and its own real mouse and keyboard as the last resort, under a shared foreground token. Every action is judged from the application's real state, and a batch needs an explicit postcondition per step. It also ships as a Codex skill that layers the same session over Codex's Computer Use API (@oai/sky).

Version 3.0.1 · Windows 10/11 · Node 22+ · .NET 8 · MIT licence

Part of the Nexus family: NexusWindows (Claude · Codex · Antigravity), NexusBrowser (repo), NexusAndroid (repo). Project page: julienpiron.fr/nexuswindows.

Why

Codex's built-in Computer Use acts with the physical mouse and keyboard: it brings the target window to the front and the user has to stop working while it acts. Many Windows applications can be driven without that. NexusWindows for Codex tries the background techniques first, judges the result from the application's real state, and only uses its helper's real mouse and keyboard as a fallback, after a pause in the user's own typing and under a token shared with the other agents on the PC.

It is an MCP server (Node, no npm dependency) with a self-contained .NET helper: no listening network port, no token and no private Electron API. The optional Codex skill runs the same session in Codex's Node REPL instead, over Codex's Computer Use API.

Related MCP server: codex-cua-mcp

NexusWindows family

Three MCP servers, one per agent, built separately because each model needs its tools shaped for it, with the same promise: the user keeps their mouse, keyboard and foreground window, and every action is read back.

Every step reports ✓ verified, = already done, ~ unknown (never replayed) or ✗ failed or refused. The three share the guardrail policy, the foreground token, the emergency stop (Ctrl+Alt+Shift+Esc), a common journal format and a common bench.

Installation

Windows 10 or 11 and the Codex app (or the Codex CLI). The server runs on Node.js 22 or later; the npm package carries a self-contained helper: no .NET install.

One step (installs Node.js LTS if missing, downloads and checks the server, registers it in Codex): open Windows PowerShell (Start menu, type powershell) and paste:

irm https://raw.githubusercontent.com/pironjulien/NexusWindows-Codex/main/setup.ps1 | iex

Then quit Codex completely and open it again. setup.ps1 is short and can be read first; running it again only does what is missing. Node.js comes from its official package through winget (Windows asks once for approval).

Codex plugin (the same server; Node.js 22+ required). This repository is a plugin marketplace. In the Codex app: Settings → Plugins → Add → Add a marketplace, source pironjulien/NexusWindows-Codex, then install NexusWindows from the Plugins directory. Or in a terminal:

codex plugin marketplace add pironjulien/NexusWindows-Codex
codex plugin add nexus-windows@nexus-windows-codex

By hand (Node.js 22+ required, from the official installer). In the Codex app: Settings → Plugins → Add → Add an MCP server, name nexus-windows, type STDIO, command npx, arguments -y and nexus-windows-codex@latest. Or in a terminal:

codex mcp add nexus-windows -- npx -y nexus-windows-codex@latest

Or in ~/.codex/config.toml (shared by the Codex app, CLI and IDE extension):

[mcp_servers.nexus-windows]
command = "npx"
args = ["-y", "nexus-windows-codex@latest"]

Restart Codex, then ask: "Open Notepad and write a shopping list: milk, eggs, bread." Other MCP clients use the same command (npx -y nexus-windows-codex@latest; a client that cannot start .cmd scripts needs cmd /c npx -y nexus-windows-codex@latest). With @latest, npm checks for a new version at each start: Codex runs the newest release, nothing to reinstall.

Codex skill (alternative, from a clone)

The skill runs the same session inside Codex's Node REPL and can fall back on Codex's Computer Use API. It needs the Codex desktop app with its Computer Use plugin and the .NET 8 SDK:

git clone https://github.com/pironjulien/NexusWindows-Codex.git
cd NexusWindows-Codex
pwsh -NoProfile -File install.ps1             # build the helper, install the skill into %USERPROFILE%\.codex\skills\nexus-windows
pwsh -NoProfile -File install.ps1 -CheckOnly  # verify the installation matches the sources

install.ps1 keeps versioned helper builds under %LOCALAPPDATA%\NexusCodex\ComputerUse (or -StateRoot), writes a source-linked entry.mjs next to the skill (so keep the clone where it is), checks the four .NET runtime files by hash, and serialises concurrent installations. CODEX_HOME or -CodexHome changes the Codex folder. Re-run it after updating the clone. Note: the build path must stay under the Windows 260-character limit. The MCP server also finds this helper when it runs from a clone.

The skill is picked up by new Codex sessions. A REPL that already imported an older version must be reset, because the JavaScript module cache does not reload.

Tools

Step kinds: click (selector, or point and native capture id; button, count), setValue, typeText, key, select, menu, secondary, scroll, drag, hover (one mouse move, no button). Each step reports ✓ verified, = already done, ~ unknown (look again, never replayed) or ✗ failed or refused.

Usage

As an MCP server: windows, then look at one window, then act with selectors from that look and an expect that proves the effect. An observation serves one act and expires after 60 s.

As a skill, the agent follows SKILL.md and the API reference. In Codex's Node REPL:

if (!globalThis.sky) { const { sky } = await import('@oai/sky'); globalThis.sky = sky; }
const home = nodeRepl.homeDir ?? (await import('node:os')).homedir();
globalThis.nexusWindows = await import('file:///' + home.replaceAll('\\', '/') + '/.codex/skills/nexus-windows/entry.mjs');
globalThis.win = nexusWindows.createWindowsSession(sky);
nodeRepl.write(await win.windows());          // pick exactly one window from this list
await win.bind({ id: chosenWindowId, app: chosenAppId });
globalThis.obs = await win.observe();
globalThis.result = await win.act(obs, {
  kind: 'click', selector: { automationId: 'okButton', role: 'button' },
  expect: { selector: { automationId: 'status' }, field: 'name', equals: 'Saved' }
});

Read result.status, result.technique and result.foregroundTaken, then continue from result.observation. Call await win.close() at the end.

Local files:

What it does

Background first, physical input last

Each semantic click, setValue, typeText, secondary, select and menu goes first to the helper:

A measured detail drives the design: once the managed System.Windows.Automation client has been used in a process, a COM Invoke or Toggle from that same process activates the target window despite AutoSetFocus = FALSE (WPF and WinForms on .NET 8). UI Automation patterns are therefore sent from a child process (--com-worker) that never loads the managed client. Since 1.4.0 the managed client is not loaded anywhere: the tree is read with the COM UI Automation client in one round trip (CacheRequest, Subtree scope, control view; about 50 ms for the bench forms instead of 150 to 300 ms). For an action, only the target and its ancestors are read again, and any difference from the observation is refused.

The options of a Win32/WinForms combo box are read by messages (CB_GETCOUNT, CB_GETLBTEXT, CB_GETCURSEL), open or not, as list/listitem nodes under it; expanded comes from CB_GETDROPPEDSTATE. Measured: the UIA subtree of an open WinForms combo box answers "Malformed Cacheresponse" after about 7 s and then stops answering, so it is never walked.

Each technique reads its effect back: applied, none (nothing changed) or sent (no read-back possible). Physical fallback happens only when no technique applies, or when the expect is not met and nothing observable changed. A partial effect is never repeated physically; fallback:false forbids the physical path. Every result says which technique acted (background:messages, background:uia, foreground:uia, physical:sky, sky:semantic), whether the foreground was taken, and every attempt.

Explicit postconditions

expect distinguishes verified, unmet, already-satisfied and unknown results. An observation is consumed once; a stale observation, another window, a missing or ambiguous control, or a changed control identity aborts the action before any input. A truncated UIA value cannot satisfy an exact equality, and an empty tree never proves that a control disappeared. Native password fields are refused.

A postcondition already true before the action skips it (already-satisfied, nothing sent) only when it is a precise state (equals) that the action changes: value, checked, selected, expanded or focused on the target, or a result on another element. A postcondition that only restates the target ("the button exists") is refused, and a non-precise one already true (exists, includes, the target's label) is refused before any input: it could not tell the effect from the previous state. A combo box choice is proven by the combo box value, never by its option element.

Clean capture with PrintWindow

observe({mode:'image', capture:'native'}) captures the bound window with PrintWindow(PW_RENDERFULLCONTENT) without bringing it forward, even when covered: per-monitor DPI aware, cropped to the DWM frame, DPI-unaware windows drawn at their logical size and scaled. In the Codex skill, a blank, minimized or failed capture falls back to Sky's screenshot; the MCP server has no such fallback and reports the failure. Native images follow the common Nexus image rule: at most 1568 px and 1.15 MP, lossless WebP from a built-in encoder (near-lossless above 200 KB, never over 500 KB), local files (32 at most, removed after 10 minutes at the next capture, at server start and at a clean stop): evidence for the model, and the coordinate frame of a point action that names the image (screenshotId), scaled back to the screen pixel. look(region=[x1, y1, x2, y2]) reads an area of the last full image at full resolution, enlarged up to 2x for small text; its own screenshotId takes points. An image identical to the last one sent for that window (same pixels and frame) is not attached again; the reply names the id that takes points, and mode="image" always attaches it. look(mode="both", marks="auto"|"all") reads the tree just before the capture and draws on the image the tree line number of each kept element (auto: unnamed controls; all: every element with a rectangle), at a constant size after scaling; no number when the window moved between the two reads, on another window's popup, or when the label does not fit whole. Default none. Numbers link the image to the tree; act still targets a selector or a point.

Verified batches (actBatch)

actBatch(obs, steps) runs up to 32 actions in one call. Every step needs an expect; all steps are validated before any input; each step acts on the observation refreshed by the previous one; the batch stops at the first step that is not verified or already-satisfied.

Multiple windows

The session follows dialogs and popups without a new bind: windows owned by the followed windows, windows that disable the window in front (modal), and windows of the same process that appear during an action. When a dialog closes, the session returns to its nearest open owner. Each observation reports windowStack and windowChange. Transient popups (caption-less WS_POPUP windows with WS_EX_NOACTIVATE: an open drop-down list, a tooltip, a WPF popup; or a Win32 ComboLBox) are never followed: they are read through the window's own tree and listed in obs.popups.

Guardrails: one shared policy

Since 1.5.0 the guardrails come from the policy shared by the three NexusWindows editions (Codex, Claude, Antigravity), garde-fous.json, with a codex entry. A copy is embedded at the root of this repository; inside the author's private workspace the live shared file is read instead (a test checks both are byte-identical). NEXUS_GARDE_FOUS can point to another file; an imposed path is never silently replaced. A missing or invalid policy refuses every action (fail closed), and the .NET helper refuses every window request without a readable policy.

Hard block (refused before any read or input): the secure desktop (UAC, lock screen, sign-in), Windows credential prompts, password managers (KeePass, Bitwarden, 1Password, Dashlane, NordPass, RoboForm, LastPass, by process prefix), and Codex's own application (Codex, ChatGPT), because Codex Computer Use asks for app access inside its main window. Consoles and terminals, File Explorer and administration tools are no longer refused (they were until 1.4.1): the layer is meant for a user who already lets Codex run commands. Password fields stay refused everywhere, and their value is never read.

Confirmation (confirm:true on the action, set only on the user's explicit order or after their yes): paying, calling, sending, publishing, deleting permanently, formatting, uninstalling, resetting, cancelling a subscription, making a repository public, plus a generic verb (Validate, OK, Start) in a window whose title is about payment or formatting. The check is on what the gesture triggers, not on its form, before any input and whatever technique follows: a click by selector or by screenshot coordinates (single or double; a text or icon inside a button counts as the button), Enter, Ctrl+Enter, Space, Alt+letter (access key or underlined letter), typed text containing a line break, a menu command, a secondary action other than expand, collapse, toggle, select or scroll. The refusal (error.confirmationRequired) sends nothing; a batch stops at that step. A learned recipe never carries confirm. Direct calls to Sky bypass this layer: always go through the session.

The user's presence (Raw Input)

A long-lived --stop-guard process registers Raw Input (RIDEV_INPUTSINK, message-only window, no hook). It reports only the instant of each physical keyboard or mouse input, never its content. Injected input, including Sky's own SendInput, has no source device and is ignored. Before any physical input the session waits for 1.618 s without user input (at most 8 s, otherwise the action is deferred and nothing is sent), then types in chunks of at most 48 graphemes and stops (interrupted, never resent) if the user takes the keyboard or mouse back. Without Raw Input it falls back to GetLastInputInfo, excluding its own injections.

Application memory

A verified semantic click or secondary action can be saved as a recipe with its expected effect, a fingerprint of the executable's metadata and one of the control structure. Any change forces a new inspection. No control number or pixel is ever replayed, and typed content is never stored.

Agent at work

While an action runs (act, actBatch, activate; never an observation), a small logo spins on itself in the bottom-right corner of the bound window's screen, like a game loading screen, with a breathing blue halo. It goes away 1.6 s after the last action. The emergency-stop guard, already alive for the whole REPL, draws it on the commands busy <hwnd> and idle (native/BusyIndicator.cs): a layered window that is always on top, borderless, click-through, never activated, absent from the taskbar and excluded from screen captures. Rendering is analytic (halo, shadow, coin) from native/logo.png decoded by GDI+, with no added dependency. NEXUS_WINDOWS_INDICATOR=0 turns it off.

Working alongside other agents

This layer runs next to two other desktop agents on the same PC (a Claude MCP server, NexusWindows for Claude, and an Antigravity layer). They coordinate through two file-based protocols that any agent can implement:

Foreground token (%USERPROFILE%\.nexus\foreground.lock): held only while really using the mouse or the foreground (Sky physical input, activation, the foreground UIA fallback), never for reads or background techniques. Holding it means an exclusive LockFileEx on 1 byte at offset 2^32 (in C#: FileStream with FileShare.ReadWrite | FileShare.Delete, then Lock(1L << 32, 1)). Windows releases it when the handle closes, including when the process dies. The holder writes {"owner", "pid", "since", "purpose"} for diagnostics only. A waiter waits at most 8 s, then reports a deferred action and sends nothing.

Emergency stop (Ctrl+Alt+Shift+Esc, files in %USERPROFILE%\.nexus\): one process per PC holds RegisterHotKey(MOD_NOREPEAT) (others retry every 3 s) and beats in stop.owner every 3 s; a press rewrites stop with {"by", "pid", "at", "hold_s": 120, "nonce"}. Here the --stop-guard helper takes the hotkey when nobody else holds it, for as long as the Codex REPL lives. The JavaScript session watches stop every 0.2 s and before each action, and the helper checks it again before each UIA action and token acquisition. A new version younger than 120 s blocks every desktop action for the remaining time; observations stay allowed. The stop is latched in memory on a monotonic clock: deleting the file or changing the clock does not lift it.

Architecture

flowchart LR
    Codex["Codex"] --> MCP["MCP server bin and lib mcp.mjs"]
    MCP --> Provider["lib native-provider.mjs"]
    Provider --> Session["lib session.mjs"]
    Codex --> Skill["skill entry.mjs in the Node REPL"]
    Skill --> Session
    Session -. skill only .-> Sky["Codex Computer Use API"]
    Session --> Native["lib native.mjs"]
    Native --> Helper["NexusCodex.UIA server"]
    Helper --> Messages["Win32 messages"]
    Helper --> ComWorker["COM only worker for UIA patterns"]
    Helper --> Capture["PrintWindow capture"]
    Session --> Guard["stop guard with Raw Input"]
    Guard --> Shared["shared files in USERPROFILE nexus"]
    Helper --> Shared

bin/nexus-windows-codex.mjs   the MCP server command (stdio)
lib/
  mcp.mjs        MCP protocol and tools (no npm dependency)
  native-provider.mjs  window inventory by the helper, every window driven by the helper alone
  session.mjs    WindowsSession: bind, observe, act, actBatch, recipes, window following
  native.mjs     client for the .NET helper (one reused process, correlated requests, timeouts)
  tree.mjs       accessibility tree normalisation and digests
  memory.mjs     recipes and metrics (atomic, locked writes)
  presence.mjs   user presence from the stop guard
  stop.mjs       emergency stop watcher and guard process
native/          .NET 8 helper: Program.cs (modes --server, --com-worker, --stop-guard, --foreground-token),
                 Background.cs, ComUia.cs, ComWorker.cs, Capture.cs, Presence.cs, EmergencyStop.cs,
                 ForegroundToken.cs, Win32.cs
skill/nexus-windows/   SKILL.md and references (API, per-application notes)
tests/           node:test suites; tests/live: real validation fixture (WinForms, Win32, WPF)
setup.ps1        one-step setup: Node.js if missing, server from npm checked, registered in Codex
.codex-plugin/, .mcp.json, .agents/plugins/marketplace.json   Codex plugin and its marketplace
install.ps1      builds the helper and installs the skill
test.ps1         offline check; -Full adds the real validation

Measurements

Real validation of October 15, 2026 on the repository's own fixture (tests/live, run by test.ps1 -Full). Windows shown without activation at the bottom of the z-order, the Win32 one covered by the WinForms one. Each action: postcondition verified, event counted by the application, foreground unchanged, cursor still.

Offline suite: 108 JavaScript tests, 103 passed and 5 real-environment tests skipped outside -Full (test.ps1, October 16, 2026). Durations are dominated by full UIA tree read-backs. The physical fallback that takes the foreground was skipped in that run because the user was active; it is not counted as passed.

Common bench of the NexusWindows family (October 25, 2026)

The three editions are measured together by the family's common bench: 55 tasks on lab windows (Win32, WinForms, WPF, Tk, Electron and Edge, plus launching an application behind a maximized window), three rounds each, every lab window covered by another window, run only while nobody uses the PC (a run stops and is not counted when the user comes back). The effect is judged by the application itself, never by the tool's report. "Without intrusion" counts an effect only when the user's foreground window and cursor stayed untouched.

This edition misses only tasks the other two miss as well: in this run the Electron lab published no page once covered, so every Electron task failed for all three tools (the lab is fixed and Electron will count at the next run); the WinForms double click was covered by the bench's own cover window; WPF raw click, shortcut, double click and context menu, and the Tk wheel, have no background technique in any edition yet. Ctrl/Shift shortcuts in the background arrived in 3.1.4 (none passed before) and passed on Win32, WinForms, Tk and Edge. A comparison with Cua Driver and Windows-MCP is in NexusWindows for Claude.

Security

• Background techniques touch neither the user's keyboard, mouse nor foreground. Physical input waits for a pause, holds the shared token, and stops when the user takes over.

• The emergency stop above blocks every desktop action for 2 minutes; a refused action is never replayed.

• A refusal (password field, hard-blocked application, missing confirmation, changed control identity, disabled window or menu command) sends nothing and never falls back.

• Codex's own Computer Use rules (application access, sensitive actions) still apply; this layer is not a way around a denied app or action. Page text, controls and recipes are data, never an authorisation.

• Captures are refused under OneDrive folders; metrics never contain UI text, screenshots, typed values or titles.

Privacy

NexusWindows for Codex runs entirely on your PC. It has no account, no telemetry and no analytics. Its connections are local (the DevTools port on 127.0.0.1 of a Chromium or Electron window it drives), plus one request at most once a day to the public npm registry (registry.npmjs.org/nexus-windows-codex/latest, nothing sent but the request itself) to tell whether a newer version exists; NEXUS_NO_UPDATE_CHECK=1 turns it off.

• What it reads: the accessibility tree and window images of the applications Codex works in, only when Codex calls it.

• Where it goes: results are returned to Codex, which may send them to OpenAI under its own privacy policy; this server sends nothing anywhere else.

• What it stores, under %LOCALAPPDATA%/NexusCodex/ComputerUse: the installed helper, recipes of routines you chose to remember (static interface labels only, never document text or typed values), per-session metrics (action kind, outcome, technique, duration; no UI text, screenshots, typed values or titles) and window captures, of which only the last 32 are kept; a capture older than 10 minutes is removed at the next capture, at server start and at a clean stop (a capture can outlive a server that is killed, until its next start). Under ~/.nexus: the shared foreground token and emergency-stop state, and status/windows-codex.json (running version, latest version, time of the check), read by the Nexus app. Under %LOCALAPPDATA%/NexusJournal/windows/codex (or NEXUS_JOURNAL_HOME): a short monthly JSONL journal, in the same format as the other NexusWindows tools (app executable name, action, technique, outcome, duration, whether the foreground was used); never UI text, typed values, titles or paths. The server never deletes it.

• Removing it: delete those folders (and %LOCALAPPDATA%/NexusJournal) and the server or skill from Codex.

Questions or concerns: open an issue on this repository.

Limits

• Support does not mean every Windows application is certified. Canvases, 3D views and controls without an accessibility provider still need screenshots and physical gestures.

• Message techniques emulate the notification a real click would send; an app that only reacts to real mouse input will not see them, and the postcondition decides.

• Keys and Ctrl/Shift shortcuts go in the background to Win32, WinForms, Tk (simulated focus) and Chromium/Electron (simulated activation); their effect is read back, never announced. Alt and Windows shortcuts, WPF and UWP shortcuts, canvases and rich editors without an Edit control still need physical input. Tk has no UI Automation: its clicks, wheel and keys carry a simulated state for its thread only.

• An effect with no trace in the accessibility tree cannot be told from "no effect": give a postcondition that observes it, or fallback:false.

• launch attributes a window to the launch by its process, and says how (proof): process, the process the shell returned; or application, for an application named by its executable or Store id (whose launcher may hand over to another process), a process of that application born after the request. With application, another instance of the same application started by something else at the same moment could be taken for it. Files and folders need an absolute path; their windows come back as candidates unless the shell returned the process that shows them.

• In the skill, Sky's physical input cannot be tested outside the Codex REPL; its orchestration (pause, token, chunks, interruption) is covered by the offline tests only. The MCP server never uses Sky.

• The skill, comments and some messages are written for one user (they name the user) and partly in French.

Development

pwsh -NoProfile -File test.ps1         # node tests + helper build in a temp folder; never touches %USERPROFILE%\.nexus
pwsh -NoProfile -File test.ps1 -Full   # also real token/stop tests and the background validation on the fixture

Licence

MIT, see LICENSE. Copyright (c) 2026 Julien Piron.