GitHub

Installation Guide

Install nWave to your global Claude Code configuration. This adds 23 specialized agents (12 primary + 11 reviewers) and 22 slash commands across all your projects.

v2.8.0 Breaking Change: Command Format

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.

Choose Your Method

Scenario Use Why
First time CLI Full-featured, recommended
Team rollout CLI Same command format everywhere
Contributing CLI Dev scripts, internals access

Why not Plugin? The plugin marketplace install is currently missing DES enforcement, attribution hooks, and rigor profiles. It also uses a different command format (/nw:deliver vs /nw-deliver) due to Claude Code's plugin namespace system. We recommend CLI install for the full nWave experience. See issue #31 for details.

Running a different editor or CLI? This guide also covers OpenCode and the Codex CLI further down, plus the plugin marketplace.

Installing for OpenCode

nWave also works with OpenCode, an open-source IDE for AI pair programming. Installation needs a few extra steps to configure OpenCode's environment.

1. Install prerequisites:

npm install -g opencode-ai
uv tool install nwave-ai        # or: pipx install nwave-ai

2. Configure OpenCode:

mkdir -p ~/.config/opencode
echo '{"model": "openai/gpt-4o-mini"}' > ~/.config/opencode/opencode.json

3. Set your OpenAI API key:

export OPENAI_API_KEY=your-key-here

4. Install nWave into OpenCode:

nwave-ai install

Compatibility notes:

  • About 67% of nWave features work natively on OpenCode via compatibility paths.
  • DES hooks integrate via OpenCode's tool.execute.before mechanism.
  • Some advanced subagent coordination may differ from Claude Code. Use the core /nw-discuss, /nw-design, /nw-distill, /nw-deliver commands for best results.
  • For full feature parity and support, Claude Code remains the primary environment.

Installing for Codex CLI

nWave integrates with the OpenAI Codex CLI via pre-tool-use hooks. Once installed, every Bash and file-edit action fires nWave's DES validation — the same enforcement that runs on Claude Code.

Prerequisites:

  • OpenAI Codex CLI installed (codex binary on PATH) or a ~/.codex/ directory present
  • Python 3.10+

Auto-detect installation (recommended):

uv tool install nwave-ai    # or, as a fallback: pipx install nwave-ai
nwave-ai install            # auto-detects Codex + installs hooks

Explicit Codex installation:

nwave-ai install --platform codex

What gets written: nWave creates ~/.codex/hooks.json with an event-keyed structure:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "^Bash$|^apply_patch$",
        "hooks": [
          {
            "type": "command",
            "command": "python -m des.adapters.drivers.hooks.claude_code_hook_adapter pre-tool-use"
          }
        ]
      }
    ]
  }
}

Verify installation succeeded:

cat ~/.codex/hooks.json | jq '.hooks.PreToolUse | length'
# Expected output: 1 (or higher if you have other hook entries)

Troubleshooting:

  • "Codex not detected" — Check which codex and ls ~/.codex/. To force install before the Codex binary exists, use --platform codex. You'll need to install Codex separately before hooks will fire.
  • "Hook fires but audit log empty" — Verify ~/.claude/des-audit.jsonl is writable and ~/.claude/lib/python/des/ exists. Run a Codex action and check the log: tail -5 ~/.claude/des-audit.jsonl | jq .
  • "Codex says hook not loaded" — Ensure hooks.json uses the event-keyed format above (not a legacy top-level array). Reinstall with nwave-ai install --platform codex --force if in doubt.

For detailed setup and workflow, see Installing for Codex CLI.

Plugin (Beta Preview — Not Feature-Complete)

Warning: The plugin install is missing DES enforcement, attribution hooks, rigor profiles, and uses a different command format (/nw:deliver instead of /nw-deliver). Use CLI install above for the full experience.

The plugin method installs nWave directly from the Claude Code marketplace. No Python or pipx required.

From Claude Code, run:

/plugin marketplace add nwave-ai/nwave
/plugin install nw@nwave-marketplace

Restart Claude Code and type /nw- to see all available commands.

The plugin method is in beta preview and NOT feature-complete. It provides agents and skills but NOT DES enforcement, attribution, or rigor profiles. Commands use /nw:deliver format (not /nw-deliver). For the full experience, use the CLI method above.

What Gets Installed

Both methods install the same components to your ~/.claude/ directory:

~/.claude/
├── agents/nw/                 # 23 agents (12 primary + 11 reviewers)
├── commands/nw/               # 22 slash commands
├── templates/                 # Wave and DES templates
├── skills/nw-*/               # 197 agent skill files (flat layout)
├── scripts/                   # DES utilities
├── lib/python/des/            # DES runtime imported by hooks
└── settings.json              # DES hooks (5 events: PreToolUse, SessionStart, SubagentStart, SubagentStop, PostToolUse)

All agents and commands become available globally across all Claude Code projects.

DES Hooks

Both methods register DES (Deterministic Execution System) hooks in your Claude Code settings:

  • Pre-task validation
  • Post-tool-use monitoring
  • Subagent timeout tracking
  • Audit logging

Configure globally in ~/.claude/settings.json or per-project via .nwave/des-config.json.

Activating nWave in a Project

nWave hooks install globally but are opt-in per project by default. In an inactive project, hooks silently exit 0 — you cannot tell nWave is installed. To turn nWave on for the current project:

nwave-ai project enable

To check the activation state:

nwave-ai status

Commit .nwave/local-config.json so teammates inherit the same nWave state. For the full mental model and resolution policy, see Activating nWave in a Project.

Commit Attribution

Installation enables commit attribution by default. It adds a dual Co-Authored-By trailer (Claude + nWave) to commits Claude makes, by writing a managed string to the attribution.commit key in ~/.claude/settings.json:

"attribution": {
  "commit": "🤖 Generated with Claude Code\n\nCo-Authored-By: Claude <noreply@anthropic.com>\nCo-Authored-By: nWave <nwave@nwave.ai>",
  "pr": "…"
}

Toggle it with the CLI (nwave-ai must be on your PATH — see nwave-ai not found; from a source checkout use uv run nwave-ai … instead):

nwave-ai attribution status   # show current state
nwave-ai attribution off      # remove the nWave credit (deletes the attribution key)
nwave-ai attribution on       # re-enable it

⚠️ Changes apply to new sessions only. Claude Code reads attribution.commit when a session starts, not per commit. After toggling, restart Claude for it to take effect — and do not /resume a conversation created before the change, because a resumed session replays its original setting and will keep using the old value. A commit reflects the current setting only if it comes from a session created after the change.

attribution off removes only nWave's credit. Claude Code's own co-authorship line (🤖 Generated with Claude Code + Co-Authored-By: Claude) is controlled separately by Claude Code's includeCoAuthoredBy setting, which nWave does not change. Set "includeCoAuthoredBy": false in ~/.claude/settings.json to suppress that as well.

Attribution is global (it lives in ~/.claude/ and ~/.nwave/); there is no per-project opt-out.

Per-Project Configuration

To customize DES behavior for a specific project, create .nwave/des-config.json in your project directory:

{
  "audit_log_enabled": true,
  "audit_log_path": ".nwave/audit.log",
  "validation_enabled": true,
  "tool_monitoring_enabled": true,
  "max_execution_time": 3600,
  "subagent_timeout": 300
}
Setting Default Description
audit_log_enabled true Enable DES execution audit trail for debugging
audit_log_path ".nwave/audit.log" Where to write audit records
validation_enabled true Enforce TDD phase sequence; set false to disable DES checks
tool_monitoring_enabled true Monitor Task invocations for unbounded loops
max_execution_time 3600 Kill subagent after this many seconds (default: 1 hour)
subagent_timeout 300 Kill unresponsive subagent after this many seconds (default: 5 min)

Settings here override global defaults for that project only.

Updating

CLI method (uv, recommended):

uv tool upgrade nwave-ai
nwave-ai install

CLI method (pipx, fallback):

pipx upgrade nwave-ai
nwave-ai install

The installer automatically backs up your configuration before updating, allowing rollback if needed.

Plugin method:

/plugin marketplace update nwave-marketplace

Or enable auto-updates in Claude Code plugin settings.

nWave checks for new versions when you open Claude Code. Control check frequency via update_check.frequency in ~/.nwave/des-config.json:

Value Behavior
daily Check once per day
weekly Check once per week
every_session Check on every session start (default)
never Disable update checks

Uninstalling

CLI method (uv, recommended):

nwave-ai uninstall              # Removes agents, commands, config, DES hooks from ~/.claude/
uv tool uninstall nwave-ai     # Removes the nwave-ai Python package itself

CLI method (pipx, fallback):

nwave-ai uninstall              # Removes agents, commands, config, DES hooks from ~/.claude/
pipx uninstall nwave-ai        # Removes the nwave-ai Python package itself

Plugin method:

/plugin uninstall nw

Both methods remove agents, commands, and configuration from ~/.claude/. Your project files (.nwave/, source code) are never touched.

Verification

CLI method

nwave-ai version

Then in Claude Code, type @ to see agents or /nw- to see commands.

Plugin method

Restart Claude Code after installation. Type /nw- in the command palette — you should see all 22 commands. Type @nw to see agents.

If commands don't appear after plugin install, quit Claude Code completely and reopen it.

Troubleshooting

Agents Not Appearing in Claude Code

If agents don't appear after installation:

  1. Restart Claude Code completely (quit and reopen)
  2. Verify installation completed successfully:
nwave-ai version
  1. Check that ~/.claude/agents/nw/ exists with agent files
  2. Ensure your Claude Code version is current (update via your package manager)

Installation Failed

If the installer reports errors:

  1. Check Python version:
python --version
# Must be 3.10 or higher
  1. Ensure write access to ~/.claude/:
ls -la ~/.claude/
  1. If you see permission errors, check file permissions:
chmod 755 ~/.claude/
  1. Restore from backup:
nwave-ai install --restore

uv Issues

If uv tool commands fail:

# Verify uv is installed
uv --version

# Ensure the uv tool bin dir is on PATH
uv tool update-shell      # then restart your shell

# If uv is missing, reinstall it
curl -LsSf https://astral.sh/uv/install.sh | sh

pipx Issues

If pipx commands fail (pipx is a supported fallback):

# Verify pipx is installed
pipx --version

# Ensure pipx is in your PATH
which pipx

# If not found, reinstall pipx
pip install --user pipx

Import Errors When Using nWave

If you see import errors when running nWave commands:

  1. Ensure Claude Code is using the correct Python environment
  2. Reinstall nWave (uv, recommended):
uv tool uninstall nwave-ai
uv tool install nwave-ai
nwave-ai install

Or via pipx (fallback):

pipx uninstall nwave-ai
pipx install nwave-ai
nwave-ai install
  1. Restart Claude Code

DES Audit Log Errors

If audit logging isn't working:

  1. Create the .nwave/ directory in your project:
mkdir -p .nwave
  1. Verify .nwave/ is writable:
touch .nwave/test.txt
rm .nwave/test.txt
  1. Check DES configuration in .nwave/des-config.json is valid JSON

Rollback After Update

If an update causes problems:

nwave-ai install --restore

This restores your previous configuration from the most recent backup.

Next Steps

After installation, navigate to any project and start your first workflow:

# For fresh features (greenfield)
/nw-discover "feature market research"
/nw-discuss "feature requirements"
/nw-design
/nw-devops
/nw-distill "acceptance tests"
/nw-deliver

# Or for existing code (brownfield)
/nw-deliver

For workflow guidance, see Jobs To Be Done Guide.

Support

  • Discord Community: Join the nWave Discord for help with installation issues
  • Documentation: Complete framework documentation is available in the repository
  • Logs: Check ~/.claude/nwave-install.log for installation details
  • Version: Run nwave-ai version to see your installed version

Ready to build? Start with Jobs To Be Done Guide to learn when and how to use each workflow.

Edit this page on GitHub