OpenAI Codex Setup (Beta)

Beta Integration

Codex support is in beta. The Codex runtime currently exposes hooks for bash commands and session lifecycle. File writes, MCP calls, and web search events are not yet interceptable. Coverage will expand as Codex adds upstream hook support.

Omnodex supports tracing OpenAI Codex sessions via Codex’s hook system. The integration approach is the same as Claude Code: hook-based, async, non-blocking.

This guide applies to both the Codex CLI (terminal) and Codex Desktop app. On macOS and Linux, everything runs natively. On Windows, Codex Desktop runs a WSL-based agent internally - see the Desktop app note below.

Prerequisites

Hooks must be enabled in ~/.codex/config.toml (add the section if it does not exist):

[features]
hooks = true

Restart Codex after editing this file.

Installation

1. Install the hook into your project:

   Run this once per project you want to trace, from the project root:

   npx omnodex install codex

   This creates a .codex/hooks.json file that routes Codex events through Omnodex.

2. Verify the configuration:

   npx omnodex status

3. (Optional) Install the MCP proxy plugin for MCP tool visibility:

   The Codex plugin system is folder-based. The .plugin bundle is a zip archive that must be unpacked first:

   mkdir -p ~/.codex/plugins/omnodex-codex
   unzip -o omnodex-codex.plugin -d ~/.codex/plugins/omnodex-codex

   Then register it as a local plugin in Codex. See the Codex plugin documentation for details on local plugin registration.

4. Run Codex normally. Traced events will appear alongside any Claude Code events in the same Omnodex dashboard.

Codex Desktop by Platform

macOS / Linux

Codex Desktop runs as a native process. All config, hooks, and data use your standard home directory (~). No special setup is needed beyond the hook installation above.

• ~/.codex/config.toml - Codex configuration
• ~/.omnodex/ - Omnodex event log and config
• npx omnodex dashboard works without any overrides

Windows

The Codex Desktop app on Windows has a split architecture: the Electron UI layer runs as a native Windows process, but the agent runs inside WSL. Hooks and plugin files are loaded from the WSL home (~, i.e. /home/<user>/).

This means:

• omnodex install codex should be run from inside WSL, not from a Windows terminal
• OMNODEX_HOME defaults to the WSL home (~/.omnodex) for Codex Desktop sessions
• The dashboard should also be run from WSL to read the same event log

If you need to view Codex Desktop events alongside events from other tools in one dashboard, see the Multi-Root Dashboard configuration.

Current Coverage

Event Type	Status
Bash commands	Traced (hooks)
Session lifecycle	Traced (hooks)
MCP tool calls	Traced (MCP proxy plugin)
File writes	Not yet available (upstream hooks)
Web search	Not yet available (upstream hooks)

As Codex expands its hook surface area, Omnodex will automatically capture additional event types without requiring reinstallation.

Viewing Results

Codex events flow into the same event log and dashboard as all other interceptors:

npx omnodex dashboard

Events from Codex sessions are tagged with their source, so you can filter by agent type in the dashboard.

Next Steps

• Running Detection - Risk detection works the same across all interceptors
• Events and Traces - Understand the event model