Quickstart

Get your first pipeline running in 60 seconds.

1. Install Wave

Install Script Recommended

curl -fsSL https://raw.githubusercontent.com/re-cinq/wave/main/scripts/install.sh | sh

Build from Source

Requires Go 1.25+ and git:

git clone https://github.com/re-cinq/wave.git
cd wave && make build
sudo mv wave /usr/local/bin/

Verify installation:

wave --version

2. Choose Your AI Adapter

Wave executes AI workflows through CLI adapters. Choose one of the supported options:

Claude Code (Default)

Claude Code is the recommended adapter for Wave, providing the best integration and capabilities.

# Install Claude Code CLI
npm install -g @anthropic-ai/claude-code

# Verify installation
claude --version

Don't have Node.js?

Install via nvm (macOS/Linux) or download from nodejs.org (all platforms).

OpenCode (Alternative)

OpenCode provides an open-source alternative with support for multiple LLM providers.

# Install OpenCode
go install github.com/opencode-ai/opencode@latest

# Or via Homebrew (macOS/Linux)
brew install opencode

# Verify installation
opencode --version

To use OpenCode as your default adapter, configure it in your wave.yaml:

adapters:
  default: opencode
  opencode:
    model: gpt-4-turbo

See Adapters Reference for complete configuration options.

3. Set Your API Key

export ANTHROPIC_API_KEY="your-api-key"

Don't have an API key?

Get one at console.anthropic.com. Free tier available for testing.

API Key Security

Never commit your API key to version control. Add ANTHROPIC_API_KEY to your shell profile (~/.bashrc, ~/.zshrc) or use a secrets manager.

4. Initialize Your Project

cd /path/to/your-project
wave init

This creates:

• wave.yaml - Project manifest
• .wave/personas/ - AI agent definitions
• .wave/pipelines/ - Ready-to-run pipelines

Don't have a codebase?

Wave works great for self-analysis:

git clone https://github.com/re-cinq/wave.git
cd wave && wave init

5. Run Your First Pipeline

wave run hello-world "testing Wave"

Expected Output

With the default TUI mode you'll see a progress bar and spinners. To see text output, use -o text:

wave run hello-world "testing Wave" -o text

[10:00:01] → greet (craftsman)
[10:00:01]   greet: Executing agent
[10:00:05]   greet: Processing results
[10:00:05] ✓ greet completed (4.0s, 0k tokens)
[10:00:05] → verify (navigator)
[10:00:05]   verify: Executing agent
[10:00:12]   verify: Processing results
[10:00:12] ✓ verify completed (6.9s, 0k tokens)

  ✓ Pipeline 'hello-world' completed successfully (10.9s)

  Deliverables (4):
     • .wave/workspaces/hello-world-aca3e016/greet/CLAUDE.md
     • .wave/workspaces/hello-world-aca3e016/greet/greeting.txt
     • .wave/workspaces/hello-world-aca3e016/verify/CLAUDE.md
     • .wave/workspaces/hello-world-aca3e016/verify/output/result.json

What Just Happened?

1. Wave loaded the hello-world pipeline from .wave/pipelines/
2. The greet step ran with the craftsman persona
3. The verify step received the greeting artifact and confirmed it
4. Each step ran with fresh memory (no context bleed between steps)
5. Artifacts were saved to .wave/workspaces/ for inspection

Troubleshooting

ANTHROPIC_API_KEY not set

Error: Error: ANTHROPIC_API_KEY environment variable is not set

Solution: Set your API key before running Wave:

export ANTHROPIC_API_KEY="sk-ant-..."

Or add it permanently to your shell profile:

echo 'export ANTHROPIC_API_KEY="your-key"' >> ~/.bashrc
source ~/.bashrc

Claude Code not installed

Error: Error: adapter 'claude' not found. Is Claude Code CLI installed?

Solution: Install the Claude Code CLI:

npm install -g @anthropic-ai/claude-code

Verify it's in your PATH:

which claude  # Should show the installation path

Permission denied errors

Error: Permission denied: cannot write to /usr/local/bin/wave

Solution: Build from source and install to a user directory:

# Option 1: Install to /usr/local/bin (requires sudo)
git clone https://github.com/re-cinq/wave.git
cd wave && make build
sudo mv wave /usr/local/bin/

# Option 2: Install to user directory
git clone https://github.com/re-cinq/wave.git
cd wave && make build
mkdir -p ~/.local/bin && mv wave ~/.local/bin/
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

Common YAML syntax errors

Error: yaml: line X: did not find expected key

Common causes and fixes:

1. Incorrect indentation - YAML requires consistent spacing (use 2 spaces, not tabs):

   # Wrong
   steps:
   	- name: greet  # Tab character
   
   # Correct
   steps:
     - name: greet  # 2 spaces

2. Missing colons or quotes:

   # Wrong
   prompt This is a prompt
   
   # Correct
   prompt: "This is a prompt"

3. Invalid special characters - Wrap strings containing :, #, or { in quotes:

   # Wrong
   prompt: Review this: analyze the code
   
   # Correct
   prompt: "Review this: analyze the code"

Pro tip: Validate your YAML with wave validate before running pipelines.

Try a Real Pipeline

Run a code review on your project:

wave run gh-pr-review "review the main module"

Or run an ad-hoc task without a pipeline file:

wave do "analyze the error handling in this codebase"

Quick Commands

# List available pipelines
wave list pipelines

# Check pipeline status
wave status

# View artifacts from last run
wave artifacts

# View logs
wave logs

# Validate configuration
wave validate

# Clean up workspaces
wave clean

Optional: Enable Sandbox Mode

For isolated development with filesystem and environment protection:

# Requires Nix (https://nixos.org/download.html)
nix develop

This enters a bubblewrap sandbox where the filesystem is read-only except for the project directory, and the home directory (~/.ssh, ~/.aws, etc.) is hidden. See Sandbox Setup Guide for details.

Next Steps

• Sandbox Setup - Isolate AI agent sessions
• Use Cases - Find pipelines for code review, documentation, and tests
• Concepts: Pipelines - Understand pipeline structure
• Concepts: Personas - Learn about AI agent roles
• CLI Reference - Complete command documentation
• Adapters Reference - Configure alternative LLM providers