Windows and WSL

On a Windows machine, agents can run natively on Windows, inside WSL, or both. Omnodex works in either place. This page explains how the two fit together so you can set up whichever mix you use.

Two hosts on one machine

Native Windows and WSL are separate hosts. Each has its own home directory, its own agent configuration, and its own Omnodex data:

	Native Windows	WSL
Shell for setup commands	PowerShell	WSL terminal
Omnodex home	C:\Users\<you>\.omnodex\	/home/<you>/.omnodex/
Codex config	C:\Users\<you>\.codex\config.toml	/home/<you>/.codex/config.toml
Claude Code user settings	C:\Users\<you>\.claude\settings.json	/home/<you>/.claude/settings.json
Node.js	Windows install (where.exe node)	WSL install (which node)
Path style in config files	C:\... (escaped as C:\\... in JSON)	/home/..., /mnt/c/...

Which host an agent uses depends on how you start it:

• Cowork and ChatGPT Desktop run on native Windows.
• Claude Code, the Codex CLI, and other terminal agents run on whichever host you start them from: PowerShell or a WSL terminal.
• IDE extensions follow the IDE window. A VS Code window connected to WSL runs extensions in WSL; a local window runs them on Windows.

Set up Omnodex on each host where you run agents. Keep each host’s Omnodex data in its own home directory; do not point both hosts at the same directory.

Install on each host

Follow Installation once in PowerShell and once in WSL, or only on the host you use. With npm, that is npm install -g omnodex in each shell: each host has its own Node.js and its own global packages.

For a source install, a single clone can serve both hosts if it lives on the Windows drive (for example C:\src\omnodex, which WSL sees as /mnt/c/src/omnodex). Each host’s configuration must still use its own path style for that clone. If you build that clone from WSL and a change does not show up, run npx tsc -b --force.

If Windows-native Node reports ERR_MODULE_NOT_FOUND for an @omnodex/... package after you ran npm install in WSL, convert the workspace links in PowerShell from the repo root, then restart the desktop app:

PowerShell -ExecutionPolicy Bypass -File scripts\convert_symlinks_to_junctions.ps1

Hooks in a project used from both hosts

When omnodex install records every project, each host keeps its hooks in its own home folder, so a project opened from both hosts is recorded by whichever one runs the agent.

When it records only one project, it writes hook commands into the project (for example .claude/settings.local.json or .codex/hooks.json). With the default Omnodex home, those commands name no host: they run node "$HOME/.omnodex/bin/<launcher>", which each host resolves to its own home. One project can then be used from both hosts, and each host records the sessions it runs. Install Omnodex on both hosts so each has its launcher.

If you set a custom OMNODEX_HOME or install with --debug, the commands contain the installing host’s paths instead. The project can then hold one host’s hooks at a time: installing from the other host replaces them, and hooks from the wrong host fail silently. Install from the host you use for that project’s agent sessions, and run omnodex status from that host to confirm.

If the project folder is synced to another computer (by a file sync tool rather than git), exclude .claude/settings.local.json and .codex/hooks.json from sync unless both computers use the default Omnodex home.

Enforcement on each host

Each host’s enforcement mode lives in its own home, in the enforcement section of omnodex-config.json. omnodex enforce changes the mode of the host you run it on and nothing else, so set it on each host where agents run. For ChatGPT Desktop (including Codex) and Cowork, that is native Windows: run it in PowerShell.

omnodex enforce status
omnodex enforce shadow

When a project is used from both hosts, its hooks file is shared:

• Codex hooks never change with the mode, so a project’s .codex/hooks.json works the same from both hosts in every mode.
• Claude Code and Antigravity hooks answer before each call while either host is in guardrails. Omnodex keeps track in a small file beside the hooks file, such as .claude/settings.local.omnodex-guardrails.json, which exists only while a host that uses the project is in guardrails. A host that is not in guardrails still never stops a call; its agents only wait for the check.

Running omnodex enforce with the mode a host already has applies its hooks again, which repairs a project whose hooks were changed by an older version of Omnodex.

Desktop apps on native Windows

Cowork and ChatGPT Desktop start MCP servers as Windows processes:

• Use Windows paths everywhere in their configuration, including omnodex-proxy.json in C:\Users\<you>\.omnodex\.
• Use absolute paths for node.exe and npx.cmd. Desktop apps do not always see your terminal’s PATH, and user environment variables you set may not reach the MCP server.
• Fully quit and reopen the app after changing Omnodex configuration.

See the Cowork guide and the Codex guide for the exact setup.

View both hosts in one local dashboard

Each host’s dashboard reads its own Omnodex home. Add the other host’s home as an extra root to see both.

Dashboard in WSL

omnodex dashboard --roots /mnt/c/Users/<you>/.omnodex

Or add it permanently to ~/.omnodex/config.json:

{
  "dashboard": {
    "roots": ["/mnt/c/Users/<you>/.omnodex"]
  }
}

Dashboard on Windows

Find your WSL distribution name first:

wsl.exe --list --verbose

Then add the WSL home to C:\Users\<you>\.omnodex\config.json, using that name:

{
  "dashboard": {
    "roots": ["\\\\wsl$\\Ubuntu\\home\\<you>\\.omnodex"]
  }
}

The dashboard reads the other host’s event log and keeps its combined read model in its own home. It does not change the other host’s events.

Connect both hosts to the hosted dashboard

Run omnodex connect on each host with the same account. Each host stores its own connection in its own Omnodex home and appears as a separate machine in the hosted dashboard. Give them readable names with machine.label in each host’s config.json, for example "Desktop (Windows)" and "Desktop (WSL)". See Configuration.

Next steps

• Installation
• Choosing a Dashboard
• Configuration Reference