GitHub

Installing nWave for Codex CLI

Use this guide to install the nWave CLI into Codex. You need Python 3.11 or later, Codex CLI, and a published nwave-ai package or a checked-out source tree. Restart Codex after installation so it loads the new assets.

Step 1: Install the CLI package

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

Step 2: Install into Codex

The installer writes Codex-native assets — TOML agents, the hook wiring at ~/.codex/hooks.json and a manifest — plus the shared skills under ~/.agents/skills/, which live outside ~/.codex/. Preview first, then install:

nwave-ai install --platform codex --dry-run
nwave-ai install --platform codex

pipx install nwave-ai is a supported alternative to uv tool install. Read the installer's final validation before opening Codex. A package name or workflow definition does not identify a particular release; pin a version or use an exact release receipt when your project requires one.

Install from this source tree

From the nWave checkout:

uv sync
uv run python -m nwave_ai.cli install --platform codex

This installs from the checked-out revision. Keep the checkout if you plan to run its CLI again.

Codex global install checklist

Check the installer's final validation of Codex agents and shared skills, then restart Codex. From the same environment, check the delivery command — the one nwdes command you run at setup:

nwdes --help

Do not use a promised doctor count or the presence of a hook file as proof of delivery verification. The host runs each slice's declared commands.

Enable a project

In the project where you want nWave active:

nwave-ai project enable
nwave-ai status

status reports the effective activation, running CLI version, and whether Codex installation manifests were found. It does not validate every Codex action. If you installed from source, call the checkout's absolute .venv/bin/nwave-ai path from the project directory instead.

The project command writes .nwave/config.json and updates .gitignore. It can also add a managed section to AGENTS.md with your consent; --yes accepts that optional guidance step. Commit the project config if teammates should inherit the activation setting.

Verify and recover

After restarting Codex, run $nw-buddy in the enabled project. If Codex does not show the installed nWave skills, check the installer's reported Codex validation and run nwave-ai status in that project. Reinstall with the explicit --platform codex flag after correcting the reported cause; the dry run also surfaces Codex ownership-collision refusals safely before a real install.

nwave-ai doctor checks the Claude Code installation. A Codex-only install may therefore report missing Claude Code assets; use the Codex installer validation for that host. status is a read-only view, not a hook execution test.

To remove nWave's installed assets, run nwave-ai uninstall. Remove the CLI package separately with the same application installer you used to add it.