nw

nWave

AI agents that guide you from idea to working code — with you in control at every step.

nWave runs inside Claude Code. You describe what to build. Specialized agents handle requirements, architecture, test design, and implementation. You review and approve at each stage.

BREAKING CHANGE: Command Format (v2.8.0)

Starting with v2.8.0, all slash commands use hyphen format instead of colons.

Before (v2.7.x)	After (v2.8.0+)
/nw:deliver	/nw-deliver
/nw:design	/nw-design
/nw:discuss	/nw-discuss
/nw:distill	/nw-distill
/nw:discover	/nw-discover
All other commands	/nw-{command}

Why? Commands migrated from Claude Code's dynamic commands/ directory to the stable skills/ system to prevent commands from disappearing during long sessions.

To upgrade: Run pipx upgrade nwave-ai && nwave-ai install (CLI) or /plugin marketplace update nwave-marketplace (plugin). Old /nw: commands are automatically removed.

Quick Start

Requirements

• Python 3.10+ — nWave's DES hooks use match/case statements and X | Y union type syntax introduced in Python 3.10. Verify with python3 --version.

Plugin (Recommended)

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.

CLI Installer (Alternative)

Install from PyPI — useful for contributing or environments without plugin support:

pipx install nwave-ai
nwave-ai install

Agents and commands go to ~/.claude/.

Don't have pipx? Install with: pip install pipx && pipx ensurepath, then restart your terminal. Windows users: Use WSL (Windows Subsystem for Linux). Install with: wsl --install

Full setup details: Installation Guide

OpenCode Support (Alternative IDE)

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

Install prerequisites:

npm install -g opencode-ai
pipx install nwave-ai

Configure OpenCode:

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

Set your OpenAI API key:

export OPENAI_API_KEY=your-key-here

Install nWave into OpenCode:

nwave-ai install

Compatibility notes:

• ~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

Which method?

Scenario	Use	Why
First time	Plugin	Zero dependencies, instant setup
Team rollout	Either	Plugin for simplicity, CLI for automation
Contributing	CLI	Dev scripts, internals access
Already on CLI	Either	Both coexist safely

Use (inside Claude Code, after reopening it)

/nw-discuss "user login with email and password"   # Requirements
/nw-design --architecture=hexagonal                 # Architecture
/nw-distill "user-login"                            # Acceptance tests
/nw-deliver                                         # TDD implementation

Four commands. Four human checkpoints. One working feature.

Full walkthrough: Your First Feature

Staying Updated

nWave checks for new versions when you open Claude Code. When available, you'll see a note in Claude's context with version details and changes.

Plugin (self-hosted marketplace):

/plugin marketplace update nwave-marketplace

Updates are available immediately after each release — no review delay.

Plugin (official Anthropic directory):

The official directory pins plugins to reviewed versions. Updates go through Anthropic's review process before reaching users. If you installed from the official directory and want the latest version sooner, add the self-hosted marketplace:

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

CLI method:

pipx upgrade nwave-ai
nwave-ai install

Control check frequency via update_check.frequency in ~/.nwave/des-config.json: daily, weekly, every_session, or never.

Uninstalling

Plugin method:

/plugin uninstall nw

CLI method:

nwave-ai uninstall              # Remove agents, commands, config, DES hooks
pipx uninstall nwave-ai        # Remove the Python package