Cowork Desktop Setup

Omnodex integrates with Cowork Desktop via a plugin that routes MCP tool calls through the Omnodex proxy. Every tool call your agent makes through an MCP server is captured, traced, and surfaced in the dashboard.

How this differs from Claude Code

Claude Code integration is hook-based and captures all tool calls (file reads, bash, web search, MCP). Cowork integration is proxy-based: it captures MCP tool calls specifically. Hook-level tracing for Cowork is planned for a future release.

---

User Guide

This section covers installation for end users running the published Omnodex plugin.

Prerequisites

Node.js must be installed natively on your OS. The Omnodex plugin spawns the proxy as a child process using the system node binary.

macOS

Install via Homebrew or the nodejs.org installer:

brew install node@24
node --version

Windows

Download and install Node.js LTS using the Windows installer. If Node.js is only installed inside WSL, the plugin cannot start the proxy.

Verify in PowerShell:

node --version

If node is not found, restart your machine after the install and try again.

Linux

Install via your package manager or NodeSource:

curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs
node --version

Installation

1. Install the Omnodex plugin:

   Drag omnodex-cowork.plugin onto the Cowork window, or open Settings -> Plugins and install from file.

   Confirm the plugin appears as omnodex-cowork in the installed plugins list.

2. Create the proxy configuration file:

   Omnodex needs to know which upstream MCP servers to intercept. Create the config at ~/.omnodex/omnodex-proxy.json:

   macOS / Linux

   mkdir -p ~/.omnodex

   Create ~/.omnodex/omnodex-proxy.json:

   {
     "version": 1,
     "redact_parameters": false,
     "upstream_servers": [
       {
         "name": "my-server",
         "transport": "stdio",
         "command": "npx",
         "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/<you>/Documents"]
       }
     ]
   }

   Windows

   New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.omnodex"

   Create C:\Users\<you>\.omnodex\omnodex-proxy.json:

   {
     "version": 1,
     "redact_parameters": false,
     "upstream_servers": [
       {
         "name": "my-server",
         "transport": "stdio",
         "command": "npx",
         "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\Users\\<you>\\Documents"]
       }
     ]
   }

   Use Windows-native paths (C:\...) in the args array. WSL paths like /home/... will not work here.

   Replace the example entry with the MCP servers you actually use.

3. Start a Cowork session and verify the connection:

   Type /omnodex in the chat. If the proxy connected successfully, you will see a summary of the current session’s MCP tool activity.

   If the skill reports that the proxy is not connected, see Troubleshooting below.

Viewing Events

Cowork events are stored in ~/.omnodex/ (macOS/Linux) or C:\Users\<you>\.omnodex\ (Windows). To view them in the Omnodex dashboard:

macOS / Linux

npx omnodex dashboard

No extra configuration needed. The dashboard reads from ~/.omnodex/ by default.

Windows (PowerShell)

$env:OMNODEX_HOME = "$env:USERPROFILE\.omnodex"
npx omnodex dashboard

WSL

Because Cowork is a native Windows process, it writes events to the Windows home directory - not the WSL home. Point the dashboard at the Windows path:

OMNODEX_HOME=/mnt/c/Users/<you>/.omnodex npx omnodex dashboard

Without OMNODEX_HOME, the dashboard reads from the WSL home (~/.omnodex), which is a separate directory that Cowork does not write to.

Troubleshooting

Proxy does not connect after plugin install:

1. Confirm Node.js is installed at the OS level and in PATH:

   • macOS/Linux: which node
   • Windows: where.exe node in PowerShell

   If it returns nothing, install Node.js (see Prerequisites above) and restart Cowork.

2. Confirm ~/.omnodex/omnodex-proxy.json exists (macOS/Linux) or C:\Users\<you>\.omnodex\omnodex-proxy.json (Windows). On Windows, Cowork looks for the config in the Windows home, not the WSL home.

3. Check ~/.omnodex/launcher.log (macOS/Linux) or C:\Users\<you>\.omnodex\launcher.log (Windows) for error details. If the file does not exist, the launcher never ran - this points to Node.js not being found in PATH. If the file exists but shows an error, read it to diagnose further.

4. (Windows only) Verify paths in your config use Windows format (C:\...). WSL-style paths (/home/...) are not resolved by the Windows-side proxy.

Events appear in the wrong place (Windows/WSL only):

Cowork writes to C:\Users\<you>\.omnodex\. If omnodex dashboard shows no events, check that OMNODEX_HOME points to the Windows home path (see Viewing Events above). This issue does not apply on macOS or Linux.

---

Developer Guide

This section is for contributors building and testing Omnodex from source.

Prerequisites

In addition to the Node.js requirement above, you need:

• Both source repos cloned: source/omnodex/ and source/omnodex-plugins/
• Monorepo built: cd source/omnodex && npm install && npm run build
• Plugin bundle built: cd source/omnodex-plugins && node scripts/build-plugin.mjs cowork

WSL + Windows: fixing workspace symlinks

Note

This section applies only to Windows/WSL development. macOS and Linux do not have this issue.

When npm install runs inside WSL, npm workspaces create LX_SYMLINK reparse points that Windows-native Node.js cannot follow. This causes ERR_MODULE_NOT_FOUND errors when Cowork tries to load the proxy.

After every WSL npm install, run the junction-conversion script from PowerShell (repo root):

PowerShell -ExecutionPolicy Bypass -File scripts\convert_symlinks_to_junctions.ps1

Then restart Cowork. The compiled .js files in dist/ do not need to be rebuilt.

Proxy binary override (proxy_bin)

Cowork strips user-level environment variables when spawning MCP server child processes. The OMNODEX_PROXY_BIN env var is silently ignored. Instead, use the proxy_bin field in omnodex-proxy.json to point the launcher at your local build:

macOS / Linux

{
  "version": 1,
  "proxy_bin": "/path/to/source/omnodex/packages/mcp-proxy/dist/bin/omnodex-mcp-proxy.js",
  "redact_parameters": false,
  "upstream_servers": [
    {
      "name": "filesystem",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/<you>/Documents"]
    }
  ]
}

Windows

{
  "version": 1,
  "proxy_bin": "C:\\Users\\<you>\\path\\to\\source\\omnodex\\packages\\mcp-proxy\\dist\\bin\\omnodex-mcp-proxy.js",
  "redact_parameters": false,
  "upstream_servers": [
    {
      "name": "filesystem",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\Users\\<you>\\Documents"]
    }
  ]
}

Update proxy_bin whenever you rebuild the monorepo or move the repo directory.

Enabling verbose diagnostics

macOS / Linux

export OMNODEX_DEBUG=1

Then restart Cowork.

Windows

Set OMNODEX_DEBUG=1 as a Windows user environment variable and restart Cowork:

[System.Environment]::SetEnvironmentVariable("OMNODEX_DEBUG", "1", "User")

With this set, the launcher writes detailed resolution logs to ~/.omnodex/launcher.log (macOS/Linux) or C:\Users\<you>\.omnodex\launcher.log (Windows), including every binary search attempt and the final path used. Fatal errors are always written to this file regardless of the flag.

Reading the launcher log

~/.omnodex/launcher.log (macOS/Linux) or C:\Users\<you>\.omnodex\launcher.log (Windows) is your first stop for diagnosing proxy startup failures:

Log entry	Cause
[omnodex] Could not locate omnodex-mcp-proxy	Binary not found; check proxy_bin in config
[omnodex] Failed to spawn proxy	Spawn ENOENT; proxy_bin path does not exist
ERR_MODULE_NOT_FOUND: Cannot find package '@omnodex/event-log'	WSL workspace symlinks (Windows only); run the junction-conversion script

Viewing Cowork events from WSL (Windows only)

If you develop on Windows/WSL and need to view Cowork events from the WSL dashboard:

OMNODEX_HOME=/mnt/c/Users/<you>/.omnodex node packages/cli/dist/index.js dashboard

This points the dashboard at the Windows home where Cowork writes its event log. On macOS and Linux, npx omnodex dashboard works without any override.

---

Next Steps

• Running Detection - Risk detection works the same across all interceptors
• Using the Dashboard - Navigate the real-time dashboard
• Configuration Reference - Full proxy configuration options