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.

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

omnodex install writes hook commands into the project (for example .claude/settings.local.json or .codex/hooks.json), and those commands contain the installing host’s paths. A project folder can hold one host’s hooks at a time: installing from the other host replaces them, and hooks from the wrong host fail silently.

If you open the same project from both hosts, install the hooks from the host you use for that project’s agent sessions. 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; they contain machine-specific paths.

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
• Using the Dashboard
• Configuration Reference