Orchestration for agent factories. Just the right amount of guardrails.
Wave is the open-source orchestration layer for AI agent factories — define multi-agent pipelines in YAML, scope each persona's permissions precisely, and run repeatable workflows with contract-validated handoffs and full audit trails.
Agent factories need boundaries — not to hobble agents, but to make them trustworthy enough to run unsupervised.
Most teams end up at one of two extremes: agents wrapped in approval loops that accomplish nothing, or unconstrained agents one misread prompt away from a production incident. Wave finds the middle path — just the right amount of guardrails.
Scoping is declarative, per-persona, enforced at runtime, and versioned in git. Agents do more. Accidents don't happen.
Wave is the orchestration layer described in Building Agent Factories — the open-source runtime for specification-driven AI workflows at scale.
curl -fsSL https://raw.githubusercontent.com/re-cinq/wave/main/scripts/install.sh | shInstall a specific version:
curl -fsSL https://raw.githubusercontent.com/re-cinq/wave/main/scripts/install.sh | sh -s -- 0.3.0Download pre-built binaries from GitHub Releases. Archives are available for Linux (x86_64, ARM64) and macOS (Intel, Apple Silicon).
git clone https://github.com/re-cinq/wave.git
cd wave
make build
# Binary is at ./wave — move it to your PATH:
make install # installs to ~/.local/bin by defaultnix developSee Installation Guide for more options including .deb packages and custom install directories.
# Initialize Wave in your project
cd /path/to/your/project
wave init
# Run your first pipeline
wave run hello-world
# Run a feature development pipeline
wave run speckit-flow "add user authentication"
# Or run ad-hoc tasks
wave do "fix the failing test in auth_test.go"
# Monitor running pipelines
wave status
# View logs
wave logs --follow ╦ ╦╔═╗╦ ╦╔═╗
║║║╠═╣╚╗╔╝║╣
╚╩╝╩ ╩ ╚╝ ╚═╝
Multi-Agent Pipeline Orchestrator
Wave coordinates multiple AI personas through structured pipelines,
enforcing permissions, contracts, and workspace isolation at every step.
Usage:
wave [command]
Available Commands:
artifacts List and export pipeline artifacts
cancel Cancel a running pipeline
chat Interactive analysis of pipeline runs
clean Clean up project artifacts
completion Generate the autocompletion script for the specified shell
do Execute an ad-hoc task
help Help about any command
init Initialize a new Wave project
list List pipelines and personas
logs Show pipeline logs
meta Generate a custom pipeline
migrate Database migration commands
run Run a pipeline (use --from-step to resume)
serve Start the web operations dashboard
status Show pipeline status
validate Validate Wave configuration
Flags:
-d, --debug Enable debug mode
-h, --help help for wave
-m, --manifest string Path to manifest file (default "wave.yaml")
-o, --output string Output format: auto, json, text, quiet (default "auto")
-v, --verbose Include real-time tool activity
--no-tui Disable TUI and print help text
--version version for wave
Use "wave [command] --help" for more information about a command.
| Command | Description |
|---|---|
wave init |
Initialize project with personas and pipelines |
wave run <pipeline> |
Execute a pipeline |
wave do "<task>" |
Quick ad-hoc task (auto-generates 2-step pipeline) |
wave meta "<task>" |
Generate custom multi-step pipeline with schemas |
wave cancel [run-id] |
Cancel running pipeline (graceful or --force) |
| Command | Description |
|---|---|
wave status [run-id] |
Show pipeline status (running, recent, details) |
wave logs [run-id] |
View event logs (--follow, --tail, --errors) |
wave artifacts [run-id] |
List and export pipeline artifacts |
wave list [resource] |
List pipelines, personas, adapters, or runs |
| Command | Description |
|---|---|
wave validate |
Check manifest and pipeline configuration |
wave clean |
Remove workspaces and state (--older-than, --status) |
# Feature development
wave run speckit-flow "add OAuth2 with Google"
# Fix production bug
wave run hotfix "500 errors on /api/users"
# Review PR
wave run gh-pr-review "review auth module changes"
# Generate tests
wave run test-gen "improve coverage for internal/cache"
# Quick fixes
wave do "fix typo in README"
wave do "add input validation to signup form"
wave do "review for SQL injection" --persona auditorGenerate custom pipelines dynamically using wave meta:
# Generate a custom pipeline for your task
wave meta "implement user authentication"
wave meta "add database migrations"
wave meta "create REST API endpoints"
# Save generated pipeline for reuse
wave meta "implement caching layer" --save my-cache-pipeline.yaml
# Dry run to see what would be generated
wave meta "add monitoring dashboard" --dry-runWhat happens with wave meta:
- AI Architect analyzes your task and designs a custom pipeline
- Auto-generates schemas for data validation between steps
- Creates optimized workflow with appropriate personas and dependencies
- Executes immediately or saves for later use
Generated pipelines include:
- ✅ Navigator step for codebase analysis
- ✅ Specification and planning steps
- ✅ Implementation with proper personas
- ✅ Review and validation steps
- ✅ JSON schemas for contract validation
- ✅ Proper output artifact handling
# Show currently running pipelines
wave status
# Show all recent pipelines
wave status --all
# Show specific run details
wave status debug-20260202-143022
# Stream logs in real-time
wave logs --follow
# Show only errors from last run
wave logs --errors
# Show last 50 log entries
wave logs --tail 50
# Filter logs by step
wave logs --step investigate
# JSON output for scripting
wave status --format json
wave logs --format json# Cancel most recent running pipeline
wave cancel
# Force cancel (SIGTERM/SIGKILL)
wave cancel --force
# Cancel specific run
wave cancel abc123-def456
# List recent runs
wave list runs
# List runs filtered by status
wave list runs --run-status failed
# Export artifacts from a run
wave artifacts --export ./output
# Export specific step's artifacts
wave artifacts --step implement --export ./output# Preview what would be deleted
wave clean --dry-run --all
# Clean all workspaces
wave clean --all
# Clean workspaces older than 7 days
wave clean --older-than 7d
# Clean only failed pipelines
wave clean --status failed
# Keep last 5 workspaces
wave clean --all --keep-last 5personas:
navigator:
adapter: claude
#temperature: 0.3
permissions:
allowed_tools: [Read, Glob, Grep, "Bash(git log*)", "Bash(git status*)"]
deny: ["Write(*)", "Edit(*)", "Bash(git commit*)", "Bash(git push*)"]30 built-in personas including navigator, craftsman, auditor, philosopher, debugger, and more.
Explore all personas in
.wave/personas/
steps:
- id: navigate
persona: navigator
- id: implement
persona: craftsman
dependencies: [navigate]
- id: review
persona: auditor
dependencies: [implement]Steps without mutual dependencies run concurrently. Fan-out from a shared step, or start independent parallel tracks:
steps:
- id: analyze
persona: navigator
- id: security
persona: auditor
dependencies: [analyze]
- id: quality
persona: auditor
dependencies: [analyze]
- id: summary
persona: summarizer
dependencies: [security, quality] # runs after both complete47 built-in pipelines for development, debugging, documentation, and GitHub automation.
Explore all pipelines in
.wave/pipelines/
Every step boundary validates output against JSON Schema, TypeScript interfaces, or test suites. Malformed artifacts trigger retries or halt the pipeline.
A selection of the 47 built-in pipelines:
| Pipeline | Description |
|---|---|
speckit-flow |
Specification-driven feature development |
feature |
Feature planning and implementation |
hotfix |
Quick investigation and fix for production issues |
refactor |
Safe refactoring with comprehensive test coverage |
prototype |
Prototype-driven development (spec → docs → dummy → implement → pr) |
| Pipeline | Description |
|---|---|
gh-pr-review |
Comprehensive code review for pull requests |
test-gen |
Generate comprehensive test coverage |
debug |
Systematic debugging with hypothesis testing |
| Pipeline | Description |
|---|---|
plan |
Break down a feature into actionable tasks |
doc-fix |
Generate or update documentation |
doc-audit |
Documentation consistency gate |
| Pipeline | Description |
|---|---|
gh-implement |
Implement a GitHub issue end-to-end |
gh-scope |
Decompose epics into child issues |
gh-research |
Research and report on issues |
More pipelines:
hello-world,smoke-test,explain,onboard,improve,dead-code,security-scan,changelog,adr,wave-land,recinq,supervise, plus platform variants for GitHub (gh-*), GitLab (gl-*), Gitea (gt-*), and Bitbucket (bb-*)Explore all in
.wave/pipelines/
A selection of the 30 built-in personas:
| Persona | Purpose | Key Permissions |
|---|---|---|
navigator |
Codebase exploration | Read, Glob, Grep, git log/status |
philosopher |
Architecture & specs | Read, Write, Edit, Bash, Glob, Grep |
planner |
Task breakdown | Read, Write, Edit, Bash, Glob, Grep |
craftsman |
Implementation | Read, Write, Edit, Bash |
debugger |
Root cause analysis | Read, Grep, Glob, go test, git log/diff/bisect |
auditor |
Security review | Read, Grep, go vet, npm audit |
summarizer |
Context compaction | Read, Write, Edit, Bash, Glob, Grep |
More personas:
implementer,researcher,reviewer,supervisor,validator,synthesizer,provocateur, plus platform-specific personas for GitHub, GitLab, Gitea, and BitbucketExplore all in
.wave/personas/
wave.yaml # Project manifest
.wave/
├── personas/ # System prompts
│ ├── navigator.md
│ ├── craftsman.md
│ └── ...
├── pipelines/ # Pipeline definitions
│ ├── speckit-flow.yaml
│ ├── hotfix.yaml
│ └── ...
├── contracts/ # JSON schemas
├── workspaces/ # Ephemeral step workspaces
├── pids/ # Process ID files for cancel
├── state.db # SQLite state database
└── traces/ # Audit logs
- Quick Start Guide
- Installation
- Sandbox Setup
- Personas Guide
- Pipelines Guide
- CLI Reference
- Manifest Schema
- Pipeline Schema
- Event Reference
- Adapters Reference
Wave provides defense-in-depth isolation for AI agent sessions.
# Enter sandboxed shell (bubblewrap on Linux, unsandboxed on macOS)
nix develop
# Escape hatch: no sandbox
nix develop .#yoloThe sandbox isolates the entire session:
- Filesystem:
/is read-only, only project dir +~/.claude+~/go+/tmpare writable - Home directory: hidden via
tmpfs— selective read-only mounts for~/.ssh,~/.gitconfig,~/.config/gh - Environment: Nix-provided environment inherited (no
--clearenv) - Process isolation:
--unshare-all+--die-with-parent
Persona permissions from wave.yaml are projected into Claude Code's settings.json and CLAUDE.md:
personas:
navigator:
permissions:
allowed_tools: [Read, Glob, Grep, "Bash(git log*)", "Bash(git status*)"]
deny: ["Write(*)", "Edit(*)", "Bash(git commit*)", "Bash(git push*)"]
sandbox:
allowed_domains: [api.anthropic.com]
runtime:
sandbox:
enabled: true
default_allowed_domains: [api.anthropic.com, github.com]
env_passthrough: [ANTHROPIC_API_KEY, GH_TOKEN]See Sandbox Setup Guide for details.
| Tool | Purpose | Required | Install |
|---|---|---|---|
wave |
Pipeline orchestrator | Yes | Installation Guide |
claude |
LLM adapter (Claude Code) | Yes* | npm install -g @anthropic-ai/claude-code |
gh |
GitHub CLI for issue/PR pipelines | Optional | cli.github.com |
git |
Version control, worktree isolation | Yes | git-scm.com |
| Go 1.25+ | Building from source | Optional | go.dev |
| Nix | Sandboxed development shell | Optional | nixos.org |
* At least one LLM CLI adapter is required. claude (Claude Code) is the default. Other adapters (opencode, custom) can be configured in wave.yaml.
Run wave doctor after installation to verify your environment is correctly configured. See the Installation Guide for detailed setup instructions.
Contributions are welcome! Please see CONTRIBUTING.md for guidelines on building, testing, commit conventions, and the PR workflow.