Installation Guide
Install the published nwave-ai package, then run its installer for
your host. Choose the host explicitly (claude-code, opencode, codex,
cursor, copilot, omp, devin), then enable nWave in the project where
you intend to work. Installation writes host-wide files (for example
~/.claude/ for Claude Code, ~/.codex/ for Codex, ~/.cursor/ for
Cursor); it does not opt every project in.
A local-clone route remains available for source development; see Install from a source checkout below.
Historical: v2.8.0 command-format change
Starting with v2.8.0, all nWave commands use hyphens instead of colons:
- Before:
/nw:deliver,/nw:design,/nw:discuss, etc. - After:
/nw-deliver,/nw-design,/nw-discuss, etc.
If you upgrade from an earlier version, run the installer again to clean up old /nw: commands. No data loss — only the command format changes.
Install the package
Requirements: Python 3.11 or newer, Git, and a supported coding host. Install the coding host separately: Claude Code, Codex CLI, Cursor, or another supported host. On Windows, use WSL.
Install the CLI with the package manager you prefer:
uv tool install nwave-ai # recommended
# or, as a fallback:
pipx install nwave-ai
Then install into your host. Preview first with --dry-run:
nwave-ai install --platform claude-code --dry-run # preview
nwave-ai install --platform claude-code # install
# OR, for Codex CLI:
nwave-ai install --platform codex
--platform accepts exactly auto, claude-code, opencode, codex,
cursor, copilot, omp, devin, all. Omitting --platform asks the
installer to auto-detect hosts; if none are detected, it refuses rather than
guessing. For scripted installation, --yes does not enable any project.
Installation does not ask for or write a density preference.
Restart the host after installation, then confirm the delivery command — the
one nwdes command you run at setup:
nwdes --help
Before an upgrade you can create a recovery point with
nwave-ai install --backup-only, which snapshots the Claude Code and Codex
installations. nwave-ai install --restore currently restores only the
Claude Code backup (on a Codex-only install it finds nothing to restore);
no backup or restore exists for OpenCode, Cursor, Copilot, OMP or Devin.
See Migrate from nWave 3.x.
Install from a source checkout
Use this route only for source development. Requirements: Python 3.11+,
Git, and uv (recommended), or Python's venv
and pip.
git clone https://github.com/nWave-ai/nWave.git nWave
cd nWave
uv sync
The explicit nWave directory name keeps the paths below consistent.
Alternatively, in the checkout, use a local virtual environment instead of uv sync:
python3 -m venv .venv
.venv/bin/python -m pip install -e .
Run one of these from the checkout, using the host you actually use:
uv run python -m nwave_ai.cli install --platform claude-code
# OR, for Codex CLI:
uv run python -m nwave_ai.cli install --platform codex
If you used venv/pip, replace uv run python with .venv/bin/python.
For scripted installation, --yes does not enable any project.
For source development, select development mode explicitly:
uv run python -m nwave_ai.cli install --dev --platform claude-code
Use --platform codex for Codex, or replace uv run python with
.venv/bin/python for the venv/pip route. Keep the checkout and repeat
--dev when reinstalling. Do not replace source or development installs with
a public-package upgrade; package replacement is refused for recorded
development mode.
An applied --dev installation activates nwdes and nwave-ai in
~/.local/bin for this checkout's installed runtime. Keep ~/.local/bin on
your PATH; no manual relinking is needed. If the commands already run that
runtime, installation reports each as unchanged and leaves the launchers alone.
Otherwise, it reports each successfully selected launcher as activated.
For clean isolated installs or tests, put the launcher directory for the same
HOME used for installation on PATH, without borrowing operator launchers.
Commands already active for the selected runtime elsewhere on PATH remain
unchanged.
Activation and final verification fail loudly if either command cannot run the
checkout's runtime, including an earlier PATH entry shadowing it or a runtime
installed editable from another checkout. Follow the reported WHAT/WHY/HOW
remedy and rerun the installation. A regular file at an owned launcher path is
never overwritten: move it aside first. Previewing with --dry-run does not
activate launchers. Selection covers only nwdes and nwave-ai, and a later generation
installation can replace the stable links without changing the dev runtime.
Verify the installed host
For Claude Code:
nwave-ai doctor
Doctor checks the Claude installation, including its hooks and files; if it reports a failing check, address that check and rerun the install and doctor. Quit and reopen Claude Code after every install or reinstall so it loads the new agents, skills, and commands.
For a Codex-only install, use the installer's final validation of Codex agents and shared skills, then reopen Codex. Claude-specific doctor failures do not diagnose a Codex-only install.
For Cursor-only, Copilot, OMP, and Devin installs, use each installer's final validation and the per-host guides: Cursor, OMP, Devin, and the vendor support matrix for what each host receives. On hosts other than Claude Code, doctor may report missing Claude assets on a host-only install; that is not a defect of that install.
Per-host guides
- Codex CLI — agents, skills and hooks; the host drives nwdes and runs the
declared verification commands; installation is not evidence that a
delivery has passed. Explicit installation:
nwave-ai install --platform codex. Details: Installing for Codex CLI. - Cursor — integration via global user hooks in
~/.cursor/hooks.json; the wiring applies across all Cursor projects on the machine. Explicit installation:nwave-ai install --platform cursor. Details: Installing for Cursor. - OpenCode — install OpenCode itself first, then
nwave-ai install --platform opencode. The installer writes OpenCode-native skills, agents and commands. - OMP, Devin — see Installing for OMP and Installing for Devin CLI.
Activate your project and start
In the project where you want nWave active:
cd /path/to/your/project
nwave-ai project enable
nwave-ai status
status should say This project is active. The enable command writes
.nwave/config.json with "enabled": true and repairs .gitignore to keep
that config trackable (Git does not commit it automatically). An interactive
enable also offers beta guidance in CLAUDE.md and AGENTS.md; in a
non-interactive shell it skips that optional guidance. Run
nwave-ai project enable --yes if you want to add it without prompts. Commit
the configuration and ignore-rule changes if your team should inherit
activation; if you want to undo it instead, run nwave-ai project disable
and check nwave-ai status again. See the
per-project activation guide for
precedence and recovery.
status is read-only and also reports the running CLI version, settings,
and detected host assets. The default activation mode is opt-in.
Restart the selected host and open it in the enabled project. In Claude Code,
try /nw-buddy What should I do next?; in Codex, invoke $nw-buddy and ask
the same question. These are host commands/skills, not shell commands.
Then describe the user, input, and expected result of your first request.
Existing projects can continue their current work without repeating onboarding.
If something goes wrong
nwave-ai: command not found: the CLI is not on yourPATH. With a package install, checkuv tool list/pipx listand the bin directory they report; with a source checkout, call/absolute/path/to/nWave/.venv/bin/nwave-aidirectly.- No coding host detected: retry with the explicit
--platformvalue for your host. - Doctor fails: read the failing check;
doctor --fixis not implemented. For Claude, reruninstall --platform claude-codeanddoctor, then restart Claude Code. Other hosts are checked with their installer validation, not Claude-only doctor checks. statusstill says inactive: runnwave-ai project enablefrom the intended project directory, inspect.nwave/config.jsonfor a boolean"enabled": true, and rerunstatus. If enable reports a publication or verification error, repair the.nwave/directory or resolve concurrent edits to.nwave/config.jsonand retry.project disablewrites an explicitfalse; it does not remove the file.
Historical package recovery (not the current installation path)
The following procedure documents an older experimental package identity. It requires a verified corrected release receipt. Do not use its remote-source, package-manager, or migration commands to install nWave; use the package installation above. It is retained only for owners of that exact predecessor with an independently verified release receipt.
Recover a previous experimental package identity (archive)
The prior experimental package was published as nwave
4.0.0+atddpure.2d5a26a, while its module and command were named nwave_ai
and nwave-ai. A corrected release uses the canonical distribution
nwave-ai. This procedure is for that specific predecessor only.
Wait for the corrected release receipt. Set CORRECTED_REF to the exact commit
recorded there; do not substitute an unverified branch or commit.
CORRECTED_REF='<exact corrected commit from the release receipt>'
EXPECTED_VERSION='<exact corrected version from the release receipt>'
CORRECTED_SOURCE="git+https://github.com/nWave-ai/nWave-experimental.git@${CORRECTED_REF}"
ROOT='/absolute/path/to/the/project-to-migrate'
Before changing packages, select exactly one owner. Inspect uv tool list --show-paths, pipx list --json, and the affected virtual environment when it
is known. Use the uv branch only when uv reports the affected app; use the pipx
branch only when pipx reports it; use the same-venv branch only when the probe
is run with that exact affected interpreter. If more than one record can own the
installation, or none can, stop without changing packages.
For the selected uv or pipx predecessor, set PREDECESSOR_TOOL to the exact
tool-environment key that its manager record reports: nwave-ai for canonical
v3 or nwave for the verified obsolete predecessor. Bind only its interpreter
before the initial probe:
# uv
PREDECESSOR_TOOL='<exact key from uv tool list --show-paths>'
UV_TOOL_ROOT="$(uv tool dir)"
PREDECESSOR_PYTHON="$UV_TOOL_ROOT/$PREDECESSOR_TOOL/bin/python"
test -x "$PREDECESSOR_PYTHON" || exit 1
# pipx
PREDECESSOR_TOOL='<exact key from pipx list --json>'
PIPX_VENVS="$(pipx environment --value PIPX_LOCAL_VENVS)"
PREDECESSOR_PYTHON="$PIPX_VENVS/$PREDECESSOR_TOOL/bin/python"
test -x "$PREDECESSOR_PYTHON" || exit 1
Run the initial probe with PREDECESSOR_PYTHON. It must report that exact
predecessor identity before an obsolete owner can be removed.
After the corrected install, bind the canonical manager launch paths. For uv:
UV_TOOL_ROOT="$(uv tool dir)"
UV_BIN_DIR="$(uv tool dir --bin)"
MANAGER_PYTHON="$UV_TOOL_ROOT/nwave-ai/bin/python"
MANAGER_NWAVE_AI_CONSOLE="$UV_BIN_DIR/nwave-ai"
MANAGER_NWDES_CONSOLE="$UV_BIN_DIR/nwdes"
test -x "$MANAGER_PYTHON" -a -x "$MANAGER_NWAVE_AI_CONSOLE" -a -x "$MANAGER_NWDES_CONSOLE" || exit 1
For pipx, bind all canonical paths from its post-install records:
PIPX_RECORD="$(mktemp)"
pipx list --json > "$PIPX_RECORD"
PIPX_VENVS="$(pipx environment --value PIPX_LOCAL_VENVS)"
MANAGER_PYTHON="$PIPX_VENVS/nwave-ai/bin/python"
manager_app() {
python3 -c 'import json,sys; v=json.load(open(sys.argv[1]))["venvs"]["nwave-ai"]["metadata"]["main_package"]["app_paths"]; out=[]; walk=lambda x: out.extend([x]) if isinstance(x,str) else [walk(y) for y in (x.values() if isinstance(x,dict) else x if isinstance(x,list) else [])]; walk(v); print(next(p for p in out if p.rsplit("/",1)[-1] == sys.argv[2]))' "$PIPX_RECORD" "$1"
}
MANAGER_NWAVE_AI_CONSOLE="$(manager_app nwave-ai)"
MANAGER_NWDES_CONSOLE="$(manager_app nwdes)"
test -x "$MANAGER_PYTHON" -a -x "$MANAGER_NWAVE_AI_CONSOLE" -a -x "$MANAGER_NWDES_CONSOLE" || exit 1
If any binding is absent, stop. The manager-bin application paths are launch paths; the sibling paths reported by the probe are identity evidence in the manager environment and need not be the same filesystem paths.
Define this probe once. Its argument is the interpreter whose package and console ownership it observes:
probe() {
"$1" -I - <<'PY'
import importlib.metadata as m, importlib.util, json, os, pathlib, sys
bin_dir = pathlib.Path(sys.executable).parent
apps = {name: bin_dir / (name + '.exe' if os.name == 'nt' else name) for name in ('nwave-ai', 'nwdes')}
distributions = {d.metadata['Name'].lower(): d.version for d in m.distributions()
if d.metadata.get('Name', '').lower() in {'nwave', 'nwave-ai'}}
owners = sorted(m.packages_distributions().get('nwave_ai', []))
entry_points = {name: sorted(d.metadata['Name'] for d in m.distributions() for e in d.entry_points
if e.group == 'console_scripts' and e.name == name)
for name in apps}
spec = importlib.util.find_spec('nwave_ai')
print(json.dumps({'python': sys.executable, 'distributions': distributions,
'module_owners': owners, 'entry_point_owners': entry_points,
'applications': {name: {'path': str(path), 'executable': path.is_file() and os.access(path, os.X_OK)} for name, path in apps.items()},
'module_path': None if spec is None else spec.origin}, sort_keys=True))
PY
}
probe "$PREDECESSOR_PYTHON"
Continue only when the probe shows one canonical nwave-ai owner, the verified
obsolete nwave 4.0.0+atddpure.2d5a26a owner, or the explicit same-venv pair
of those two owners. If it shows an unknown nwave, a third owner, or paths
outside the selected manager environment, stop without changing packages.
uv or pipx: previous experimental nwave only
Remove the obsolete distribution before installing the canonical replacement: it shares files with the corrected package. Run the block for the one manager selected above.
# uv
uv tool uninstall nwave
uv tool install "${CORRECTED_SOURCE}"
# pipx
pipx uninstall nwave
pipx install "${CORRECTED_SOURCE}"
After the manager reports the new nwave-ai environment, resolve
MANAGER_PYTHON, MANAGER_NWAVE_AI_CONSOLE, and MANAGER_NWDES_CONSOLE again
from the selected manager record, then run probe "$MANAGER_PYTHON". It must
show only nwave-ai as the module and both console-entry-point owner; both
manager launch paths and both probe sibling paths must be executable. Then
finish the deployed runtime and project migration:
probe "$MANAGER_PYTHON"
test "$("$MANAGER_PYTHON" -I -c 'import importlib.metadata as m; print(m.version("nwave-ai"))')" = "$EXPECTED_VERSION" || exit 1
test "$("$MANAGER_NWAVE_AI_CONSOLE" --version)" = "nwave-ai $EXPECTED_VERSION" || exit 1
"$MANAGER_NWAVE_AI_CONSOLE" --version
"$MANAGER_NWAVE_AI_CONSOLE" install --yes
"$MANAGER_NWAVE_AI_CONSOLE" doctor --json
Same virtual environment containing both nwave-ai and obsolete nwave
Assign the exact interpreter from the initial mixed-state probe, then remove nwave first and
force-reinstall canonical nwave-ai so shared files are restored:
AFFECTED_PYTHON='<exact python field from the mixed-state probe>'
test -x "$AFFECTED_PYTHON" || exit 1
"$AFFECTED_PYTHON" -m pip uninstall -y nwave
"$AFFECTED_PYTHON" -m pip install --upgrade --force-reinstall "nwave-ai @ ${CORRECTED_SOURCE}"
Run probe "$AFFECTED_PYTHON", then bind its exact sibling paths:
probe "$AFFECTED_PYTHON"
MANAGER_PYTHON="$AFFECTED_PYTHON"
MANAGER_NWAVE_AI_CONSOLE="$(dirname "$AFFECTED_PYTHON")/nwave-ai"
MANAGER_NWDES_CONSOLE="$(dirname "$AFFECTED_PYTHON")/nwdes"
test -x "$MANAGER_NWAVE_AI_CONSOLE" -a -x "$MANAGER_NWDES_CONSOLE" || exit 1
test "$("$MANAGER_PYTHON" -I -c 'import importlib.metadata as m; print(m.version("nwave-ai"))')" = "$EXPECTED_VERSION" || exit 1
test "$("$MANAGER_NWAVE_AI_CONSOLE" --version)" = "nwave-ai $EXPECTED_VERSION" || exit 1
Run the same install and doctor commands above only after the
probe shows exactly one nwave-ai owner.
Canonical nwave-ai only
For a canonical installation, reinstall through the manager that owns it, then repeat the post-install probe and the absolute executable commands above: run one manager block only.
# uv
uv tool install --reinstall "${CORRECTED_SOURCE}"
# pipx
pipx install --force "${CORRECTED_SOURCE}"
The recovery order is package replacement, identity proof, runtime install, then doctor. It preserves the existing refusal for ambiguous metadata; it does not select a preferred owner automatically. Follow the migration guide for the separate project compatibility decision.
Historical PATH recovery (package-managed installations only)
For a verified older uv tool or pipx installation, uv tool update-shell
or pipx ensurepath can refresh the manager's bin directory. This does not
install from a source checkout; for a local checkout, activate its .venv
instead.
CLI install options
Run nwave-ai install --help to see the installed script's options (from a
source checkout: uv run python -m nwave_ai.cli install --help).
--platform selects a host; --dry-run previews without installing;
--backup-only snapshots the Claude Code and Codex installations;
--restore restores the prior Claude Code backup (a Codex-only --restore
currently finds nothing to restore).
What Gets Installed
The Claude target installs agents, commands, skills, templates and utility scripts under
~/.claude/ (or the selected Claude config directory), and its hook registrations in settings.json. Those assets become
visible after a restart. Other targets install their native host assets; see
the vendor support matrix for the per-host list.
Delivery uses nwdes. The host invokes role prompts, and runs the declared verification commands. The builder does not enforce a workflow or maintain a completion ledger.
Configuration
Commit attribution
Use nwave-ai attribution status to inspect the effective preference and
its source; nwave-ai attribution on or off changes the machine preference.
Project configuration can override it. Credit is added only for active
repositories with a supported commit hook; nWave's preference does not
control the host's own co-authorship settings.
Per-project settings
Set the supported project overrides with the CLI:
nwave-ai project set verbosity terse
nwave-ai project set attribution off
nwave-ai project set enabled true
nwave-ai status
verbosity accepts terse, standard, or verbose; attribution accepts
on or off; enabled accepts true or false. These commands write
.nwave/config.json, as do project enable and project disable. The
legacy .nwave/local-config.json is not what current project enable writes.
See the activation guide
for precedence, team sharing, and recovery, and the
global configuration reference for other settings.
Completed-wave reading and explanation
nwdes renders full briefs and HTML through nwdes document. A reading view is
not evidence that a wave completed or that a document was approved.
documentation.expansion_prompt separately controls optional explanation in
chat after a completed wave. Neither preference changes required verification
or chooses a provider/model. See the
documentation configuration reference
for the supported values, preference provenance, and rendering limits.
Updating
Update a package installation
Upgrade the package with the manager that owns it, then rerun the installer for the same selected host:
uv tool install --reinstall nwave-ai # or: pipx upgrade nwave-ai
nwave-ai install --platform claude-code
nwave-ai doctor
uv tool upgrade nwave-ai does not move a tool installed with an exact version pin
(for example uv tool install nwave-ai==4.4.0): uv reports "Nothing to upgrade" and
prints a hint. uv tool install --reinstall nwave-ai moves a pinned or an unpinned
install to the latest release and removes the pin.
For Codex, use install --platform codex instead; its final validation is
the Codex-specific check, whereas doctor checks Claude. Restart the host
after installation.
A package update does not migrate an in-progress v3 delivery. Finish it on
3.22.2 or restart with nwdes feature new; see the
migration guide.
For a supported stable installation with recorded host destinations and a verified package owner:
nwave-ai update --check
nwave-ai update --yes --root "$PWD"
Close active work before the explicit update: it takes the replacement lock but does not establish global idle. It preserves recorded host destinations and does not repeat project-guidance enrollment. Missing install provenance, development mode, or an unsupported release channel can refuse replacement; consent does not make those installations compatible.
Update a source checkout
When you intentionally update your clone, resync its environment and rerun the installer for the same selected host. For example, after updating the checkout's source to the revision you want:
uv sync
uv run python -m nwave_ai.cli install --platform claude-code
uv run python -m nwave_ai.cli doctor
For Codex, use install --platform codex instead; its final validation is
the Codex-specific check, whereas doctor checks Claude. With the venv/pip
route, rerun .venv/bin/python -m pip install -e . in the checkout before
.venv/bin/python -m nwave_ai.cli install --platform .... Restart the host
after installation.
Controlled startup and update permissions
On POSIX, nwave-ai run HOST -- ARGS supports claude-code, codex,
opencode, and copilot; it does not install a missing host. For example:
nwave-ai run claude-code --
nwave-ai run codex -- --no-daemon
Automatic release checking and installation are separate permissions, both off by default. A check-only grant cannot install anything. For a compatible stable installation, grant checking explicitly:
nwave-ai update consent check on
Before granting automatic installation, close all older host sessions that started before the activity registry was installed. Then, only if future sessions sharing the package will use controlled startup, record both acknowledgements:
nwave-ai update consent install on --confirm-old-sessions-closed
nwave-ai update consent controlled-launch on --confirm-controlled-launch
These flags record your statements; nWave cannot independently detect the
older sessions. Automatic installation requires both check and install
permissions plus the controlled-launch commitment. Revoke a grant with the
same command and off, without a confirmation flag.
The wrapper records the session before launching the host. Automatic checks and installation require controlled prelaunch and idle evidence before the first release request. Other sessions, unknown or malformed records, and unfinished local work block both automatic actions. Ordinary native startup remains available, but its update hooks are advisory only: native hooks cannot provide a reliable admission boundary. Direct starts, disabled hooks, and detached work are outside the controlled lifetime guarantee.
Inspect records with nwave-ai update sessions. Close a session in its host
first; remove a remaining record only with
nwave-ai update sessions close KEY --confirm-closed. Records are not cleared
by guessing from process state or age. An explicit nwave-ai update --check
remains read-only and available outside controlled startup. A manual
update --yes does not grant persistent consent.
These controls do not convert source/development installs into public-index installations. Read the update configuration reference before enabling either automatic action.
Interrupted-update recovery
An interrupted replacement reports its stage and recovery action and retains
durable evidence. Even if the package version is current, checks and ordinary
updates report update-incomplete, not success. No broad rollback is promised.
After stopping all remaining updater processes and affected sessions, use the
reported environment and project root to run:
nwave-ai update --recover --yes --confirm-stopped
Recovery proves the pinned package version, repeats selected-host preflight and synchronization, and applies the registered artifact migration. Evidence is cleared only when all stages succeed. If the pinned package is missing or wrong, follow the reported package-owner restoration command first. Do not delete recovery markers or substitute an unpinned public upgrade.
Uninstalling
Run nwave-ai uninstall; with a source checkout, activate its .venv first.
It removes nWave-managed installed assets; it does not erase your project's
.nwave/config.json or source files. If you only want to turn nWave off in
one project, use nwave-ai project disable there instead.
For a package installation, remove deployed assets with
nwave-ai uninstall, then remove its CLI with
uv tool uninstall nwave-ai or pipx uninstall nwave-ai, matching its owner.
This also leaves the project's .nwave/ files in place.
Verification and troubleshooting
For Claude, run nwave-ai doctor after installation. Then restart Claude
Code and look for /nw-buddy among commands. If it is absent, verify you
installed with --platform claude-code and address any failing doctor
checks; reinstall with that target if needed. nwave-ai version only proves
the CLI can run, not that host assets or a project activation were installed.
For Codex, rely on the Codex-target installer's final validation and check the Codex-native assets as described above; doctor does not yet diagnose Codex-only assets. Reopen Codex to load the installed skills. If the installer refuses an ownership conflict, follow its reported remedy rather than overwriting unowned files.
For either host, nwave-ai status from the intended project must say
This project is active. If not, run nwave-ai project enable there and
follow the activation recovery guide.
If the installation fails because a destination is not writable, resolve
its ownership or permissions and retry; do not indiscriminately chmod
your entire Claude configuration. doctor --fix is not implemented.
Next Steps
Enable nWave in your own project, verify with nwave-ai status, reopen
your selected host, and ask its buddy command/skill for the first action:
Claude Code /nw-buddy What should I do next?, or Codex $nw-buddy with
the same question. For workflow guidance, see
Jobs To Be Done Guide.
Support
- Discord Community: Join the nWave Discord for help with installation issues
- Documentation: Guides and references are in this repository.
- Claude installer logs: Check
~/.claude/nwave-install.logfor errors. - CLI: Run
nwave-ai version.
Ready to build? The nwdes steps are your assistant's to run: paste it
the sentence from For your assistant. To
see the command flow once by hand, walk the safe
First feature with nwdes lesson in a
throwaway repository, then start real work with
Deliver a feature.