Skip to content
Omnodex Omnodex Omnodex Docs

OpenAI Codex Setup

Omnodex traces OpenAI Codex in the Codex mode of ChatGPT Desktop, the Codex CLI, and the Codex IDE extension.

What gets installed

Section titled “What gets installed”

There are two independent parts. You can use either one, and the full setup uses both.

PartWhat it doesHow you install it
HooksRecord Codex session lifecycle and the tool calls Codex runs locally, such as shell commands and file editsomnodex install codex in each project
Omnodex pluginRegisters the Omnodex MCP server, routes the upstream MCP servers you choose, and adds the omnodex_status, omnodex_connect, and omnodex_connection_status toolsInstall once per host from a local marketplace

omnodex install codex installs hooks only. The plugin installs the MCP connection; it does not install hooks or the Omnodex runtime. You can also register the MCP server manually if you prefer.

For the full setup: install the runtime, install the plugin, install hooks in your project, then optionally connect to the hosted dashboard. Plugin downloads are public, including for Free users.

Choose where Codex runs

Section titled “Choose where Codex runs”

Codex reads its configuration from the Codex home on the host where it runs. Desktop, CLI, and IDE share configuration only when they run on the same host.

Where Codex runsCodex configOmnodex homePath style
Native Windows (ChatGPT Desktop, or the CLI in PowerShell)C:\Users\<you>\.codex\config.tomlC:\Users\<you>\.omnodex\Backslashes
WSL/home/<you>/.codex/config.toml/home/<you>/.omnodex/Forward slashes
macOS/Users/<you>/.codex/config.toml/Users/<you>/.omnodex/Forward slashes
Linux/home/<you>/.codex/config.toml/home/<you>/.omnodex/Forward slashes

ChatGPT Desktop on Windows runs Codex natively; WSL is not required. If you also run the Codex CLI inside WSL, that is a second host with its own configuration and its own Omnodex data. Set up each host you use. Windows and WSL covers running both.

An npm install in WSL does not cover native Windows Codex. Install with npm in PowerShell as well if you use ChatGPT Desktop or the CLI on Windows. Run updates on both hosts, using each host’s shell and Node.js installation.

Never mix path styles: do not put C:\... paths in WSL configuration, or /mnt/c/... or ~ in configuration used by native Windows.

Before you start

Section titled “Before you start”

On the host where Codex runs:

  1. Install Omnodex on this host: from npm, or from source including the omnodex-config.json step for hooks.
  2. Confirm Node.js 24+ is available. The plugin starts with node; if your desktop app cannot find it, use the absolute path printed below in the unpacked plugin’s .mcp.json command field before installing it.
Terminal window
where.exe node
node --version

Install the Omnodex plugin

Section titled “Install the Omnodex plugin”

The plugin’s Node.js launcher works on native Windows, macOS, and Linux. A personal marketplace makes the downloaded plugin available in the app’s Plugins directory. You do not need to add a separate MCP server entry.

The app steps below apply to the host running ChatGPT Desktop. For a CLI-only host without the desktop plugin browser, such as WSL, use the manual MCP alternative on that host. Installing the plugin in the Windows app does not install it inside WSL.

  1. Configure the proxy.

    Create omnodex-proxy.json in your Omnodex home. Its location is C:\Users\<you>\.omnodex\ on native Windows or ~/.omnodex/ on macOS, Linux, and WSL.

    The plugin finds the npm install on its own:

    {
      "version": 1,
      "redact_parameters": false,
      "upstream_servers": []
    }

    An empty upstream_servers list is enough to use Omnodex’s status and dashboard connection tools. To record other MCP servers at the proxy layer, add them using the proxy configuration reference. Keep any existing upstream entries when adding proxy_bin.

  2. Download and unpack the plugin.

    Download omnodex-codex.zip and extract its contents into ~/.codex/plugins/omnodex-codex/ (C:\Users\<you>\.codex\plugins\omnodex-codex\ on Windows).

    The archive contains files at its root: .codex-plugin/plugin.json, .mcp.json, and bin/launch-proxy.js should be directly inside that folder, without an extra nested folder. If your archive tool hides files beginning with a dot, make sure it still extracts them.

  3. Add it to a personal marketplace.

    Create ~/.agents/plugins/marketplace.json (C:\Users\<you>\.agents\plugins\marketplace.json on Windows), creating the parent folders if needed:

    {
      "name": "omnodex-local",
      "interface": { "displayName": "Omnodex local" },
      "plugins": [
        {
          "name": "omnodex-codex",
          "source": { "source": "local", "path": "./.codex/plugins/omnodex-codex" },
          "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" },
          "category": "Productivity"
        }
      ]
    }

    The source.path is relative to your home directory, the personal marketplace root, rather than to .agents/plugins/. The forward slashes in this relative path work on Windows too.

    If you already have a personal marketplace, keep its name and other plugins, and append only the omnodex-codex entry to its plugins array. You can keep an existing marketplace name such as local-testing; it does not need to be named omnodex-local.

  4. Install in the app.

    Fully quit and reopen ChatGPT Desktop. Open Plugins, select your personal marketplace (Omnodex local in the example), open Omnodex, and install it. Confirm it is enabled, then start a new Codex conversation.

    Ask Codex to call omnodex_status. In the CLI, /mcp also shows the server connection. A plugin installed and enabled on this host can be used by local Codex CLI and IDE sessions using the same Codex home.

This is the local marketplace workflow described in OpenAI’s plugin documentation. It does not require Omnodex to be listed in OpenAI’s public directory or a login to download the archive.

Alternative: register the Omnodex MCP server manually

This is an alternative to plugin installation. Skip this section if you installed the plugin. You can use the same proxy configuration from above; proxy_bin is used by the plugin launcher, while a manual entry names the proxy script directly.

The entry runs the proxy script with Node.js, including on Windows, where node cannot run npm’s .cmd wrapper. The script is:

<global node_modules>/omnodex/bin/omnodex-mcp-proxy.js, where npm root -g prints the global node_modules folder. Run it on the same host as Codex. On Windows it is usually C:\Users\<you>\AppData\Roaming\npm\node_modules\omnodex\bin\omnodex-mcp-proxy.js.

  1. Create the proxy configuration.

    List the upstream MCP servers to route in omnodex-proxy.json in your Omnodex home. The file may list none, in which case the proxy serves only its built-in omnodex_* tools:

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

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

    Use the npx.cmd path that where.exe npx prints.

    Replace the example with the MCP servers you want Omnodex to see. Put secrets in environment variables and reference them as ${VAR} in an upstream’s env, never as literal values. See Configuration.

  2. Add the server in ChatGPT Desktop.

    Open Settings > MCP servers > Add server, choose STDIO, and enter:

    FieldValue
    Nameomnodex
    CommandAbsolute path to Node.js
    ArgumentsThe proxy script above, --config, and the path to your omnodex-proxy.json

    Use absolute paths in the path style of the host. Save, then restart Codex.

  3. Or add it from the CLI or a config file.

    codex mcp add writes the same entry to the host’s config.toml, so the Desktop app, CLI, and IDE extension on that host all see it.

    These fill in the Node.js and proxy paths for you:

    Terminal window
    codex mcp add omnodex -- (Get-Command node).Source "$(npm root -g)\omnodex\bin\omnodex-mcp-proxy.js" --config "$env:USERPROFILE\.omnodex\omnodex-proxy.json"
    codex mcp list

    The same entry in config.toml, with the proxy script from above. On Windows, TOML literal strings (single quotes) keep backslashes as they are:

    [mcp_servers.omnodex]
    command = 'C:\Program Files\nodejs\node.exe'
    args = [
      'C:\path\to\omnodex-mcp-proxy.js',
      '--config',
      'C:\Users\<you>\.omnodex\omnodex-proxy.json',
    ]

    To remove it: codex mcp remove omnodex.

  4. Verify.

    Start a new conversation, enter /mcp, and confirm omnodex is connected. Ask Codex to call omnodex_status, then to call one of the routed tools. Routed tools appear as <server>__<tool>, for example filesystem__list_allowed_directories.

    Start a new conversation after changing MCP servers. Existing conversations keep the tool list they started with.

Install the hooks

Section titled “Install the hooks”

  1. Install into the project.

    From the project directory, in the shell of the host where Codex runs:

    Terminal window
    omnodex install codex

    This writes Omnodex entries to <project>/.codex/hooks.json. Hooks are enabled by default in Codex; there is no feature flag to set. If hooks do not run at all, check that your config.toml does not contain hooks = false under [features].

    When it finishes, the command offers to connect this host to the hosted dashboard. Press Ctrl+C to skip; the hooks are already installed.

  2. Trust the hooks in Codex.

    Codex does not run new project hooks until you trust them. When Codex prompts you to review the hooks for the project, approve the Omnodex entries.

    Codex may report that it clamps the SessionEnd hook timeout to 3 seconds. That is expected; the hook finishes well within it.

  3. Verify.

    Start a new conversation in the project and have Codex run a shell command. A session file for it appears under event-log/sessions/ in your Omnodex home.

What gets traced

Section titled “What gets traced”
ActivityRecorded byNotes
Session start and endHooks
Thread namesHookssession.renamed when Codex names the thread or you rename it, read from Codex’s session index
Shell commandsHookstool.invoked and tool.completed with timing and status
File edits (apply_patch)HooksRecorded as tool calls, not yet as file.written events
MCP tool calls routed through OmnodexOmnodex MCP serverParameters (unless redacted), timing, status, and response size
MCP server sessionsOmnodex MCP serverSee the note below about session end
Hosted tools such as web searchNot visibleThese run on OpenAI’s side, outside local hooks

Hooks and the MCP server record different layers. A call routed through Omnodex can appear once from each. Use redact_parameters in omnodex-proxy.json to keep parameter values out of the log for any upstream.

When ChatGPT Desktop quits, it may stop the Omnodex MCP server without closing its connection, so the proxy session can be missing its end event. Tool call records are not affected.

Connect to the hosted dashboard

Section titled “Connect to the hosted dashboard”

On each host, run:

Terminal window
omnodex connect

This starts a device code flow: the CLI shows a short code and a URL. Open the URL, sign in or create an account, and enter the code. The API token and sync passphrase are stored in stream-config.json in that host’s Omnodex home. The passphrase is transferred end-to-end encrypted.

You can also connect from inside Codex by asking it to call omnodex_connect from the Omnodex MCP server.

If a stream is disconnected or revoked in the dashboard, run omnodex connect again.

View results

Section titled “View results”
Terminal window
omnodex dashboard

Codex events carry interceptor: "codex-hook" (hooks) or interceptor: "mcp-proxy" (MCP server), so you can tell the sources apart in the dashboard.

Updating

Section titled “Updating”

  1. Update your Omnodex runtime on each host where Codex runs: PowerShell for ChatGPT Desktop and the CLI on native Windows, a WSL terminal for the CLI in WSL.

    Run omnodex update. The plugin launcher and hook launchers use the installed package; no build is needed.

    See Updating. Neither method downloads a new plugin archive.

  2. Update the plugin only when its package changes.

    Compare .codex-plugin/plugin.json in your plugin folder with the Codex version in the release manifest. A runtime update alone does not require a plugin reinstall.

    For a new plugin release, uninstall Omnodex from your personal marketplace in the app, replace the contents of ~/.codex/plugins/omnodex-codex/ with the latest ZIP, then restart the app and install it again from the same marketplace. Keep your marketplace entry and proxy configuration.

    Codex can load an installed copy from its plugin cache, so replacing the source folder alone may leave the old installed files in use. Reinstalling refreshes that copy. If you use manual MCP registration, skip this step.

  3. Restart Codex. Fully quit and reopen ChatGPT Desktop, or start a new CLI session. Then start a new conversation: existing conversations keep the tool list they started with.

  4. Verify. Ask Codex to call omnodex_status and omnodex_connection_status. Run a shell command in a project with hooks installed, then check the local dashboard, or the hosted dashboard if connected. In the CLI, /mcp also confirms the server connection.

For a marketplace tracked through codex plugin marketplace add, codex plugin marketplace upgrade <marketplace-name> refreshes that marketplace source. It does not download Omnodex’s public ZIP into a manually maintained local plugin folder. Use the steps above for the personal marketplace setup on this page.

Troubleshooting

Section titled “Troubleshooting”

omnodex does not show as connected in /mcp:

  • Run the command from the server entry yourself in the host’s shell. It should start and wait for input; press Ctrl+C to stop it. If it exits with a config error, fix omnodex-proxy.json.
  • Check that every path in the entry is absolute and uses the host’s path style.
  • Restart Codex after any change to MCP servers.

No hook events:

  • Run omnodex status in the project to confirm the hooks are installed.
  • Confirm you trusted the hooks in Codex for this project.
  • Check launcher.log in your Omnodex home. Could not locate codex hook shim means the launcher could not find Omnodex: for a source install, omnodex-config.json is missing or has the wrong codex path; for an npm install, omnodex is not on the PATH Codex runs hooks with.
  • The conversation must be in the project where you installed the hooks.

ChatGPT on the web: web sessions, including Codex on the web, do not use the Codex configuration on your machine, so local hooks and the Omnodex MCP server do not see them.

Plugin missing from the directory: check that marketplace.json is valid JSON and that its source.path points to the unpacked plugin folder. Fully restart the app after creating the marketplace.

Plugin installed but the server does not start: the current plugin uses a Node.js launcher on Windows and Unix. Check that Node.js 24+ is available to the app. For source installs, check proxy_bin; for npm installs, confirm the package includes omnodex-mcp-proxy and was installed on the same host as Codex. If the desktop app cannot locate your npm prefix, set proxy_bin to the full JavaScript path from the manual setup above. Fatal launcher errors are written to launcher-codex.log in your Omnodex home. If your old plugin references launch-proxy.sh, replace it with the latest download.

Next steps

Section titled “Next steps”