Activating nWave in a Project
Installation makes nWave available to a coding host, but project activation
is opt-in by default. Use this guide after installing the nwave-ai
package (see the installation guide):
cd /path/to/your/project
nwave-ai project enable
The cd matters: project enable, project disable, and status operate
on the current project's configuration. Do not run enable in an nWave
checkout unless that is the repository you intend to opt in.
Installed from a source checkout instead?
If the checkout's CLI is not on your PATH, activate its environment in
your shell first, then run the same commands from your project directory:
source /absolute/path/to/nWave/.venv/bin/activate
cd /path/to/your/project
Enable and verify
nwave-ai project enable
nwave-ai status
The command reports nWave activation for this project: enabled.; status
should report This project is active. and show the activation source without
writing files. The enable command publishes .nwave/config.json with
"enabled": true. It also repairs the root .gitignore and the generated
.nwave/.gitignore so this config can be tracked while other generated
.nwave/ contents remain ignored. It does not run git add or git commit
for you.
An interactive enable offers optional nWave beta-feedback guidance in both
CLAUDE.md and AGENTS.md. In a non-interactive shell without --yes,
activation still succeeds but that guidance is skipped. To add/update the
managed guidance without prompts later, run nwave-ai project enable --yes
from the same project. On disable, the CLI removes only its managed sections.
Review any guidance changes before committing them.
For a team-shared opt-in, first verify the configuration is not ignored and inspect the proposed changes:
git check-ignore .nwave/config.json
git status --short -- .nwave/config.json .gitignore .nwave/.gitignore CLAUDE.md AGENTS.md
git check-ignore returning no output means the config is not ignored;
it does not mean it is already tracked. If a custom or parent ignore rule
still hides it, fix that rule and rerun the check. Stage and commit the
configuration and root ignore rule if you want teammates to inherit this
activation; optionally track the nested .nwave/.gitignore too:
git add .nwave/config.json .gitignore
git commit -m "Enable nWave for this project"
After staging or committing, git ls-files -- .nwave/config.json prints the
tracked path. If you do not want team-wide activation, do not commit
the config. The local activation still works on this machine.
Start or continue work
Restart Claude Code after installing and invoke
/nw-buddy What should I do next? in the active project, or reopen Codex and
invoke $nw-buddy with the same question. These are host commands/skills,
not shell commands.
On POSIX, you can instead start an installed host through
nwave-ai run HOST -- ARGS, where HOST is claude-code, codex, opencode,
or copilot. The launcher does not install the host. Native startup remains
available; native hooks provide update guidance only, not automatic checks
or installation.
Project activation does not grant update permission. Automatic checking and installation have separate, default-off consents. Automatic checks require controlled prelaunch and idle evidence; installation additionally requires install consent, acknowledgement that older unregistered sessions are closed, and a commitment to use the controlled launcher for future sessions sharing the package. Direct starts, disabled hooks, and detached work are outside that controlled lifetime guarantee. Read the update configuration reference before granting either permission.
For this guide's local source/development installation, keep using the source channel's explicit update procedure in the installation guide; update consent does not make that installation eligible for public package-index updates. If a supported package replacement is interrupted, follow its reported recovery action: recovery verifies the pinned version before completing host synchronization and migration. Do not delete recovery evidence or assume a rollback.
After an applicable completed wave, optional local HTML views are controlled separately by documentation density; the Markdown remains authoritative. See configuring documentation density.
Disable or change the default
nwave-ai project disable
nwave-ai status
Disable updates the same .nwave/config.json to "enabled": false, an
explicit opt-out. status should say This project is inactive. It does
not delete the config or commit the change. If the repo's config is shared,
commit the new value to share the opt-out. To reverse it, run
nwave-ai project enable again, check status, and commit if appropriate.
The machine-wide default is opt-in. nwave-ai mode all activates
repositories with no declared enabled opinion; nwave-ai mode opt-in
restores the safer default. Explicit project "enabled": false wins even
in all mode. Changing global mode affects this machine, not your team's
clones. Keep opt-in if you work across both nWave and non-nWave projects.
How resolution works
The current reader checks an explicitly declared boolean "enabled" in:
- This repository's
.nwave/config.json. - Your global
~/.nwave/config.json, when the repository has no opinion. - The global
activation.mode(defaultopt-in) only when neither config declares an opinion.
A missing file, keyless document, or wrongly typed enabled does not mean
false: it declares no opinion. An explicit false overrides global all;
an explicit true overrides global opt-in. From a subdirectory inside a
Git repository, the config reader resolves the repository root. status
reads and reports the resulting state and its source without writing files.
Legacy marker: Earlier instructions referred to
.nwave/local-config.json with "enabled_for_repo". That is a legacy
input handled during configuration migration, not a runtime activation
tier, what current project enable|disable writes, or a second marker to
create or commit for a new project. Keep any existing legacy file untouched
until the writer handles migration; do not copy its old key into a new file
or manually rename files to "fix" activation. If migration detects invalid
or conflicting values, it refuses the write and reports why; resolve the
reported conflict rather than guessing a conversion.
Recovery
nwave-ainot found: Activate the checkout's.venvin the current shell as shown above, or invoke the checkout's absolute.venv/bin/nwave-aipath. A localuv syncdoes not add the script to your globalPATH.- Enable reports success, but
statusis inactive: Check you are in the intended Git repository, read.nwave/config.jsonfor boolean"enabled": true, and rerunnwave-ai statusthere. If you are in a different repo or outside Git, change to the intended repo and enable it there. Do not test tracking by looking for the retired marker. - Enable refuses to write or verify: Follow the CLI's error: fix
permissions on the project's
.nwave/directory, resolve malformed or conflicting config declarations or concurrent edits to.nwave/config.json, and retry.statusis read-only and can be used again after repair. - Status is active but the host command or hook is absent: Project
activation does not install host assets. Check the installer's final
validation, run
nwave-ai doctorfor Claude Code (not as a Codex-only verification), reinstall into the selected host if necessary, and restart that host. See the installation guide.