getting-started.md

title	Getting Started

Wavemill is designed to be run primarily through wavemill mill. The other commands help you prepare work, inspect results, or step in manually when needed.

Prerequisites

• Node.js 18+
• npm
• tmux
• jq
• Linear API key (LINEAR_API_KEY)
• Optional: GitHub CLI (gh)

1) Install Wavemill

git clone https://github.com/timogilvie/wavemill/ wavemill
cd wavemill
./install.sh
wavemill help

2) Configure Linear Access

export LINEAR_API_KEY="your-key-here"

Add that export to your shell profile for persistence.

3) Initialize Repo Config

In the target project repo:

wavemill init

This creates a comprehensive .wavemill-config.json with all available sections:

• linear: Project name for backlog queries
• mill: Continuous execution settings (parallelism, agent, worktree root)
• expand: Batch expansion settings
• plan: Epic decomposition settings
• eval: LLM evaluation with judge model, pricing, and intervention penalties
• autoEval: Auto-run eval after workflow completion
• review: Self-review loop configuration
• router: Model routing based on historical eval data
• validation: Task packet validation layers
• constraints: Constraint rule validation
• ui: UI review and design verification settings
• permissions: Auto-approve patterns for agent tools

Edit .wavemill-config.json and set:

• Linear project name (required)
• Base branch (usually main)
• Parallelism and agent defaults as needed
• Enable/disable features like autoEval, router, review, etc.

4) Run Mill Mode

Start with the default workflow:

cd <your-project>
wavemill mill

What happens next:

• Wavemill reads the configured backlog
• expands thin tasks when needed
• routes work to the best available models
• launches parallel worktrees and agents
• evaluates outcomes so future routing improves

5) Optional: Opt Into Hokusai

If you want routing to benefit from collective intelligence in addition to your own local history:

wavemill hokusai enable

Hokusai is optional. Wavemill still improves from your own repository data without it.

Config Versioning

The config includes a configVersion field to track format compatibility. When running wavemill mill, expand, or plan, you'll be prompted to upgrade if your config is outdated.

To manually upgrade:

npx tsx tools/sync-config.ts

To skip version checks:

SKIP_CONFIG_CHECK=true wavemill mill

Next Steps

• For the default operating model: Mill Mode
• For the routing and learning loop: Routing & Hokusai
• For every available command: CLI Reference

See Also

• Mill Mode — autonomous parallel backlog processing
• Routing & Hokusai — how Wavemill gets better over time
• CLI Reference — full command surface
• Plan Mode — decompose epics into well-scoped sub-issues
• Expand Mode — batch expand issues into task packets
• Eval Mode — evaluate LLM performance on workflows
• Troubleshooting — common issues and fixes