nWave

AI agents that guide you from idea to working code, with human judgment at every gate.

nWave runs inside Claude Code. It breaks feature delivery into seven waves (discover, diverge, discuss, design, devops, distill, deliver). Specialized agents produce artifacts at each wave. You review and approve before proceeding.

Documentation: docs.nwave.ai — guides, reference, and explanations, versioned per release.

Install in 5 Minutes

Requirements: Python 3.10+ and Claude Code.

sh -c "$(curl -fsSL https://raw.githubusercontent.com/nWave-ai/nWave/main/scripts/install/install.sh)"

This installs the nwave-ai CLI and wires nWave into Claude Code in one step. It uses uv when available (recommended); pipx is supported but not recommended. Restart Claude Code when it finishes.

Need CLI flags, environment variables, CI/non-interactive use, or manual and offline steps? See the Installation Guide.

Your First Command

Inside Claude Code, type:

/nw-buddy What should I do next?

The buddy reads your project and tells you which wave to start, where your artifacts are, and how to use nWave for your specific context. It works on day one with no configuration.

Before nWave: "Where do I start? Requirements doc or code first? Which agent?" After nWave: The buddy reads your project and gives you a concrete next step.

Using pipx, OpenCode, or Codex instead? See the Installation Guide.

Learn More

What's New in v3.19

• Per-project activation (opt-in gate) — nWave's globally-installed DES hooks are now opt-in per repository. Unmarked repos stay silent (hooks exit 0); a tracked .nwave/local-config.json marker plus a global activation.mode (opt-in default, or all) decide where nWave runs. Manage it with nwave-ai project enable|disable, nwave-ai mode, and nwave-ai status. Existing projects auto-adopt on first /nw- use, so nothing breaks. See Activating nWave in a Project.
• nwave-ai CLI reference — the user-facing command surface (install, uninstall, doctor, status, project, mode, attribution, completion, version) is documented in one place, including the install flag pass-through to the underlying installer. See CLI Reference.

See the full What's New in v3.19 for details.

Previous Releases

v3.15

• 3-Phase TDD Canon (Default) — New canonical TDD methodology (RED → GREEN → COMMIT) replaces the legacy 5-phase contract (PREPARE → RED_ACCEPTANCE → RED_UNIT → GREEN → COMMIT). Documented in ADR-025. Dual-canon backward compatibility: existing audit logs and pre-2026-05-07 executions replay correctly under v4 5-phase contract; new work uses 3-phase by default. Configured per rigor profile (lean mode uses RED → GREEN).
• Codex CLI support — Full nWave DES enforcement now works with OpenAI Codex CLI. Pre-tool-use hooks wire automatically; every Bash and file action validates against your TDD phase gates. See Installing for Codex CLI.

v3.14

• Lean wave docs (L7 single-file) — Each feature lives in one feature-delta.md with schema-typed section headings (## Wave: <WAVE> / [REF|WHY|HOW] <name>). Tier-1 [REF] is auto-produced; Tier-2 [WHY] and [HOW] are opt-in via --expand. Downstream agents grep section headings instead of reading whole subdirectories. See Feature Delta Format (L7).
• Feature-delta validator — nwave-ai validate-feature-delta <path> checks structural rules (E1–E5) and emits JSON for CI integration. Vendor-neutral: no hooks auto-installed; pick a recipe from Enforcement Recipes (12 platforms covered).
• Outcomes registry — Design-time deduplication. nwave-ai outcomes register|check|check-delta flags spec-level collisions before code is written, via type-shape + keyword Jaccard. See Why an outcomes registry? and Your first outcome.
• Doc density config — Per-project lean vs full density controls how much each wave emits. Tune token cost per wave. See Configuring Doc Density.
• Uninstall correctness fix (v3.14.0-rc1) — nwave-ai uninstall --force now removes all installed artifacts (skills/nw-*, lib/python/des/, all 5 DES hook event types in settings.json) while preserving user-created skills. Previous versions left ~197 skill dirs and 3 hook entries behind. See Troubleshooting → Uninstall left files behind.

For upgrading from v3.3 or earlier, see Breaking Changes below.

How It Works

  machine        human         machine        human         machine
    │              │              │              │              │
    ▼              ▼              ▼              ▼              ▼
  Agent ──→ Documentation ──→ Review ──→ Decision ──→ Agent ──→ ...
 generates    artifacts      validates   approves    continues

Each wave produces artifacts that you review before the next wave begins. The machine never runs unsupervised end-to-end.

The workflow has seven waves. Entry point depends on your context:

Wave routing: Entry points vary by context:

• Greenfield project: Start at DISCOVER or DIVERGE, proceed through all waves
• Brownfield feature: Start at DIVERGE or DISCUSS, skip to DESIGN
• Bug fix: Jump straight to DISTILL (write failing test) then DELIVER
• Refactoring: Jump to DELIVER (green already, refactor inside existing tests)

DISTILL then DELIVER is always the terminal pair. See the Wave Routing Guide for the full decision matrix.

40 agents total: 10 wave agents (including 3 DESIGN specialists), 1 concierge, 8 cross-wave specialists, 14 peer reviewers, 7 business agents. Full list: Commands Reference

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.

CLI Installer

Run the one-liner under Install in 5 Minutes at the top of this page. Agents and commands go to ~/.claude/.

Don't have uv? Install with: curl -LsSf https://astral.sh/uv/install.sh | sh or see uv installation docs. Alternatively, use pipx (requires Python 3.10+): pip install pipx && pipx ensurepath. **Windows