Installing nWave for Codex CLI

Step 1: Install nWave CLI

uv tool install nwave-ai     # recommended
# or, as a fallback:
pipx install nwave-ai

Step 2: Auto-detect and install into Codex

nwave-ai install

The installer automatically detects if Codex is present and wires the DES PreToolUse hook. If you see "DES hook installed successfully", you're ready to proceed.

Explicit Codex installation (if auto-detect doesn't find Codex):

nwave-ai install --platform codex

Step 3: Verify installation

nwave-ai doctor

Expected output: confirmation that DES hooks are installed and writable.

Step 1: Start a Codex session

codex
# or: OPENAI_API_KEY=your-key codex

Step 2: Run a Bash action

In Codex, invoke a simple Bash command (e.g., ls /tmp or echo hello).

Step 3: Check the audit log

cat ~/.claude/des-audit.jsonl | jq 'select(.event == "HOOK_INVOKED" and .handler == "pre_tool_use")' | head -3

Expected output: At least one JSON object with:

{
  "event": "HOOK_INVOKED",
  "handler": "pre_tool_use",
  "timestamp": "2026-05-14T...",
  ...
}

If you see this entry, DES enforcement is wired and working. If the log file is empty or missing, check the troubleshooting section below.

Legacy schema (top-level array)

Symptom: ~/.codex/hooks.json is a JSON array [...] instead of an object {...}.

Root cause: Pre-FM-1 nWave version wrote the legacy schema that Codex doesn't recognize.

Fix: Reinstall to repair:

nwave-ai install --platform codex --force

Missing pre-tool-use argv token

Symptom: Hook fires but exits with code 1 and produces no audit-log entry. Codex shows no validation output.

Root cause: Pre-FM-2 nWave version didn't include the required pre-tool-use argument to the hook command.

Fix: Upgrade to v3.15+:

uv tool upgrade nwave-ai    # or: pipx upgrade nwave-ai
nwave-ai install --platform codex --force

Fictional Task tool in matcher

Symptom: ~/.codex/hooks.json contains a regex with Task in it (e.g., ^Task$|^Bash$), but Codex never fires the hook for Task because Codex doesn't emit that tool name.

Root cause: Pre-FM-3 nWave version mirrored the Claude Code plugin without reading Codex's actual tool registry.

Fix: Upgrade to v3.15+:

uv tool upgrade nwave-ai    # or: pipx upgrade nwave-ai
nwave-ai install --platform codex --force

Hook didn't fire / audit log is empty

Check 1: Verify hooks.json has the right schema

jq '.hooks | keys' ~/.codex/hooks.json
# Expected output: ["PreToolUse"]

Check 2: Verify the matcher regex

jq -r '.hooks.PreToolUse[0].matcher' ~/.codex/hooks.json
# Expected output: ^Bash$|^apply_patch$ (or similar Codex tool names, not Task)

Check 3: Verify the hook command is present

jq -r '.hooks.PreToolUse[0].hooks[0].command' ~/.codex/hooks.json
# Expected output: command string ending with "pre-tool-use"

Check 4: Verify the audit log directory is writable

touch ~/.claude/des-audit.jsonl
# Should succeed without permission errors

Check 5: Verify the DES module is installed

python3 -c "from des.adapters.drivers.hooks import claude_code_hook_adapter; print('DES module OK')"
# If this fails, reinstall: nwave-ai install --force

If all checks pass but the audit log is still empty after running a Codex action, file a bug report with the output of nwave-ai doctor.

"PYTHONPATH environment variable" warnings

Symptom: Codex shows warnings about PYTHONPATH when the hook fires.

Cause: nWave sets PYTHONPATH to resolve the DES module. This is normal and safe.

Action: No action needed. The warnings can be ignored.